apex-code 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/core/context/deferred-schemas.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Deferred-schema resolution — announce-by-name projection and explicit load path.
+ *
+ * Ordering context (`docs/architecture/contracts.md` § 2, "Context pipeline order —
+ * settled"): deferred-schema resolution is the first of three stages applied at the
+ * `transformContext` seam —
+ *
+ *   deferred-schema resolution → tool-result eviction → compaction
+ *
+ * — because it changes the static prefix (system prompt + tool definitions) that both
+ * later stages measure themselves against. This module implements only that first
+ * stage's two primitives; wiring it into `transformContext` is task 3.3.
+ *
+ * `ContextSpec.deferSchema` (`core/tools/contract.ts`) is the per-tool flag this
+ * module reads: a tool with `deferSchema: true` is announced to the model by name and
+ * description only — its full JSON parameter schema is withheld from the static
+ * prefix — and materialized on demand through `loadDeferredSchema` when a later
+ * wiring stage needs the real schema for a tool the model decided to call.
+ *
+ * Both functions are pure: everything they need arrives as a parameter, nothing is
+ * read from a global tool registry, and neither performs I/O.
+ */
+/**
+ * Minimal shape this module needs from a tool definition. Any richer type — e.g.
+ * `ApexToolDefinition` from `core/tools/contract.ts` — satisfies this structurally,
+ * so a caller can pass its real tool-definition array directly with no adapter.
+ */
+export interface DeferrableTool {
+    name: string;
+    description: string;
+    /**
+     * The tool's full parameter schema (a TypeBox `TSchema` on `ApexToolDefinition` in
+     * this repo, but this module treats it as opaque — it never inspects, validates,
+     * or transforms its shape, only copies or withholds it whole).
+     */
+    parameters: unknown;
+    contract: {
+        context: {
+            deferSchema: boolean;
+        };
+    };
+}
+/**
+ * A tool as announced to the model: name, description, and a parameter schema that is
+ * either the tool's real schema (`deferSchema: false`) or the stub below
+ * (`deferSchema: true`).
+ */
+export interface AnnouncedTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+/**
+ * Stub schema substituted for a deferred tool's real parameters in the announce-by-name
+ * projection. An empty object schema rather than `undefined`/omission, so a provider
+ * that requires a `parameters`/`input_schema` field on every tool entry still receives
+ * a well-formed one.
+ */
+export declare const DEFERRED_SCHEMA_STUB: Readonly<{
+    type: "object";
+    properties: Record<string, never>;
+}>;
+/**
+ * Announce-by-name projection (context pipeline stage 1, "deferred-schema
+ * resolution").
+ *
+ * Tools with `contract.context.deferSchema === true` are represented by name and
+ * description only; their `parameters` field is replaced with `DEFERRED_SCHEMA_STUB`.
+ * Tools with `deferSchema === false` pass through with their real schema unchanged
+ * (the same reference, so deep- and reference-equality both hold).
+ *
+ * Pure: same length and order as `tools` in, no field other than `parameters` is
+ * altered, no global state is read.
+ */
+export declare function announceToolsByName<T extends DeferrableTool>(tools: readonly T[]): AnnouncedTool[];
+/**
+ * Explicit load path (context pipeline stage 1's counterpart): given a tool name,
+ * returns its real, full parameter schema — the mechanism a later wiring stage
+ * (task 3.3) calls when the model needs the real schema for a deferred tool it
+ * decided to call.
+ *
+ * Looks up `name` in `tools` and returns that tool's real `parameters`, regardless of
+ * whether `deferSchema` is `true` or `false` — a tool that never deferred its schema
+ * still has a well-defined "real schema" to return, and the caller should not have to
+ * branch on `deferSchema` before loading.
+ *
+ * Throws if no tool named `name` exists in `tools`. Does not throw for a tool whose
+ * `deferSchema` is `false`; that is a valid no-op returning the same schema the
+ * announce-by-name projection already showed for it.
+ */
+export declare function loadDeferredSchema<T extends DeferrableTool>(tools: readonly T[], name: string): unknown;
+//# sourceMappingURL=deferred-schemas.d.ts.map

package/dist/core/context/deferred-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-schemas.d.ts","sourceRoot":"","sources":["../../../src/core/context/deferred-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE;QACT,OAAO,EAAE;YACR,WAAW,EAAE,OAAO,CAAC;SACrB,CAAC;KACF,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CAAE,CAG/F,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,aAAa,EAAE,CAMlG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAMvG","sourcesContent":["/**\n * Deferred-schema resolution — announce-by-name projection and explicit load path.\n *\n * Ordering context (`docs/architecture/contracts.md` § 2, \"Context pipeline order —\n * settled\"): deferred-schema resolution is the first of three stages applied at the\n * `transformContext` seam —\n *\n *   deferred-schema resolution → tool-result eviction → compaction\n *\n * — because it changes the static prefix (system prompt + tool definitions) that both\n * later stages measure themselves against. This module implements only that first\n * stage's two primitives; wiring it into `transformContext` is task 3.3.\n *\n * `ContextSpec.deferSchema` (`core/tools/contract.ts`) is the per-tool flag this\n * module reads: a tool with `deferSchema: true` is announced to the model by name and\n * description only — its full JSON parameter schema is withheld from the static\n * prefix — and materialized on demand through `loadDeferredSchema` when a later\n * wiring stage needs the real schema for a tool the model decided to call.\n *\n * Both functions are pure: everything they need arrives as a parameter, nothing is\n * read from a global tool registry, and neither performs I/O.\n */\n\n/**\n * Minimal shape this module needs from a tool definition. Any richer type — e.g.\n * `ApexToolDefinition` from `core/tools/contract.ts` — satisfies this structurally,\n * so a caller can pass its real tool-definition array directly with no adapter.\n */\nexport interface DeferrableTool {\n\tname: string;\n\tdescription: string;\n\t/**\n\t * The tool's full parameter schema (a TypeBox `TSchema` on `ApexToolDefinition` in\n\t * this repo, but this module treats it as opaque — it never inspects, validates,\n\t * or transforms its shape, only copies or withholds it whole).\n\t */\n\tparameters: unknown;\n\tcontract: {\n\t\tcontext: {\n\t\t\tdeferSchema: boolean;\n\t\t};\n\t};\n}\n\n/**\n * A tool as announced to the model: name, description, and a parameter schema that is\n * either the tool's real schema (`deferSchema: false`) or the stub below\n * (`deferSchema: true`).\n */\nexport interface AnnouncedTool {\n\tname: string;\n\tdescription: string;\n\tparameters: unknown;\n}\n\n/**\n * Stub schema substituted for a deferred tool's real parameters in the announce-by-name\n * projection. An empty object schema rather than `undefined`/omission, so a provider\n * that requires a `parameters`/`input_schema` field on every tool entry still receives\n * a well-formed one.\n */\nexport const DEFERRED_SCHEMA_STUB: Readonly<{ type: \"object\"; properties: Record<string, never> }> = Object.freeze({\n\ttype: \"object\",\n\tproperties: {},\n});\n\n/**\n * Announce-by-name projection (context pipeline stage 1, \"deferred-schema\n * resolution\").\n *\n * Tools with `contract.context.deferSchema === true` are represented by name and\n * description only; their `parameters` field is replaced with `DEFERRED_SCHEMA_STUB`.\n * Tools with `deferSchema === false` pass through with their real schema unchanged\n * (the same reference, so deep- and reference-equality both hold).\n *\n * Pure: same length and order as `tools` in, no field other than `parameters` is\n * altered, no global state is read.\n */\nexport function announceToolsByName<T extends DeferrableTool>(tools: readonly T[]): AnnouncedTool[] {\n\treturn tools.map((tool) => ({\n\t\tname: tool.name,\n\t\tdescription: tool.description,\n\t\tparameters: tool.contract.context.deferSchema ? DEFERRED_SCHEMA_STUB : tool.parameters,\n\t}));\n}\n\n/**\n * Explicit load path (context pipeline stage 1's counterpart): given a tool name,\n * returns its real, full parameter schema — the mechanism a later wiring stage\n * (task 3.3) calls when the model needs the real schema for a deferred tool it\n * decided to call.\n *\n * Looks up `name` in `tools` and returns that tool's real `parameters`, regardless of\n * whether `deferSchema` is `true` or `false` — a tool that never deferred its schema\n * still has a well-defined \"real schema\" to return, and the caller should not have to\n * branch on `deferSchema` before loading.\n *\n * Throws if no tool named `name` exists in `tools`. Does not throw for a tool whose\n * `deferSchema` is `false`; that is a valid no-op returning the same schema the\n * announce-by-name projection already showed for it.\n */\nexport function loadDeferredSchema<T extends DeferrableTool>(tools: readonly T[], name: string): unknown {\n\tconst tool = tools.find((candidate) => candidate.name === name);\n\tif (!tool) {\n\t\tthrow new Error(`loadDeferredSchema: no tool named \"${name}\" in the provided definitions`);\n\t}\n\treturn tool.parameters;\n}\n"]}

package/dist/core/context/deferred-schemas.js

@@ -0,0 +1,74 @@
+/**
+ * Deferred-schema resolution — announce-by-name projection and explicit load path.
+ *
+ * Ordering context (`docs/architecture/contracts.md` § 2, "Context pipeline order —
+ * settled"): deferred-schema resolution is the first of three stages applied at the
+ * `transformContext` seam —
+ *
+ *   deferred-schema resolution → tool-result eviction → compaction
+ *
+ * — because it changes the static prefix (system prompt + tool definitions) that both
+ * later stages measure themselves against. This module implements only that first
+ * stage's two primitives; wiring it into `transformContext` is task 3.3.
+ *
+ * `ContextSpec.deferSchema` (`core/tools/contract.ts`) is the per-tool flag this
+ * module reads: a tool with `deferSchema: true` is announced to the model by name and
+ * description only — its full JSON parameter schema is withheld from the static
+ * prefix — and materialized on demand through `loadDeferredSchema` when a later
+ * wiring stage needs the real schema for a tool the model decided to call.
+ *
+ * Both functions are pure: everything they need arrives as a parameter, nothing is
+ * read from a global tool registry, and neither performs I/O.
+ */
+/**
+ * Stub schema substituted for a deferred tool's real parameters in the announce-by-name
+ * projection. An empty object schema rather than `undefined`/omission, so a provider
+ * that requires a `parameters`/`input_schema` field on every tool entry still receives
+ * a well-formed one.
+ */
+export const DEFERRED_SCHEMA_STUB = Object.freeze({
+    type: "object",
+    properties: {},
+});
+/**
+ * Announce-by-name projection (context pipeline stage 1, "deferred-schema
+ * resolution").
+ *
+ * Tools with `contract.context.deferSchema === true` are represented by name and
+ * description only; their `parameters` field is replaced with `DEFERRED_SCHEMA_STUB`.
+ * Tools with `deferSchema === false` pass through with their real schema unchanged
+ * (the same reference, so deep- and reference-equality both hold).
+ *
+ * Pure: same length and order as `tools` in, no field other than `parameters` is
+ * altered, no global state is read.
+ */
+export function announceToolsByName(tools) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.contract.context.deferSchema ? DEFERRED_SCHEMA_STUB : tool.parameters,
+    }));
+}
+/**
+ * Explicit load path (context pipeline stage 1's counterpart): given a tool name,
+ * returns its real, full parameter schema — the mechanism a later wiring stage
+ * (task 3.3) calls when the model needs the real schema for a deferred tool it
+ * decided to call.
+ *
+ * Looks up `name` in `tools` and returns that tool's real `parameters`, regardless of
+ * whether `deferSchema` is `true` or `false` — a tool that never deferred its schema
+ * still has a well-defined "real schema" to return, and the caller should not have to
+ * branch on `deferSchema` before loading.
+ *
+ * Throws if no tool named `name` exists in `tools`. Does not throw for a tool whose
+ * `deferSchema` is `false`; that is a valid no-op returning the same schema the
+ * announce-by-name projection already showed for it.
+ */
+export function loadDeferredSchema(tools, name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool) {
+        throw new Error(`loadDeferredSchema: no tool named "${name}" in the provided definitions`);
+    }
+    return tool.parameters;
+}
+//# sourceMappingURL=deferred-schemas.js.map

package/dist/core/context/deferred-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-schemas.js","sourceRoot":"","sources":["../../../src/core/context/deferred-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAkCH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAoE,MAAM,CAAC,MAAM,CAAC;IAClH,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,EAAE;CACd,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAA2B,KAAmB,EAAmB;IACnG,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU;KACtF,CAAC,CAAC,CAAC;AAAA,CACJ;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAA2B,KAAmB,EAAE,IAAY,EAAW;IACxG,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAChE,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,+BAA+B,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,IAAI,CAAC,UAAU,CAAC;AAAA,CACvB","sourcesContent":["/**\n * Deferred-schema resolution — announce-by-name projection and explicit load path.\n *\n * Ordering context (`docs/architecture/contracts.md` § 2, \"Context pipeline order —\n * settled\"): deferred-schema resolution is the first of three stages applied at the\n * `transformContext` seam —\n *\n *   deferred-schema resolution → tool-result eviction → compaction\n *\n * — because it changes the static prefix (system prompt + tool definitions) that both\n * later stages measure themselves against. This module implements only that first\n * stage's two primitives; wiring it into `transformContext` is task 3.3.\n *\n * `ContextSpec.deferSchema` (`core/tools/contract.ts`) is the per-tool flag this\n * module reads: a tool with `deferSchema: true` is announced to the model by name and\n * description only — its full JSON parameter schema is withheld from the static\n * prefix — and materialized on demand through `loadDeferredSchema` when a later\n * wiring stage needs the real schema for a tool the model decided to call.\n *\n * Both functions are pure: everything they need arrives as a parameter, nothing is\n * read from a global tool registry, and neither performs I/O.\n */\n\n/**\n * Minimal shape this module needs from a tool definition. Any richer type — e.g.\n * `ApexToolDefinition` from `core/tools/contract.ts` — satisfies this structurally,\n * so a caller can pass its real tool-definition array directly with no adapter.\n */\nexport interface DeferrableTool {\n\tname: string;\n\tdescription: string;\n\t/**\n\t * The tool's full parameter schema (a TypeBox `TSchema` on `ApexToolDefinition` in\n\t * this repo, but this module treats it as opaque — it never inspects, validates,\n\t * or transforms its shape, only copies or withholds it whole).\n\t */\n\tparameters: unknown;\n\tcontract: {\n\t\tcontext: {\n\t\t\tdeferSchema: boolean;\n\t\t};\n\t};\n}\n\n/**\n * A tool as announced to the model: name, description, and a parameter schema that is\n * either the tool's real schema (`deferSchema: false`) or the stub below\n * (`deferSchema: true`).\n */\nexport interface AnnouncedTool {\n\tname: string;\n\tdescription: string;\n\tparameters: unknown;\n}\n\n/**\n * Stub schema substituted for a deferred tool's real parameters in the announce-by-name\n * projection. An empty object schema rather than `undefined`/omission, so a provider\n * that requires a `parameters`/`input_schema` field on every tool entry still receives\n * a well-formed one.\n */\nexport const DEFERRED_SCHEMA_STUB: Readonly<{ type: \"object\"; properties: Record<string, never> }> = Object.freeze({\n\ttype: \"object\",\n\tproperties: {},\n});\n\n/**\n * Announce-by-name projection (context pipeline stage 1, \"deferred-schema\n * resolution\").\n *\n * Tools with `contract.context.deferSchema === true` are represented by name and\n * description only; their `parameters` field is replaced with `DEFERRED_SCHEMA_STUB`.\n * Tools with `deferSchema === false` pass through with their real schema unchanged\n * (the same reference, so deep- and reference-equality both hold).\n *\n * Pure: same length and order as `tools` in, no field other than `parameters` is\n * altered, no global state is read.\n */\nexport function announceToolsByName<T extends DeferrableTool>(tools: readonly T[]): AnnouncedTool[] {\n\treturn tools.map((tool) => ({\n\t\tname: tool.name,\n\t\tdescription: tool.description,\n\t\tparameters: tool.contract.context.deferSchema ? DEFERRED_SCHEMA_STUB : tool.parameters,\n\t}));\n}\n\n/**\n * Explicit load path (context pipeline stage 1's counterpart): given a tool name,\n * returns its real, full parameter schema — the mechanism a later wiring stage\n * (task 3.3) calls when the model needs the real schema for a deferred tool it\n * decided to call.\n *\n * Looks up `name` in `tools` and returns that tool's real `parameters`, regardless of\n * whether `deferSchema` is `true` or `false` — a tool that never deferred its schema\n * still has a well-defined \"real schema\" to return, and the caller should not have to\n * branch on `deferSchema` before loading.\n *\n * Throws if no tool named `name` exists in `tools`. Does not throw for a tool whose\n * `deferSchema` is `false`; that is a valid no-op returning the same schema the\n * announce-by-name projection already showed for it.\n */\nexport function loadDeferredSchema<T extends DeferrableTool>(tools: readonly T[], name: string): unknown {\n\tconst tool = tools.find((candidate) => candidate.name === name);\n\tif (!tool) {\n\t\tthrow new Error(`loadDeferredSchema: no tool named \"${name}\" in the provided definitions`);\n\t}\n\treturn tool.parameters;\n}\n"]}

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"]}