apex-code 0.0.1-alpha.0 → 0.0.1-alpha.2

package/dist/core/context/eviction.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Tool-result eviction — Phase 3 task 3.1.
+ *
+ * Implements the eviction algorithm settled in `docs/architecture/contracts.md` § 2
+ * ("Context pipeline order — settled"): a pure, prefix-oldest, contiguous-run
+ * transform over the message list. It runs *before* compaction in the pipeline
+ * order (deferred-schema resolution → eviction → compaction), but this module knows
+ * nothing about that ordering or about `transformContext` — wiring is task 3.3.
+ *
+ * Pure by construction: no clock, no randomness, no I/O, no reads of the live tool
+ * registry. Every fact this function needs about a tool comes through the injected
+ * `contractLookup`, and every fact about "how big is this" comes from the message
+ * content already in hand.
+ */
+import type { AgentMessage } from "apex-code-agent-core";
+import type { ToolContract } from "../tools/contract.ts";
+/**
+ * What `evictToolResults` needs to know about a tool's contract to decide whether
+ * (and how) to evict one of its results. Only the `context` axis of `ToolContract`
+ * matters here — callers may pass a full contract, or (as tests do) a hand-built
+ * stand-in with just `context` filled in.
+ */
+export type ContractLookup = (toolName: string) => Pick<ToolContract, "context"> | undefined;
+/** Marker substituted for an evicted result when its contract declares none. */
+export declare const DEFAULT_EVICTION_MARKER = "[Tool result evicted to save context. Re-run the tool to see it again.]";
+/**
+ * Replace the oldest contiguous run of recoverable tool results with markers, until
+ * the estimated total token cost of *all* tool-result messages in the list drops to
+ * or below `budget` (chars/4, the same heuristic `estimateTokens` uses elsewhere in
+ * this codebase — see `core/compaction/compaction.ts`). "Contiguous run from the
+ * oldest end" is enforced by walking messages in order and stopping the walk for
+ * good — not just skipping — the moment a tool result is encountered whose contract
+ * says it is not recoverable (or has no contract at all, matching the `UNCLASSIFIED`
+ * default of `resultRecoverable: false`): later eligible results are never reached,
+ * so no hole ever opens in the middle of the transcript. Non-tool-result messages
+ * (assistant/user turns) are passed through untouched and do not interrupt or count
+ * toward the walk.
+ *
+ * Deterministic and idempotent: a message whose content already exactly equals its
+ * tool's marker is recognized as already evicted and left alone, so re-running this
+ * function over its own output (or over a budget that is already satisfied) is a
+ * no-op. Never mutates `messages` or any message object — always returns a new
+ * array; unevicted messages keep their original object identity (unmutated sharing
+ * is not mutation), evicted ones are new objects with only `content` replaced.
+ */
+export declare function evictToolResults(messages: readonly AgentMessage[], contractLookup: ContractLookup, budget: number): AgentMessage[];
+//# sourceMappingURL=eviction.d.ts.map

package/dist/core/context/eviction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eviction.d.ts","sourceRoot":"","sources":["../../../src/core/context/eviction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;AAE7F,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,4EAA4E,CAAC;AAiBjH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,MAAM,GACZ,YAAY,EAAE,CAsChB","sourcesContent":["/**\n * Tool-result eviction — Phase 3 task 3.1.\n *\n * Implements the eviction algorithm settled in `docs/architecture/contracts.md` § 2\n * (\"Context pipeline order — settled\"): a pure, prefix-oldest, contiguous-run\n * transform over the message list. It runs *before* compaction in the pipeline\n * order (deferred-schema resolution → eviction → compaction), but this module knows\n * nothing about that ordering or about `transformContext` — wiring is task 3.3.\n *\n * Pure by construction: no clock, no randomness, no I/O, no reads of the live tool\n * registry. Every fact this function needs about a tool comes through the injected\n * `contractLookup`, and every fact about \"how big is this\" comes from the message\n * content already in hand.\n */\n\nimport type { TextContent } from \"@earendil-works/pi-ai\";\nimport type { AgentMessage } from \"apex-code-agent-core\";\nimport { estimateTokens } from \"../compaction/compaction.ts\";\nimport type { ToolContract } from \"../tools/contract.ts\";\n\n/**\n * What `evictToolResults` needs to know about a tool's contract to decide whether\n * (and how) to evict one of its results. Only the `context` axis of `ToolContract`\n * matters here — callers may pass a full contract, or (as tests do) a hand-built\n * stand-in with just `context` filled in.\n */\nexport type ContractLookup = (toolName: string) => Pick<ToolContract, \"context\"> | undefined;\n\n/** Marker substituted for an evicted result when its contract declares none. */\nexport const DEFAULT_EVICTION_MARKER = \"[Tool result evicted to save context. Re-run the tool to see it again.]\";\n\nfunction isToolResultMessage(message: AgentMessage): message is Extract<AgentMessage, { role: \"toolResult\" }> {\n\treturn message.role === \"toolResult\";\n}\n\n/** True when `content` is already exactly the single-text-block marker form. */\nfunction isAlreadyEvicted(content: readonly unknown[], marker: string): boolean {\n\treturn (\n\t\tcontent.length === 1 &&\n\t\ttypeof content[0] === \"object\" &&\n\t\tcontent[0] !== null &&\n\t\t(content[0] as { type?: unknown }).type === \"text\" &&\n\t\t(content[0] as { text?: unknown }).text === marker\n\t);\n}\n\n/**\n * Replace the oldest contiguous run of recoverable tool results with markers, until\n * the estimated total token cost of *all* tool-result messages in the list drops to\n * or below `budget` (chars/4, the same heuristic `estimateTokens` uses elsewhere in\n * this codebase — see `core/compaction/compaction.ts`). \"Contiguous run from the\n * oldest end\" is enforced by walking messages in order and stopping the walk for\n * good — not just skipping — the moment a tool result is encountered whose contract\n * says it is not recoverable (or has no contract at all, matching the `UNCLASSIFIED`\n * default of `resultRecoverable: false`): later eligible results are never reached,\n * so no hole ever opens in the middle of the transcript. Non-tool-result messages\n * (assistant/user turns) are passed through untouched and do not interrupt or count\n * toward the walk.\n *\n * Deterministic and idempotent: a message whose content already exactly equals its\n * tool's marker is recognized as already evicted and left alone, so re-running this\n * function over its own output (or over a budget that is already satisfied) is a\n * no-op. Never mutates `messages` or any message object — always returns a new\n * array; unevicted messages keep their original object identity (unmutated sharing\n * is not mutation), evicted ones are new objects with only `content` replaced.\n */\nexport function evictToolResults(\n\tmessages: readonly AgentMessage[],\n\tcontractLookup: ContractLookup,\n\tbudget: number,\n): AgentMessage[] {\n\tlet remaining = 0;\n\tfor (const message of messages) {\n\t\tif (isToolResultMessage(message)) remaining += estimateTokens(message);\n\t}\n\n\tconst result: AgentMessage[] = [];\n\tlet stopped = false;\n\n\tfor (const message of messages) {\n\t\tif (stopped || !isToolResultMessage(message) || remaining <= budget) {\n\t\t\tresult.push(message);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst contract = contractLookup(message.toolName);\n\t\tconst recoverable = contract?.context.resultRecoverable === true;\n\t\tif (!recoverable) {\n\t\t\tstopped = true;\n\t\t\tresult.push(message);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst marker = contract.context.evictionMarker ?? DEFAULT_EVICTION_MARKER;\n\t\tif (isAlreadyEvicted(message.content, marker)) {\n\t\t\tresult.push(message);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst before = estimateTokens(message);\n\t\tconst markerContent: TextContent[] = [{ type: \"text\", text: marker }];\n\t\tconst evicted = { ...message, content: markerContent };\n\t\tconst after = estimateTokens(evicted);\n\t\tremaining = remaining - before + after;\n\t\tresult.push(evicted);\n\t}\n\n\treturn result;\n}\n"]}

package/dist/core/context/eviction.js

@@ -0,0 +1,83 @@
+/**
+ * Tool-result eviction — Phase 3 task 3.1.
+ *
+ * Implements the eviction algorithm settled in `docs/architecture/contracts.md` § 2
+ * ("Context pipeline order — settled"): a pure, prefix-oldest, contiguous-run
+ * transform over the message list. It runs *before* compaction in the pipeline
+ * order (deferred-schema resolution → eviction → compaction), but this module knows
+ * nothing about that ordering or about `transformContext` — wiring is task 3.3.
+ *
+ * Pure by construction: no clock, no randomness, no I/O, no reads of the live tool
+ * registry. Every fact this function needs about a tool comes through the injected
+ * `contractLookup`, and every fact about "how big is this" comes from the message
+ * content already in hand.
+ */
+import { estimateTokens } from "../compaction/compaction.js";
+/** Marker substituted for an evicted result when its contract declares none. */
+export const DEFAULT_EVICTION_MARKER = "[Tool result evicted to save context. Re-run the tool to see it again.]";
+function isToolResultMessage(message) {
+    return message.role === "toolResult";
+}
+/** True when `content` is already exactly the single-text-block marker form. */
+function isAlreadyEvicted(content, marker) {
+    return (content.length === 1 &&
+        typeof content[0] === "object" &&
+        content[0] !== null &&
+        content[0].type === "text" &&
+        content[0].text === marker);
+}
+/**
+ * Replace the oldest contiguous run of recoverable tool results with markers, until
+ * the estimated total token cost of *all* tool-result messages in the list drops to
+ * or below `budget` (chars/4, the same heuristic `estimateTokens` uses elsewhere in
+ * this codebase — see `core/compaction/compaction.ts`). "Contiguous run from the
+ * oldest end" is enforced by walking messages in order and stopping the walk for
+ * good — not just skipping — the moment a tool result is encountered whose contract
+ * says it is not recoverable (or has no contract at all, matching the `UNCLASSIFIED`
+ * default of `resultRecoverable: false`): later eligible results are never reached,
+ * so no hole ever opens in the middle of the transcript. Non-tool-result messages
+ * (assistant/user turns) are passed through untouched and do not interrupt or count
+ * toward the walk.
+ *
+ * Deterministic and idempotent: a message whose content already exactly equals its
+ * tool's marker is recognized as already evicted and left alone, so re-running this
+ * function over its own output (or over a budget that is already satisfied) is a
+ * no-op. Never mutates `messages` or any message object — always returns a new
+ * array; unevicted messages keep their original object identity (unmutated sharing
+ * is not mutation), evicted ones are new objects with only `content` replaced.
+ */
+export function evictToolResults(messages, contractLookup, budget) {
+    let remaining = 0;
+    for (const message of messages) {
+        if (isToolResultMessage(message))
+            remaining += estimateTokens(message);
+    }
+    const result = [];
+    let stopped = false;
+    for (const message of messages) {
+        if (stopped || !isToolResultMessage(message) || remaining <= budget) {
+            result.push(message);
+            continue;
+        }
+        const contract = contractLookup(message.toolName);
+        const recoverable = contract?.context.resultRecoverable === true;
+        if (!recoverable) {
+            stopped = true;
+            result.push(message);
+            continue;
+        }
+        const marker = contract.context.evictionMarker ?? DEFAULT_EVICTION_MARKER;
+        if (isAlreadyEvicted(message.content, marker)) {
+            result.push(message);
+            continue;
+        }
+        const before = estimateTokens(message);
+        const markerContent = [{ type: "text", text: marker }];
+        const evicted = { ...message, content: markerContent };
+        const after = estimateTokens(evicted);
+        remaining = remaining - before + after;
+        result.push(evicted);
+    }
+    return result;
+}
+//# sourceMappingURL=eviction.js.map

package/dist/core/context/eviction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eviction.js","sourceRoot":"","sources":["../../../src/core/context/eviction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAW7D,gFAAgF;AAChF,MAAM,CAAC,MAAM,uBAAuB,GAAG,yEAAyE,CAAC;AAEjH,SAAS,mBAAmB,CAAC,OAAqB,EAA4D;IAC7G,OAAO,OAAO,CAAC,IAAI,KAAK,YAAY,CAAC;AAAA,CACrC;AAED,gFAAgF;AAChF,SAAS,gBAAgB,CAAC,OAA2B,EAAE,MAAc,EAAW;IAC/E,OAAO,CACN,OAAO,CAAC,MAAM,KAAK,CAAC;QACpB,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI;QAClB,OAAO,CAAC,CAAC,CAAwB,CAAC,IAAI,KAAK,MAAM;QACjD,OAAO,CAAC,CAAC,CAAwB,CAAC,IAAI,KAAK,MAAM,CAClD,CAAC;AAAA,CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,QAAiC,EACjC,cAA8B,EAC9B,MAAc,EACG;IACjB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAChC,IAAI,mBAAmB,CAAC,OAAO,CAAC;YAAE,SAAS,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAChC,IAAI,OAAO,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;YACrE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,SAAS;QACV,CAAC;QAED,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,WAAW,GAAG,QAAQ,EAAE,OAAO,CAAC,iBAAiB,KAAK,IAAI,CAAC;QACjE,IAAI,CAAC,WAAW,EAAE,CAAC;YAClB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,SAAS;QACV,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,IAAI,uBAAuB,CAAC;QAC1E,IAAI,gBAAgB,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,SAAS;QACV,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,aAAa,GAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACtE,MAAM,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACtC,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["/**\n * Tool-result eviction — Phase 3 task 3.1.\n *\n * Implements the eviction algorithm settled in `docs/architecture/contracts.md` § 2\n * (\"Context pipeline order — settled\"): a pure, prefix-oldest, contiguous-run\n * transform over the message list. It runs *before* compaction in the pipeline\n * order (deferred-schema resolution → eviction → compaction), but this module knows\n * nothing about that ordering or about `transformContext` — wiring is task 3.3.\n *\n * Pure by construction: no clock, no randomness, no I/O, no reads of the live tool\n * registry. Every fact this function needs about a tool comes through the injected\n * `contractLookup`, and every fact about \"how big is this\" comes from the message\n * content already in hand.\n */\n\nimport type { TextContent } from \"@earendil-works/pi-ai\";\nimport type { AgentMessage } from \"apex-code-agent-core\";\nimport { estimateTokens } from \"../compaction/compaction.ts\";\nimport type { ToolContract } from \"../tools/contract.ts\";\n\n/**\n * What `evictToolResults` needs to know about a tool's contract to decide whether\n * (and how) to evict one of its results. Only the `context` axis of `ToolContract`\n * matters here — callers may pass a full contract, or (as tests do) a hand-built\n * stand-in with just `context` filled in.\n */\nexport type ContractLookup = (toolName: string) => Pick<ToolContract, \"context\"> | undefined;\n\n/** Marker substituted for an evicted result when its contract declares none. */\nexport const DEFAULT_EVICTION_MARKER = \"[Tool result evicted to save context. Re-run the tool to see it again.]\";\n\nfunction isToolResultMessage(message: AgentMessage): message is Extract<AgentMessage, { role: \"toolResult\" }> {\n\treturn message.role === \"toolResult\";\n}\n\n/** True when `content` is already exactly the single-text-block marker form. */\nfunction isAlreadyEvicted(content: readonly unknown[], marker: string): boolean {\n\treturn (\n\t\tcontent.length === 1 &&\n\t\ttypeof content[0] === \"object\" &&\n\t\tcontent[0] !== null &&\n\t\t(content[0] as { type?: unknown }).type === \"text\" &&\n\t\t(content[0] as { text?: unknown }).text === marker\n\t);\n}\n\n/**\n * Replace the oldest contiguous run of recoverable tool results with markers, until\n * the estimated total token cost of *all* tool-result messages in the list drops to\n * or below `budget` (chars/4, the same heuristic `estimateTokens` uses elsewhere in\n * this codebase — see `core/compaction/compaction.ts`). \"Contiguous run from the\n * oldest end\" is enforced by walking messages in order and stopping the walk for\n * good — not just skipping — the moment a tool result is encountered whose contract\n * says it is not recoverable (or has no contract at all, matching the `UNCLASSIFIED`\n * default of `resultRecoverable: false`): later eligible results are never reached,\n * so no hole ever opens in the middle of the transcript. Non-tool-result messages\n * (assistant/user turns) are passed through untouched and do not interrupt or count\n * toward the walk.\n *\n * Deterministic and idempotent: a message whose content already exactly equals its\n * tool's marker is recognized as already evicted and left alone, so re-running this\n * function over its own output (or over a budget that is already satisfied) is a\n * no-op. Never mutates `messages` or any message object — always returns a new\n * array; unevicted messages keep their original object identity (unmutated sharing\n * is not mutation), evicted ones are new objects with only `content` replaced.\n */\nexport function evictToolResults(\n\tmessages: readonly AgentMessage[],\n\tcontractLookup: ContractLookup,\n\tbudget: number,\n): AgentMessage[] {\n\tlet remaining = 0;\n\tfor (const message of messages) {\n\t\tif (isToolResultMessage(message)) remaining += estimateTokens(message);\n\t}\n\n\tconst result: AgentMessage[] = [];\n\tlet stopped = false;\n\n\tfor (const message of messages) {\n\t\tif (stopped || !isToolResultMessage(message) || remaining <= budget) {\n\t\t\tresult.push(message);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst contract = contractLookup(message.toolName);\n\t\tconst recoverable = contract?.context.resultRecoverable === true;\n\t\tif (!recoverable) {\n\t\t\tstopped = true;\n\t\t\tresult.push(message);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst marker = contract.context.evictionMarker ?? DEFAULT_EVICTION_MARKER;\n\t\tif (isAlreadyEvicted(message.content, marker)) {\n\t\t\tresult.push(message);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst before = estimateTokens(message);\n\t\tconst markerContent: TextContent[] = [{ type: \"text\", text: marker }];\n\t\tconst evicted = { ...message, content: markerContent };\n\t\tconst after = estimateTokens(evicted);\n\t\tremaining = remaining - before + after;\n\t\tresult.push(evicted);\n\t}\n\n\treturn result;\n}\n"]}

package/dist/core/context/pipeline.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Context pipeline wiring — shared by `AgentSession` (production) and the offline
+ * replay harness (`src/testing/replay/runner.ts`), so there is exactly one
+ * implementation of "how deferred-schema resolution and eviction attach to an
+ * `Agent`" rather than two independently maintained copies.
+ *
+ * Implements the ordering settled in `docs/architecture/contracts.md` § 2:
+ * deferred-schema resolution → tool-result eviction → compaction. Compaction runs
+ * reactively from its own existing seam (`_checkCompaction` in `agent-session.ts`)
+ * and is untouched here; this module only adds the two stages that run *ahead of*
+ * every LLM request, so that reactive check is reached less often because the
+ * request it is reacting to is smaller.
+ *
+ * The two stages land in different seams because they operate on different halves
+ * of the outbound request. Eviction is a pure function of `AgentMessage[]`, which is
+ * exactly what `transformContext` sees, immediately before `convertToLlm` — so it is
+ * wired there. Deferred-schema resolution operates on the *tool list*, not messages;
+ * `transformContext`'s signature has no tools parameter, and `AgentContext.tools` is
+ * a snapshot taken once per prompt rather than rebuilt per request. The seam that
+ * actually sees the assembled outbound tool list on every request is
+ * `streamFunction` — it receives the full `Context`, tools included, immediately
+ * before the provider call — so the projection is applied there instead. Because the
+ * two stages act on disjoint fields of the request with no data dependency between
+ * them, this does not change the observable pipeline order.
+ */
+import type { Agent, StreamFn } from "apex-code-agent-core";
+import { type ContractLookup } from "./eviction.ts";
+/**
+ * Eviction-budget formula shared by every caller of `installContextPipeline`.
+ * Compaction fires once total context tokens exceed `contextWindow - reserveTokens`
+ * (`shouldCompact` in `core/compaction/compaction.ts`). Budgeting eviction — counted
+ * purely against tool-result tokens, per `evictToolResults`'s own contract — at half
+ * of that headroom leaves the other half free for system prompt and conversational
+ * growth, so eviction (cheap, structure-preserving) gets a chance to shrink the
+ * transcript before the expensive compaction stage is ever reached, matching
+ * contracts.md § 2's "why this order" (eviction before compaction, so compaction is
+ * reached later and less often).
+ *
+ * `Math.max(0, ...)` mirrors `shouldCompact`'s own behavior when `contextWindow` is
+ * unknown (0): evict aggressively rather than not at all, rather than inventing a
+ * different, unproven fallback.
+ *
+ * Production (`AgentSession`) calls this with the real model's `contextWindow` and
+ * the user's configured `reserveTokens`. The offline replay harness deliberately
+ * does *not* call this with the fixture model's `contextWindow` — see
+ * `REPLAY_EVICTION_BUDGET` in `src/testing/replay/runner.ts` for why a dedicated
+ * constant is used there instead.
+ */
+export declare function evictionBudget(contextWindow: number, reserveTokens: number): number;
+/**
+ * Adapter between a caller's tool registry and `announceToolsByName`, which
+ * operates on a minimal `DeferrableTool` shape that has no notion of a tool
+ * registry. Only `parameters` is ever replaced; every other field of the outbound
+ * tool (name, description, and on `AgentTool` specifically, `execute`, `label`,
+ * etc.) passes through unchanged via the object spread.
+ *
+ * A tool with no entry in `contractLookup` (a foreign/unclassified tool) is treated
+ * as `deferSchema: false` here — the safe default on this axis is to keep
+ * describing it fully, the mirror image of eviction's "no contract => don't evict"
+ * default: when unsure, don't withhold information the model needs.
+ */
+export declare function projectToolSchemas<T extends {
+    name: string;
+    description: string;
+    parameters: unknown;
+}>(tools: readonly T[], contractLookup: ContractLookup, loadedSchemaNames?: ReadonlySet<string>): T[];
+/** Returns true for the built-in streamSimple function, including its context-pipeline wrapper. */
+export declare function isDefaultStreamFunction(streamFunction: StreamFn): boolean;
+export interface ContextPipelineOptions {
+    /** Resolves a tool's contract; shared by both eviction and schema projection. */
+    contractLookup: ContractLookup;
+    /** Names whose real schemas have been loaded by the model in this session. */
+    loadedSchemaNames?: ReadonlySet<string>;
+    /**
+     * Eviction budget as a thunk, not a plain number: `AgentSession`'s budget
+     * depends on `this.model` and `this.settingsManager`, both of which can change
+     * over the session's lifetime (model switch, settings edit), and is never
+     * cached. Evaluating it fresh on every request is what keeps eviction correct
+     * after either changes mid-session.
+     */
+    evictionBudget: () => number;
+}
+/**
+ * Installs the settled context pipeline (deferred-schema resolution → eviction)
+ * onto `agent`, chaining onto whatever `transformContext` / `streamFunction` the
+ * caller already installed rather than replacing it — the same pattern
+ * `AgentSession._installAgentNextTurnRefresh` uses for `prepareNextTurnWithContext`.
+ */
+export declare function installContextPipeline(agent: Agent, options: ContextPipelineOptions): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/core/context/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/core/context/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,eAAe,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,EACtG,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,cAAc,EAAE,cAAc,EAC9B,iBAAiB,GAAE,WAAW,CAAC,MAAM,CAAa,GAChD,CAAC,EAAE,CAcL;AAID,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,QAAQ,GAAG,OAAO,CAEzE;AAED,MAAM,WAAW,sBAAsB;IACtC,iFAAiF;IACjF,cAAc,EAAE,cAAc,CAAC;IAC/B,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,sBAAsB,GAAG,IAAI,CA0B1F","sourcesContent":["/**\n * Context pipeline wiring — shared by `AgentSession` (production) and the offline\n * replay harness (`src/testing/replay/runner.ts`), so there is exactly one\n * implementation of \"how deferred-schema resolution and eviction attach to an\n * `Agent`\" rather than two independently maintained copies.\n *\n * Implements the ordering settled in `docs/architecture/contracts.md` § 2:\n * deferred-schema resolution → tool-result eviction → compaction. Compaction runs\n * reactively from its own existing seam (`_checkCompaction` in `agent-session.ts`)\n * and is untouched here; this module only adds the two stages that run *ahead of*\n * every LLM request, so that reactive check is reached less often because the\n * request it is reacting to is smaller.\n *\n * The two stages land in different seams because they operate on different halves\n * of the outbound request. Eviction is a pure function of `AgentMessage[]`, which is\n * exactly what `transformContext` sees, immediately before `convertToLlm` — so it is\n * wired there. Deferred-schema resolution operates on the *tool list*, not messages;\n * `transformContext`'s signature has no tools parameter, and `AgentContext.tools` is\n * a snapshot taken once per prompt rather than rebuilt per request. The seam that\n * actually sees the assembled outbound tool list on every request is\n * `streamFunction` — it receives the full `Context`, tools included, immediately\n * before the provider call — so the projection is applied there instead. Because the\n * two stages act on disjoint fields of the request with no data dependency between\n * them, this does not change the observable pipeline order.\n */\n\nimport { streamSimple } from \"@earendil-works/pi-ai/compat\";\nimport type { Agent, StreamFn } from \"apex-code-agent-core\";\nimport { resolveToolContext } from \"../tools/contract.ts\";\nimport { announceToolsByName, type DeferrableTool } from \"./deferred-schemas.ts\";\nimport { type ContractLookup, evictToolResults } from \"./eviction.ts\";\n\n/**\n * Eviction-budget formula shared by every caller of `installContextPipeline`.\n * Compaction fires once total context tokens exceed `contextWindow - reserveTokens`\n * (`shouldCompact` in `core/compaction/compaction.ts`). Budgeting eviction — counted\n * purely against tool-result tokens, per `evictToolResults`'s own contract — at half\n * of that headroom leaves the other half free for system prompt and conversational\n * growth, so eviction (cheap, structure-preserving) gets a chance to shrink the\n * transcript before the expensive compaction stage is ever reached, matching\n * contracts.md § 2's \"why this order\" (eviction before compaction, so compaction is\n * reached later and less often).\n *\n * `Math.max(0, ...)` mirrors `shouldCompact`'s own behavior when `contextWindow` is\n * unknown (0): evict aggressively rather than not at all, rather than inventing a\n * different, unproven fallback.\n *\n * Production (`AgentSession`) calls this with the real model's `contextWindow` and\n * the user's configured `reserveTokens`. The offline replay harness deliberately\n * does *not* call this with the fixture model's `contextWindow` — see\n * `REPLAY_EVICTION_BUDGET` in `src/testing/replay/runner.ts` for why a dedicated\n * constant is used there instead.\n */\nexport function evictionBudget(contextWindow: number, reserveTokens: number): number {\n\treturn Math.max(0, Math.floor((contextWindow - reserveTokens) / 2));\n}\n\n/**\n * Adapter between a caller's tool registry and `announceToolsByName`, which\n * operates on a minimal `DeferrableTool` shape that has no notion of a tool\n * registry. Only `parameters` is ever replaced; every other field of the outbound\n * tool (name, description, and on `AgentTool` specifically, `execute`, `label`,\n * etc.) passes through unchanged via the object spread.\n *\n * A tool with no entry in `contractLookup` (a foreign/unclassified tool) is treated\n * as `deferSchema: false` here — the safe default on this axis is to keep\n * describing it fully, the mirror image of eviction's \"no contract => don't evict\"\n * default: when unsure, don't withhold information the model needs.\n */\nexport function projectToolSchemas<T extends { name: string; description: string; parameters: unknown }>(\n\ttools: readonly T[],\n\tcontractLookup: ContractLookup,\n\tloadedSchemaNames: ReadonlySet<string> = new Set(),\n): T[] {\n\tconst deferrable: DeferrableTool[] = tools.map((tool) => ({\n\t\tname: tool.name,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters,\n\t\tcontract: {\n\t\t\tcontext: {\n\t\t\t\tdeferSchema:\n\t\t\t\t\t!loadedSchemaNames.has(tool.name) && resolveToolContext(contractLookup, tool.name).context.deferSchema,\n\t\t\t},\n\t\t},\n\t}));\n\tconst announced = announceToolsByName(deferrable);\n\treturn tools.map((tool, index) => ({ ...tool, parameters: announced[index].parameters }));\n}\n\nconst defaultStreamFunctions = new WeakSet<StreamFn>();\n\n/** Returns true for the built-in streamSimple function, including its context-pipeline wrapper. */\nexport function isDefaultStreamFunction(streamFunction: StreamFn): boolean {\n\treturn streamFunction === streamSimple || defaultStreamFunctions.has(streamFunction);\n}\n\nexport interface ContextPipelineOptions {\n\t/** Resolves a tool's contract; shared by both eviction and schema projection. */\n\tcontractLookup: ContractLookup;\n\t/** Names whose real schemas have been loaded by the model in this session. */\n\tloadedSchemaNames?: ReadonlySet<string>;\n\t/**\n\t * Eviction budget as a thunk, not a plain number: `AgentSession`'s budget\n\t * depends on `this.model` and `this.settingsManager`, both of which can change\n\t * over the session's lifetime (model switch, settings edit), and is never\n\t * cached. Evaluating it fresh on every request is what keeps eviction correct\n\t * after either changes mid-session.\n\t */\n\tevictionBudget: () => number;\n}\n\n/**\n * Installs the settled context pipeline (deferred-schema resolution → eviction)\n * onto `agent`, chaining onto whatever `transformContext` / `streamFunction` the\n * caller already installed rather than replacing it — the same pattern\n * `AgentSession._installAgentNextTurnRefresh` uses for `prepareNextTurnWithContext`.\n */\nexport function installContextPipeline(agent: Agent, options: ContextPipelineOptions): void {\n\tconst { contractLookup, evictionBudget: getBudget, loadedSchemaNames = new Set<string>() } = options;\n\n\tconst previousTransformContext = agent.transformContext;\n\tagent.transformContext = async (messages, signal) => {\n\t\tconst afterPrevious = previousTransformContext ? await previousTransformContext(messages, signal) : messages;\n\t\treturn evictToolResults(afterPrevious, contractLookup, getBudget());\n\t};\n\n\tconst previousStreamFunction = agent.streamFunction;\n\tconst wrappedStreamFunction = (\n\t\tmodel: Parameters<typeof previousStreamFunction>[0],\n\t\tcontext: Parameters<typeof previousStreamFunction>[1],\n\t\tstreamOptions: Parameters<typeof previousStreamFunction>[2],\n\t) => {\n\t\tif (!context.tools || context.tools.length === 0) {\n\t\t\treturn previousStreamFunction(model, context, streamOptions);\n\t\t}\n\t\treturn previousStreamFunction(\n\t\t\tmodel,\n\t\t\t{ ...context, tools: projectToolSchemas(context.tools, contractLookup, loadedSchemaNames) },\n\t\t\tstreamOptions,\n\t\t);\n\t};\n\tif (isDefaultStreamFunction(previousStreamFunction)) defaultStreamFunctions.add(wrappedStreamFunction);\n\tagent.streamFunction = wrappedStreamFunction;\n}\n"]}

package/dist/core/context/pipeline.js

@@ -0,0 +1,109 @@
+/**
+ * Context pipeline wiring — shared by `AgentSession` (production) and the offline
+ * replay harness (`src/testing/replay/runner.ts`), so there is exactly one
+ * implementation of "how deferred-schema resolution and eviction attach to an
+ * `Agent`" rather than two independently maintained copies.
+ *
+ * Implements the ordering settled in `docs/architecture/contracts.md` § 2:
+ * deferred-schema resolution → tool-result eviction → compaction. Compaction runs
+ * reactively from its own existing seam (`_checkCompaction` in `agent-session.ts`)
+ * and is untouched here; this module only adds the two stages that run *ahead of*
+ * every LLM request, so that reactive check is reached less often because the
+ * request it is reacting to is smaller.
+ *
+ * The two stages land in different seams because they operate on different halves
+ * of the outbound request. Eviction is a pure function of `AgentMessage[]`, which is
+ * exactly what `transformContext` sees, immediately before `convertToLlm` — so it is
+ * wired there. Deferred-schema resolution operates on the *tool list*, not messages;
+ * `transformContext`'s signature has no tools parameter, and `AgentContext.tools` is
+ * a snapshot taken once per prompt rather than rebuilt per request. The seam that
+ * actually sees the assembled outbound tool list on every request is
+ * `streamFunction` — it receives the full `Context`, tools included, immediately
+ * before the provider call — so the projection is applied there instead. Because the
+ * two stages act on disjoint fields of the request with no data dependency between
+ * them, this does not change the observable pipeline order.
+ */
+import { streamSimple } from "@earendil-works/pi-ai/compat";
+import { resolveToolContext } from "../tools/contract.js";
+import { announceToolsByName } from "./deferred-schemas.js";
+import { evictToolResults } from "./eviction.js";
+/**
+ * Eviction-budget formula shared by every caller of `installContextPipeline`.
+ * Compaction fires once total context tokens exceed `contextWindow - reserveTokens`
+ * (`shouldCompact` in `core/compaction/compaction.ts`). Budgeting eviction — counted
+ * purely against tool-result tokens, per `evictToolResults`'s own contract — at half
+ * of that headroom leaves the other half free for system prompt and conversational
+ * growth, so eviction (cheap, structure-preserving) gets a chance to shrink the
+ * transcript before the expensive compaction stage is ever reached, matching
+ * contracts.md § 2's "why this order" (eviction before compaction, so compaction is
+ * reached later and less often).
+ *
+ * `Math.max(0, ...)` mirrors `shouldCompact`'s own behavior when `contextWindow` is
+ * unknown (0): evict aggressively rather than not at all, rather than inventing a
+ * different, unproven fallback.
+ *
+ * Production (`AgentSession`) calls this with the real model's `contextWindow` and
+ * the user's configured `reserveTokens`. The offline replay harness deliberately
+ * does *not* call this with the fixture model's `contextWindow` — see
+ * `REPLAY_EVICTION_BUDGET` in `src/testing/replay/runner.ts` for why a dedicated
+ * constant is used there instead.
+ */
+export function evictionBudget(contextWindow, reserveTokens) {
+    return Math.max(0, Math.floor((contextWindow - reserveTokens) / 2));
+}
+/**
+ * Adapter between a caller's tool registry and `announceToolsByName`, which
+ * operates on a minimal `DeferrableTool` shape that has no notion of a tool
+ * registry. Only `parameters` is ever replaced; every other field of the outbound
+ * tool (name, description, and on `AgentTool` specifically, `execute`, `label`,
+ * etc.) passes through unchanged via the object spread.
+ *
+ * A tool with no entry in `contractLookup` (a foreign/unclassified tool) is treated
+ * as `deferSchema: false` here — the safe default on this axis is to keep
+ * describing it fully, the mirror image of eviction's "no contract => don't evict"
+ * default: when unsure, don't withhold information the model needs.
+ */
+export function projectToolSchemas(tools, contractLookup, loadedSchemaNames = new Set()) {
+    const deferrable = tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        contract: {
+            context: {
+                deferSchema: !loadedSchemaNames.has(tool.name) && resolveToolContext(contractLookup, tool.name).context.deferSchema,
+            },
+        },
+    }));
+    const announced = announceToolsByName(deferrable);
+    return tools.map((tool, index) => ({ ...tool, parameters: announced[index].parameters }));
+}
+const defaultStreamFunctions = new WeakSet();
+/** Returns true for the built-in streamSimple function, including its context-pipeline wrapper. */
+export function isDefaultStreamFunction(streamFunction) {
+    return streamFunction === streamSimple || defaultStreamFunctions.has(streamFunction);
+}
+/**
+ * Installs the settled context pipeline (deferred-schema resolution → eviction)
+ * onto `agent`, chaining onto whatever `transformContext` / `streamFunction` the
+ * caller already installed rather than replacing it — the same pattern
+ * `AgentSession._installAgentNextTurnRefresh` uses for `prepareNextTurnWithContext`.
+ */
+export function installContextPipeline(agent, options) {
+    const { contractLookup, evictionBudget: getBudget, loadedSchemaNames = new Set() } = options;
+    const previousTransformContext = agent.transformContext;
+    agent.transformContext = async (messages, signal) => {
+        const afterPrevious = previousTransformContext ? await previousTransformContext(messages, signal) : messages;
+        return evictToolResults(afterPrevious, contractLookup, getBudget());
+    };
+    const previousStreamFunction = agent.streamFunction;
+    const wrappedStreamFunction = (model, context, streamOptions) => {
+        if (!context.tools || context.tools.length === 0) {
+            return previousStreamFunction(model, context, streamOptions);
+        }
+        return previousStreamFunction(model, { ...context, tools: projectToolSchemas(context.tools, contractLookup, loadedSchemaNames) }, streamOptions);
+    };
+    if (isDefaultStreamFunction(previousStreamFunction))
+        defaultStreamFunctions.add(wrappedStreamFunction);
+    agent.streamFunction = wrappedStreamFunction;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/core/context/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../../src/core/context/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAuB,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAuB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAAC,aAAqB,EAAE,aAAqB,EAAU;IACpF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,aAAa,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAAA,CACpE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CACjC,KAAmB,EACnB,cAA8B,EAC9B,iBAAiB,GAAwB,IAAI,GAAG,EAAE,EAC5C;IACN,MAAM,UAAU,GAAqB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzD,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,QAAQ,EAAE;YACT,OAAO,EAAE;gBACR,WAAW,EACV,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,WAAW;aACvG;SACD;KACD,CAAC,CAAC,CAAC;IACJ,MAAM,SAAS,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AAAA,CAC1F;AAED,MAAM,sBAAsB,GAAG,IAAI,OAAO,EAAY,CAAC;AAEvD,mGAAmG;AACnG,MAAM,UAAU,uBAAuB,CAAC,cAAwB,EAAW;IAC1E,OAAO,cAAc,KAAK,YAAY,IAAI,sBAAsB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAAA,CACrF;AAiBD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,OAA+B,EAAQ;IAC3F,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,GAAG,EAAU,EAAE,GAAG,OAAO,CAAC;IAErG,MAAM,wBAAwB,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACxD,KAAK,CAAC,gBAAgB,GAAG,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;QACpD,MAAM,aAAa,GAAG,wBAAwB,CAAC,CAAC,CAAC,MAAM,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC7G,OAAO,gBAAgB,CAAC,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC,CAAC;IAAA,CACpE,CAAC;IAEF,MAAM,sBAAsB,GAAG,KAAK,CAAC,cAAc,CAAC;IACpD,MAAM,qBAAqB,GAAG,CAC7B,KAAmD,EACnD,OAAqD,EACrD,aAA2D,EAC1D,EAAE,CAAC;QACJ,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,sBAAsB,CAC5B,KAAK,EACL,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,iBAAiB,CAAC,EAAE,EAC3F,aAAa,CACb,CAAC;IAAA,CACF,CAAC;IACF,IAAI,uBAAuB,CAAC,sBAAsB,CAAC;QAAE,sBAAsB,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACvG,KAAK,CAAC,cAAc,GAAG,qBAAqB,CAAC;AAAA,CAC7C","sourcesContent":["/**\n * Context pipeline wiring — shared by `AgentSession` (production) and the offline\n * replay harness (`src/testing/replay/runner.ts`), so there is exactly one\n * implementation of \"how deferred-schema resolution and eviction attach to an\n * `Agent`\" rather than two independently maintained copies.\n *\n * Implements the ordering settled in `docs/architecture/contracts.md` § 2:\n * deferred-schema resolution → tool-result eviction → compaction. Compaction runs\n * reactively from its own existing seam (`_checkCompaction` in `agent-session.ts`)\n * and is untouched here; this module only adds the two stages that run *ahead of*\n * every LLM request, so that reactive check is reached less often because the\n * request it is reacting to is smaller.\n *\n * The two stages land in different seams because they operate on different halves\n * of the outbound request. Eviction is a pure function of `AgentMessage[]`, which is\n * exactly what `transformContext` sees, immediately before `convertToLlm` — so it is\n * wired there. Deferred-schema resolution operates on the *tool list*, not messages;\n * `transformContext`'s signature has no tools parameter, and `AgentContext.tools` is\n * a snapshot taken once per prompt rather than rebuilt per request. The seam that\n * actually sees the assembled outbound tool list on every request is\n * `streamFunction` — it receives the full `Context`, tools included, immediately\n * before the provider call — so the projection is applied there instead. Because the\n * two stages act on disjoint fields of the request with no data dependency between\n * them, this does not change the observable pipeline order.\n */\n\nimport { streamSimple } from \"@earendil-works/pi-ai/compat\";\nimport type { Agent, StreamFn } from \"apex-code-agent-core\";\nimport { resolveToolContext } from \"../tools/contract.ts\";\nimport { announceToolsByName, type DeferrableTool } from \"./deferred-schemas.ts\";\nimport { type ContractLookup, evictToolResults } from \"./eviction.ts\";\n\n/**\n * Eviction-budget formula shared by every caller of `installContextPipeline`.\n * Compaction fires once total context tokens exceed `contextWindow - reserveTokens`\n * (`shouldCompact` in `core/compaction/compaction.ts`). Budgeting eviction — counted\n * purely against tool-result tokens, per `evictToolResults`'s own contract — at half\n * of that headroom leaves the other half free for system prompt and conversational\n * growth, so eviction (cheap, structure-preserving) gets a chance to shrink the\n * transcript before the expensive compaction stage is ever reached, matching\n * contracts.md § 2's \"why this order\" (eviction before compaction, so compaction is\n * reached later and less often).\n *\n * `Math.max(0, ...)` mirrors `shouldCompact`'s own behavior when `contextWindow` is\n * unknown (0): evict aggressively rather than not at all, rather than inventing a\n * different, unproven fallback.\n *\n * Production (`AgentSession`) calls this with the real model's `contextWindow` and\n * the user's configured `reserveTokens`. The offline replay harness deliberately\n * does *not* call this with the fixture model's `contextWindow` — see\n * `REPLAY_EVICTION_BUDGET` in `src/testing/replay/runner.ts` for why a dedicated\n * constant is used there instead.\n */\nexport function evictionBudget(contextWindow: number, reserveTokens: number): number {\n\treturn Math.max(0, Math.floor((contextWindow - reserveTokens) / 2));\n}\n\n/**\n * Adapter between a caller's tool registry and `announceToolsByName`, which\n * operates on a minimal `DeferrableTool` shape that has no notion of a tool\n * registry. Only `parameters` is ever replaced; every other field of the outbound\n * tool (name, description, and on `AgentTool` specifically, `execute`, `label`,\n * etc.) passes through unchanged via the object spread.\n *\n * A tool with no entry in `contractLookup` (a foreign/unclassified tool) is treated\n * as `deferSchema: false` here — the safe default on this axis is to keep\n * describing it fully, the mirror image of eviction's \"no contract => don't evict\"\n * default: when unsure, don't withhold information the model needs.\n */\nexport function projectToolSchemas<T extends { name: string; description: string; parameters: unknown }>(\n\ttools: readonly T[],\n\tcontractLookup: ContractLookup,\n\tloadedSchemaNames: ReadonlySet<string> = new Set(),\n): T[] {\n\tconst deferrable: DeferrableTool[] = tools.map((tool) => ({\n\t\tname: tool.name,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters,\n\t\tcontract: {\n\t\t\tcontext: {\n\t\t\t\tdeferSchema:\n\t\t\t\t\t!loadedSchemaNames.has(tool.name) && resolveToolContext(contractLookup, tool.name).context.deferSchema,\n\t\t\t},\n\t\t},\n\t}));\n\tconst announced = announceToolsByName(deferrable);\n\treturn tools.map((tool, index) => ({ ...tool, parameters: announced[index].parameters }));\n}\n\nconst defaultStreamFunctions = new WeakSet<StreamFn>();\n\n/** Returns true for the built-in streamSimple function, including its context-pipeline wrapper. */\nexport function isDefaultStreamFunction(streamFunction: StreamFn): boolean {\n\treturn streamFunction === streamSimple || defaultStreamFunctions.has(streamFunction);\n}\n\nexport interface ContextPipelineOptions {\n\t/** Resolves a tool's contract; shared by both eviction and schema projection. */\n\tcontractLookup: ContractLookup;\n\t/** Names whose real schemas have been loaded by the model in this session. */\n\tloadedSchemaNames?: ReadonlySet<string>;\n\t/**\n\t * Eviction budget as a thunk, not a plain number: `AgentSession`'s budget\n\t * depends on `this.model` and `this.settingsManager`, both of which can change\n\t * over the session's lifetime (model switch, settings edit), and is never\n\t * cached. Evaluating it fresh on every request is what keeps eviction correct\n\t * after either changes mid-session.\n\t */\n\tevictionBudget: () => number;\n}\n\n/**\n * Installs the settled context pipeline (deferred-schema resolution → eviction)\n * onto `agent`, chaining onto whatever `transformContext` / `streamFunction` the\n * caller already installed rather than replacing it — the same pattern\n * `AgentSession._installAgentNextTurnRefresh` uses for `prepareNextTurnWithContext`.\n */\nexport function installContextPipeline(agent: Agent, options: ContextPipelineOptions): void {\n\tconst { contractLookup, evictionBudget: getBudget, loadedSchemaNames = new Set<string>() } = options;\n\n\tconst previousTransformContext = agent.transformContext;\n\tagent.transformContext = async (messages, signal) => {\n\t\tconst afterPrevious = previousTransformContext ? await previousTransformContext(messages, signal) : messages;\n\t\treturn evictToolResults(afterPrevious, contractLookup, getBudget());\n\t};\n\n\tconst previousStreamFunction = agent.streamFunction;\n\tconst wrappedStreamFunction = (\n\t\tmodel: Parameters<typeof previousStreamFunction>[0],\n\t\tcontext: Parameters<typeof previousStreamFunction>[1],\n\t\tstreamOptions: Parameters<typeof previousStreamFunction>[2],\n\t) => {\n\t\tif (!context.tools || context.tools.length === 0) {\n\t\t\treturn previousStreamFunction(model, context, streamOptions);\n\t\t}\n\t\treturn previousStreamFunction(\n\t\t\tmodel,\n\t\t\t{ ...context, tools: projectToolSchemas(context.tools, contractLookup, loadedSchemaNames) },\n\t\t\tstreamOptions,\n\t\t);\n\t};\n\tif (isDefaultStreamFunction(previousStreamFunction)) defaultStreamFunctions.add(wrappedStreamFunction);\n\tagent.streamFunction = wrappedStreamFunction;\n}\n"]}

package/dist/core/credential-failover.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure helpers for bounded, pre-completion credential failover around
+ * ModelRuntime.streamSimple(). Classification and stream buffering/replay only;
+ * pool selection state lives in CredentialPool, request orchestration in ModelRuntime.
+ */
+import type { AssistantMessage, AssistantMessageEvent } from "@earendil-works/pi-ai";
+import type { CredentialFailureKind } from "./credential-pool.ts";
+/**
+ * Classifies a failed AssistantMessage into a rotation-eligible CredentialFailureKind,
+ * or undefined when the failure should not trigger credential rotation (success,
+ * abort, or a non-retryable provider error such as quota exhaustion).
+ */
+export declare function classifyCredentialFailure(message: AssistantMessage): CredentialFailureKind | undefined;
+/** An AsyncIterable<AssistantMessageEvent> paired with its eventual AssistantMessage, matching the shape `lazyStream` forwards. */
+export interface ResultStream extends AsyncIterable<AssistantMessageEvent> {
+    result(): Promise<AssistantMessage>;
+}
+export interface DrainedAttempt {
+    events: readonly AssistantMessageEvent[];
+    message: AssistantMessage;
+}
+/**
+ * Fully consumes one attempt's stream before any event reaches the caller. This is
+ * what makes a failed attempt invisible to the caller: nothing is forwarded until the
+ * attempt's outcome (and therefore its retry eligibility) is known.
+ */
+export declare function drainAttempt(stream: ResultStream): Promise<DrainedAttempt>;
+/** Replays a fully-drained attempt's events as a fresh stream terminating in its known message. */
+export declare function replayAttempt({ events, message }: DrainedAttempt): ResultStream;
+//# sourceMappingURL=credential-failover.d.ts.map

package/dist/core/credential-failover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-failover.d.ts","sourceRoot":"","sources":["../../src/core/credential-failover.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAErF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAMlE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,GAAG,qBAAqB,GAAG,SAAS,CAOtG;AAED,mIAAmI;AACnI,MAAM,WAAW,YAAa,SAAQ,aAAa,CAAC,qBAAqB,CAAC;IACzE,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzC,OAAO,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAIhF;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,cAAc,GAAG,YAAY,CAO/E","sourcesContent":["/**\n * Pure helpers for bounded, pre-completion credential failover around\n * ModelRuntime.streamSimple(). Classification and stream buffering/replay only;\n * pool selection state lives in CredentialPool, request orchestration in ModelRuntime.\n */\n\nimport type { AssistantMessage, AssistantMessageEvent } from \"@earendil-works/pi-ai\";\nimport { isRetryableAssistantError } from \"@earendil-works/pi-ai\";\nimport type { CredentialFailureKind } from \"./credential-pool.ts\";\n\nconst RATE_LIMIT_PATTERN = /\\b429\\b|rate.?limit|too many requests/i;\nconst BLOCKED_CREDENTIAL_PATTERN =\n\t/\\b401\\b|\\b403\\b|unauthorized|forbidden|invalid.?api.?key|permission denied|expired/i;\n\n/**\n * Classifies a failed AssistantMessage into a rotation-eligible CredentialFailureKind,\n * or undefined when the failure should not trigger credential rotation (success,\n * abort, or a non-retryable provider error such as quota exhaustion).\n */\nexport function classifyCredentialFailure(message: AssistantMessage): CredentialFailureKind | undefined {\n\tif (message.stopReason !== \"error\" || !message.errorMessage) return undefined;\n\tconst text = message.errorMessage;\n\tif (RATE_LIMIT_PATTERN.test(text)) return \"rate_limited\";\n\tif (BLOCKED_CREDENTIAL_PATTERN.test(text)) return \"blocked\";\n\tif (isRetryableAssistantError(message)) return \"temporary\";\n\treturn undefined;\n}\n\n/** An AsyncIterable<AssistantMessageEvent> paired with its eventual AssistantMessage, matching the shape `lazyStream` forwards. */\nexport interface ResultStream extends AsyncIterable<AssistantMessageEvent> {\n\tresult(): Promise<AssistantMessage>;\n}\n\nexport interface DrainedAttempt {\n\tevents: readonly AssistantMessageEvent[];\n\tmessage: AssistantMessage;\n}\n\n/**\n * Fully consumes one attempt's stream before any event reaches the caller. This is\n * what makes a failed attempt invisible to the caller: nothing is forwarded until the\n * attempt's outcome (and therefore its retry eligibility) is known.\n */\nexport async function drainAttempt(stream: ResultStream): Promise<DrainedAttempt> {\n\tconst events: AssistantMessageEvent[] = [];\n\tfor await (const event of stream) events.push(event);\n\treturn { events, message: await stream.result() };\n}\n\n/** Replays a fully-drained attempt's events as a fresh stream terminating in its known message. */\nexport function replayAttempt({ events, message }: DrainedAttempt): ResultStream {\n\treturn {\n\t\tasync *[Symbol.asyncIterator]() {\n\t\t\tyield* events;\n\t\t},\n\t\tresult: () => Promise.resolve(message),\n\t};\n}\n"]}

package/dist/core/credential-failover.js

@@ -0,0 +1,46 @@
+/**
+ * Pure helpers for bounded, pre-completion credential failover around
+ * ModelRuntime.streamSimple(). Classification and stream buffering/replay only;
+ * pool selection state lives in CredentialPool, request orchestration in ModelRuntime.
+ */
+import { isRetryableAssistantError } from "@earendil-works/pi-ai";
+const RATE_LIMIT_PATTERN = /\b429\b|rate.?limit|too many requests/i;
+const BLOCKED_CREDENTIAL_PATTERN = /\b401\b|\b403\b|unauthorized|forbidden|invalid.?api.?key|permission denied|expired/i;
+/**
+ * Classifies a failed AssistantMessage into a rotation-eligible CredentialFailureKind,
+ * or undefined when the failure should not trigger credential rotation (success,
+ * abort, or a non-retryable provider error such as quota exhaustion).
+ */
+export function classifyCredentialFailure(message) {
+    if (message.stopReason !== "error" || !message.errorMessage)
+        return undefined;
+    const text = message.errorMessage;
+    if (RATE_LIMIT_PATTERN.test(text))
+        return "rate_limited";
+    if (BLOCKED_CREDENTIAL_PATTERN.test(text))
+        return "blocked";
+    if (isRetryableAssistantError(message))
+        return "temporary";
+    return undefined;
+}
+/**
+ * Fully consumes one attempt's stream before any event reaches the caller. This is
+ * what makes a failed attempt invisible to the caller: nothing is forwarded until the
+ * attempt's outcome (and therefore its retry eligibility) is known.
+ */
+export async function drainAttempt(stream) {
+    const events = [];
+    for await (const event of stream)
+        events.push(event);
+    return { events, message: await stream.result() };
+}
+/** Replays a fully-drained attempt's events as a fresh stream terminating in its known message. */
+export function replayAttempt({ events, message }) {
+    return {
+        async *[Symbol.asyncIterator]() {
+            yield* events;
+        },
+        result: () => Promise.resolve(message),
+    };
+}
+//# sourceMappingURL=credential-failover.js.map

package/dist/core/credential-failover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-failover.js","sourceRoot":"","sources":["../../src/core/credential-failover.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,MAAM,kBAAkB,GAAG,wCAAwC,CAAC;AACpE,MAAM,0BAA0B,GAC/B,qFAAqF,CAAC;AAEvF;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAyB,EAAqC;IACvG,IAAI,OAAO,CAAC,UAAU,KAAK,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY;QAAE,OAAO,SAAS,CAAC;IAC9E,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAClC,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,cAAc,CAAC;IACzD,IAAI,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,yBAAyB,CAAC,OAAO,CAAC;QAAE,OAAO,WAAW,CAAC;IAC3D,OAAO,SAAS,CAAC;AAAA,CACjB;AAYD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAoB,EAA2B;IACjF,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM;QAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;AAAA,CAClD;AAED,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,EAAkB,EAAgB;IAChF,OAAO;QACN,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG;YAC/B,KAAK,CAAC,CAAC,MAAM,CAAC;QAAA,CACd;QACD,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;KACtC,CAAC;AAAA,CACF","sourcesContent":["/**\n * Pure helpers for bounded, pre-completion credential failover around\n * ModelRuntime.streamSimple(). Classification and stream buffering/replay only;\n * pool selection state lives in CredentialPool, request orchestration in ModelRuntime.\n */\n\nimport type { AssistantMessage, AssistantMessageEvent } from \"@earendil-works/pi-ai\";\nimport { isRetryableAssistantError } from \"@earendil-works/pi-ai\";\nimport type { CredentialFailureKind } from \"./credential-pool.ts\";\n\nconst RATE_LIMIT_PATTERN = /\\b429\\b|rate.?limit|too many requests/i;\nconst BLOCKED_CREDENTIAL_PATTERN =\n\t/\\b401\\b|\\b403\\b|unauthorized|forbidden|invalid.?api.?key|permission denied|expired/i;\n\n/**\n * Classifies a failed AssistantMessage into a rotation-eligible CredentialFailureKind,\n * or undefined when the failure should not trigger credential rotation (success,\n * abort, or a non-retryable provider error such as quota exhaustion).\n */\nexport function classifyCredentialFailure(message: AssistantMessage): CredentialFailureKind | undefined {\n\tif (message.stopReason !== \"error\" || !message.errorMessage) return undefined;\n\tconst text = message.errorMessage;\n\tif (RATE_LIMIT_PATTERN.test(text)) return \"rate_limited\";\n\tif (BLOCKED_CREDENTIAL_PATTERN.test(text)) return \"blocked\";\n\tif (isRetryableAssistantError(message)) return \"temporary\";\n\treturn undefined;\n}\n\n/** An AsyncIterable<AssistantMessageEvent> paired with its eventual AssistantMessage, matching the shape `lazyStream` forwards. */\nexport interface ResultStream extends AsyncIterable<AssistantMessageEvent> {\n\tresult(): Promise<AssistantMessage>;\n}\n\nexport interface DrainedAttempt {\n\tevents: readonly AssistantMessageEvent[];\n\tmessage: AssistantMessage;\n}\n\n/**\n * Fully consumes one attempt's stream before any event reaches the caller. This is\n * what makes a failed attempt invisible to the caller: nothing is forwarded until the\n * attempt's outcome (and therefore its retry eligibility) is known.\n */\nexport async function drainAttempt(stream: ResultStream): Promise<DrainedAttempt> {\n\tconst events: AssistantMessageEvent[] = [];\n\tfor await (const event of stream) events.push(event);\n\treturn { events, message: await stream.result() };\n}\n\n/** Replays a fully-drained attempt's events as a fresh stream terminating in its known message. */\nexport function replayAttempt({ events, message }: DrainedAttempt): ResultStream {\n\treturn {\n\t\tasync *[Symbol.asyncIterator]() {\n\t\t\tyield* events;\n\t\t},\n\t\tresult: () => Promise.resolve(message),\n\t};\n}\n"]}

package/dist/core/credential-pool.d.ts

@@ -0,0 +1,60 @@
+/** Non-secret credential selection state for a single process. */
+export type CredentialIdentity = string & {
+    readonly __brand: "CredentialIdentity";
+};
+export declare function createCredentialIdentity(value: string): CredentialIdentity;
+export interface CredentialPoolEntry {
+    identity: CredentialIdentity;
+    providerId: string;
+}
+export type CredentialFailureKind = "rate_limited" | "blocked" | "temporary";
+export interface CredentialPoolOptions {
+    entries: readonly CredentialPoolEntry[];
+    now?: () => number;
+    cooldownMs?: number;
+}
+export interface CredentialPoolSelection {
+    identity: CredentialIdentity;
+    providerId: string;
+}
+export interface CredentialPoolSnapshotEntry {
+    identity: CredentialIdentity;
+    providerId: string;
+    blockedUntil: number | undefined;
+}
+export interface CredentialRefreshLease {
+    identity: CredentialIdentity;
+    owner: string;
+    expiresAt: number;
+}
+export declare class CredentialPool {
+    private readonly entries;
+    private readonly now;
+    private readonly cooldownMs;
+    private readonly blockedUntilByIdentity;
+    private readonly refreshLeaseByIdentity;
+    private nextIndex;
+    constructor({ entries, now, cooldownMs }: CredentialPoolOptions);
+    select({ providerId, attempted }: {
+        providerId: string;
+        attempted: ReadonlySet<CredentialIdentity>;
+    }): CredentialPoolSelection | undefined;
+    recordFailure({ identity, kind }: {
+        identity: CredentialIdentity;
+        kind: CredentialFailureKind;
+    }): void;
+    snapshot(): CredentialPoolSnapshotEntry[];
+    private activeLease;
+    /** Grant a refresh lease for an identity, unless another owner already holds an unexpired one. */
+    acquireRefreshLease({ identity, owner, durationMs }: {
+        identity: CredentialIdentity;
+        owner: string;
+        durationMs: number;
+    }): CredentialRefreshLease | undefined;
+    /** Release a held refresh lease. Returns false if the caller is not the current owner. */
+    releaseRefreshLease({ identity, owner }: {
+        identity: CredentialIdentity;
+        owner: string;
+    }): boolean;
+}
+//# sourceMappingURL=credential-pool.d.ts.map

package/dist/core/credential-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-pool.d.ts","sourceRoot":"","sources":["../../src/core/credential-pool.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAErF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAG1E;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAyC;IAChF,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAyD;IAChG,OAAO,CAAC,SAAS,CAAK;IAEtB,YAAY,EAAE,OAAO,EAAE,GAAc,EAAE,UAAmB,EAAE,EAAE,qBAAqB,EAWlF;IAED,MAAM,CAAC,EACN,UAAU,EACV,SAAS,EACT,EAAE;QACF,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;KAC3C,GAAG,uBAAuB,GAAG,SAAS,CAkBtC;IAED,aAAa,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;QAAE,QAAQ,EAAE,kBAAkB,CAAC;QAAC,IAAI,EAAE,qBAAqB,CAAA;KAAE,GAAG,IAAI,CAIrG;IAED,QAAQ,IAAI,2BAA2B,EAAE,CAMxC;IAED,OAAO,CAAC,WAAW;IAUnB,kGAAkG;IAClG,mBAAmB,CAAC,EACnB,QAAQ,EACR,KAAK,EACL,UAAU,EACV,EAAE;QACF,QAAQ,EAAE,kBAAkB,CAAC;QAC7B,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACnB,GAAG,sBAAsB,GAAG,SAAS,CAMrC;IAED,0FAA0F;IAC1F,mBAAmB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAAE,QAAQ,EAAE,kBAAkB,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAKjG;CACD","sourcesContent":["/** Non-secret credential selection state for a single process. */\n\nexport type CredentialIdentity = string & { readonly __brand: \"CredentialIdentity\" };\n\nexport function createCredentialIdentity(value: string): CredentialIdentity {\n\tif (!value.trim()) throw new Error(\"Credential identity must not be empty\");\n\treturn value as CredentialIdentity;\n}\n\nexport interface CredentialPoolEntry {\n\tidentity: CredentialIdentity;\n\tproviderId: string;\n}\n\nexport type CredentialFailureKind = \"rate_limited\" | \"blocked\" | \"temporary\";\n\nexport interface CredentialPoolOptions {\n\tentries: readonly CredentialPoolEntry[];\n\tnow?: () => number;\n\tcooldownMs?: number;\n}\n\nexport interface CredentialPoolSelection {\n\tidentity: CredentialIdentity;\n\tproviderId: string;\n}\n\nexport interface CredentialPoolSnapshotEntry {\n\tidentity: CredentialIdentity;\n\tproviderId: string;\n\tblockedUntil: number | undefined;\n}\n\nexport interface CredentialRefreshLease {\n\tidentity: CredentialIdentity;\n\towner: string;\n\texpiresAt: number;\n}\n\nexport class CredentialPool {\n\tprivate readonly entries: readonly CredentialPoolEntry[];\n\tprivate readonly now: () => number;\n\tprivate readonly cooldownMs: number;\n\tprivate readonly blockedUntilByIdentity = new Map<CredentialIdentity, number>();\n\tprivate readonly refreshLeaseByIdentity = new Map<CredentialIdentity, CredentialRefreshLease>();\n\tprivate nextIndex = 0;\n\n\tconstructor({ entries, now = Date.now, cooldownMs = 60_000 }: CredentialPoolOptions) {\n\t\tconst seen = new Set<CredentialIdentity>();\n\t\tfor (const entry of entries) {\n\t\t\tif (seen.has(entry.identity)) {\n\t\t\t\tthrow new Error(`Duplicate credential identity \"${entry.identity}\"`);\n\t\t\t}\n\t\t\tseen.add(entry.identity);\n\t\t}\n\t\tthis.entries = entries;\n\t\tthis.now = now;\n\t\tthis.cooldownMs = cooldownMs;\n\t}\n\n\tselect({\n\t\tproviderId,\n\t\tattempted,\n\t}: {\n\t\tproviderId: string;\n\t\tattempted: ReadonlySet<CredentialIdentity>;\n\t}): CredentialPoolSelection | undefined {\n\t\tif (this.entries.length === 0) return undefined;\n\t\tconst now = this.now();\n\t\tfor (let offset = 0; offset < this.entries.length; offset++) {\n\t\t\tconst index = (this.nextIndex + offset) % this.entries.length;\n\t\t\tconst entry = this.entries[index];\n\t\t\tconst blockedUntil = this.blockedUntilByIdentity.get(entry.identity);\n\t\t\tif (\n\t\t\t\tentry.providerId !== providerId ||\n\t\t\t\tattempted.has(entry.identity) ||\n\t\t\t\t(blockedUntil !== undefined && blockedUntil > now)\n\t\t\t) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tthis.nextIndex = (index + 1) % this.entries.length;\n\t\t\treturn entry;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\trecordFailure({ identity, kind }: { identity: CredentialIdentity; kind: CredentialFailureKind }): void {\n\t\tif (kind === \"rate_limited\" || kind === \"blocked\") {\n\t\t\tthis.blockedUntilByIdentity.set(identity, this.now() + this.cooldownMs);\n\t\t}\n\t}\n\n\tsnapshot(): CredentialPoolSnapshotEntry[] {\n\t\treturn this.entries.map((entry) => ({\n\t\t\tidentity: entry.identity,\n\t\t\tproviderId: entry.providerId,\n\t\t\tblockedUntil: this.blockedUntilByIdentity.get(entry.identity),\n\t\t}));\n\t}\n\n\tprivate activeLease(identity: CredentialIdentity): CredentialRefreshLease | undefined {\n\t\tconst lease = this.refreshLeaseByIdentity.get(identity);\n\t\tif (!lease) return undefined;\n\t\tif (lease.expiresAt <= this.now()) {\n\t\t\tthis.refreshLeaseByIdentity.delete(identity);\n\t\t\treturn undefined;\n\t\t}\n\t\treturn lease;\n\t}\n\n\t/** Grant a refresh lease for an identity, unless another owner already holds an unexpired one. */\n\tacquireRefreshLease({\n\t\tidentity,\n\t\towner,\n\t\tdurationMs,\n\t}: {\n\t\tidentity: CredentialIdentity;\n\t\towner: string;\n\t\tdurationMs: number;\n\t}): CredentialRefreshLease | undefined {\n\t\tconst existing = this.activeLease(identity);\n\t\tif (existing && existing.owner !== owner) return undefined;\n\t\tconst lease: CredentialRefreshLease = { identity, owner, expiresAt: this.now() + durationMs };\n\t\tthis.refreshLeaseByIdentity.set(identity, lease);\n\t\treturn lease;\n\t}\n\n\t/** Release a held refresh lease. Returns false if the caller is not the current owner. */\n\treleaseRefreshLease({ identity, owner }: { identity: CredentialIdentity; owner: string }): boolean {\n\t\tconst existing = this.activeLease(identity);\n\t\tif (!existing || existing.owner !== owner) return false;\n\t\tthis.refreshLeaseByIdentity.delete(identity);\n\t\treturn true;\n\t}\n}\n"]}