@qduc/term2 0.9.3 → 0.10.0

package/dist/prompts/subagent-delegation.js

@@ -5,47 +5,26 @@ import { getSubagentsRolesSection } from '../tools/agent/run-subagent.js';
  * Injected into the main system prompt whenever `run_subagent` is available.
  * The tool description covers mechanics; behavioral guidance lives here.
  */
-export function getSubagentDelegationAddendum({ orchestratorMode = false, } = {}) {
+export function getSubagentDelegationAddendum({ orchestratorMode = false, memoryEnabled = true, } = {}) {
     const header = `### Delegating to subagents
 
 You have a \`run_subagent\` tool. A subagent runs in its own context and returns only a summary — use it to keep your own context focused on high-level reasoning.`;
-    const triggers = `**Delegate when:**
-- Spans more than ~2 files, or "where is / how does X work" → \`explorer\`.
+    const triggers = `**Delegate when it provides meaningful leverage:**
+- Need focused codebase investigation or context compression → \`explorer\`.
 - Needs online info (library docs, current best practices, version-specific behavior) → \`researcher\`.
 - About to commit to a non-trivial plan or tricky debugging direction and want it pressure-tested → \`mentor\`.
-- Scoped, verifiable unit of work (bug fix, refactor, feature behind a clear interface, migration, tests) with a checkable done condition → \`worker\`. If you don't yet know *where* the change goes, send an \`explorer\` first.${orchestratorMode
+${memoryEnabled ? '- Need relevant persistent-memory context or memory maintenance → `librarian`.\n' : ''}- Have a cohesive, separable implementation or review unit with a checkable done condition → \`worker\`.${orchestratorMode
         ? `
 
-In Orchestrator mode, answer directly only when no tool-backed work is needed. Delegate workspace inspection, web research, file edits, shell work, and verification. For interactive back-and-forth with the user, respond directly. Only delegate once the next concrete unit of work is clear.
-
-**Coordination principles** — default to safe coordination over maximum parallelism:
-
-**Coordination checklist for coupled or multi-worker implementation:**
-
-For coupled or multi-worker implementation, identify before delegating:
-- Shared files or likely conflict points
-- Contracts/APIs/schemas/state flows that should remain stable
-- Which worker owns which files or modules
-- Files workers should treat as read-only, if relevant
-- Validation each worker should run
-- Stop conditions where a worker should report instead of guessing
-
-Include ownership and scope details naturally in each worker's task text — no rigid format required.
-
-Do not over-process simple single-worker tasks. A clear task, bounded scope, and validation command are enough.`
+In Orchestrator mode, directly inspect, edit, run commands, and test small or clear work when delegation has no meaningful leverage. Delegate for specialization, context compression, safe parallelism, or cohesive separable work. Delegation transfers execution, never outcome ownership: integrate results, follow up, correct errors, and finish the user outcome. Avoid concurrent overlapping edits; sequence coupled work and validate proportionately to its risk.`
         : `
 
 Otherwise, just do it yourself — especially when the task needs mid-flight course-correction, user back-and-forth, fuzzy judgment, or is the user's actual deliverable they expect to watch.`}`;
-    const planningStep = `**Before any \`run_subagent\` call, plan silently:**
-1. Restate the user's objective in one sentence.
-2. Decompose into sub-objectives (one item, or zero, are both valid).
-3. For each delegated sub-objective specify: **role**, **scoped task** (written for the subagent, not the user), **context to embed** (paths, symbols, prior findings, constraints, things ruled out), and **done condition**.
-
-"No delegation needed" is a legitimate conclusion. Don't delegate to justify having planned.
-
-**Task-field check:** if the \`task\` reads like a paraphrase of the user's message, if multiple subagents would get near-identical tasks, or if you can't state the done condition concretely — the delegation isn't ready. Rewrite, re-decompose, or investigate first.
+    const planningStep = `**Task framing:** Choose delegation deliberately; "no delegation needed" is a legitimate conclusion. The orchestrator decides where execution units begin and end. Workers retain autonomy over how to complete their assigned unit. Workers are autonomous agents with read, write, and shell access. Describe the goal, relevant context, and constraints—not implementation steps. A worker task should be one cohesive unit that can be understood, implemented, and verified without owning an entire multi-stage plan.
 
-**Task framing:** Workers are autonomous agents with read, write, and shell access. Describe the goal, relevant context, and constraints — not implementation steps. The worker will explore the code and choose its own approach. Over-specifying 'how' wastes context; specify 'what' and 'why'.`;
-    return `${header}\n\n${triggers}\n\n${planningStep}\n\n${getSubagentsRolesSection()}`;
+Do not repeat automatically supplied context: role instructions, generic tool guidance, worktree hygiene, environment metadata, root \`AGENTS.md\`, or skills catalog. The subagent does not see your conversation or reasoning, so include only objective, task-specific scope, non-discoverable parent findings or decisions, constraints, deliverable or acceptance criteria, and validation when applicable.`;
+    return `${header}\n\n${triggers}\n\n${planningStep}\n\n${getSubagentsRolesSection({
+        includeLibrarian: memoryEnabled,
+    })}`;
 }
 //# sourceMappingURL=subagent-delegation.js.map

package/dist/prompts/subagent-delegation.js.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-delegation.js","sourceRoot":"","sources":["../../source/prompts/subagent-delegation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,EAC5C,gBAAgB,GAAG,KAAK,GACzB,GAAmC,EAAE;IACpC,MAAM,MAAM,GAAG;;mKAEkJ,CAAC;IAElK,MAAM,QAAQ,GAAG;;;;oOAKf,gBAAgB;QACd,CAAC,CAAC;;;;;;;;;;;;;;;;;;gHAkBwG;QAC1G,CAAC,CAAC;;6LAGN,EAAE,CAAC;IAEH,MAAM,YAAY,GAAG;;;;;;;;;mSAS4Q,CAAC;IAElS,OAAO,GAAG,MAAM,OAAO,QAAQ,OAAO,YAAY,OAAO,wBAAwB,EAAE,EAAE,CAAC;AACxF,CAAC"}
+{"version":3,"file":"subagent-delegation.js","sourceRoot":"","sources":["../../source/prompts/subagent-delegation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,EAC5C,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,IAAI,GACrB,GAA4D,EAAE;IAC7D,MAAM,MAAM,GAAG;;mKAEkJ,CAAC;IAElK,MAAM,QAAQ,GAAG;;;;EAKjB,aAAa,CAAC,CAAC,CAAC,kFAAkF,CAAC,CAAC,CAAC,EACvG,2GACI,gBAAgB;QACd,CAAC,CAAC;;6cAEqc;QACvc,CAAC,CAAC;;6LAGN,EAAE,CAAC;IAEH,MAAM,YAAY,GAAG;;iZAE0X,CAAC;IAEhZ,OAAO,GAAG,MAAM,OAAO,QAAQ,OAAO,YAAY,OAAO,wBAAwB,CAAC;QAChF,gBAAgB,EAAE,aAAa;KAChC,CAAC,EAAE,CAAC;AACP,CAAC"}

package/dist/prompts/subagent-delegation.test.ts

@@ -10,11 +10,13 @@ it('getSubagentDelegationAddendum returns non-empty delegation guidance', () =>
   expect(result.includes('run_subagent')).toBe(true);
 });
 
-it('getSubagentDelegationAddendum includes orchestrator-specific text when orchestratorMode is true', () => {
+it('getSubagentDelegationAddendum gives orchestrators adaptive delegation and direct-work guidance', () => {
   const result = getSubagentDelegationAddendum({ orchestratorMode: true });
 
   expect(result.includes('Orchestrator mode')).toBe(true);
-  expect(result.includes('Delegate workspace inspection')).toBe(true);
+  expect(result).toContain('Delegate when it provides meaningful leverage');
+  expect(result).toContain('directly inspect, edit, run commands, and test small or clear work');
+  expect(result).not.toContain('Delegate workspace inspection');
 });
 
 it('getSubagentDelegationAddendum includes self-service fallback when orchestratorMode is false', () => {
@@ -23,36 +25,48 @@ it('getSubagentDelegationAddendum includes self-service fallback when orchestrat
   expect(result.includes('just do it yourself')).toBe(true);
 });
 
-it('orchestrator mode includes safe coordination guidance', () => {
+it('orchestrator mode protects outcome ownership and safe coordination', () => {
   const result = getSubagentDelegationAddendum({ orchestratorMode: true });
-  expect(result.includes('safe coordination over maximum parallelism')).toBe(true);
+  expect(result).toContain('Delegation transfers execution, never outcome ownership');
+  expect(result).toContain('Avoid concurrent overlapping edits');
+  expect(result).not.toContain('Coordination checklist');
+  expect(result).not.toContain('First delegate investigation');
 });
 
-it('orchestrator mode includes coupled or multi-worker language', () => {
-  const result = getSubagentDelegationAddendum({ orchestratorMode: true });
-  expect(result.includes('coupled or multi-worker')).toBe(true);
+it('includes task framing guidance about autonomous workers', () => {
+  const result = getSubagentDelegationAddendum();
+  expect(result.includes('Task framing')).toBe(true);
+  expect(result.includes('autonomous agents')).toBe(true);
+  expect(result.includes('goal, relevant context, and constraints')).toBe(true);
+  expect(result.includes('not implementation steps')).toBe(true);
 });
 
-it('orchestrator mode includes ownership language', () => {
-  const result = getSubagentDelegationAddendum({ orchestratorMode: true });
-  expect(result.includes('Which worker owns')).toBe(true);
+it('requires task-specific context without repeating automatically supplied context', () => {
+  const result = getSubagentDelegationAddendum();
+
+  expect(result).toContain(
+    'Do not repeat automatically supplied context: role instructions, generic tool guidance, worktree hygiene, environment metadata, root `AGENTS.md`, or skills catalog.',
+  );
+  expect(result).toContain(
+    'objective, task-specific scope, non-discoverable parent findings or decisions, constraints',
+  );
+  expect(result).toContain('deliverable or acceptance criteria, and validation when applicable');
+  expect(result).toContain('The subagent does not see your conversation or reasoning');
 });
 
-it('orchestrator mode says not to over-process simple single-worker tasks', () => {
+it('retains worker autonomy without mandatory pre-delegation ceremony', () => {
   const result = getSubagentDelegationAddendum({ orchestratorMode: true });
-  expect(result.includes('Do not over-process')).toBe(true);
+  expect(result.includes('one cohesive unit that can be understood, implemented, and verified')).toBe(true);
+  expect(result.includes('The orchestrator decides where execution units begin and end')).toBe(true);
+  expect(result).not.toContain('Before any `run_subagent` call, plan silently');
 });
 
-it('non-orchestrator mode does not include coordination checklist', () => {
-  const result = getSubagentDelegationAddendum({ orchestratorMode: false });
-  expect(result.includes('coupled or multi-worker')).toBe(false);
-  expect(result.includes('Coordination checklist')).toBe(false);
+it('includes librarian delegation trigger when persistent memory is enabled', () => {
+  const result = getSubagentDelegationAddendum({ memoryEnabled: true });
+  expect(result.includes('librarian')).toBe(true);
 });
 
-it('includes task framing guidance about autonomous workers', () => {
-  const result = getSubagentDelegationAddendum();
-  expect(result.includes('Task framing')).toBe(true);
-  expect(result.includes('autonomous agents')).toBe(true);
-  expect(result.includes('goal, relevant context, and constraints')).toBe(true);
-  expect(result.includes('not implementation steps')).toBe(true);
+it('does not advertise the librarian when persistent memory is disabled', () => {
+  const result = getSubagentDelegationAddendum({ memoryEnabled: false });
+  expect(result.includes('librarian')).toBe(false);
 });

package/dist/prompts/subagent-delegation.ts

@@ -8,51 +8,33 @@ import { getSubagentsRolesSection } from '../tools/agent/run-subagent.js';
  */
 export function getSubagentDelegationAddendum({
   orchestratorMode = false,
-}: { orchestratorMode?: boolean } = {}): string {
+  memoryEnabled = true,
+}: { orchestratorMode?: boolean; memoryEnabled?: boolean } = {}): string {
   const header = `### Delegating to subagents
 
 You have a \`run_subagent\` tool. A subagent runs in its own context and returns only a summary — use it to keep your own context focused on high-level reasoning.`;
 
-  const triggers = `**Delegate when:**
-- Spans more than ~2 files, or "where is / how does X work" → \`explorer\`.
+  const triggers = `**Delegate when it provides meaningful leverage:**
+- Need focused codebase investigation or context compression → \`explorer\`.
 - Needs online info (library docs, current best practices, version-specific behavior) → \`researcher\`.
 - About to commit to a non-trivial plan or tricky debugging direction and want it pressure-tested → \`mentor\`.
-- Scoped, verifiable unit of work (bug fix, refactor, feature behind a clear interface, migration, tests) with a checkable done condition → \`worker\`. If you don't yet know *where* the change goes, send an \`explorer\` first.${
+${
+  memoryEnabled ? '- Need relevant persistent-memory context or memory maintenance → `librarian`.\n' : ''
+}- Have a cohesive, separable implementation or review unit with a checkable done condition → \`worker\`.${
     orchestratorMode
       ? `
 
-In Orchestrator mode, answer directly only when no tool-backed work is needed. Delegate workspace inspection, web research, file edits, shell work, and verification. For interactive back-and-forth with the user, respond directly. Only delegate once the next concrete unit of work is clear.
-
-**Coordination principles** — default to safe coordination over maximum parallelism:
-
-**Coordination checklist for coupled or multi-worker implementation:**
-
-For coupled or multi-worker implementation, identify before delegating:
-- Shared files or likely conflict points
-- Contracts/APIs/schemas/state flows that should remain stable
-- Which worker owns which files or modules
-- Files workers should treat as read-only, if relevant
-- Validation each worker should run
-- Stop conditions where a worker should report instead of guessing
-
-Include ownership and scope details naturally in each worker's task text — no rigid format required.
-
-Do not over-process simple single-worker tasks. A clear task, bounded scope, and validation command are enough.`
+In Orchestrator mode, directly inspect, edit, run commands, and test small or clear work when delegation has no meaningful leverage. Delegate for specialization, context compression, safe parallelism, or cohesive separable work. Delegation transfers execution, never outcome ownership: integrate results, follow up, correct errors, and finish the user outcome. Avoid concurrent overlapping edits; sequence coupled work and validate proportionately to its risk.`
       : `
 
 Otherwise, just do it yourself — especially when the task needs mid-flight course-correction, user back-and-forth, fuzzy judgment, or is the user's actual deliverable they expect to watch.`
   }`;
 
-  const planningStep = `**Before any \`run_subagent\` call, plan silently:**
-1. Restate the user's objective in one sentence.
-2. Decompose into sub-objectives (one item, or zero, are both valid).
-3. For each delegated sub-objective specify: **role**, **scoped task** (written for the subagent, not the user), **context to embed** (paths, symbols, prior findings, constraints, things ruled out), and **done condition**.
-
-"No delegation needed" is a legitimate conclusion. Don't delegate to justify having planned.
-
-**Task-field check:** if the \`task\` reads like a paraphrase of the user's message, if multiple subagents would get near-identical tasks, or if you can't state the done condition concretely — the delegation isn't ready. Rewrite, re-decompose, or investigate first.
+  const planningStep = `**Task framing:** Choose delegation deliberately; "no delegation needed" is a legitimate conclusion. The orchestrator decides where execution units begin and end. Workers retain autonomy over how to complete their assigned unit. Workers are autonomous agents with read, write, and shell access. Describe the goal, relevant context, and constraints—not implementation steps. A worker task should be one cohesive unit that can be understood, implemented, and verified without owning an entire multi-stage plan.
 
-**Task framing:** Workers are autonomous agents with read, write, and shell access. Describe the goal, relevant context, and constraints — not implementation steps. The worker will explore the code and choose its own approach. Over-specifying 'how' wastes context; specify 'what' and 'why'.`;
+Do not repeat automatically supplied context: role instructions, generic tool guidance, worktree hygiene, environment metadata, root \`AGENTS.md\`, or skills catalog. The subagent does not see your conversation or reasoning, so include only objective, task-specific scope, non-discoverable parent findings or decisions, constraints, deliverable or acceptance criteria, and validation when applicable.`;
 
-  return `${header}\n\n${triggers}\n\n${planningStep}\n\n${getSubagentsRolesSection()}`;
+  return `${header}\n\n${triggers}\n\n${planningStep}\n\n${getSubagentsRolesSection({
+    includeLibrarian: memoryEnabled,
+  })}`;
 }

package/dist/prompts/subagents/librarian.md

@@ -0,0 +1,61 @@
+---
+name: Memory Librarian
+description: memory reasoning agent. Use for retrieving context from persistent memory and recommending memory maintenance.
+model: inherit
+provider: inherit
+canRead: false
+canWrite: false
+canSearchWeb: false
+canRunShell: false
+maxTurns: 40
+---
+
+You are the memory librarian — the specialist other agents consult when they encounter uncertainty about prior knowledge. Your job is to find, synthesize, and organize relevant memories efficiently.
+
+You are the memory librarian. Your job is to turn raw stored memories into useful context for the calling agent. You access memory only through the public memory tools and operate under the same runtime constraints as any other subagent.
+
+## Capabilities
+
+You have read and write access to persistent memory through the public memory API: `memory_list`, `memory_get`, `memory_search`, `memory_retrieve`, `memory_create`, `memory_update`, `memory_delete`. You have no filesystem, shell, or web access — your sole tools are the memory tools and `activate_skill`.
+
+## What you are asked to do
+
+You may receive one of two types of requests:
+
+### Context retrieval
+
+Interpret the task or question, search memory broadly, read the most promising items in full, discard irrelevant material, identify contradictions or stale information, and return a compact context brief with references to the source memory IDs.
+
+Your approach:
+1. Retrieve from multiple angles with `memory_retrieve` — try synonyms, module names, and related concepts as separate queries.
+2. Use `memory_search` and `memory_get` when you need to inspect ranking or load a specific item. Summaries can omit crucial details.
+3. Judge each item against the task. Discard the irrelevant.
+4. Flag contradictions between memories and anything that looks stale.
+5. Return a brief. Include:
+   - A concise synthesis of the most relevant findings
+   - Contradictions or staleness, explicitly flagged
+   - Source memory IDs for every claim
+   - Items considered but discarded, with a one-line reason
+
+Do not mutate memory during a retrieval task. If you find knowledge worth persisting or correcting, note it in your report for the caller.
+
+### Memory maintenance
+
+Review the existing memory store and any new information provided. Identify duplication, conflict, and staleness. Recommend whether to create, update, merge, retain, or delete memory items.
+
+Your approach:
+1. Search and list the current memory store.
+2. Read full content of existing memories.
+3. Propose specific actions: create, update, merge, retain, or delete — with rationale and source IDs.
+4. Present your recommendations as a **reviewable proposal**.
+
+By default, **propose only — do not execute mutations.** Only perform mutations through `memory_create`, `memory_update`, or `memory_delete` when the task explicitly asks you to apply the recommendations. Every mutation must be explained in your final report with the memory ID and what changed.
+
+## Principles
+
+- Always cite source memory IDs. The caller must be able to trace every claim.
+- Treat all memory as potentially stale.
+- Never fabricate memory content. If you cannot find relevant memory, say so.
+- Do not store temporary task state, intermediate reasoning, or sensitive data.
+- When merging, preserve information from all sources — do not silently drop content.
+- Keep your output concise. The caller needs a brief, not a dump.

package/dist/prompts/subagents/mentor-mode.md

@@ -1,20 +1,16 @@
-You are a senior architect acting as a peer reviewer for an AI coding assistant (the "Assistant"). The Assistant has the eyes and hands: it explores the codebase, runs tools, and makes changes on behalf of a human user. You do not—you rely entirely on what the Assistant reports to you.
+You are a strategic engineering mentor. Your job is to improve the executor's reasoning, not to approve or reject by default.
 
 Three participants exist, and you only ever speak to the Assistant:
 - **You (Mentor)**: strategic advisor and reviewer. No codebase, tool, or file access.
 - **Assistant**: relays the user's goal, its findings, proposed approach, and confidence level.
 - **User (human)**: owns the requirements. You never address them directly; the Assistant handles requirement clarifications.
 
-Your role is adversarial review, not rubber-stamping:
-- Challenge the Assistant's assumptions, even when its reasoning sounds solid
-- Probe for gaps: what did it not check? What could go wrong?
-- Suggest alternatives it may have dismissed too quickly
-- Ask the Assistant for specific evidence (file paths, code snippets, tool output) when its confidence seems misplaced
+Do not be agreeable for politeness. Do not be skeptical for performance. Calibrate your response to the evidence provided.
 
-Scale your scrutiny to the Assistant's stated confidence and the risk of the change—push hardest on Low-confidence, high-impact, or architectural decisions.
+If the plan is sound, say so and point out the one or two risks worth watching.
+If the plan is weak, explain the highest-impact flaw and what evidence is needed.
+If information is insufficient, ask for the minimum additional evidence needed to decide.
 
-Remember the Assistant is the only one who can actually see the code. If it pushes back with concrete evidence that contradicts your assumption, weigh that seriously rather than insisting.
+Never invent codebase facts. Treat all repo-specific claims as unknown unless provided by the executor.
 
-When satisfied, give clear approval with specific next steps. When not, say exactly what the Assistant needs to investigate or report back.
-
-Be concise. Push back hard, but don't block unnecessarily.
+Be concise.

package/dist/prompts/subagents/mentor.md

@@ -10,16 +10,14 @@ canRunShell: false
 maxTurns: 1
 ---
 
-You are a senior architect acting as a peer reviewer for an AI coding assistant (the "Assistant"). The Assistant has the eyes and hands: it explores the codebase, runs tools, and makes changes on behalf of a human user. You do not—you rely entirely on what the Assistant reports to you.
+You are a strategic engineering mentor. Your job is to improve the executor's reasoning, not to approve or reject by default.
 
-Your role is adversarial review, not rubber-stamping:
-- Challenge the Assistant's assumptions, even when its reasoning sounds solid
-- Probe for gaps: what did it not check? What could go wrong?
-- Suggest alternatives it may have dismissed too quickly
-- Ask the Assistant for specific evidence (file paths, code snippets, tool output) when its confidence seems misplaced
+Do not be agreeable for politeness. Do not be skeptical for performance. Calibrate your response to the evidence provided.
 
-Remember the Assistant is the only one who can actually see the code. If it pushes back with concrete evidence that contradicts your assumption, weigh that seriously rather than insisting.
+If the plan is sound, say so and point out the one or two risks worth watching.
+If the plan is weak, explain the highest-impact flaw and what evidence is needed.
+If information is insufficient, ask for the minimum additional evidence needed to decide.
 
-When satisfied, give clear approval with specific next steps. When not, say exactly what the Assistant needs to investigate or report back.
+Never invent codebase facts. Treat all repo-specific claims as unknown unless provided by the executor.
 
-Be concise. Push back hard, but don't block unnecessarily.
+Be concise.

package/dist/providers/chained-wire-state.d.ts

@@ -0,0 +1,92 @@
+export type ChainedWireStateKey = string;
+export type ChainedRequestToken = string;
+/**
+ * Protocol that a provider implements to plug into the chained-wire state
+ * machine. Each method encapsulates a provider-specific concern so the
+ * state machine itself stays transport- and model-agnostic.
+ */
+export interface ChainedWireProtocol {
+    /** Extract the logical input array from a prepared request object. */
+    getInput(requestData: Record<string, unknown>): unknown[];
+    /** Extract the `previous_response_id` carried by the request, if any. */
+    getPreviousResponseId(requestData: Record<string, unknown>): string | undefined;
+    /**
+     * Compute a stable fingerprint for a request. Two requests whose fingerprint
+     * differs are treated as belonging to incompatible chains and will never
+     * produce a delta from the same stored state.
+     */
+    getFingerprint(requestData: Record<string, unknown>, input: unknown[]): string;
+    /**
+     * Extract the reusable prefix from the input. When the full baseline does
+     * not match (e.g. because the provider already holds earlier history), the
+     * prefix acts as a fallback anchor: everything after the prefix becomes the
+     * delta.
+     */
+    getPrefix(input: unknown[]): unknown[];
+    /**
+     * Normalize output items before they are stored for later replay matching.
+     * This typically strips server-assigned ids so that the replayed items in a
+     * subsequent request match the stored canonical form.
+     */
+    normalizeOutputItems(items: unknown[]): unknown[];
+}
+/** Result of preparing a request for the wire. */
+export interface PreparedChainedRequest {
+    /**
+     * The request data that should be sent. When `usedDelta` is true, the
+     * `input` field has been trimmed to only the items the server does not
+     * already hold.
+     */
+    requestData: Record<string, unknown>;
+    /** Whether a delta was computed from stored state. */
+    usedDelta: boolean;
+    /** Correlation token that pairs this preparation with a future `recordResponse` call. */
+    token: ChainedRequestToken;
+}
+/**
+ * Provider-neutral state machine for chained-wire (delta) requests.
+ *
+ * Keeps the canonical request separate from the smaller payload sent over a
+ * reused response chain. The caller may provide either the full logical input
+ * or a server-managed delta. Strict baseline matching is preferred; prefix
+ * matching is the safe fallback for requests whose older history is already
+ * held by the provider.
+ *
+ * Requests are correlated by an opaque token so that multiple concurrent
+ * requests under the same key can be tracked independently even when their
+ * responses arrive out of order.
+ */
+export declare class ChainedWireState {
+    private readonly protocol;
+    private readonly stored;
+    private readonly pending;
+    private nextSequence;
+    constructor(protocol: ChainedWireProtocol);
+    /**
+     * Prepare a request for the wire.
+     *
+     * Stores the request as pending so a future `recordResponse` call can
+     * correlate it. If a stored response chain exists for the same key and the
+     * fingerprints and `previous_response_id` match, the request input is
+     * trimmed to a delta.
+     */
+    prepare(key: ChainedWireStateKey, token: ChainedRequestToken, requestData: Record<string, unknown>): PreparedChainedRequest;
+    /**
+     * Record a completed response so it can be used for delta computation in
+     * future requests on the same key.
+     */
+    recordResponse(key: ChainedWireStateKey, token: ChainedRequestToken, responseId: string, outputItems: unknown[]): void;
+    /**
+     * Stop tracking a request that ended without an acknowledged response.
+     */
+    abandon(key: ChainedWireStateKey, token: ChainedRequestToken): void;
+    /**
+     * Remove all state (stored and pending) for a single key.
+     */
+    invalidate(key: ChainedWireStateKey): void;
+    /**
+     * Remove all state across every key. Safe to call on an empty instance.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=chained-wire-state.d.ts.map

package/dist/providers/chained-wire-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chained-wire-state.d.ts","sourceRoot":"","sources":["../../source/providers/chained-wire-state.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;IAE1D,yEAAyE;IACzE,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;IAEhF;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE/E;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IAEvC;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;CACnD;AAED,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,yFAAyF;IACzF,KAAK,EAAE,mBAAmB,CAAC;CAC5B;AA8BD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAKf,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiD;IACxE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4E;IACpG,OAAO,CAAC,YAAY,CAAK;IAEzB,YAA6B,QAAQ,EAAE,mBAAmB,EAAI;IAE9D;;;;;;;OAOG;IACH,OAAO,CACL,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,mBAAmB,EAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,sBAAsB,CAiDxB;IAED;;;OAGG;IACH,cAAc,CACZ,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,mBAAmB,EAC1B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,EAAE,GACrB,IAAI,CAmBN;IAED;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAQlE;IAED;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAGzC;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAGZ;CACF"}

package/dist/providers/chained-wire-state.js

@@ -0,0 +1,136 @@
+import deepEqual from 'fast-deep-equal';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function startsWith(input, prefix) {
+    if (prefix.length > input.length)
+        return false;
+    return prefix.every((item, index) => deepEqual(item, input[index]));
+}
+// ---------------------------------------------------------------------------
+// Public class
+// ---------------------------------------------------------------------------
+/**
+ * Provider-neutral state machine for chained-wire (delta) requests.
+ *
+ * Keeps the canonical request separate from the smaller payload sent over a
+ * reused response chain. The caller may provide either the full logical input
+ * or a server-managed delta. Strict baseline matching is preferred; prefix
+ * matching is the safe fallback for requests whose older history is already
+ * held by the provider.
+ *
+ * Requests are correlated by an opaque token so that multiple concurrent
+ * requests under the same key can be tracked independently even when their
+ * responses arrive out of order.
+ */
+export class ChainedWireState {
+    protocol;
+    stored = new Map();
+    pending = new Map();
+    nextSequence = 0;
+    constructor(protocol) {
+        this.protocol = protocol;
+    }
+    /**
+     * Prepare a request for the wire.
+     *
+     * Stores the request as pending so a future `recordResponse` call can
+     * correlate it. If a stored response chain exists for the same key and the
+     * fingerprints and `previous_response_id` match, the request input is
+     * trimmed to a delta.
+     */
+    prepare(key, token, requestData) {
+        const input = this.protocol.getInput(requestData);
+        const fingerprint = this.protocol.getFingerprint(requestData, input);
+        // Book the pending slot so recordResponse can correlate later.
+        let keyPending = this.pending.get(key);
+        if (!keyPending) {
+            keyPending = new Map();
+            this.pending.set(key, keyPending);
+        }
+        const existingPending = keyPending.get(token);
+        keyPending.set(token, {
+            fingerprint,
+            input: [...input],
+            sequence: existingPending?.sequence ?? this.nextSequence++,
+        });
+        const previousResponseId = this.protocol.getPreviousResponseId(requestData);
+        const stored = this.stored.get(key);
+        // No stored chain, missing previous_response_id, or stale response id →
+        // full request.
+        if (!stored || !previousResponseId || stored.responseId !== previousResponseId) {
+            return { requestData, usedDelta: false, token };
+        }
+        // Fingerprint changed → incompatible chain, full request.
+        if (stored.fingerprint !== fingerprint) {
+            return { requestData, usedDelta: false, token };
+        }
+        // Try exact baseline match first.
+        const baseline = [...stored.input, ...stored.outputItems];
+        const prefix = this.protocol.getPrefix(input);
+        const delta = startsWith(input, baseline)
+            ? input.slice(baseline.length)
+            : startsWith(input, prefix)
+                ? input.slice(prefix.length)
+                : null;
+        if (delta === null) {
+            return { requestData, usedDelta: false, token };
+        }
+        return {
+            requestData: { ...requestData, input: delta },
+            usedDelta: true,
+            token,
+        };
+    }
+    /**
+     * Record a completed response so it can be used for delta computation in
+     * future requests on the same key.
+     */
+    recordResponse(key, token, responseId, outputItems) {
+        const keyPending = this.pending.get(key);
+        if (!keyPending)
+            return;
+        const pending = keyPending.get(token);
+        if (!pending)
+            return;
+        const stored = this.stored.get(key);
+        if (!stored || pending.sequence > stored.sequence) {
+            this.stored.set(key, {
+                ...pending,
+                responseId,
+                outputItems: Array.isArray(outputItems) ? this.protocol.normalizeOutputItems(outputItems) : [],
+            });
+        }
+        keyPending.delete(token);
+        if (keyPending.size === 0) {
+            this.pending.delete(key);
+        }
+    }
+    /**
+     * Stop tracking a request that ended without an acknowledged response.
+     */
+    abandon(key, token) {
+        const keyPending = this.pending.get(key);
+        if (!keyPending)
+            return;
+        keyPending.delete(token);
+        if (keyPending.size === 0) {
+            this.pending.delete(key);
+        }
+    }
+    /**
+     * Remove all state (stored and pending) for a single key.
+     */
+    invalidate(key) {
+        this.stored.delete(key);
+        this.pending.delete(key);
+    }
+    /**
+     * Remove all state across every key. Safe to call on an empty instance.
+     */
+    clear() {
+        this.stored.clear();
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=chained-wire-state.js.map

package/dist/providers/chained-wire-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chained-wire-state.js","sourceRoot":"","sources":["../../source/providers/chained-wire-state.ts"],"names":[],"mappings":"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"}

package/dist/providers/codex-responses-model.d.ts

@@ -1,5 +1,6 @@
 import { OpenAIResponsesModel, OpenAIResponsesWSModel } from '@openai/agents-openai';
 import type { ISessionContextService, IProviderTraffic } from '../services/service-interfaces.js';
+import { type WebSocketReceiveTimeouts } from './websocket-receive-watchdog.js';
 type DiagnosticLogger = {
     debug?: (message: string, meta?: Record<string, unknown>) => void;
     warn?: (message: string, meta?: Record<string, unknown>) => void;
@@ -7,21 +8,27 @@ type DiagnosticLogger = {
 };
 export declare class CodexResponsesWSModel extends OpenAIResponsesWSModel {
     #private;
+    private readonly modelId;
     private readonly tokenManager;
     private readonly diagnosticLogger?;
     private readonly sessionContextService?;
+    private readonly websocketReceiveTimeouts;
     private readonly codexPreviousResponseIds;
     private readonly codexConsumedToolResultCallIdsByResponseId;
+    private readonly codexTurnIdsBySession;
     private readonly providerTraffic;
-    constructor(client: any, model: string, tokenManager: any, diagnosticLogger?: DiagnosticLogger | undefined, providerTraffic?: IProviderTraffic, sessionContextService?: ISessionContextService | undefined);
+    private readonly chainedWireState;
+    private readonly requestTokens;
+    constructor(client: any, modelId: string, tokenManager: any, diagnosticLogger?: DiagnosticLogger | undefined, providerTraffic?: IProviderTraffic, sessionContextService?: ISessionContextService | undefined, websocketReceiveTimeouts?: WebSocketReceiveTimeouts);
     getResponse(request: any): Promise<any>;
     getStreamedResponse(request: any): AsyncIterable<any>;
     _buildResponsesCreateRequest(request: any, stream: boolean): any;
     protected _fetchResponse(request: any, stream: boolean): Promise<any>;
 }
 export declare class CodexResponsesModel extends OpenAIResponsesModel {
+    private readonly modelId;
     private readonly diagnosticLogger?;
-    constructor(client: any, model: string, diagnosticLogger?: DiagnosticLogger | undefined);
+    constructor(client: any, modelId: string, diagnosticLogger?: DiagnosticLogger | undefined);
     _buildResponsesCreateRequest(request: any, stream: boolean): any;
     protected _fetchResponse(request: any, stream: boolean): Promise<any>;
 }