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

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

package/dist/core/credential-pool.js

@@ -0,0 +1,84 @@
+/** Non-secret credential selection state for a single process. */
+export function createCredentialIdentity(value) {
+    if (!value.trim())
+        throw new Error("Credential identity must not be empty");
+    return value;
+}
+export class CredentialPool {
+    entries;
+    now;
+    cooldownMs;
+    blockedUntilByIdentity = new Map();
+    refreshLeaseByIdentity = new Map();
+    nextIndex = 0;
+    constructor({ entries, now = Date.now, cooldownMs = 60_000 }) {
+        const seen = new Set();
+        for (const entry of entries) {
+            if (seen.has(entry.identity)) {
+                throw new Error(`Duplicate credential identity "${entry.identity}"`);
+            }
+            seen.add(entry.identity);
+        }
+        this.entries = entries;
+        this.now = now;
+        this.cooldownMs = cooldownMs;
+    }
+    select({ providerId, attempted, }) {
+        if (this.entries.length === 0)
+            return undefined;
+        const now = this.now();
+        for (let offset = 0; offset < this.entries.length; offset++) {
+            const index = (this.nextIndex + offset) % this.entries.length;
+            const entry = this.entries[index];
+            const blockedUntil = this.blockedUntilByIdentity.get(entry.identity);
+            if (entry.providerId !== providerId ||
+                attempted.has(entry.identity) ||
+                (blockedUntil !== undefined && blockedUntil > now)) {
+                continue;
+            }
+            this.nextIndex = (index + 1) % this.entries.length;
+            return entry;
+        }
+        return undefined;
+    }
+    recordFailure({ identity, kind }) {
+        if (kind === "rate_limited" || kind === "blocked") {
+            this.blockedUntilByIdentity.set(identity, this.now() + this.cooldownMs);
+        }
+    }
+    snapshot() {
+        return this.entries.map((entry) => ({
+            identity: entry.identity,
+            providerId: entry.providerId,
+            blockedUntil: this.blockedUntilByIdentity.get(entry.identity),
+        }));
+    }
+    activeLease(identity) {
+        const lease = this.refreshLeaseByIdentity.get(identity);
+        if (!lease)
+            return undefined;
+        if (lease.expiresAt <= this.now()) {
+            this.refreshLeaseByIdentity.delete(identity);
+            return undefined;
+        }
+        return lease;
+    }
+    /** Grant a refresh lease for an identity, unless another owner already holds an unexpired one. */
+    acquireRefreshLease({ identity, owner, durationMs, }) {
+        const existing = this.activeLease(identity);
+        if (existing && existing.owner !== owner)
+            return undefined;
+        const lease = { identity, owner, expiresAt: this.now() + durationMs };
+        this.refreshLeaseByIdentity.set(identity, lease);
+        return lease;
+    }
+    /** Release a held refresh lease. Returns false if the caller is not the current owner. */
+    releaseRefreshLease({ identity, owner }) {
+        const existing = this.activeLease(identity);
+        if (!existing || existing.owner !== owner)
+            return false;
+        this.refreshLeaseByIdentity.delete(identity);
+        return true;
+    }
+}
+//# sourceMappingURL=credential-pool.js.map

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

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

package/dist/core/defaults.d.ts

@@ -1,3 +1,4 @@
 import type { ThinkingLevel } from "apex-code-agent-core";
 export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
+export declare const THINKING_LEVEL_OPTIONS: readonly ThinkingLevel[];
 //# sourceMappingURL=defaults.d.ts.map

package/dist/core/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/core/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC","sourcesContent":["import type { ThinkingLevel } from \"apex-code-agent-core\";\n\nexport const DEFAULT_THINKING_LEVEL: ThinkingLevel = \"medium\";\n"]}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/core/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAC9D,eAAO,MAAM,sBAAsB,EAAE,SAAS,aAAa,EAQ1D,CAAC","sourcesContent":["import type { ThinkingLevel } from \"apex-code-agent-core\";\n\nexport const DEFAULT_THINKING_LEVEL: ThinkingLevel = \"medium\";\nexport const THINKING_LEVEL_OPTIONS: readonly ThinkingLevel[] = [\n\t\"off\",\n\t\"minimal\",\n\t\"low\",\n\t\"medium\",\n\t\"high\",\n\t\"xhigh\",\n\t\"max\",\n];\n"]}

package/dist/core/defaults.js

@@ -1,2 +1,11 @@
 export const DEFAULT_THINKING_LEVEL = "medium";
+export const THINKING_LEVEL_OPTIONS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
 //# sourceMappingURL=defaults.js.map

package/dist/core/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/core/defaults.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,sBAAsB,GAAkB,QAAQ,CAAC","sourcesContent":["import type { ThinkingLevel } from \"apex-code-agent-core\";\n\nexport const DEFAULT_THINKING_LEVEL: ThinkingLevel = \"medium\";\n"]}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/core/defaults.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,sBAAsB,GAAkB,QAAQ,CAAC;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAA6B;IAC/D,KAAK;IACL,SAAS;IACT,KAAK;IACL,QAAQ;IACR,MAAM;IACN,OAAO;IACP,KAAK;CACL,CAAC","sourcesContent":["import type { ThinkingLevel } from \"apex-code-agent-core\";\n\nexport const DEFAULT_THINKING_LEVEL: ThinkingLevel = \"medium\";\nexport const THINKING_LEVEL_OPTIONS: readonly ThinkingLevel[] = [\n\t\"off\",\n\t\"minimal\",\n\t\"low\",\n\t\"medium\",\n\t\"high\",\n\t\"xhigh\",\n\t\"max\",\n];\n"]}

package/dist/core/delegation/agents.d.ts

@@ -0,0 +1,15 @@
+/** Markdown agent-definition discovery (roadmap Phase 5, task 5.5).
+ * User definitions are always eligible. Project definitions are eligible only
+ * through the existing project-trust decision; discovery never prompts or creates
+ * a second trust mechanism. Files are parsed on lookup so edits take effect on the
+ * next delegation and malformed definitions simply remain unavailable.
+ */
+import type { AgentDefinitionResolver } from "./runtime.ts";
+export interface CreateAgentDefinitionResolverOptions {
+    cwd: string;
+    agentDir: string;
+    /** Delegated to SettingsManager.isProjectTrusted() in production. */
+    isProjectTrusted: () => boolean;
+}
+export declare function createAgentDefinitionResolver(options: CreateAgentDefinitionResolverOptions): AgentDefinitionResolver;
+//# sourceMappingURL=agents.d.ts.map

package/dist/core/delegation/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/agents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAmB,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAS7E,MAAM,WAAW,oCAAoC;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,OAAO,CAAC;CAChC;AAyCD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,oCAAoC,GAAG,uBAAuB,CAKpH","sourcesContent":["/** Markdown agent-definition discovery (roadmap Phase 5, task 5.5).\n * User definitions are always eligible. Project definitions are eligible only\n * through the existing project-trust decision; discovery never prompts or creates\n * a second trust mechanism. Files are parsed on lookup so edits take effect on the\n * next delegation and malformed definitions simply remain unavailable.\n */\n\nimport { existsSync, readdirSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { parseFrontmatter } from \"../../utils/frontmatter.ts\";\nimport type { AgentDefinition, AgentDefinitionResolver } from \"./runtime.ts\";\n\ninterface AgentFrontmatter extends Record<string, unknown> {\n\tname?: unknown;\n\tdescription?: unknown;\n\ttools?: unknown;\n\tmodel?: unknown;\n}\n\nexport interface CreateAgentDefinitionResolverOptions {\n\tcwd: string;\n\tagentDir: string;\n\t/** Delegated to SettingsManager.isProjectTrusted() in production. */\n\tisProjectTrusted: () => boolean;\n}\n\nfunction parseDefinition(content: string): AgentDefinition | undefined {\n\ttry {\n\t\tconst { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);\n\t\tif (\n\t\t\ttypeof frontmatter.name !== \"string\" ||\n\t\t\t!frontmatter.name ||\n\t\t\ttypeof frontmatter.description !== \"string\" ||\n\t\t\t!frontmatter.description ||\n\t\t\t!Array.isArray(frontmatter.tools) ||\n\t\t\t!frontmatter.tools.every((tool): tool is string => typeof tool === \"string\" && tool.length > 0) ||\n\t\t\t(frontmatter.model !== undefined && (typeof frontmatter.model !== \"string\" || !frontmatter.model))\n\t\t)\n\t\t\treturn undefined;\n\t\treturn {\n\t\t\tname: frontmatter.name,\n\t\t\tdescription: frontmatter.description,\n\t\t\ttools: [...frontmatter.tools],\n\t\t\tmodel: frontmatter.model,\n\t\t\tsystemPrompt: body,\n\t\t};\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction discover(dir: string, agentType: string): AgentDefinition | undefined {\n\tif (!existsSync(dir)) return undefined;\n\ttry {\n\t\tfor (const filename of readdirSync(dir).sort()) {\n\t\t\tif (!filename.endsWith(\".md\")) continue;\n\t\t\tconst definition = parseDefinition(readFileSync(join(dir, filename), \"utf8\"));\n\t\t\tif (definition?.name === agentType) return definition;\n\t\t}\n\t} catch {\n\t\t// A directory that cannot be read behaves as having no usable definitions.\n\t}\n\treturn undefined;\n}\n\nexport function createAgentDefinitionResolver(options: CreateAgentDefinitionResolverOptions): AgentDefinitionResolver {\n\tconst userDir = join(options.agentDir, \"agents\");\n\tconst projectDir = join(options.cwd, \".apex-code\", \"agents\");\n\treturn (agentType) =>\n\t\tdiscover(userDir, agentType) ?? (options.isProjectTrusted() ? discover(projectDir, agentType) : undefined);\n}\n"]}