@namzu/sdk 2.0.0 → 3.0.0

package/dist/types/agent/router.d.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from '../common/index.js';
 import type { LLMProvider } from '../provider/index.js';
 import type { BaseAgentConfig, BaseAgentResult } from './base.js';
 import type { Agent } from './core.js';
@@ -7,6 +8,16 @@ export interface RoutingDecision {
     confidence: number;
     reasoning?: string;
     routingSource: RoutingDecisionSource;
+    /**
+     * Tokens the routing call itself spent, summed over any retries.
+     *
+     * Routing runs before the delegate's run exists, so it has no
+     * `RunPersistence` to accumulate into. Reporting it here lets the
+     * router fold it into the result it returns, instead of the caller
+     * seeing only the delegate's usage and under-reporting every routed
+     * run by one model call.
+     */
+    usage?: TokenUsage;
 }
 export interface RouteDefinition {
     agentId: string;

package/dist/types/agent/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/types/agent/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAEtC,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAA;AAEzE,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,qBAAqB,CAAA;CACpC;AAED,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,CAAA;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACzD,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,QAAQ,EAAE,WAAW,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACzD,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,eAAe,CAAA;IAChC,cAAc,EAAE,eAAe,CAAA;CAC/B"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/types/agent/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAEtC,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAA;AAEzE,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,qBAAqB,CAAA;IACpC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,CAAA;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACzD,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,QAAQ,EAAE,WAAW,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACzD,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,eAAe,CAAA;IAChC,cAAc,EAAE,eAAe,CAAA;CAC/B"}

package/dist/types/agent/supervisor.d.ts

@@ -28,8 +28,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
      * Optional human-in-the-loop hook for tool review and run-pause
      * decisions. When omitted, the supervisor delegates to drainQuery's
      * built-in `autoApproveHandler`, which approves every tool call
-     * without prompting — matching Anthropic's "Act without asking"
-     * cowork mode.
+     * without prompting — the unattended mode, where the run is expected
+     * to finish without a human at the keyboard.
      *
      * Hosts that want "Ask before acting" behaviour pass a custom
      * handler that surfaces the `tool_review_requested` RunEvent to

package/dist/types/agent/task.d.ts

@@ -64,6 +64,17 @@ export interface AgentTask {
     state: AgentTaskState;
     result?: BaseAgentResult;
     progress?: AgentTaskProgress;
+    /**
+     * Tokens reserved from the shared pool when this child was spawned.
+     *
+     * A RESERVATION, not a spend: it is subtracted up front so siblings
+     * cannot each be promised the same headroom, and the unused part is
+     * returned when the child settles. Without the return, a pool shrank
+     * by the full allocation every spawn regardless of what the child
+     * actually used, so a long session ran out of budget while almost none
+     * of it had been spent.
+     */
+    budgetReservation?: number;
     pendingMessages: Message[];
     createdAt: number;
     completedAt?: number;
@@ -108,5 +119,18 @@ export interface AgentManagerConfig {
     maxDepth: number;
     evictionMs: number;
     maxBudgetFraction: number;
+    /**
+     * Wall-clock deadline given to a spawned child when the caller supplies
+     * no `budgetAllocation.timeoutMs`.
+     *
+     * This exists because the fallback used to be
+     * `context.budgetTracker.remaining` — a TOKEN count read as
+     * milliseconds. The unit error hid for so long because a typical
+     * six-figure token budget lands in a plausible-looking range of
+     * milliseconds; it only bites at the edges, where an unlimited budget
+     * (`0`) became a zero-millisecond deadline and a small budget became a
+     * child that died in under a second.
+     */
+    childTimeoutMs: number;
 }
 //# sourceMappingURL=task.d.ts.map

package/dist/types/agent/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/types/agent/task.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/types/agent/task.ts"],"names":[],"mappings":"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"}

package/dist/types/bidi/index.d.ts

@@ -0,0 +1,140 @@
+import type { RunId } from '../ids/index.js';
+import type { LLMToolSchema } from '../tool/index.js';
+/**
+ * A conversation with no turn boundary.
+ *
+ * Every other seam in this kernel is turn-based by construction: a run
+ * has iterations, an iteration sends a complete message list and reads a
+ * stream back, and a checkpoint is taken between two of them. That shape
+ * is load-bearing everywhere it appears and it cannot describe a duplex
+ * session, where input keeps arriving while output is still being
+ * produced and "the turn" is not a thing either side can point at.
+ *
+ * So this is a second contract rather than a widening of the first. The
+ * alternative — bending `chatStream` until it accepts a live input
+ * channel — would put a half-duplex assumption inside every consumer of
+ * the turn-based path in exchange for a duplex path that still would not
+ * fit.
+ *
+ * What is here: the driver contract, the session loop that runs tools
+ * against it, and a scripted driver so both are exercised. What is NOT
+ * here, and deliberately: audio capture and playback, which belong to
+ * whatever owns the microphone, and checkpoint/resume, which has no
+ * meaning yet for a session whose state lives on the far side of a
+ * socket.
+ */
+export type BidiInput = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'audio';
+    readonly data: string;
+    readonly mediaType: string;
+};
+/**
+ * What the far side reports.
+ *
+ * `interrupted` is the event that makes this contract different from the
+ * turn-based one. In a duplex session the human can speak over the model,
+ * and everything the model was in the middle of — text it was emitting, a
+ * tool it just asked for — is now answering a question nobody is asking.
+ * A driver that cannot detect that never emits it and the loop behaves as
+ * if the model always finished what it started.
+ */
+export type BidiEvent = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'audio';
+    readonly data: string;
+    readonly mediaType: string;
+} | {
+    readonly type: 'tool_call';
+    readonly id: string;
+    readonly name: string;
+    /** JSON, as the model produced it. */
+    readonly arguments: string;
+}
+/** The model finished a stretch of output and is waiting. */
+ | {
+    readonly type: 'turn_complete';
+}
+/** The human spoke over the model; anything in flight is now stale. */
+ | {
+    readonly type: 'interrupted';
+} | {
+    readonly type: 'error';
+    readonly message: string;
+} | {
+    readonly type: 'closed';
+    readonly reason?: string;
+};
+export interface BidiConnectParams {
+    readonly model: string;
+    readonly system?: string;
+    readonly tools?: readonly LLMToolSchema[];
+    readonly signal?: AbortSignal;
+}
+export interface BidiSession {
+    /** Push input from the human. Never waits for the model to be idle. */
+    send(input: BidiInput): Promise<void>;
+    /**
+     * Answer a `tool_call`.
+     *
+     * Separate from {@link send} because it is not input from the human:
+     * a driver has to attach it to the call it answers, and a session that
+     * received it as ordinary input would have to guess.
+     */
+    sendToolResult(id: string, output: string, isError?: boolean): Promise<void>;
+    events(): AsyncIterable<BidiEvent>;
+    close(): Promise<void>;
+}
+export interface BidiProvider {
+    readonly id: string;
+    connect(params: BidiConnectParams): Promise<BidiSession>;
+}
+/** What the loop reports back to whoever is driving it. */
+export type BidiRunEvent = {
+    readonly type: 'text';
+    readonly runId: RunId;
+    readonly text: string;
+} | {
+    readonly type: 'audio';
+    readonly runId: RunId;
+    readonly data: string;
+    readonly mediaType: string;
+} | {
+    readonly type: 'tool_started';
+    readonly runId: RunId;
+    readonly toolUseId: string;
+    readonly toolName: string;
+} | {
+    readonly type: 'tool_completed';
+    readonly runId: RunId;
+    readonly toolUseId: string;
+    readonly toolName: string;
+    readonly output: string;
+    readonly isError: boolean;
+}
+/** A tool's answer was thrown away because the human interrupted. */
+ | {
+    readonly type: 'tool_abandoned';
+    readonly runId: RunId;
+    readonly toolUseId: string;
+    readonly toolName: string;
+} | {
+    readonly type: 'turn_complete';
+    readonly runId: RunId;
+} | {
+    readonly type: 'interrupted';
+    readonly runId: RunId;
+} | {
+    readonly type: 'error';
+    readonly runId: RunId;
+    readonly message: string;
+} | {
+    readonly type: 'closed';
+    readonly runId: RunId;
+    readonly reason?: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/bidi/index.d.ts.map

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

package/dist/types/bidi/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/bidi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/bidi/index.ts"],"names":[],"mappings":""}

package/dist/types/common/__tests__/numeric-correctness.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=numeric-correctness.test.d.ts.map

package/dist/types/common/__tests__/numeric-correctness.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-correctness.test.d.ts","sourceRoot":"","sources":["../../../../src/types/common/__tests__/numeric-correctness.test.ts"],"names":[],"mappings":""}

package/dist/types/common/__tests__/numeric-correctness.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { toolsHash } from '../../../connector/mcp/policy.js';
+import { mergeTokenUsage } from '../index.js';
+/**
+ * Arithmetic defects, each pinned by the exact counterexample that proves it.
+ * A test here is only worth having if it fails against the old formula, so
+ * every one names the number the old code produced.
+ */
+describe('mergeTokenUsage — totalTokens is derived, not independent', () => {
+    it('does not lose the completion tokens Anthropic reports in a later frame', () => {
+        // A driver reports the input on `message_start` and the output on
+        // `message_delta`. The driver derives each frame's own total as
+        // input+output, so the two frames carry 1200 and 350 — and a max of
+        // those returns the larger COMPONENT, not the sum.
+        const messageStart = {
+            promptTokens: 1200,
+            completionTokens: 0,
+            totalTokens: 1200,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        const messageDelta = {
+            promptTokens: 0,
+            completionTokens: 350,
+            totalTokens: 350,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        const merged = mergeTokenUsage(messageStart, messageDelta);
+        expect(merged.promptTokens).toBe(1200);
+        expect(merged.completionTokens).toBe(350);
+        // Old formula: Math.max(1200, 350) = 1200. Every completion token was
+        // invisible to the budget hard stop, which reads only totalTokens.
+        expect(merged.totalTokens).toBe(1550);
+    });
+    it('holds for the minimal case too', () => {
+        const a = {
+            promptTokens: 1,
+            completionTokens: 0,
+            totalTokens: 1,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        const b = {
+            promptTokens: 0,
+            completionTokens: 1,
+            totalTokens: 1,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        expect(mergeTokenUsage(a, b).totalTokens).toBe(2);
+    });
+    it('never under-reports a provider total that exceeds prompt + completion', () => {
+        // Some providers count tokens the two components do not cover. The
+        // merge must be monotone: it may never return less than what was
+        // reported.
+        const reported = {
+            promptTokens: 10,
+            completionTokens: 5,
+            totalTokens: 99,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        const empty = {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        expect(mergeTokenUsage(reported, empty).totalTokens).toBe(99);
+    });
+    it('is idempotent, so re-merging a frame cannot inflate the total', () => {
+        const usage = {
+            promptTokens: 1200,
+            completionTokens: 350,
+            totalTokens: 1550,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        };
+        expect(mergeTokenUsage(usage, usage).totalTokens).toBe(1550);
+        expect(mergeTokenUsage(mergeTokenUsage(usage, usage), usage).totalTokens).toBe(1550);
+    });
+});
+describe('toolsHash — the fingerprint covers what the HITL gate reads', () => {
+    const tool = (annotations) => ({
+        name: 'delete_rows',
+        description: 'Delete rows',
+        inputSchema: { type: 'object', properties: {} },
+        ...(annotations ? { annotations } : {}),
+    });
+    it('notices a server flipping destructive to read-only', () => {
+        // `annotations` becomes `isDestructive` / `isReadOnly` on the tool
+        // definition, and those drive whether a human reviews the call. A
+        // fingerprint that ignores them cannot see the exact rug-pull it was
+        // built to catch: same name, same schema, no longer reviewed.
+        const before = toolsHash([tool({ destructiveHint: true, readOnlyHint: false })]);
+        const after = toolsHash([tool({ destructiveHint: false, readOnlyHint: true })]);
+        expect(after).not.toBe(before);
+    });
+    it('notices annotations appearing where there were none', () => {
+        expect(toolsHash([tool()])).not.toBe(toolsHash([tool({ readOnlyHint: true })]));
+    });
+    it('is still stable for an unchanged tool', () => {
+        expect(toolsHash([tool({ destructiveHint: true })])).toBe(toolsHash([tool({ destructiveHint: true })]));
+    });
+});
+//# sourceMappingURL=numeric-correctness.test.js.map

package/dist/types/common/__tests__/numeric-correctness.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-correctness.test.js","sourceRoot":"","sources":["../../../../src/types/common/__tests__/numeric-correctness.test.ts"],"names":[],"mappings":"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"}

package/dist/types/common/index.d.ts

@@ -11,7 +11,7 @@ export declare function accumulateTokenUsage(current: TokenUsage, addition: Toke
 /**
  * Merge two usage snapshots seen WITHIN a single streamed turn. Provider usage
  * frames over one stream are cumulative/monotonic (input set once early, output
- * grows), but a late frame can OMIT a field (report 0) — e.g. Anthropic's
+ * grows), but a late frame can OMIT a field (report 0) — e.g. a
  * `message_delta` may carry only output tokens. A naive last-write-wins
  * (`usage = chunk.usage`) then drops the earlier prompt/cache counts and
  * under-reports the turn. Taking the per-field high-water mark preserves every

package/dist/types/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/common/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE/F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED,MAAM,WAAW,UAAU;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,CAQ1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAQjF;AAED,MAAM,WAAW,QAAQ;IACxB,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,SAAS,EAAE,OAAO,CAAA;CAClB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/common/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE/F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED,MAAM,WAAW,UAAU;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,CAQ1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAoBjF;AAED,MAAM,WAAW,QAAQ;IACxB,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,SAAS,EAAE,OAAO,CAAA;CAClB"}

package/dist/types/common/index.js

@@ -13,17 +13,28 @@ export function accumulateTokenUsage(current, addition) {
 /**
  * Merge two usage snapshots seen WITHIN a single streamed turn. Provider usage
  * frames over one stream are cumulative/monotonic (input set once early, output
- * grows), but a late frame can OMIT a field (report 0) — e.g. Anthropic's
+ * grows), but a late frame can OMIT a field (report 0) — e.g. a
  * `message_delta` may carry only output tokens. A naive last-write-wins
  * (`usage = chunk.usage`) then drops the earlier prompt/cache counts and
  * under-reports the turn. Taking the per-field high-water mark preserves every
  * field. DISTINCT from {@link accumulateTokenUsage}, which SUMS across turns.
  */
 export function mergeTokenUsage(current, next) {
+    const promptTokens = Math.max(current.promptTokens, next.promptTokens);
+    const completionTokens = Math.max(current.completionTokens, next.completionTokens);
     return {
-        promptTokens: Math.max(current.promptTokens, next.promptTokens),
-        completionTokens: Math.max(current.completionTokens, next.completionTokens),
-        totalTokens: Math.max(current.totalTokens, next.totalTokens),
+        promptTokens,
+        completionTokens,
+        // `totalTokens` is DERIVED (`input + output`), not independent, so the
+        // per-field high-water mark is wrong for it: a provider reports the
+        // input on `message_start` and the output on `message_delta`, and each
+        // frame's own total covers only the component that frame carried.
+        // Maxing those two totals returns the larger COMPONENT, not the sum —
+        // 1200 and 350 merge to 1200 instead of 1550, and every completion
+        // token vanishes from the run's budget. Take the max of what was
+        // reported and what the merged components imply, so the result is
+        // monotone and can never under-report.
+        totalTokens: Math.max(current.totalTokens, next.totalTokens, promptTokens + completionTokens),
         cachedTokens: Math.max(current.cachedTokens, next.cachedTokens),
         cacheWriteTokens: Math.max(current.cacheWriteTokens, next.cacheWriteTokens),
     };

package/dist/types/common/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/common/index.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IACnD,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,CAAA;AAC/E,CAAC;AAUD,MAAM,UAAU,oBAAoB,CAAC,OAAmB,EAAE,QAAoB;IAC7E,OAAO;QACN,YAAY,EAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY;QAC1D,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB;QACtE,WAAW,EAAE,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW;QACvD,YAAY,EAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY;QAC1D,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB;KACtE,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAmB,EAAE,IAAgB;IACpE,OAAO;QACN,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;QAC/D,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC;QAC3E,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC;QAC5D,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;QAC/D,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC;KAC3E,CAAA;AACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/common/index.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IACnD,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,CAAA;AAC/E,CAAC;AAUD,MAAM,UAAU,oBAAoB,CAAC,OAAmB,EAAE,QAAoB;IAC7E,OAAO;QACN,YAAY,EAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY;QAC1D,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB;QACtE,WAAW,EAAE,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW;QACvD,YAAY,EAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY;QAC1D,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,GAAG,QAAQ,CAAC,gBAAgB;KACtE,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAmB,EAAE,IAAgB;IACpE,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;IACtE,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAA;IAElF,OAAO;QACN,YAAY;QACZ,gBAAgB;QAChB,uEAAuE;QACvE,oEAAoE;QACpE,uEAAuE;QACvE,kEAAkE;QAClE,sEAAsE;QACtE,mEAAmE;QACnE,iEAAiE;QACjE,kEAAkE;QAClE,uCAAuC;QACvC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,gBAAgB,CAAC;QAC7F,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;QAC/D,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC;KAC3E,CAAA;AACF,CAAC"}

package/dist/types/connector/mcp.d.ts

@@ -64,6 +64,15 @@ export interface MCPToolDefinition {
     name: string;
     description?: string;
     inputSchema: MCPJsonSchema;
+    /**
+     * The shape the tool returns, as the server declares it.
+     *
+     * Servers publish this on a tool listing regardless of negotiated
+     * protocol revision, and it had no slot here — so a declared return
+     * shape never reached the model at all, which was left inferring one
+     * from prose or from whatever the first call happened to return.
+     */
+    outputSchema?: MCPJsonSchema;
     annotations?: MCPToolAnnotations;
 }
 export type MCPContentBlock = {
@@ -84,6 +93,18 @@ export type MCPContentBlock = {
 export interface MCPToolResult {
     content: MCPContentBlock[];
     isError?: boolean;
+    /**
+     * A machine-readable payload alongside (or instead of) the content
+     * blocks.
+     *
+     * A server may return this and omit the compatibility text block. The
+     * field survived the wire cast and was read by nothing, so that call
+     * produced an empty tool result for a request that succeeded — with no
+     * diagnostic anywhere, since `isError` was false and the content array
+     * was legitimately empty.
+     */
+    structuredContent?: unknown;
+    _meta?: Record<string, unknown>;
 }
 export interface MCPResource {
     uri: string;
@@ -154,6 +175,14 @@ export interface MCPClientConfig {
         name: string;
         version: string;
     };
+    /**
+     * Deadline for a single JSON-RPC round trip. Defaults to
+     * `DEFAULT_MCP_REQUEST_TIMEOUT_MS`.
+     *
+     * Without one, a wedged stdio server left every caller pending
+     * forever — no error, no failure, just a run that stopped.
+     */
+    requestTimeoutMs?: number;
 }
 export interface MCPClientState {
     id: MCPClientId;

package/dist/types/connector/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/types/connector/mcp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/types/connector/mcp.ts"],"names":[],"mappings":"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"}

package/dist/types/errors/__tests__/catalog.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=catalog.test.d.ts.map

package/dist/types/errors/__tests__/catalog.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.test.d.ts","sourceRoot":"","sources":["../../../../src/types/errors/__tests__/catalog.test.ts"],"names":[],"mappings":""}

package/dist/types/errors/__tests__/catalog.test.js

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import { ProviderError } from '../../provider/errors.js';
+import { DEFAULT_ERROR_RULES, explainError, factsOf, readHint, withHint } from '../catalog.js';
+import { NamzuError } from '../index.js';
+/**
+ * A failure surfaced as whatever prose the vendor SDK happened to write:
+ * no stable id to grep in logs, no instruction on what to change, and no
+ * growth point — a newly-observed failure shape could only be given
+ * curated copy by editing the classifier itself.
+ *
+ * Classification and remediation are separate jobs. The first is
+ * structural and belongs at the boundary; the second is editorial and
+ * belongs in a list a human appends to. `DoctorCheckResult` already
+ * carried `message` and `remediation` as separate fields — `namzu doctor`
+ * was simply the only surface that got either.
+ */
+const providerError = (code, status) => new ProviderError({
+    code: code,
+    message: 'the vendor wrote this',
+    providerId: 'test',
+    ...(status !== undefined ? { status } : {}),
+});
+describe('explaining a failure', () => {
+    it('gives a stale key an id and something to do about it', () => {
+        const explanation = explainError(providerError('auth', 401));
+        expect(explanation?.id).toBe('provider.auth');
+        expect(explanation?.hint).toMatch(/API key/);
+        // Not the vendor's sentence: the point is copy an operator can act
+        // on, keyed by an id they can grep for.
+        expect(explanation?.message).not.toContain('the vendor wrote this');
+    });
+    it('separates a permission failure from an authentication one', () => {
+        // The provider codes collapse 401 and 403, but the two call for
+        // different actions and the status still tells them apart.
+        expect(explainError(providerError('auth', 403))?.id).toBe('provider.permission');
+        expect(explainError(providerError('auth', 401))?.id).toBe('provider.auth');
+    });
+    it('recognises the failures an operator hits first', () => {
+        expect(explainError(providerError('rate_limit', 429))?.id).toBe('provider.rate_limit');
+        expect(explainError(providerError('context_length_exceeded'))?.id).toBe('provider.context_overflow');
+        expect(explainError(providerError('overloaded', 529))?.id).toBe('provider.unavailable');
+        expect(explainError(providerError('network'))?.id).toBe('provider.network');
+        expect(explainError(providerError('not_found', 404))?.id).toBe('provider.model_not_found');
+    });
+    it('says nothing rather than inventing advice', () => {
+        // A generic fallback would send the reader somewhere specific and
+        // wrong, which is worse than admitting the failure is unfamiliar.
+        expect(explainError(new Error('something nobody has characterised'))).toBeNull();
+    });
+    it('matches on structure, not on vendor prose', () => {
+        // Vendor copy changes without warning and differs per SDK version,
+        // so a rule keyed to it silently stops matching.
+        const reworded = providerError('rate_limit', 429);
+        Object.defineProperty(reworded, 'message', { value: 'completely different wording' });
+        expect(explainError(reworded)?.id).toBe('provider.rate_limit');
+    });
+    it('takes the first matching rule, so a rule can be as specific as it likes', () => {
+        const ids = DEFAULT_ERROR_RULES.map((rule) => rule.id);
+        expect(ids.indexOf('provider.permission')).toBeLessThan(ids.indexOf('provider.auth'));
+    });
+});
+describe('a hint attached where the failure was raised', () => {
+    it('wins over a rule matched on a status code', () => {
+        // Code that raised the failure knows more about it than a generic
+        // rule ever will — a container that has not been built, a daemon
+        // that is not running.
+        const err = withHint(providerError('rate_limit', 429), 'the sandbox worker is not running');
+        const explanation = explainError(err);
+        expect(explanation?.id).toBe('hint.from_throw_site');
+        expect(explanation?.hint).toBe('the sandbox worker is not running');
+    });
+    it('survives being read back off a plain throwable', () => {
+        expect(readHint(withHint(new Error('boom'), 'check the socket path'))).toBe('check the socket path');
+    });
+    it('does not change the message or the type', () => {
+        // Baking remediation into the message is what made it impossible to
+        // separate again — a surface could not render one without the other.
+        const original = new NamzuError({ code: 'storage_error', message: 'write failed' });
+        const hinted = withHint(original, 'the run directory is not writable');
+        expect(hinted).toBe(original);
+        expect(hinted.message).toBe('write failed');
+        expect(hinted instanceof NamzuError).toBe(true);
+    });
+    it('is not enumerable, so it cannot leak into a serialized error', () => {
+        const err = withHint(new Error('boom'), 'a hint');
+        expect(Object.keys(err)).not.toContain('hint');
+    });
+    it('ignores an empty or non-string hint', () => {
+        expect(readHint(withHint(new Error('boom'), ''))).toBeUndefined();
+        expect(readHint({ hint: 42 })).toBeUndefined();
+        expect(readHint(null)).toBeUndefined();
+    });
+});
+describe('the facts a rule matches on', () => {
+    it('reads a provider classification', () => {
+        const facts = factsOf(providerError('rate_limit', 429));
+        expect(facts).toMatchObject({ code: 'rate_limit', status: 429 });
+    });
+    it('reads a namzu code', () => {
+        expect(factsOf(new NamzuError({ code: 'tool_error', message: 'x' })).code).toBe('tool_error');
+    });
+    it('still produces facts for something that was never an Error', () => {
+        expect(factsOf('just a string').message).toBe('just a string');
+    });
+});
+//# sourceMappingURL=catalog.test.js.map