@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
733 lines (664 loc) • 35.8 kB
text/typescript
/**
* Per-message effort history (#6895): the decision state machine behind the Anthropic adapter's
* experimental `perMessageEffort` option.
*
* A Codex conversation that changes reasoning effort mid-chat rewrites Anthropic's top-level
* `output_config.effort`, and that rewrite invalidates every cached message block. Anthropic's
* per-message effort beta instead takes an effort-only system message at the turn where the
* effort changes, so the top-level value, and with it the cached prefix, can stay pinned to the
* conversation's first effort. Codex history carries no per-turn effort, so this module remembers,
* per conversation, where each change point sits and which effort it set.
*
* Design: rkb32's contract and offline slice on #6895 (rules 0-9, failure table, bounds). The store
* is process-local and holds hashes and pinned values only, never transcript text. Every path that
* cannot prove the request extends a committed history answers "off", which sends the request
* exactly as it would be sent without the option.
*
* Owner: structure/providers/anthropic-per-message-effort.md. Production seam:
* src/adapters/anthropic/per-message-effort.ts.
*/
import { createHmac, randomBytes } from "node:crypto";
// Per-process key: fingerprints are not reproducible outside this process.
const hashKey = randomBytes(32);
export const MAX_ENTRIES = 64;
/** Hard bound on everything the store holds, pending slots and their buffers included. */
export const MAX_TOTAL_BYTES = 512 * 1024;
/** Cap on the output one pending slot may commit (stored records are hashes, so this bounds the buffer). */
export const MAX_BUFFER_BYTES = 128 * 1024;
/** Change points are re-sent on every later turn, so their count is capped. */
export const MAX_CHANGE_POINTS = 64;
/** One hour from last use. */
export const ENTRY_TTL_MS = 60 * 60 * 1000;
/** A model/destination refusal is remembered this long. */
export const CAPABILITY_TTL_MS = 60 * 60 * 1000;
const MAX_CAPABILITY = 256;
/** A pending slot expires this long after admission. */
export const PENDING_TTL_MS = 10 * 60 * 1000;
export const SCOPE_PARTS = ["cohort", "provider", "destination", "adapter", "model", "credential", "authMode"] as const;
// api.anthropic.com only. Fable 5.1 stays off until its wire id is checked against the Mythos rule.
const IN_SCOPE_MODEL = /^(claude-)?(mythos-5-1|opus-5-5|opus-5|sonnet-5-5|haiku-5-5)$/;
const ENDPOINT = "api.anthropic.com";
// Effort names the serializer can emit (anthropic.ts adaptiveEffort / reasoningBudget).
const EFFORTS = new Set(["minimal", "low", "medium", "high", "xhigh", "max"]);
/**
* The documented 400 for a model without per-message effort:
* "output_config.effort requires a model that supports per-turn effort; this model does not".
* Any other 400 sets nothing.
*/
export const BETA_FRAGMENT = "requires a model that supports per-turn effort";
type Rec = Record<string, unknown>;
export type EffortHistoryScope = Record<(typeof SCOPE_PARTS)[number], string | undefined>;
/** One request, as the decision sees it. Every compared value is the one actually emitted. */
export interface EffortHistoryRequest {
chatLineage?: string;
scope?: Partial<EffortHistoryScope>;
/** Raw Responses items before this turn's new input. */
parent: unknown[];
/** This turn's new input: user, tool-result, developer and configuration items. */
suffix: unknown[];
effort?: string;
/** The emitted `thinking` field. */
thinking?: unknown;
emittedMaxTokens?: number;
explicitCap?: number;
omittedMaxTokens?: number;
/** Hash of everything on the wire that does not depend on effort (system, tools, display...). */
frame?: string;
generation?: string;
cacheControl?: boolean;
stripped?: boolean;
transport?: "http" | "websocket";
apiKind?: "responses" | "messages";
previousResponseId?: unknown;
compactionSummary?: boolean;
/** A positive new-transcript receipt for this turn (never inferred from shape alone). */
newTranscriptReceipt?: boolean;
/**
* The Anthropic `messages` index the effort message for this turn's change point would take:
* the wire message that starts with this turn's user message. Undefined when it cannot be placed.
*/
changeWireIndex?: number;
}
export interface EffortHistoryOptions {
enabled?: boolean;
activated?: boolean;
websocketHeaderRead?: boolean;
compactionMarkerIdentified?: boolean;
now?: number;
}
export interface EffortChangePoint { at: number; wireIndex: number; effort: string }
export type EffortHistoryDecision =
| { action: "off"; reason: string; deleted?: boolean }
| {
action: "send";
kind: "new" | "matched";
pendingToken: string;
anchorEffort: string;
changePoint?: boolean;
shape?: "a" | "tool-only";
insert?: EffortChangePoint | null;
changePoints?: EffortChangePoint[];
};
interface PinnedRequest {
/** Digest of the chat lineage; the raw value is never kept. */
lineageKey: string;
/** Digest of the model and destination the capability record is keyed by. */
capabilityKey: string;
effort?: string;
/** Digest of the emitted `thinking` field. */
thinkingKey: string;
explicitCap?: number;
emittedMaxTokens?: number;
omittedMaxTokens?: number;
frame?: string;
generation?: string;
changeAt: number;
changeWireIndex?: number;
}
interface Entry {
scopeKey: string;
frame?: string;
generation?: string;
prefixHash: string;
inputHash: string;
effortInEffect: string;
lineageKey: string;
anchorEffort: string;
thinkingKey: string;
budget: number;
limit: number;
changePoints: EffortChangePoint[];
P: number;
version: number;
lastUsed: number;
bytes: number;
}
interface Slot {
kind: "new" | "matched";
key: string;
token: string;
version: number;
createdAt: number;
inputHash: string;
scopeKey: string;
req: PinnedRequest;
pinnedBytes: number;
attemptGeneration?: string;
entry?: Entry;
changePoint?: boolean;
buffered?: number;
}
export interface EffortHistoryStore {
entries: Map<string, Entry>;
pending: Map<string, Slot>;
capability: Map<string, { state: "unsupported"; at: number }>;
committedInputs: Map<string, true>;
nextVersion: number;
}
export interface EffortHistoryCommitResult {
messageStop?: boolean;
failedBeforeSend?: boolean;
restoreOnFailure?: boolean;
cacheRead?: number;
P?: number;
outputItems?: unknown[];
generation?: string;
}
export type EffortHistoryOutcome = { action: string; reason?: string; key?: string; deleted?: boolean };
// A tool call with no output in the same request: the serializer would synthesize one the client never sent.
function hasOrphanCall(items: unknown[]): boolean {
const outputs = new Set(items.filter(i => TOOL_OUTPUTS.has(String((i as Rec | null)?.type))).map(i => (i as Rec).call_id));
return items.some(i => {
const type = (i as Rec | null)?.type;
return (type === "function_call" || type === "custom_tool_call") && !outputs.has((i as Rec).call_id);
});
}
// Activation gates: no request reached the upstream path, so nothing is deleted.
const GATE_REASONS = new Set(["switch-off", "not-activated", "websocket-before-activation"]);
// Canonical JSON: object keys sorted at every level, so equal content hashes equally. A null field
// is the same as an absent one: Codex 0.167 echoes a reasoning item with `content: null` that the
// proxy never sent (live capture, 2026-11-16).
function canonical(value: unknown): unknown {
if (Array.isArray(value)) return value.map(canonical);
if (value && typeof value === "object") {
const rec = value as Rec;
return Object.fromEntries(Object.keys(rec).filter(k => rec[k] !== null).sort().map(k => [k, canonical(rec[k])]));
}
return value;
}
const stableJson = (value: unknown): string => JSON.stringify(canonical(value)) ?? "undefined";
/** The one projection used for commit and lookup. Key order is canonical; nothing else is dropped. */
export const project = (items: unknown): unknown => canonical(items);
export const hash = (value: unknown): string => createHmac("sha256", hashKey).update(stableJson(value)).digest("hex");
// A prefix digest is a chain over per-item digests, so a pending slot can extend it at commit
// without keeping any item text.
const extendChain = (digest: string, items: unknown[]): string => items.reduce<string>((d, item) => hash([d, hash(project(item))]), digest);
export const EMPTY_CHAIN = hash([]);
export const hashItems = (items: unknown[]): string => extendChain(EMPTY_CHAIN, items);
const bytesOf = (value: unknown): number => Buffer.byteLength(stableJson(value));
/** `minimal` maps to `low` for adaptive output (anthropic.ts adaptiveEffort), so the two are not a change point. */
export const mapEffort = (effort: string): string => (effort === "minimal" ? "low" : effort);
// Reasoning budget by effort (anthropic.ts reasoningBudget).
const BUDGET: Record<string, number> = { minimal: 1024, low: 4096, medium: 8192, high: 16384, xhigh: 24576, max: 32000 };
/**
* Effective output limit for this request. The emitted `max_tokens` wins; otherwise an explicit
* client cap; otherwise the adaptive derivation max(omitted, min(40192, max(8192, budget + 8192))).
*/
export function effectiveLimit(req: Pick<EffortHistoryRequest, "emittedMaxTokens" | "explicitCap" | "effort" | "omittedMaxTokens">): number {
if (req.emittedMaxTokens !== undefined) return req.emittedMaxTokens;
if (req.explicitCap !== undefined) return req.explicitCap;
const budget = (Object.hasOwn(BUDGET, mapEffort(String(req.effort))) ? BUDGET[mapEffort(String(req.effort))] : undefined) ?? 8192;
return Math.max(req.omittedMaxTokens ?? 8192, Math.min(40192, Math.max(8192, budget + 8192)));
}
const off = (reason: string, extra: { deleted?: boolean } = {}): EffortHistoryDecision => ({ action: "off", reason, ...extra });
// Capability is per model and destination, not per chat or credential.
const capabilityKey = (s: Partial<EffortHistoryScope>): string => hash({ model: s.model, destination: s.destination });
export function createStore(): EffortHistoryStore {
return { entries: new Map(), pending: new Map(), capability: new Map(), committedInputs: new Map(), nextVersion: 1 };
}
// Entry key: scope + committed prefix. The frame is a field, not part of the key, so a frame
// change finds the entry by prefix and rule 6 can fire.
const entryKey = (scopeKey: string, prefixHash: string): string => hash([scopeKey, prefixHash]);
const newKey = (scopeKey: string, inputHash: string): string => hash(["new", scopeKey, inputHash]);
/**
* Codex's own per-turn `x-codex-turn-metadata` value: true only for `history_initialization` "new".
* Codex 0.167 sends the lowercase serde spelling; the enum's source name `New` is accepted too.
* The caller decides which copy of the metadata describes the turn (see the production seam).
*/
export function lineageFromMetadata(headerValue: unknown): boolean {
if (typeof headerValue !== "string") return false;
let parsed: unknown;
try {
parsed = JSON.parse(headerValue);
} catch {
return false;
}
const value = parsed !== null && typeof parsed === "object" ? (parsed as Rec).history_initialization : undefined;
return value === "new" || value === "New";
}
// Tool output types the Responses parser handles.
const TOOL_OUTPUTS = new Set(["function_call_output", "custom_tool_call_output", "tool_search_output"]);
/** Item kind: a test shorthand (`kind`), or a real Responses input item by its type and role. */
export function kindOf(item: unknown): string {
const rec = (item && typeof item === "object" ? item : {}) as Rec;
if (typeof rec.kind === "string" && rec.type === undefined && rec.role === undefined) return rec.kind;
const type = rec.type ?? (rec.role ? "message" : undefined);
if (type === "message") {
if (rec.role === "user") return "user";
if (rec.role === "assistant") return "assistant";
if (rec.role === "developer" || rec.role === "system") return "developer";
}
if (TOOL_OUTPUTS.has(String(type))) return "tool_result";
if (type === "configuration_update") return "configuration_update";
return `other:${String(type)}`;
}
const isUser = (item: unknown): boolean => kindOf(item) === "user";
const isTool = (item: unknown): boolean => kindOf(item) === "tool_result";
const isDeveloper = (item: unknown): boolean => kindOf(item) === "developer";
const hasConfigUpdate = (items: unknown[]): boolean => items.some(item => kindOf(item) === "configuration_update");
// Off, and the parent entry is deleted before the request is sent.
function offSend(store: EffortHistoryStore, parentKey: string, reason: string): EffortHistoryDecision {
store.entries.delete(parentKey);
store.pending.delete(parentKey);
return off(reason, { deleted: true });
}
// Drop entries past their TTL and pending slots past theirs.
function sweep(store: EffortHistoryStore, now: number): void {
for (const [key, cap] of store.capability) {
if (now - cap.at > CAPABILITY_TTL_MS) store.capability.delete(key);
}
for (const [key, entry] of store.entries) {
if (now - entry.lastUsed > ENTRY_TTL_MS) store.entries.delete(key);
}
for (const [key, slot] of store.pending) {
if (now - slot.createdAt > PENDING_TTL_MS) store.pending.delete(key);
}
}
// An account, provider, or model change ends the old scope of this chat.
function endOtherScopes(store: EffortHistoryStore, lineage: string, scopeKey: string): void {
for (const [key, entry] of store.entries) {
if (entry.lineageKey === lineage && entry.scopeKey !== scopeKey) store.entries.delete(key);
}
for (const [key, slot] of store.pending) {
if (slot.req?.lineageKey === lineage && slot.scopeKey !== scopeKey) store.pending.delete(key);
}
}
function dropParent(store: EffortHistoryStore, req: EffortHistoryRequest): void {
const s = req.scope;
if (!s || !req.chatLineage || !Array.isArray(req.parent)) return;
const key = entryKey(hash([s, req.chatLineage]), hashItems(req.parent));
store.entries.delete(key);
store.pending.delete(key);
}
function decideWithCleanup(store: EffortHistoryStore, req: EffortHistoryRequest, opts?: EffortHistoryOptions): EffortHistoryDecision {
const result = decideInner(store, req, opts);
if (result.action === "off" && !GATE_REASONS.has(result.reason)) dropParent(store, req);
return result;
}
const validWireIndex = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 0;
// Ordered algorithm. The first rule that decides wins.
function decideInner(store: EffortHistoryStore, req: EffortHistoryRequest, opts: EffortHistoryOptions = {}): EffortHistoryDecision {
const now = opts.now ?? Date.now();
sweep(store, now);
// Rule 0 (global gate): nothing runs unless the option is on and activated.
if (opts.enabled !== true) return off("switch-off");
if (opts.activated !== true) return off("not-activated");
if (req.transport === "websocket" && opts.websocketHeaderRead !== true) return off("websocket-before-activation");
// Rule 1: out of scope. Claude Messages requests and requests with previous_response_id are always off.
if (req.apiKind === "messages") return off("out-of-scope-messages-api");
if (req.previousResponseId) return off("out-of-scope-previous-response-id");
// Fable 5.1 is in scope only once its wire id is checked against the Mythos rule; until then off.
if (/fable/i.test(req.scope?.model ?? "")) return off("fable-wire-id-unchecked");
if (hasOrphanCall([...req.parent, ...req.suffix])) return off("orphan-tool-call");
// No effort level ("none" or absent) cannot be a per-message effort value: off, as today.
if (typeof req.effort !== "string" || !EFFORTS.has(req.effort)) return off("no-effort-level");
// Rule 2: every scope part is required.
const s = req.scope;
if (!s || SCOPE_PARTS.some(k => !s[k])) return off("missing-scope");
if (s.authMode !== "apiKey") return off("oauth-not-in-first-slice");
if (s.destination !== ENDPOINT) return off("out-of-scope-destination");
if (typeof s.model !== "string" || !IN_SCOPE_MODEL.test(s.model)) return off("out-of-scope-model");
// Chat identity: two chats can share a first message, so each chat needs its own lineage value.
if (!req.chatLineage) return off("no-chat-lineage");
const scopeKey = hash([s, req.chatLineage]);
endOtherScopes(store, hash(req.chatLineage), scopeKey);
const parentHash = hashItems(req.parent);
const parentKey = entryKey(scopeKey, parentHash);
const inputHash = hashItems([...req.parent, ...req.suffix]);
// Rule 2a: no cache breakpoint. Rule 3: the proxy stripped reasoning.
if (!req.cacheControl) return offSend(store, parentKey, "no-cache-control");
if (req.stripped) return offSend(store, parentKey, "proxy-stripped");
// Rule 3a: an unsupported capability record.
const cap = store.capability.get(capabilityKey(s));
if (cap && cap.state === "unsupported" && now - cap.at <= CAPABILITY_TTL_MS) return offSend(store, parentKey, "capability-unsupported");
// Rule 3b runs before rule 4: a thinking change on a matching parent. Only emitted fields count:
// an emitted budget_tokens change is a change; the adaptive branch's internal budget is never emitted.
const parent = store.entries.get(parentKey);
if (parent && hash(req.thinking) !== parent.thinkingKey) return offSend(store, parentKey, "thinking-change");
// Rule 4: replay. The request is a turn already committed (same input hash).
for (const [key, entry] of store.entries) {
if (entry.scopeKey === scopeKey && entry.inputHash === inputHash) {
store.entries.delete(key);
store.entries.delete(parentKey);
return off("replay", { deleted: true });
}
}
// The turn's entry may already be consumed by a later turn; the committed-input record still refuses it.
if (store.committedInputs.has(hash([scopeKey, inputHash]))) {
store.entries.delete(parentKey);
return off("replay", { deleted: true });
}
// A placeholder with the same input hash is a duplicate first request: off, and it is deleted.
const placeholder = newKey(scopeKey, inputHash);
if (store.pending.has(placeholder)) {
store.pending.delete(placeholder);
return off("placeholder-exists", { deleted: true });
}
if (hasConfigUpdate(req.suffix)) return offSend(store, parentKey, "configuration-update-in-suffix");
// A second request for a parent that is already pending is a fork or retry.
if (store.pending.has(parentKey)) {
store.pending.delete(parentKey);
return off("in-flight-collision", { deleted: true });
}
const suffix = req.suffix;
const userCount = suffix.filter(isUser).length;
const toolOnly = suffix.length > 0 && suffix.every(isTool);
// Shape (a): one user message, optionally after tool results. Developer items may appear.
const firstUser = suffix.findIndex(isUser);
const shapeA = userCount === 1
&& suffix.every(item => isUser(item) || isTool(item) || isDeveloper(item))
&& suffix.slice(firstUser + 1).every(item => !isTool(item));
if (!parent) {
// Rule 7: a compaction summary is user-role; it never starts a history.
if (req.compactionSummary === true) return off("compaction-summary");
if (opts.compactionMarkerIdentified !== true) return off("compaction-marker-unidentified");
// A new history needs a positive new-transcript receipt and a transcript of user and developer
// items only: a real Codex first turn carries its environment context as a second user message.
// A restart, eviction, or compaction is not new.
const newChat = req.newTranscriptReceipt === true && req.parent.length === 0
&& userCount >= 1 && suffix.every(item => isUser(item) || isDeveloper(item));
if (!newChat) return off("no-history");
const pinned = pin(req);
const pinnedBytes = bytesOf(pinned);
// Decide first, evict second: a refused admission must not cost another chat its history, so
// both the byte check and the entry-count check run before anything is evicted.
if (!canFit(store, pinnedBytes)) return off("bounds-refused");
const atCount = store.entries.size + store.pending.size >= MAX_ENTRIES;
const oldest = atCount ? leastRecentlyUsed(store) : undefined;
if (atCount && oldest === undefined) return off("bounds-refused");
if (oldest !== undefined) store.entries.delete(oldest);
// The slot's bytes count against the store total: evict stored histories until it fits.
if (!evictUntilFits(store, pinnedBytes)) return off("bounds-refused");
const version = store.nextVersion++;
const token = `${placeholder}:${version}`;
store.pending.set(placeholder, {
kind: "new", key: placeholder, token, version, createdAt: now, inputHash, scopeKey, req: pinned, pinnedBytes, attemptGeneration: req.generation,
});
return { action: "send", kind: "new", pendingToken: token, anchorEffort: mapEffort(req.effort) };
}
// Rule 6: frame and generation.
if (parent.frame !== req.frame) return offSend(store, parentKey, "frame-mismatch");
if (parent.generation !== req.generation) return offSend(store, parentKey, "generation-mismatch");
// Any output limit different from the anchor's is off. A cap is never raised to make a turn eligible.
if (effectiveLimit(req) !== parent.limit) return offSend(store, parentKey, "limit-differs");
if (userCount > 1) return offSend(store, parentKey, "more-than-one-user-message");
const effort = mapEffort(req.effort);
if (toolOnly) {
if (effort !== parent.effortInEffect) return offSend(store, parentKey, "tool-only-effort-change");
return admitMatched(store, { scopeKey, parentKey, req, parent, now, inputHash, changePoint: false, shape: "tool-only" });
}
if (!shapeA) return offSend(store, parentKey, "unclassified-suffix");
const changePoint = effort !== parent.effortInEffect;
if (changePoint && parent.changePoints.length >= MAX_CHANGE_POINTS) return offSend(store, parentKey, "change-points-full");
// Mythos: any effort change is off, because its budget depends on effort.
if (changePoint && /mythos/i.test(s.model)) return offSend(store, parentKey, "mythos-effort-change");
// The effort message must land before this turn's user message on the wire; without a place, off.
if (changePoint && !validWireIndex(req.changeWireIndex)) return offSend(store, parentKey, "change-point-unplaceable");
return admitMatched(store, { scopeKey, parentKey, req, parent, now, inputHash, changePoint, shape: "a" });
}
interface MatchPlan {
scopeKey: string;
parentKey: string;
req: EffortHistoryRequest;
parent: Entry;
now: number;
inputHash: string;
changePoint: boolean;
shape: "a" | "tool-only";
}
// Matched: the parent entry moves to a pending slot until its commit.
function admitMatched(store: EffortHistoryStore, plan: MatchPlan): EffortHistoryDecision {
store.entries.delete(plan.parentKey);
const version = store.nextVersion++;
const token = `${plan.parentKey}:${version}`;
const pinned = pin(plan.req);
const pinnedBytes = bytesOf(pinned);
// The slot holds the parent entry and its pinned values; both count against the store total.
if (!evictUntilFits(store, plan.parent.bytes + pinnedBytes)) return off("bounds-refused", { deleted: true });
store.pending.set(plan.parentKey, {
kind: "matched", key: plan.parentKey, token, version, createdAt: plan.now, inputHash: plan.inputHash,
attemptGeneration: plan.req.generation,
scopeKey: plan.scopeKey, entry: plan.parent, req: pinned, pinnedBytes, changePoint: plan.changePoint,
});
const insert: EffortChangePoint | null = plan.changePoint
? { at: pinned.changeAt, wireIndex: pinned.changeWireIndex as number, effort: mapEffort(plan.req.effort as string) }
: null;
return {
action: "send",
kind: "matched",
pendingToken: token,
anchorEffort: plan.parent.anchorEffort,
changePoint: plan.changePoint,
shape: plan.shape,
// What the adapter inserts: an effort-only system message before this turn's user message.
insert,
// Every change point on this chat, in prefix order, so the adapter re-sends all of them each turn.
changePoints: [...plan.parent.changePoints.map(c => ({ ...c })), ...(insert ? [insert] : [])],
};
}
// The pending slot is the compare-and-set check: a commit is written only if its slot still exists.
function totalBytes(store: EffortHistoryStore): number {
let total = 0;
for (const entry of store.entries.values()) total += entry.bytes;
// A matched parent in flight still holds its bytes until its commit or restore, and buffered
// streaming output counts too.
for (const slot of store.pending.values()) {
if (slot.entry) total += slot.entry.bytes;
total += (slot.pinnedBytes ?? 0) + (slot.buffered ?? 0);
}
return total;
}
// Resolve a token to its slot without removing it. A token from an earlier admission does not match.
function peekSlot(store: EffortHistoryStore, token: unknown): Slot | null {
if (typeof token !== "string") return null;
const sep = token.lastIndexOf(":");
if (sep < 0) return null;
const key = token.slice(0, sep);
const slot = store.pending.get(key);
if (!slot || slot.token !== token) return null;
return slot;
}
function takeSlot(store: EffortHistoryStore, token: unknown): Slot | null {
const slot = peekSlot(store, token);
if (slot) store.pending.delete(slot.key);
return slot;
}
// Eviction order: the entry with the oldest last use, not the first inserted.
function leastRecentlyUsed(store: EffortHistoryStore): string | undefined {
let best: string | undefined;
for (const [key, entry] of store.entries) {
if (best === undefined || entry.lastUsed < (store.entries.get(best) as Entry).lastUsed) best = key;
}
return best;
}
// Streaming: buffered output for a pending slot. Over the store cap or the per-slot cap, the slot
// is deleted and nothing commits; the response itself is not interrupted.
function bufferInner(store: EffortHistoryStore, token: unknown, bytes: number): EffortHistoryOutcome {
const slot = peekSlot(store, token);
if (!slot) return { action: "dropped", reason: "pending-missing" };
if (!Number.isFinite(bytes) || bytes < 0) {
store.pending.delete(slot.key);
return { action: "deleted", reason: "bad-bytes" };
}
if (totalBytes(store) + bytes > MAX_TOTAL_BYTES) {
store.pending.delete(slot.key);
return { action: "deleted", reason: "streaming-over-store-cap" };
}
if ((slot.buffered ?? 0) + bytes > MAX_BUFFER_BYTES) {
store.pending.delete(slot.key);
return { action: "deleted", reason: "over-buffer-cap" };
}
slot.buffered = (slot.buffered ?? 0) + bytes;
return { action: "buffering" };
}
// Whether evicting stored histories could make room: pending bytes are not evictable.
function canFit(store: EffortHistoryStore, bytes: number): boolean {
let evictable = 0;
for (const entry of store.entries.values()) evictable += entry.bytes;
return totalBytes(store) - evictable + bytes <= MAX_TOTAL_BYTES;
}
function evictUntilFits(store: EffortHistoryStore, bytes: number): boolean {
// Decide first, evict second: if the pending bytes alone do not leave room, nothing is evicted.
if (!canFit(store, bytes)) return false;
while (totalBytes(store) + bytes > MAX_TOTAL_BYTES) {
const oldest = leastRecentlyUsed(store);
if (oldest === undefined) return false;
store.entries.delete(oldest);
}
return true;
}
function recordCommittedInput(store: EffortHistoryStore, slot: Slot): void {
store.committedInputs.set(hash([slot.scopeKey, slot.inputHash]), true);
while (store.committedInputs.size > MAX_ENTRIES * 4) {
store.committedInputs.delete(store.committedInputs.keys().next().value as string);
}
}
// Outcomes after a send, in the contract's order.
function commitInner(store: EffortHistoryStore, token: unknown, result: EffortHistoryCommitResult, now = Date.now()): EffortHistoryOutcome {
const slot = takeSlot(store, token);
if (!slot) return { action: "dropped", reason: "pending-missing" };
if (now - slot.createdAt > PENDING_TTL_MS) return { action: "dropped", reason: "pending-expired" };
if (!result || typeof result !== "object") return { action: "deleted", reason: "bad-result" };
const { req } = slot;
if (result.messageStop && !result.failedBeforeSend && !Array.isArray(result.outputItems)) return { action: "deleted", reason: "bad-output" };
if (result.failedBeforeSend) {
// Default: delete. Restore only the matched parent, and only when the caller enables it.
if (slot.kind === "matched" && slot.entry && result.restoreOnFailure === true) {
if (!evictUntilFits(store, slot.entry.bytes)) return { action: "dropped", reason: "over-store-cap" };
store.entries.set(slot.key, slot.entry);
return { action: "restored" };
}
return { action: "deleted", reason: slot.kind === "matched" ? "failed-before-send" : "placeholder-failed" };
}
if (!result.messageStop) return { action: "deleted", reason: "uncertain-outcome" };
// Cache check. A missing cache read counts as zero; NaN or a non-number fails closed.
const cacheRead = result.cacheRead ?? 0;
if (slot.kind === "matched" && !(cacheRead >= (slot.entry as Entry).P)) {
return { action: "deleted", reason: "cache-below-P" };
}
if (!((result.P ?? 0) > 0)) {
if (slot.kind === "new") recordCommittedInput(store, slot);
return { action: "not-committed", reason: "P-zero" };
}
// Generation check: the generation at commit must equal both the lookup and the attempt-start value.
if (result.generation !== req.generation || result.generation !== slot.attemptGeneration) {
return { action: "deleted", reason: "generation-changed" };
}
// Size checks, after the slot check: the larger of the bytes streamed and the canonical output size.
if (Math.max(slot.buffered ?? 0, bytesOf(result.outputItems)) > MAX_BUFFER_BYTES) return { action: "deleted", reason: "over-buffer-cap" };
const prior = slot.kind === "matched" ? slot.entry as Entry : null;
const effort = mapEffort(req.effort as string);
const changePoints = prior
? [...prior.changePoints, ...(slot.changePoint ? [{ at: req.changeAt, wireIndex: req.changeWireIndex as number, effort }] : [])]
: [];
const effortInEffect = prior && !slot.changePoint ? prior.effortInEffect : effort;
const prefixHash = extendChain(slot.inputHash, result.outputItems as unknown[]);
const record = {
scopeKey: slot.scopeKey,
frame: req.frame,
generation: result.generation,
prefixHash,
inputHash: slot.inputHash,
effortInEffect,
lineageKey: req.lineageKey,
anchorEffort: prior ? prior.anchorEffort : effort,
thinkingKey: req.thinkingKey,
budget: BUDGET[effort] ?? 8192,
limit: effectiveLimit(req),
changePoints,
P: result.P as number,
version: store.nextVersion++,
lastUsed: now,
};
const bytes = bytesOf(record);
if (!evictUntilFits(store, bytes)) return { action: "dropped", reason: "over-store-cap" };
const key = entryKey(slot.scopeKey, prefixHash);
// Remember the committed input so a later retry of this turn is refused even after its entry is consumed.
recordCommittedInput(store, slot);
store.entries.set(key, { ...record, bytes });
return { action: "committed", key };
}
// An error from upstream. A 400 with the documented model-unsupported text sets the capability
// record to unsupported. Every error deletes the pending slot; nothing is resent.
function rejectInner(store: EffortHistoryStore, token: unknown, { status, errorText = "" }: { status?: number; errorText?: string } = {}): EffortHistoryOutcome {
const slot = takeSlot(store, token);
if (!slot) return { action: "dropped", reason: "pending-missing" };
if (status === 400 && typeof errorText === "string" && errorText.includes(BETA_FRAGMENT)) {
store.capability.set(slot.req.capabilityKey, { state: "unsupported", at: Date.now() });
while (store.capability.size > MAX_CAPABILITY) store.capability.delete(store.capability.keys().next().value as string);
return { action: "off", reason: "capability-unsupported", deleted: true };
}
return { action: "error", reason: status === 400 ? "other-400" : "upstream-error", deleted: true };
}
// The client disconnected or the request was abandoned: nothing is committed. A matched parent is
// restored only when nothing was sent and the caller enables restore; otherwise it is deleted.
function abandonInner(store: EffortHistoryStore, token: unknown, { sent = true, restoreOnFailure = false }: { sent?: boolean; restoreOnFailure?: boolean } = {}): EffortHistoryOutcome {
const slot = takeSlot(store, token);
if (!slot) return { action: "dropped", reason: "pending-missing" };
if (!sent && restoreOnFailure && slot.kind === "matched" && slot.entry) {
if (!evictUntilFits(store, slot.entry.bytes)) return { action: "dropped", reason: "over-store-cap" };
store.entries.set(slot.key, slot.entry);
return { action: "restored" };
}
return { action: "deleted", reason: "abandoned" };
}
// A pending slot keeps only what commit needs: digests and pinned scalar values, never the request's
// items or the raw lineage, scope or thinking field.
function pin(req: EffortHistoryRequest): PinnedRequest {
return {
lineageKey: hash(req.chatLineage), capabilityKey: capabilityKey(req.scope ?? {}), effort: req.effort,
thinkingKey: hash(req.thinking), explicitCap: req.explicitCap,
emittedMaxTokens: req.emittedMaxTokens, omittedMaxTokens: req.omittedMaxTokens,
frame: req.frame, generation: req.generation, changeAt: changePointAt(req),
...(validWireIndex(req.changeWireIndex) ? { changeWireIndex: req.changeWireIndex } : {}),
};
}
function takeOrIgnore(store: EffortHistoryStore, token: unknown): void {
try {
takeSlot(store, token);
} catch {
// A malformed store is left as it is; the caller gets a fail-closed result.
}
}
/** Decide one request. Any internal failure is "off". */
export function decide(store: EffortHistoryStore, req: EffortHistoryRequest, opts?: EffortHistoryOptions): EffortHistoryDecision {
try { return decideWithCleanup(store, req, opts); } catch { return off("internal-error"); }
}
export function commit(store: EffortHistoryStore, token: unknown, result: EffortHistoryCommitResult, now?: number): EffortHistoryOutcome {
try { return commitInner(store, token, result, now); } catch { takeOrIgnore(store, token); return { action: "deleted", reason: "internal-error" }; }
}
export function buffer(store: EffortHistoryStore, token: unknown, bytes: number): EffortHistoryOutcome {
try { return bufferInner(store, token, bytes); } catch { takeOrIgnore(store, token); return { action: "deleted", reason: "internal-error" }; }
}
export function rejectUpstream(store: EffortHistoryStore, token: unknown, error?: { status?: number; errorText?: string }): EffortHistoryOutcome {
try { return rejectInner(store, token, error); } catch { takeOrIgnore(store, token); return { action: "error", reason: "internal-error", deleted: true }; }
}
export function abandon(store: EffortHistoryStore, token: unknown, opts?: { sent?: boolean; restoreOnFailure?: boolean }): EffortHistoryOutcome {
try { return abandonInner(store, token, opts); } catch { takeOrIgnore(store, token); return { action: "deleted", reason: "internal-error" }; }
}
// The change point goes after the leading tool results, before the user message, as an index into
// the request input array (the parent items come first).
function changePointAt(req: EffortHistoryRequest): number {
const firstUser = req.suffix.findIndex(isUser);
return req.parent.length + (firstUser < 0 ? 0 : firstUser);
}