@namzu/sdk 2.0.0 → 3.1.0

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

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

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

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

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

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

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

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

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { ProviderError } from '../../provider/errors.js';
+import { NamzuError, isNamzuError, toPlatformError } from '../index.js';
+/**
+ * `PlatformError` was declared and never constructed — a shape nothing
+ * produced and nothing consumed — while the runtime threw bare `Error`
+ * everywhere. A caller catching a failure from `query()` could not tell
+ * "the model rate-limited us" from "the run was configured wrong" from
+ * "that checkpoint does not exist". Matching on message text was the only
+ * recourse, and message text is not an interface.
+ */
+describe('NamzuError', () => {
+    it('is an Error, so code that only knows about Error still works', () => {
+        const err = new NamzuError({ code: 'invalid_config', message: 'no model' });
+        expect(err).toBeInstanceOf(Error);
+        expect(err.message).toBe('no model');
+        expect(err.stack).toBeDefined();
+    });
+    it('preserves the cause chain', () => {
+        const root = new Error('ENOENT');
+        const err = new NamzuError({ code: 'storage_error', message: 'write failed', cause: root });
+        expect(err.cause).toBe(root);
+    });
+    it('defaults `retryable` per code, and lets a caller override it', () => {
+        expect(new NamzuError({ code: 'invalid_config', message: 'x' }).retryable).toBe(false);
+        expect(new NamzuError({ code: 'storage_error', message: 'x' }).retryable).toBe(true);
+        expect(new NamzuError({ code: 'invalid_config', message: 'x', retryable: true }).retryable).toBe(true);
+    });
+    it('narrows through `isNamzuError`', () => {
+        expect(isNamzuError(new NamzuError({ code: 'unknown', message: 'x' }))).toBe(true);
+        expect(isNamzuError(new Error('x'))).toBe(false);
+        expect(isNamzuError('x')).toBe(false);
+    });
+});
+describe('toPlatformError', () => {
+    it('gives a host ONE shape regardless of what was thrown', () => {
+        // Which is the entire point: without this, "handle errors from the
+        // SDK" means writing the same instanceof ladder in every caller.
+        for (const thrown of [
+            new NamzuError({ code: 'plugin_error', message: 'a' }),
+            new ProviderError({ code: 'rate_limit', message: 'b' }),
+            new Error('c'),
+            'not even an error',
+        ]) {
+            const platform = toPlatformError(thrown);
+            expect(typeof platform.code).toBe('string');
+            expect(typeof platform.message).toBe('string');
+            expect(typeof platform.retryable).toBe('boolean');
+        }
+    });
+    it('carries a NamzuError through unchanged', () => {
+        const err = new NamzuError({
+            code: 'not_found',
+            message: 'Checkpoint not found: cp_1',
+            details: { checkpointId: 'cp_1' },
+        });
+        expect(toPlatformError(err)).toEqual({
+            code: 'not_found',
+            message: 'Checkpoint not found: cp_1',
+            details: { checkpointId: 'cp_1' },
+            retryable: false,
+        });
+    });
+    it('keeps a ProviderError`s classification instead of recomputing it', () => {
+        // The provider taxonomy already knows things this one does not —
+        // which status codes back off, what the server asked for.
+        const err = new ProviderError({
+            code: 'rate_limit',
+            message: 'slow down',
+            providerId: 'anthropic',
+            status: 429,
+            retryAfterMs: 3_000,
+        });
+        expect(toPlatformError(err)).toEqual({
+            code: 'provider_error',
+            message: 'slow down',
+            details: {
+                providerCode: 'rate_limit',
+                providerId: 'anthropic',
+                status: 429,
+                retryAfterMs: 3_000,
+            },
+            retryable: true,
+        });
+    });
+    it('does not claim a non-retryable provider failure is retryable', () => {
+        const err = new ProviderError({ code: 'auth', message: 'bad key' });
+        expect(toPlatformError(err).retryable).toBe(false);
+    });
+    it('reports a plain Error honestly as `unknown` rather than guessing', () => {
+        expect(toPlatformError(new Error('something broke'))).toEqual({
+            code: 'unknown',
+            message: 'something broke',
+            retryable: false,
+        });
+    });
+    it('does not lose a thrown non-Error', () => {
+        // Rare, and usually a bug elsewhere — but dropping it is worse than
+        // reporting it as-is.
+        expect(toPlatformError({ weird: true }).message).toBe('[object Object]');
+        expect(toPlatformError(undefined).message).toBe('undefined');
+    });
+});
+//# sourceMappingURL=errors.test.js.map

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

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

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

@@ -0,0 +1,83 @@
+/**
+ * An ordered rule layer between a caught throwable and the operator.
+ *
+ * A failure surfaced as whatever prose the vendor SDK happened to write:
+ * no stable id to grep for in logs, and no instruction on what to change.
+ * There was also no growth point — a newly-observed failure shape could
+ * only be given curated copy by editing the classifier itself, which mixes
+ * "what kind of failure is this" with "what should a person do about it".
+ *
+ * The two are separate jobs. Classification is structural and belongs at
+ * the boundary; remediation is editorial and belongs in a list a human
+ * appends to. `DoctorCheckResult` already proves the pattern is native
+ * here: it carries `message` and `remediation` as separate fields, and
+ * `namzu doctor` has been the only surface that got either.
+ *
+ * Rules match on STRUCTURAL signals — code, status, error name, an
+ * explicit `hint` own-property from the throw site — never on volatile
+ * vendor prose, which changes without warning and differs per SDK version.
+ */
+/** What a rule knows about a failure, flattened for matching. */
+export interface ErrorFacts {
+    /** namzu or provider code, whichever classification produced one. */
+    readonly code?: string;
+    readonly status?: number;
+    /** Constructor name, for a throwable neither classifier recognised. */
+    readonly name?: string;
+    readonly message: string;
+    /** Server-directed backoff, when one was parsed. */
+    readonly retryAfterMs?: number;
+    /** A hint the throw site attached directly. See {@link readHint}. */
+    readonly hint?: string;
+}
+export interface ErrorCatalogRule {
+    /**
+     * Stable id. Appears in logs and in operator output, so it is greppable
+     * and can be linked to. Never renamed once shipped — a rule whose
+     * meaning changes gets a new id.
+     */
+    readonly id: string;
+    readonly when: (facts: ErrorFacts) => boolean;
+    /** What happened, in an operator's terms rather than the vendor's. */
+    readonly message: string;
+    /** What to change. Separate from `message` so a surface can override it. */
+    readonly hint: string;
+}
+export interface ErrorExplanation {
+    readonly id: string;
+    readonly message: string;
+    readonly hint: string;
+}
+/**
+ * A hint attached at the throw site.
+ *
+ * Infrastructure code knows things the classifier cannot infer — that a
+ * daemon is not running, that a socket path is wrong — and had no channel
+ * to say so except by baking prose into the message, where it cannot be
+ * separated from the failure again. An own-property survives every
+ * `instanceof` check and every rethrow, and rules can pass it through
+ * under a stable id.
+ */
+export declare function readHint(err: unknown): string | undefined;
+/** Attach a hint to a throwable without changing its message or type. */
+export declare function withHint<E>(err: E, hint: string): E;
+/** Flatten a throwable into the shape rules match on. */
+export declare function factsOf(err: unknown): ErrorFacts;
+/**
+ * The seed rules.
+ *
+ * Ordered, first match wins — so a rule may be as specific as it likes
+ * without having to exclude everything below it. Three to start, chosen
+ * because they are the failures an operator hits first and the ones where
+ * the vendor's own words help least.
+ */
+export declare const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[];
+/**
+ * Explain a failure, or return `null` when no rule claims it.
+ *
+ * `null` rather than a generic fallback: inventing advice for a failure
+ * nobody has characterised is worse than saying nothing, because it sends
+ * the reader somewhere specific and wrong.
+ */
+export declare function explainError(err: unknown, rules?: readonly ErrorCatalogRule[]): ErrorExplanation | null;
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/types/errors/catalog.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iEAAiE;AACjE,MAAM,WAAW,UAAU;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;IAC7C,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIzD;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAKnD;AAED,yDAAyD;AACzD,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CA+BhD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EA+D1D,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,OAAO,EACZ,KAAK,GAAE,SAAS,gBAAgB,EAAwB,GACtD,gBAAgB,GAAG,IAAI,CAYzB"}