@namzu/sdk 5.2.0 → 6.1.0

package/dist/gateway/completion-inbox.d.ts

@@ -0,0 +1,113 @@
+import type { TaskGateway, TaskHandle } from '../types/agent/gateway.js';
+import type { TaskId } from '../types/ids/index.js';
+/**
+ * Completions that finished with nobody left to hear them.
+ *
+ * A worker's result reaches the supervisor as the `tool_result` of the
+ * `create_task` that launched it. That works whenever the launching call is
+ * still the live path — but it is not the only way a task ends:
+ *
+ *  - the launching tool hit its deadline and the executor returned
+ *    *"timed out… it may still be running"* to the model. The worker then
+ *    finished normally, holding a result nothing would ever read.
+ *  - the task was launched in the background on purpose, so there is no
+ *    call waiting on it by design.
+ *
+ * In both cases the completion exists, the gateway remembers it, and the
+ * model is never told. That is the gap this closes: the run subscribes once,
+ * every settled task lands here, and anything a tool did NOT hand over
+ * inline is drained into the transcript as a notification the next turn can
+ * read.
+ *
+ * The disambiguation is the whole design. An earlier version of the envelope
+ * path was removed (`dc16d58`) because it fired for completions the blocking
+ * tool had ALREADY delivered, so the supervisor saw every result twice —
+ * once correctly as a `tool_result`, once as an orphan envelope. Removing it
+ * fixed the duplicate and left the abandoned case with no channel at all.
+ * Claiming is what tells the two apart: a tool that delivers a completion
+ * says so, and only unclaimed completions become envelopes.
+ *
+ * It attaches through `onTaskCompleted`, which every `TaskGateway` already
+ * has, so a host gateway needs no change to take part — a host that was
+ * firing completions into a listener set with no listeners now has one.
+ */
+export declare class CompletionInbox {
+    private readonly unheard;
+    private readonly claimed;
+    /** Launched with nothing waiting on it, and not settled yet. */
+    private readonly outstanding;
+    private readonly arrivals;
+    private detach?;
+    /**
+     * Start listening.
+     *
+     * Returns a detach function; calling `attach` twice is a no-op rather
+     * than a second subscription, because a doubly-attached inbox would
+     * queue every completion twice and reproduce the exact duplicate this
+     * class exists to prevent.
+     */
+    attach(gateway: TaskGateway): () => void;
+    /**
+     * Say that a task was launched with nothing waiting on it.
+     *
+     * Without this the inbox can only see completions that have already
+     * happened, and a run whose supervisor launched a background worker and
+     * then answered would settle while the worker was still going — throwing
+     * away the very result the launch existed to produce. Knowing a task is
+     * outstanding is what lets the loop hold the run open for it.
+     */
+    expect(taskId: TaskId): void;
+    /** Whether anything is either waiting to be told or still running. */
+    get hasPendingWork(): boolean;
+    /**
+     * Wait for the next completion, or for the deadline, whichever comes first.
+     *
+     * Bounded on purpose. A worker that never finishes must not hold a run
+     * open forever, and the caller decides how long "long enough" is — the
+     * run's own budget is the only thing that knows.
+     */
+    waitForArrival(timeoutMs: number): Promise<void>;
+    /**
+     * Say that this completion reached the model as a `tool_result`.
+     *
+     * Idempotent, and safe to call before the completion is announced: the
+     * claim is remembered so a late announcement does not re-queue it.
+     */
+    claim(taskId: TaskId): void;
+    /** Whether anything is waiting to be told. */
+    get hasUnheard(): boolean;
+    /**
+     * Take every unheard completion, leaving the inbox empty.
+     *
+     * Draining rather than peeking: a notification that stays queued after
+     * being delivered is the duplicate-delivery bug in a different costume.
+     */
+    drain(): TaskHandle[];
+    /**
+     * Stop expecting a task that is never going to arrive.
+     *
+     * Cancelling is the case this exists for. `expect` puts a task on the
+     * outstanding list and only a COMPLETION takes it off, so a cancelled
+     * worker left `hasPendingWork` true for the rest of the run — and every
+     * attempt to settle then paid the full grace period waiting for a result
+     * that had been called off.
+     */
+    forget(taskId: TaskId): void;
+    /** Stop listening. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * The message a supervisor reads when a worker it stopped waiting for
+ * finishes.
+ *
+ * It carries the task id, because without one the model cannot say which of
+ * five workers this was, and it carries the output, because a notification
+ * that only says "done" forces exactly the follow-up call this mechanism
+ * exists to remove. Long output is truncated with the task id repeated in
+ * the truncation notice, so the full text stays one `wait_for_task` away and
+ * the model knows which id to ask for — that tool takes a `task_id` and
+ * returns immediately for a task that has already finished, where the
+ * listing takes only a state filter and could not have been followed.
+ */
+export declare function formatCompletionNotification(handles: readonly TaskHandle[]): string;
+//# sourceMappingURL=completion-inbox.d.ts.map

package/dist/gateway/completion-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-inbox.d.ts","sourceRoot":"","sources":["../../src/gateway/completion-inbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,MAAM,CAAC,CAAY;IAE3B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI;IAcxC;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,sEAAsE;IACtE,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BhD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM3B,8CAA8C;IAC9C,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;OAKG;IACH,KAAK,IAAI,UAAU,EAAE;IAQrB;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ5B,mDAAmD;IACnD,KAAK,IAAI,IAAI;CAUb;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CA8BnF"}

package/dist/gateway/completion-inbox.js

@@ -0,0 +1,211 @@
+/**
+ * Completions that finished with nobody left to hear them.
+ *
+ * A worker's result reaches the supervisor as the `tool_result` of the
+ * `create_task` that launched it. That works whenever the launching call is
+ * still the live path — but it is not the only way a task ends:
+ *
+ *  - the launching tool hit its deadline and the executor returned
+ *    *"timed out… it may still be running"* to the model. The worker then
+ *    finished normally, holding a result nothing would ever read.
+ *  - the task was launched in the background on purpose, so there is no
+ *    call waiting on it by design.
+ *
+ * In both cases the completion exists, the gateway remembers it, and the
+ * model is never told. That is the gap this closes: the run subscribes once,
+ * every settled task lands here, and anything a tool did NOT hand over
+ * inline is drained into the transcript as a notification the next turn can
+ * read.
+ *
+ * The disambiguation is the whole design. An earlier version of the envelope
+ * path was removed (`dc16d58`) because it fired for completions the blocking
+ * tool had ALREADY delivered, so the supervisor saw every result twice —
+ * once correctly as a `tool_result`, once as an orphan envelope. Removing it
+ * fixed the duplicate and left the abandoned case with no channel at all.
+ * Claiming is what tells the two apart: a tool that delivers a completion
+ * says so, and only unclaimed completions become envelopes.
+ *
+ * It attaches through `onTaskCompleted`, which every `TaskGateway` already
+ * has, so a host gateway needs no change to take part — a host that was
+ * firing completions into a listener set with no listeners now has one.
+ */
+export class CompletionInbox {
+    unheard = new Map();
+    claimed = new Set();
+    /** Launched with nothing waiting on it, and not settled yet. */
+    outstanding = new Set();
+    arrivals = new Set();
+    detach;
+    /**
+     * Start listening.
+     *
+     * Returns a detach function; calling `attach` twice is a no-op rather
+     * than a second subscription, because a doubly-attached inbox would
+     * queue every completion twice and reproduce the exact duplicate this
+     * class exists to prevent.
+     */
+    attach(gateway) {
+        if (this.detach)
+            return this.detach;
+        this.detach = gateway.onTaskCompleted((handle) => {
+            // A completion claimed before it was announced — a tool that
+            // finished its wait faster than the listener ran — is already
+            // delivered. Nothing to queue.
+            this.outstanding.delete(handle.taskId);
+            if (this.claimed.has(handle.taskId))
+                return;
+            this.unheard.set(handle.taskId, handle);
+            for (const wake of this.arrivals)
+                wake();
+        });
+        return this.detach;
+    }
+    /**
+     * Say that a task was launched with nothing waiting on it.
+     *
+     * Without this the inbox can only see completions that have already
+     * happened, and a run whose supervisor launched a background worker and
+     * then answered would settle while the worker was still going — throwing
+     * away the very result the launch existed to produce. Knowing a task is
+     * outstanding is what lets the loop hold the run open for it.
+     */
+    expect(taskId) {
+        if (this.claimed.has(taskId))
+            return;
+        this.outstanding.add(taskId);
+    }
+    /** Whether anything is either waiting to be told or still running. */
+    get hasPendingWork() {
+        return this.unheard.size > 0 || this.outstanding.size > 0;
+    }
+    /**
+     * Wait for the next completion, or for the deadline, whichever comes first.
+     *
+     * Bounded on purpose. A worker that never finishes must not hold a run
+     * open forever, and the caller decides how long "long enough" is — the
+     * run's own budget is the only thing that knows.
+     */
+    waitForArrival(timeoutMs) {
+        if (this.unheard.size > 0)
+            return Promise.resolve();
+        if (this.outstanding.size === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(finish, timeoutMs);
+            timer.unref?.();
+            function finish() {
+                clearTimeout(timer);
+                wake.done = true;
+                resolve();
+            }
+            const wake = Object.assign(() => {
+                if (!wake.done) {
+                    this.arrivals.delete(wake);
+                    finish();
+                }
+            }, { done: false });
+            this.arrivals.add(wake);
+        });
+    }
+    /**
+     * Say that this completion reached the model as a `tool_result`.
+     *
+     * Idempotent, and safe to call before the completion is announced: the
+     * claim is remembered so a late announcement does not re-queue it.
+     */
+    claim(taskId) {
+        this.claimed.add(taskId);
+        this.unheard.delete(taskId);
+        this.outstanding.delete(taskId);
+    }
+    /** Whether anything is waiting to be told. */
+    get hasUnheard() {
+        return this.unheard.size > 0;
+    }
+    /**
+     * Take every unheard completion, leaving the inbox empty.
+     *
+     * Draining rather than peeking: a notification that stays queued after
+     * being delivered is the duplicate-delivery bug in a different costume.
+     */
+    drain() {
+        if (this.unheard.size === 0)
+            return [];
+        const handles = [...this.unheard.values()];
+        this.unheard.clear();
+        for (const handle of handles)
+            this.claimed.add(handle.taskId);
+        return handles;
+    }
+    /**
+     * Stop expecting a task that is never going to arrive.
+     *
+     * Cancelling is the case this exists for. `expect` puts a task on the
+     * outstanding list and only a COMPLETION takes it off, so a cancelled
+     * worker left `hasPendingWork` true for the rest of the run — and every
+     * attempt to settle then paid the full grace period waiting for a result
+     * that had been called off.
+     */
+    forget(taskId) {
+        this.outstanding.delete(taskId);
+        this.unheard.delete(taskId);
+        // Anyone waiting should re-check rather than sit out their deadline
+        // for a task that is no longer coming.
+        for (const wake of [...this.arrivals])
+            wake();
+    }
+    /** Stop listening. Safe to call more than once. */
+    close() {
+        this.detach?.();
+        this.detach = undefined;
+        this.unheard.clear();
+        this.outstanding.clear();
+        // Release anyone still waiting. A closed inbox would otherwise hold
+        // them to their own deadline for a completion that can no longer come.
+        for (const wake of [...this.arrivals])
+            wake();
+        this.arrivals.clear();
+    }
+}
+/** How much of a worker's output rides in the notification itself. */
+const NOTIFICATION_OUTPUT_LIMIT = 4_000;
+/**
+ * The message a supervisor reads when a worker it stopped waiting for
+ * finishes.
+ *
+ * It carries the task id, because without one the model cannot say which of
+ * five workers this was, and it carries the output, because a notification
+ * that only says "done" forces exactly the follow-up call this mechanism
+ * exists to remove. Long output is truncated with the task id repeated in
+ * the truncation notice, so the full text stays one `wait_for_task` away and
+ * the model knows which id to ask for — that tool takes a `task_id` and
+ * returns immediately for a task that has already finished, where the
+ * listing takes only a state filter and could not have been followed.
+ */
+export function formatCompletionNotification(handles) {
+    const blocks = handles.map((handle) => {
+        const durationMs = handle.completedAt ? handle.completedAt - handle.createdAt : undefined;
+        const output = handle.result?.result ?? handle.result?.lastError ?? '';
+        const truncated = output.length > NOTIFICATION_OUTPUT_LIMIT
+            ? // `wait_for_task`, not `agent_task_list` — the listing takes only a
+                // state filter, so an instruction to call it "with task_id" named
+                // a parameter that does not exist and could not be followed. On an
+                // already-finished task the wait returns immediately.
+                `${output.slice(0, NOTIFICATION_OUTPUT_LIMIT)}\n… truncated. Call wait_for_task with task_id "${handle.taskId}" for the full output.`
+            : output;
+        const lines = [
+            `task_id: ${handle.taskId}`,
+            `agent: ${handle.agentId}`,
+            `state: ${handle.state}`,
+            ...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
+            '',
+            truncated.length > 0 ? truncated : '(the task produced no output)',
+        ];
+        return `<task-notification>\n${lines.join('\n')}\n</task-notification>`;
+    });
+    const preamble = handles.length === 1
+        ? 'A task you launched has finished. This is its result — you were not waiting on it, so it arrives here rather than as a tool result.'
+        : `${handles.length} tasks you launched have finished. These are their results — you were not waiting on them, so they arrive here rather than as tool results.`;
+    return `${preamble}\n\n${blocks.join('\n\n')}`;
+}
+//# sourceMappingURL=completion-inbox.js.map

package/dist/gateway/completion-inbox.js.map

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

package/dist/provider/__tests__/strict-schema.test.js

@@ -67,17 +67,65 @@ describe('the violation report names the exact path', () => {
         };
         expect(findStrictSchemaViolations(schema)).toEqual([]);
     });
-    it('reports numeric and string bounds, which are also outside the subset', () => {
+    it('reports the bounds the wire refuses, and only those', () => {
+        // Measured against the live API rather than read off a page. The first
+        // version of this list was derived from documentation and was wrong in
+        // both directions: it refused `maxLength`, which the wire accepts, and
+        // permitted `prefixItems`, which it rejects.
         const schema = {
             type: 'object',
             properties: {
                 n: { type: 'integer', minimum: 0 },
                 s: { type: 'string', maxLength: 10 },
+                a: { type: 'array', items: { type: 'string' }, maxItems: 3, minItems: 1 },
             },
         };
         expect(findStrictSchemaViolations(schema)
             .map((v) => v.keyword)
-            .sort()).toEqual(['maxLength', 'minimum']);
+            .sort()).toEqual(['maxItems', 'minimum']);
+    });
+    it('leaves string length alone, because strict accepts it', () => {
+        // The false positive that would have refused tools which work.
+        expect(findStrictSchemaViolations({ s: { type: 'string', minLength: 1, maxLength: 9 } })).toEqual([]);
+    });
+    it('catches a tuple in either spelling, because strict admits neither', () => {
+        // The interaction worth pinning, and the one a `prefixItems` entry alone
+        // got wrong. This check runs at REGISTRATION, on the schema as rendered
+        // — draft-07, where a tuple is `items: [a, b]` — while the wire sees the
+        // `prefixItems` the driver converts it to. So denying only `prefixItems`
+        // was a guard that could not fire on the path that produces tuples.
+        //
+        // Measured, strict rejects both, which is why a tool that is both strict
+        // and tuple-shaped cannot be expressed at all. Converting it only
+        // changes which error comes back.
+        for (const items of [
+            { prefixItems: [{ type: 'integer' }, { type: 'integer' }] },
+            { items: [{ type: 'integer' }, { type: 'integer' }] },
+        ]) {
+            const violations = findStrictSchemaViolations({
+                properties: { range: { type: 'array', ...items } },
+            });
+            expect(violations, JSON.stringify(items)).toHaveLength(1);
+            expect(violations[0]?.remedy).toContain('tuple cannot be expressed');
+        }
+    });
+    it('leaves an ordinary array alone, where `items` is one schema', () => {
+        // The false positive the tuple rule must not become: `items` is the
+        // normal spelling for a homogeneous array and strict accepts it. Only
+        // the array-of-schemas form is a tuple.
+        expect(findStrictSchemaViolations({ type: 'array', items: { type: 'string' } })).toEqual([]);
+    });
+    it('admits minItems at 0 or 1 and refuses it above, as the wire does', () => {
+        // A blanket denial here was a false positive with a real cost: it
+        // refuses `z.array(...).nonempty()`, which renders `minItems: 1` and
+        // which the wire accepts. The constraint is on the VALUE, and the
+        // vendor's error says so — "'minItems' values other than 0 or 1 are not
+        // supported".
+        expect(findStrictSchemaViolations({ type: 'array', minItems: 0 })).toEqual([]);
+        expect(findStrictSchemaViolations({ type: 'array', minItems: 1 })).toEqual([]);
+        const violations = findStrictSchemaViolations({ type: 'array', minItems: 2 });
+        expect(violations).toHaveLength(1);
+        expect(violations[0]?.keyword).toBe('minItems');
     });
     it('admits additionalProperties only as false', () => {
         expect(findStrictSchemaViolations({ additionalProperties: false })).toEqual([]);

package/dist/provider/__tests__/strict-schema.test.js.map

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

package/dist/provider/__tests__/vendor-detail.test.d.ts

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

package/dist/provider/__tests__/vendor-detail.test.d.ts.map

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

package/dist/provider/__tests__/vendor-detail.test.js

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { providerHttpError, redactSecrets, vendorDetail } from '../errors.js';
+/**
+ * The provider's own account of what was wrong, kept — and scrubbed.
+ *
+ * `ProviderRequestErrorInit` declared `detail` from the beginning and the
+ * constructor never read it, so the field existed and carried nothing. The
+ * body was read to classify and then dropped, deliberately, because an error
+ * body can echo a request and a request can carry a key.
+ *
+ * The cost of that trade showed up in production: the wire had been saying
+ * `tools.0.custom.input_schema: … must match JSON Schema draft 2020-12` and
+ * the SDK deleted the sentence, so diagnosing it took seven eliminated
+ * hypotheses and a day of downtime. Keeping the sentence and scrubbing the
+ * credential shapes is the trade that was actually available.
+ */
+describe('the sentence that names the broken field survives', () => {
+    it('lifts the structured message out of a vendor body', () => {
+        const body = JSON.stringify({
+            type: 'error',
+            error: {
+                type: 'invalid_request_error',
+                message: 'tools.0.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12',
+            },
+        });
+        expect(vendorDetail(body)).toBe('tools.0.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12');
+    });
+    it('reaches the error a caller actually catches', () => {
+        const err = providerHttpError({
+            providerId: 'anthropic',
+            status: 400,
+            body: JSON.stringify({ error: { message: "Schema type 'oneOf' is not supported" } }),
+        });
+        expect(err.detail).toContain('oneOf');
+        // …and the message too, so a log line that prints only the message is
+        // still enough to act on.
+        expect(err.message).toContain('oneOf');
+    });
+    it('falls back to the raw text when the body is not JSON', () => {
+        expect(vendorDetail('upstream connect error, transport failure')).toBe('upstream connect error, transport failure');
+    });
+    it('says nothing rather than something empty', () => {
+        expect(vendorDetail(undefined)).toBeUndefined();
+        expect(vendorDetail(null)).toBeUndefined();
+        expect(vendorDetail('   ')).toBeUndefined();
+        expect(vendorDetail({})).toBeUndefined();
+    });
+    it('truncates a body that is not a sentence', () => {
+        const detail = vendorDetail('x'.repeat(5_000));
+        expect(detail?.length).toBeLessThanOrEqual(401);
+        expect(detail?.endsWith('…')).toBe(true);
+    });
+});
+describe('a credential never rides along', () => {
+    it.each([
+        ['sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv', 'anthropic-style key'],
+        ['npm_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345', 'npm token'],
+        ['ghp_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345', 'github token'],
+        ['AKIAIOSFODNN7EXAMPLE', 'aws access key id'],
+    ])('scrubs %s (%s)', (secret) => {
+        const scrubbed = redactSecrets(`upstream rejected token ${secret} for this request`);
+        expect(scrubbed).not.toContain(secret);
+        expect(scrubbed).toContain('[redacted]');
+    });
+    it('scrubs a bearer header the vendor echoed back', () => {
+        const scrubbed = redactSecrets('bad header: Authorization: Bearer abcdef0123456789ABCDEF');
+        expect(scrubbed).not.toContain('abcdef0123456789ABCDEF');
+    });
+    it('scrubs a credential-named JSON field without eating the rest', () => {
+        const scrubbed = redactSecrets('{"api_key":"sk-live-9999","model":"the-model-that-failed"}');
+        expect(scrubbed).not.toContain('sk-live-9999');
+        // The surrounding sentence is the whole point — scrubbing must not
+        // degrade into deleting the message.
+        expect(scrubbed).toContain('the-model-that-failed');
+    });
+    it('scrubs on the real path, not only in the helper', () => {
+        const err = providerHttpError({
+            providerId: 'anthropic',
+            status: 401,
+            body: JSON.stringify({
+                error: { message: 'invalid key sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv supplied' },
+            }),
+        });
+        expect(err.detail).not.toContain('AbCdEfGhIjKlMnOpQrStUv');
+        expect(err.detail).toContain('[redacted]');
+        expect(err.message).not.toContain('AbCdEfGhIjKlMnOpQrStUv');
+    });
+});
+//# sourceMappingURL=vendor-detail.test.js.map

package/dist/provider/__tests__/vendor-detail.test.js.map

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

package/dist/provider/errors.d.ts

@@ -11,11 +11,19 @@
  *
  * So the contract here is deliberately narrow:
  *
- *  - the message is built from the STATUS LINE and the classified `kind`. The
- *    response body is read to classify and then dropped. It is never
- *    interpolated, never re-thrown, and never attached as `cause` — a `cause`
- *    survives every logger that serializes an error chain, which defeats the
- *    point.
+ *  - the message is built from the STATUS LINE, the classified `kind`, and the
+ *    provider's own complaint in `detail` — truncated and scrubbed of anything
+ *    credential-shaped. The raw body is never re-thrown and never attached as
+ *    `cause`; a `cause` survives every logger that serializes an error chain,
+ *    which defeats the point.
+ *
+ *    The body used to be dropped entirely. That was over-corrected: a provider
+ *    rejecting a request names the exact offending field, and deleting that
+ *    sentence turned a one-line diagnosis into hypothesis elimination against a
+ *    live API — once at the cost of a day of production downtime, while the
+ *    wire had been saying `tools.0.custom.input_schema: … must match JSON
+ *    Schema draft 2020-12` the entire time. Scrubbing what looks like a
+ *    credential keeps the safety and returns the sentence.
  *  - `retryAfterMs` is DATA. Nothing in this module sleeps, backs off or
  *    retries. A retry loop inside a driver burns the run's wall clock and hides
  *    the failure from the layer that should decide.
@@ -35,8 +43,33 @@ export declare class ProviderRequestError extends Error {
     readonly providerId: string;
     readonly status?: number;
     readonly retryAfterMs?: number;
+    /**
+     * What the provider said was wrong, truncated and redacted.
+     *
+     * `ProviderRequestErrorInit` has declared this field all along and the
+     * constructor never read it, so every caller that set it was writing to
+     * nothing. That is not a cosmetic gap: a provider rejecting a request
+     * usually names the exact offending field, and losing that sentence turns
+     * a one-line diagnosis into hypothesis elimination against a live API. It
+     * did — a tool schema in the wrong JSON Schema dialect cost a day of
+     * production downtime while the wire had been saying
+     * `tools.0.custom.input_schema: … must match JSON Schema draft 2020-12`
+     * the whole time.
+     *
+     * See {@link vendorDetail} for what is kept and what is scrubbed.
+     */
+    readonly detail?: string;
     constructor(init: ProviderRequestErrorInit);
 }
+/**
+ * The provider's own account of what was wrong, safe to log.
+ *
+ * Prefers the structured `error.message` a JSON body carries, because that is
+ * the field vendors put the actionable sentence in and it is bounded; falls
+ * back to the raw text. Truncated, and every credential shape replaced.
+ */
+export declare function vendorDetail(body: unknown): string | undefined;
+export declare function redactSecrets(text: string): string;
 /** Is this a classified provider failure, whichever SDK copy threw it? */
 export declare function isProviderRequestError(err: unknown): err is ProviderRequestError;
 /**

package/dist/provider/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/provider/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAC7F,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACxB,MAAM,4BAA4B,CAAA;AAWnC;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,iBAAiB,CAAA;IACvC,SAAgB,UAAU,EAAE,MAAM,CAAA;IAClC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAA;IAC/B,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAA;gBAEzB,IAAI,EAAE,wBAAwB;CAQ1C;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,oBAAoB,CAOhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAKhF;AAwCD,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAGhF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,GAAG,GAAE,MAAmB,GACtB,MAAM,GAAG,SAAS,CAepB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAClB,iBAAiB,CAanB;AAyED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,oBAAoB,CAwCvB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,oBAAoB,CASvB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/provider/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAC7F,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACxB,MAAM,4BAA4B,CAAA;AAWnC;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,iBAAiB,CAAA;IACvC,SAAgB,UAAU,EAAE,MAAM,CAAA;IAClC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAA;IAC/B,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrC;;;;;;;;;;;;;;OAcG;IACH,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAA;gBAEnB,IAAI,EAAE,wBAAwB;CAS1C;AAsBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAiB9D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD;AAkBD,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,oBAAoB,CAOhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAKhF;AAwCD,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAGhF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,GAAG,GAAE,MAAmB,GACtB,MAAM,GAAG,SAAS,CAepB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAClB,iBAAiB,CAanB;AAyED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,oBAAoB,CA0CvB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,oBAAoB,CAWvB"}