@esankhan3/anvil-agent-core 0.3.0 → 0.4.0

package/dist/prefill/strip.js

@@ -0,0 +1,93 @@
+/**
+ * Cross-provider strip policy (v2 ADR §2.3.1).
+ *
+ * Vendor-specific message blocks DO NOT survive a chain-fallback swap
+ * across providers. `stripForTarget` removes fields the target provider
+ * would reject (or silently misinterpret) when the conversation
+ * originated on a different vendor.
+ *
+ * The matrix (§2.3.1):
+ *   - reasoning_details[] / reasoning  — OpenRouter reasoning models;
+ *     strip when source !== target (Anthropic + OpenAI reject them).
+ *   - cache_control                    — Anthropic; strip when target is non-Anthropic.
+ *   - prompt_cache_key                 — OpenAI; strip when target is non-OpenAI.
+ *
+ * Same-vendor swaps short-circuit: nothing is stripped (hot path), and
+ * they additionally qualify for the §5.1 prefix-cache fast-path.
+ *
+ * The function is shape-agnostic: it walks each message object and
+ * deletes the known vendor keys (including inside content-block arrays
+ * for Anthropic's `cache_control`). It never mutates the input — every
+ * message is shallow-cloned before a key is removed.
+ */
+/** Anthropic family: native `messages` API consumers.
+ *
+ * NOTE on 'adk': ADK is provider-agnostic at runtime (claude-via-adk =
+ * Anthropic wire; gemini-via-adk = Google wire). Per ADR §2.8, ADK
+ * prefill is materialized via `Session.appendEvent`, NOT through
+ * `materializePrefill`/`stripForTarget` — so this predicate is NOT
+ * exercised for ADK targets in the H2 path. When ADK is ported (H4),
+ * its wire format must be detected from the underlying model id, not
+ * assumed Anthropic here. Kept in the Anthropic bucket only so the
+ * §5.1 same-vendor cache fast-path can recognise `claude`↔`claude`;
+ * revisit when ADK joins the prefill path. */
+function isAnthropic(p) {
+    return p === 'adk' || p === 'claude';
+}
+/** OpenAI-compatible chat-completions consumers. */
+function isOpenAICompat(p) {
+    return p === 'openai' || p === 'openrouter' || p === 'opencode' || p === 'ollama';
+}
+/**
+ * Return a new message array safe to send to `targetProvider` given it
+ * originated on `sourceProvider`. Same-vendor → returned as a shallow
+ * copy untouched.
+ */
+export function stripForTarget(messages, ctx) {
+    if (ctx.sourceProvider === ctx.targetProvider) {
+        return messages.slice();
+    }
+    const dropReasoning = !isOpenRouterFamily(ctx.targetProvider);
+    const dropCacheControl = !isAnthropic(ctx.targetProvider);
+    const dropPromptCacheKey = !isOpenAIExact(ctx.targetProvider);
+    return messages.map((raw) => {
+        if (!raw || typeof raw !== 'object')
+            return raw;
+        const msg = { ...raw };
+        if (dropReasoning) {
+            delete msg.reasoning;
+            delete msg.reasoning_details;
+        }
+        if (dropPromptCacheKey) {
+            delete msg.prompt_cache_key;
+        }
+        if (dropCacheControl) {
+            // top-level marker
+            delete msg.cache_control;
+            // Anthropic puts cache_control inside content-block arrays.
+            if (Array.isArray(msg.content)) {
+                msg.content = msg.content.map((block) => {
+                    if (block && typeof block === 'object' && 'cache_control' in block) {
+                        const clone = { ...block };
+                        delete clone.cache_control;
+                        return clone;
+                    }
+                    return block;
+                });
+            }
+        }
+        return msg;
+    });
+}
+/** OpenRouter (and OpenCode, which proxies OpenRouter-style models) are
+ *  the only consumers that accept echoed reasoning_details. */
+function isOpenRouterFamily(p) {
+    return p === 'openrouter' || p === 'opencode';
+}
+/** Exact OpenAI — the only consumer that honors `prompt_cache_key`. */
+function isOpenAIExact(p) {
+    return p === 'openai';
+}
+// Re-export the family predicates for the translate layer + tests.
+export { isAnthropic, isOpenAICompat };
+//# sourceMappingURL=strip.js.map

package/dist/prefill/strip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/prefill/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH;;;;;;;;;;8CAU8C;AAC9C,SAAS,WAAW,CAAC,CAAe;IAClC,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,QAAQ,CAAC;AACvC,CAAC;AAED,oDAAoD;AACpD,SAAS,cAAc,CAAC,CAAe;IACrC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,YAAY,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,QAAQ,CAAC;AACpF,CAAC;AAID;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAA4B,EAAE,GAAiB;IAC5E,IAAI,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC,cAAc,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9D,MAAM,gBAAgB,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1D,MAAM,kBAAkB,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAE9D,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC1B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC;QAChD,MAAM,GAAG,GAAG,EAAE,GAAI,GAAoB,EAAE,CAAC;QAEzC,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,GAAG,CAAC,SAAS,CAAC;YACrB,OAAO,GAAG,CAAC,iBAAiB,CAAC;QAC/B,CAAC;QACD,IAAI,kBAAkB,EAAE,CAAC;YACvB,OAAO,GAAG,CAAC,gBAAgB,CAAC;QAC9B,CAAC;QACD,IAAI,gBAAgB,EAAE,CAAC;YACrB,mBAAmB;YACnB,OAAO,GAAG,CAAC,aAAa,CAAC;YACzB,4DAA4D;YAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/B,GAAG,CAAC,OAAO,GAAI,GAAG,CAAC,OAAqB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;oBACrD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,eAAe,IAAK,KAAgB,EAAE,CAAC;wBAC/E,MAAM,KAAK,GAAG,EAAE,GAAI,KAAiC,EAAE,CAAC;wBACxD,OAAO,KAAK,CAAC,aAAa,CAAC;wBAC3B,OAAO,KAAK,CAAC;oBACf,CAAC;oBACD,OAAO,KAAK,CAAC;gBACf,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;AACL,CAAC;AAED;+DAC+D;AAC/D,SAAS,kBAAkB,CAAC,CAAe;IACzC,OAAO,CAAC,KAAK,YAAY,IAAI,CAAC,KAAK,UAAU,CAAC;AAChD,CAAC;AAED,uEAAuE;AACvE,SAAS,aAAa,CAAC,CAAe;IACpC,OAAO,CAAC,KAAK,QAAQ,CAAC;AACxB,CAAC;AAED,mEAAmE;AACnE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC"}

package/dist/prefill/translate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Tool-result + prefill shape translation (v2 ADR §2.3.2 / §2.3).
+ *
+ * The durable log stores tool results in a neutral shape
+ * (`NeutralToolResult`). When a chain-fallback swap re-injects a prior
+ * model's turn into a NEW provider, the adapter materializes that turn
+ * into the target provider's wire format. This module owns that
+ * translation.
+ *
+ *   - Anthropic native:
+ *       tool_use  → { role: 'assistant', content: [{ type: 'tool_use', id, name, input }] }
+ *       result    → { role: 'user', content: [{ type: 'tool_result', tool_use_id, content, is_error }] }
+ *   - OpenAI-compat (openrouter, opencode, openai, ollama):
+ *       tool_use  → { role: 'assistant', tool_calls: [{ id, type:'function', function:{ name, arguments } }] }
+ *       result    → { role: 'tool', tool_call_id, content: stringify }
+ *   - ADK: materialized via Session.appendEvent inside the adk adapter
+ *     (functionCall + functionResponse events) — NOT via this module.
+ *
+ * `materializePrefill` turns a `Prefill` into the ordered list of wire
+ * messages to splice into the request BEFORE the continuation: for each
+ * recorded tool use, an assistant(tool_call) + tool(result) pair, then
+ * a trailing assistant message carrying the partial text the prior
+ * model streamed. The target model continues from that trailing
+ * assistant message (verified empirically — Anthropic + OpenAI-compat
+ * both honor a trailing assistant message as a continuation prefix).
+ */
+import type { ProviderName } from '../types.js';
+import type { NeutralToolResult, Prefill, PrefillTurn } from '../turn-recorder/types.js';
+export interface TranslatedToolResult {
+    /** Target-specific wire object the adapter appends to messages[]. */
+    message: unknown;
+}
+/** Convert a `NeutralToolResult` to the target provider's result message. */
+export declare function translateToolResult(result: NeutralToolResult, target: ProviderName): TranslatedToolResult;
+/**
+ * Build the ordered wire messages that re-present a `Prefill` to the
+ * target provider. The caller splices these onto the end of its
+ * `messages[]` (after system + user), then lets the model continue.
+ *
+ * Ordering: each recorded tool use becomes an assistant(tool_call) +
+ * result pair, in recorded order; finally a trailing assistant message
+ * carrying the partial text (only when non-empty — an empty trailing
+ * assistant message is rejected by some providers).
+ */
+export declare function materializePrefill(prefill: Prefill, target: ProviderName): unknown[];
+/**
+ * §Tier 2 — materialize a list of COMPLETED prior turns into the target
+ * provider's wire format, spliced BEFORE the new user message so a stateful
+ * (non-claude) session resume re-presents the full conversation. Each turn
+ * emits, in order: its opening user message (when `userPrompt` is set — the
+ * first turn of a phase), then one combined assistant(text+tool_calls), then
+ * its tool results. Empty list → [] (START phase / no prior turns).
+ */
+export declare function materializePriorTurns(turns: PrefillTurn[], target: ProviderName): unknown[];
+//# sourceMappingURL=translate.d.ts.map

package/dist/prefill/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../../src/prefill/translate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,WAAW,EAAkB,MAAM,2BAA2B,CAAC;AAGzG,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,6EAA6E;AAC7E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,YAAY,GACnB,oBAAoB,CA6BtB;AA6BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,EAAE,CAUpF;AAsCD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,EAAE,CAe3F"}

package/dist/prefill/translate.js

@@ -0,0 +1,162 @@
+/**
+ * Tool-result + prefill shape translation (v2 ADR §2.3.2 / §2.3).
+ *
+ * The durable log stores tool results in a neutral shape
+ * (`NeutralToolResult`). When a chain-fallback swap re-injects a prior
+ * model's turn into a NEW provider, the adapter materializes that turn
+ * into the target provider's wire format. This module owns that
+ * translation.
+ *
+ *   - Anthropic native:
+ *       tool_use  → { role: 'assistant', content: [{ type: 'tool_use', id, name, input }] }
+ *       result    → { role: 'user', content: [{ type: 'tool_result', tool_use_id, content, is_error }] }
+ *   - OpenAI-compat (openrouter, opencode, openai, ollama):
+ *       tool_use  → { role: 'assistant', tool_calls: [{ id, type:'function', function:{ name, arguments } }] }
+ *       result    → { role: 'tool', tool_call_id, content: stringify }
+ *   - ADK: materialized via Session.appendEvent inside the adk adapter
+ *     (functionCall + functionResponse events) — NOT via this module.
+ *
+ * `materializePrefill` turns a `Prefill` into the ordered list of wire
+ * messages to splice into the request BEFORE the continuation: for each
+ * recorded tool use, an assistant(tool_call) + tool(result) pair, then
+ * a trailing assistant message carrying the partial text the prior
+ * model streamed. The target model continues from that trailing
+ * assistant message (verified empirically — Anthropic + OpenAI-compat
+ * both honor a trailing assistant message as a continuation prefix).
+ */
+import { isAnthropic } from './strip.js';
+function stringifyContent(content) {
+    return typeof content === 'string' ? content : JSON.stringify(content ?? null);
+}
+/** Convert a `NeutralToolResult` to the target provider's result message. */
+export function translateToolResult(result, target) {
+    // Defensive guard (review finding): an empty tool_use_id / tool_call_id
+    // makes the upstream reject with "tool_use_id does not reference a known
+    // tool_use". The ADK path can produce `id ?? ''`; fail loud here rather
+    // than ship a malformed request.
+    if (!result.toolUseId) {
+        throw new Error('translateToolResult: NeutralToolResult.toolUseId is empty — cannot bind tool result to a tool_use');
+    }
+    if (isAnthropic(target)) {
+        return {
+            message: {
+                role: 'user',
+                content: [{
+                        type: 'tool_result',
+                        tool_use_id: result.toolUseId,
+                        content: stringifyContent(result.content),
+                        is_error: !result.ok,
+                    }],
+            },
+        };
+    }
+    // OpenAI-compatible default.
+    return {
+        message: {
+            role: 'tool',
+            tool_call_id: result.toolUseId,
+            content: stringifyContent(result.content),
+        },
+    };
+}
+/** The assistant message that re-presents a recorded tool_use to the
+ *  target so the following tool-result message is well-formed. */
+function translateToolUseAssistant(use, target) {
+    if (isAnthropic(target)) {
+        return {
+            role: 'assistant',
+            content: [{ type: 'tool_use', id: use.id, name: use.name, input: use.input ?? {} }],
+        };
+    }
+    return {
+        // Empty string, not null: an assistant message that only carries a
+        // tool_call has no text preamble. While most OpenAI-compat upstreams
+        // accept `content: null` here, `''` is universally valid and removes
+        // any ambiguity across the openai/openrouter/opencode/ollama set.
+        role: 'assistant',
+        content: '',
+        tool_calls: [{
+                id: use.id,
+                type: 'function',
+                function: { name: use.name, arguments: JSON.stringify(use.input ?? {}) },
+            }],
+    };
+}
+/**
+ * Build the ordered wire messages that re-present a `Prefill` to the
+ * target provider. The caller splices these onto the end of its
+ * `messages[]` (after system + user), then lets the model continue.
+ *
+ * Ordering: each recorded tool use becomes an assistant(tool_call) +
+ * result pair, in recorded order; finally a trailing assistant message
+ * carrying the partial text (only when non-empty — an empty trailing
+ * assistant message is rejected by some providers).
+ */
+export function materializePrefill(prefill, target) {
+    const out = [];
+    for (const use of prefill.toolUses) {
+        out.push(translateToolUseAssistant({ id: use.id, name: use.name, input: use.input }, target));
+        out.push(translateToolResult(use.result, target).message);
+    }
+    if (prefill.text.length > 0) {
+        out.push({ role: 'assistant', content: prefill.text });
+    }
+    return out;
+}
+/**
+ * One COMPLETED prior turn as a single assistant message (text + tool_calls
+ * combined) followed by its tool-result messages. UNLIKE `materializePrefill`
+ * — which keeps the partial text as a separate TRAILING assistant message so
+ * the live model continues from it — a completed turn's text and tool calls
+ * belong to one wire message. Emitting them split would put a phase's
+ * tool-loop turns back-to-back as consecutive assistant messages (no
+ * intervening tool/user), which OpenAI-compat upstreams reject or silently
+ * merge. The combined shape reproduces the exact tool-loop wire sequence:
+ * assistant(text,tool_calls) → tool(result)* → (next turn).
+ */
+function combinedAssistantMessage(text, toolUses, target) {
+    if (isAnthropic(target)) {
+        const content = [];
+        if (text.length > 0)
+            content.push({ type: 'text', text });
+        for (const u of toolUses) {
+            content.push({ type: 'tool_use', id: u.id, name: u.name, input: u.input ?? {} });
+        }
+        return { role: 'assistant', content };
+    }
+    // OpenAI-compat: text + tool_calls live on ONE assistant message.
+    const msg = { role: 'assistant', content: text };
+    if (toolUses.length > 0) {
+        msg.tool_calls = toolUses.map((u) => ({
+            id: u.id,
+            type: 'function',
+            function: { name: u.name, arguments: JSON.stringify(u.input ?? {}) },
+        }));
+    }
+    return msg;
+}
+/**
+ * §Tier 2 — materialize a list of COMPLETED prior turns into the target
+ * provider's wire format, spliced BEFORE the new user message so a stateful
+ * (non-claude) session resume re-presents the full conversation. Each turn
+ * emits, in order: its opening user message (when `userPrompt` is set — the
+ * first turn of a phase), then one combined assistant(text+tool_calls), then
+ * its tool results. Empty list → [] (START phase / no prior turns).
+ */
+export function materializePriorTurns(turns, target) {
+    const out = [];
+    for (const turn of turns) {
+        if (typeof turn.userPrompt === 'string' && turn.userPrompt.length > 0) {
+            out.push({ role: 'user', content: turn.userPrompt });
+        }
+        // A completed turn always carries text and/or tools; guard the empty case.
+        if (turn.text.length > 0 || turn.toolUses.length > 0) {
+            out.push(combinedAssistantMessage(turn.text, turn.toolUses, target));
+        }
+        for (const use of turn.toolUses) {
+            out.push(translateToolResult(use.result, target).message);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=translate.js.map

package/dist/prefill/translate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.js","sourceRoot":"","sources":["../../src/prefill/translate.ts"],"names":[],"mappings":"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"}

package/dist/prefill/truncate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * §2.3.3 context-window truncation policy.
+ *
+ * `prefill.text` (the partial assistant continuation) plus the recorded
+ * tool history may push the resuming request over the TARGET model's
+ * input window even though it fit on the source model. Before the chain
+ * walker hands a prefill to the next attempt, it runs this gate:
+ *
+ *   budget = target.maxInputTokens − margin(8K) − baseTokens
+ *            − sourceTokens − sum(toolUseTokens)
+ *
+ *   1. If the partial text alone won't fit (budget-before-tools < 0),
+ *      the prefill CANNOT be served → return undefined. The walker then
+ *      retries the next model WITHOUT a prefill (a clean re-run beats a
+ *      failed run, per §2.3.3 step 3).
+ *   2. Otherwise drop the OLDEST tool_use/result pairs (from the start)
+ *      until the tool history fits, preserving the most-recent tools and
+ *      the trailing partial text. Those dropped tools already executed on
+ *      the source model; the resuming model simply won't see them in its
+ *      re-presented history.
+ *
+ * `maxInputTokens` comes from `cost.ts`'s model-prices table; a model
+ * missing from the table conservatively assumes 32K (§2.3.3 step 4).
+ *
+ * Token counts are estimates (default ~chars/4) — exact tokenization is
+ * deferred (§ ADR open question). The 8K margin absorbs the slack; if the
+ * estimate is too aggressive the walker just drops an extra tool pair,
+ * which is a slower chain walk, not a correctness loss.
+ */
+import type { Prefill } from '../turn-recorder/types.js';
+/** Conservative floor when the model is absent from the price table. */
+export declare const DEFAULT_MAX_INPUT_TOKENS = 32000;
+/** Headroom reserved below the model's max input window. */
+export declare const DEFAULT_MARGIN_TOKENS = 8000;
+export interface TruncatePrefillArgs {
+    prefill: Prefill;
+    /** Model id the prefill is about to be served to. */
+    targetModel: string;
+    /**
+     * Tokens already committed to the request before the prefill is
+     * spliced (system prompt + the user turn). Best-effort; default 0.
+     * Counted against the budget so a large system prompt + big prefill
+     * don't silently blow the window.
+     */
+    baseTokens?: number;
+    /** Headroom under the model's max input window. Default 8000. */
+    marginTokens?: number;
+    /** Estimator over an arbitrary string. Default ≈ chars/4. */
+    estimateTokens?: (text: string) => number;
+    /**
+     * Override the target's max-input-token lookup (tests / models the
+     * cost table can't price). Default reads `cost.ts`.
+     */
+    maxInputTokensFor?: (model: string) => number | undefined;
+}
+/**
+ * Returns the (possibly tool-trimmed) prefill that fits the target
+ * model's input budget, or `undefined` when even the bare partial text
+ * won't fit — signalling the walker to retry without a prefill.
+ */
+export declare function truncatePrefillForBudget(args: TruncatePrefillArgs): Prefill | undefined;
+//# sourceMappingURL=truncate.d.ts.map

package/dist/prefill/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../src/prefill/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEzD,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3D;AAeD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,GAAG,SAAS,CAiCvF"}

package/dist/prefill/truncate.js

@@ -0,0 +1,77 @@
+/**
+ * §2.3.3 context-window truncation policy.
+ *
+ * `prefill.text` (the partial assistant continuation) plus the recorded
+ * tool history may push the resuming request over the TARGET model's
+ * input window even though it fit on the source model. Before the chain
+ * walker hands a prefill to the next attempt, it runs this gate:
+ *
+ *   budget = target.maxInputTokens − margin(8K) − baseTokens
+ *            − sourceTokens − sum(toolUseTokens)
+ *
+ *   1. If the partial text alone won't fit (budget-before-tools < 0),
+ *      the prefill CANNOT be served → return undefined. The walker then
+ *      retries the next model WITHOUT a prefill (a clean re-run beats a
+ *      failed run, per §2.3.3 step 3).
+ *   2. Otherwise drop the OLDEST tool_use/result pairs (from the start)
+ *      until the tool history fits, preserving the most-recent tools and
+ *      the trailing partial text. Those dropped tools already executed on
+ *      the source model; the resuming model simply won't see them in its
+ *      re-presented history.
+ *
+ * `maxInputTokens` comes from `cost.ts`'s model-prices table; a model
+ * missing from the table conservatively assumes 32K (§2.3.3 step 4).
+ *
+ * Token counts are estimates (default ~chars/4) — exact tokenization is
+ * deferred (§ ADR open question). The 8K margin absorbs the slack; if the
+ * estimate is too aggressive the walker just drops an extra tool pair,
+ * which is a slower chain walk, not a correctness loss.
+ */
+import { getDetailedPricing } from '../cost.js';
+/** Conservative floor when the model is absent from the price table. */
+export const DEFAULT_MAX_INPUT_TOKENS = 32_000;
+/** Headroom reserved below the model's max input window. */
+export const DEFAULT_MARGIN_TOKENS = 8_000;
+const defaultEstimate = (text) => Math.ceil(text.length / 4);
+/** Rough token cost of re-presenting one recorded tool_use/result pair. */
+function toolUseTokens(tu, estimate) {
+    const content = typeof tu.result?.content === 'string'
+        ? tu.result.content
+        : JSON.stringify(tu.result?.content ?? '');
+    return estimate(`${tu.name}${JSON.stringify(tu.input ?? {})}${content}`);
+}
+/**
+ * Returns the (possibly tool-trimmed) prefill that fits the target
+ * model's input budget, or `undefined` when even the bare partial text
+ * won't fit — signalling the walker to retry without a prefill.
+ */
+export function truncatePrefillForBudget(args) {
+    const estimate = args.estimateTokens ?? defaultEstimate;
+    const margin = args.marginTokens ?? DEFAULT_MARGIN_TOKENS;
+    const baseTokens = args.baseTokens ?? 0;
+    const maxInput = (args.maxInputTokensFor
+        ? args.maxInputTokensFor(args.targetModel)
+        : getDetailedPricing(args.targetModel)?.maxInputTokens)
+        ?? DEFAULT_MAX_INPUT_TOKENS;
+    // Budget remaining for the tool history AFTER the fixed costs (system +
+    // user + margin + the partial-text reinjection). If this is already
+    // negative the partial alone overflows the window → cannot serve.
+    const budgetForTools = maxInput - margin - baseTokens - args.prefill.sourceTokens;
+    if (budgetForTools < 0)
+        return undefined;
+    // Per-tool token estimates, oldest-first (prefill.toolUses preserves
+    // recording order). Drop from the FRONT until the sum fits.
+    const tools = args.prefill.toolUses.slice();
+    let toolSum = tools.reduce((acc, tu) => acc + toolUseTokens(tu, estimate), 0);
+    if (toolSum <= budgetForTools) {
+        return args.prefill; // fits as-is
+    }
+    while (tools.length > 0 && toolSum > budgetForTools) {
+        const dropped = tools.shift();
+        toolSum -= toolUseTokens(dropped, estimate);
+    }
+    // budgetForTools >= 0 guarantees the empty-tools case fits; return the
+    // trimmed prefill (which may have zero tools but always keeps the text).
+    return { ...args.prefill, toolUses: tools };
+}
+//# sourceMappingURL=truncate.js.map

package/dist/prefill/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/prefill/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,wEAAwE;AACxE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAC/C,4DAA4D;AAC5D,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAwB3C,MAAM,eAAe,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAE7E,2EAA2E;AAC3E,SAAS,aAAa,CACpB,EAA+B,EAC/B,QAA+B;IAE/B,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ;QACpD,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO;QACnB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IAC7C,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAyB;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,eAAe,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IAExC,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,iBAAiB;QACtC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1C,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;WACpD,wBAAwB,CAAC;IAE9B,wEAAwE;IACxE,oEAAoE;IACpE,kEAAkE;IAClE,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;IAClF,IAAI,cAAc,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,qEAAqE;IACrE,4DAA4D;IAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC5C,IAAI,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAE9E,IAAI,OAAO,IAAI,cAAc,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,aAAa;IACpC,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,GAAG,cAAc,EAAE,CAAC;QACpD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC/B,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,uEAAuE;IACvE,yEAAyE;IACzE,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC"}

package/dist/router/errors.d.ts

@@ -19,18 +19,35 @@ export declare class RouterError extends Error {
     });
 }
 /**
- * Map a raw error to an `ErrorClass`.
+ * Map a raw error to an `ErrorClass`. This is the single source of truth for
+ * error classification across the whole stack — `LlmRouter.invoke` (single
+ * shot), `LlmRouter.invokeStream` (streaming), and `LlmRouter.runAgent`
+ * (agentic chain walk) all route through here.
  *
  * Recognizes:
- *   - 429 → rate_limit
- *   - 5xx → server_5xx
- *   - 401/403 → auth
- *   - 400 + content/safety hints → content_policy
- *   - 400 → invalid_request
- *   - timeout/abort/etimedout/econnreset/socket-hang-up → timeout
+ *   - network (status 0 / fetch failed / ECONNRESET / EPIPE / abort / timeout) → timeout
+ *   - 429 → rate_limit; 5xx → server_5xx; 401/403 → auth
+ *   - 400 + content/safety hints → content_policy; other 400 → invalid_request
+ *   - body: phantom-model / hard-billing → model_unavailable
+ *   - body: quota / rate-limit / overloaded / resource-exhausted → rate_limit
+ *   - body: auth/permission → auth
+ *   - explicit `.retryable === true` with no better signal → timeout (fall-back eligible)
  *   - otherwise → unknown
  */
 export declare function classifyError(err: unknown): ErrorClass;
+/**
+ * Terminal classes never trigger cross-model fallback (a different model from
+ * the same wall won't help) and never count toward the circuit breaker.
+ */
+export declare function isTerminalErrorClass(cls: ErrorClass): boolean;
+/**
+ * Fall-back-eligible classes: a transient/provider-side failure where trying a
+ * DIFFERENT model in the chain is the right move. This is the unified
+ * replacement for the former binary `isRetryableUpstreamError` duck-type. Note
+ * `unknown` is intentionally excluded — a generic error is more likely a bug
+ * than a provider fault, so it should surface rather than burn the chain.
+ */
+export declare function isFallbackEligibleErrorClass(cls: ErrorClass): boolean;
 /**
  * Parse a `Retry-After` header value (seconds-since-now or HTTP-date)
  * into a millisecond delay. Returns `null` if absent or unparseable.

package/dist/router/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/router/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;gBAGrB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAOjE;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAkDtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,CAY7F"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/router/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;gBAGrB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAOjE;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAqEtD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAKrE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,CAY7F"}