@namzu/sdk 2.0.0 → 3.0.0

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PluginId, RunId } from '../ids/index.js';
+import type { Message } from '../message/index.js';
 import type { ToolResult } from '../tool/index.js';
 export type PluginScope = 'project' | 'user';
 export declare function assertPluginScope(scope: PluginScope): void;
@@ -9,6 +10,33 @@ export type PluginContributionType = 'tool' | 'skill' | 'hook' | 'mcp_server' |
 export declare function assertPluginContributionType(type: PluginContributionType): void;
 export type PluginHookEvent = 'run_start' | 'run_end' | 'pre_tool_use' | 'post_tool_use' | 'pre_llm_call' | 'post_llm_call' | 'iteration_start' | 'iteration_end';
 export declare function assertPluginHookEvent(event: PluginHookEvent): void;
+/**
+ * What an extension is shown about a model call it is about to make.
+ *
+ * A projection, not the live request object. The wire params carry driver
+ * concerns an extension has no business depending on, and handing them
+ * over would make every future field of that type part of the plugin
+ * contract by accident.
+ */
+export interface PluginModelRequest {
+    readonly model: string;
+    readonly messages: readonly Message[];
+    /** Names only. A hook auditing tool exposure needs the set, not the schemas. */
+    readonly toolNames: readonly string[];
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+}
+/** What an extension is shown about the model's reply. */
+export interface PluginModelResponse {
+    readonly content: string | null;
+    readonly toolNames: readonly string[];
+    readonly finishReason: string;
+    readonly usage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly totalTokens: number;
+    };
+}
 export interface PluginHookContext {
     readonly runId: RunId;
     readonly pluginId: PluginId;
@@ -17,6 +45,40 @@ export interface PluginHookContext {
     readonly toolInput?: unknown;
     readonly toolResult?: ToolResult;
     readonly iteration?: number;
+    /**
+     * The request about to be sent, on `pre_llm_call`.
+     *
+     * Both model-call hooks fired directly beside this data and were handed
+     * none of it — only a run id and an iteration number — so an extension
+     * could observe THAT a call was happening and nothing about what it
+     * was. A redaction pass, a prompt audit, a per-tenant token ledger: all
+     * of them needed the one thing the hook did not carry.
+     *
+     * Read-only. Frozen before fan-out for the same reason probe events
+     * are: a hook that mutated the live request would change what every
+     * later hook sees, and the last one registered would silently win.
+     * Shaping the request stays the job of the single-slot host callback
+     * that owns it, where one writer is the contract rather than an
+     * accident of registration order.
+     *
+     * The freeze is one level deep, as elsewhere: each message is a frozen
+     * copy, so writing to one is inert and cannot reach the run's history,
+     * but a nested array inside a message is still the run's own.
+     */
+    readonly request?: Readonly<PluginModelRequest>;
+    /**
+     * What came back, on `post_llm_call`. Read-only, same reasoning.
+     */
+    readonly response?: Readonly<PluginModelResponse>;
+    /**
+     * Aborts when this hook's deadline expires.
+     *
+     * The runtime stops waiting on a slow hook either way, but without a
+     * signal the hook itself never learns it was abandoned: an HTTP request
+     * inside it keeps a socket open and its eventual result is written into
+     * a run that moved on without it. A hook doing I/O should forward this.
+     */
+    readonly signal?: AbortSignal;
 }
 export type PluginHookResult = {
     action: 'continue';
@@ -29,9 +91,6 @@ export type PluginHookResult = {
 } | {
     action: 'error';
     message: string;
-} | {
-    action: 'resume';
-    input: string;
 } | {
     action: 'retry';
 };
@@ -39,6 +98,22 @@ export declare function assertPluginHookResult(result: PluginHookResult): assert
 export interface PluginHookDefinition {
     readonly event: PluginHookEvent;
     readonly handler: (context: PluginHookContext) => Promise<PluginHookResult>;
+    /**
+     * Lower runs first. Default 100.
+     *
+     * Order was install order, which is neither declared nor stable — it
+     * depends on when each plugin happened to be installed. That is fine
+     * for hooks that only observe, and wrong for the ones that decide:
+     * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
+     * denies a dangerous command only gets to deny it if it runs before
+     * whatever else stops the chain. A guard that fires depending on
+     * installation history is not a guard.
+     *
+     * Ties keep registration order, so plugins that never set a priority
+     * behave exactly as before. Convention: guards below 100, observers
+     * above.
+     */
+    readonly priority?: number;
 }
 export interface PluginMCPServerConfig {
     readonly name: string;

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

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

package/dist/types/plugin/index.js

@@ -63,7 +63,6 @@ export function assertPluginHookResult(result) {
         case 'skip':
         case 'modify':
         case 'error':
-        case 'resume':
         case 'retry':
             break;
         default: {

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

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

package/dist/types/provider/__tests__/cause-chain.test.d.ts

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

package/dist/types/provider/__tests__/cause-chain.test.d.ts.map

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

package/dist/types/provider/__tests__/cause-chain.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { classifyProviderError } from '../errors.js';
+/**
+ * Every signal was read off the error handed in, so one layer of wrapping
+ * hid it — and wrapping is the normal case, not an edge one: a vendor SDK
+ * wraps its transport error and the runtime wraps again on the way out.
+ *
+ * A rate limit wrapped ONCE classified as `unknown`, which is treated as
+ * non-retryable. The retry policy was dead for every failure that was not
+ * the outermost throwable, which is most of them.
+ */
+const wrap = (message, cause) => new Error(message, { cause });
+describe('status through the chain', () => {
+    // Deliberately mute: a message that says "too many requests" would let
+    // the message-text fallback reach the same verdict, and the test would
+    // pass with the status walk removed.
+    const throttled = Object.assign(new Error('upstream returned an error'), { status: 429 });
+    it('finds a rate limit one layer down', () => {
+        const classified = classifyProviderError(wrap('request failed', throttled));
+        expect(classified.code).toBe('rate_limit');
+        expect(classified.retryable).toBe(true);
+    });
+    it('finds it three layers down', () => {
+        const classified = classifyProviderError(wrap('run failed', wrap('step failed', wrap('request failed', throttled))));
+        expect(classified.code).toBe('rate_limit');
+    });
+    it('finds a status hidden in a metadata bag under a wrapper', () => {
+        const aws = Object.assign(new Error('ThrottlingException'), {
+            $metadata: { httpStatusCode: 429 },
+        });
+        expect(classifyProviderError(wrap('send failed', aws)).code).toBe('rate_limit');
+    });
+    it('still prefers the outermost status when two links carry one', () => {
+        const inner = Object.assign(new Error('inner'), { status: 500 });
+        const outer = Object.assign(wrap('outer', inner), { status: 429 });
+        // The outer link is what the driver chose to expose; walking
+        // outward-in keeps the un-wrapped case behaving exactly as before.
+        expect(classifyProviderError(outer).status).toBe(429);
+    });
+});
+describe('errno through the chain', () => {
+    const reset = Object.assign(new Error('socket hang up'), { code: 'ECONNRESET' });
+    it('finds a transport failure two layers down', () => {
+        const classified = classifyProviderError(wrap('provider call failed', wrap('fetch failed', reset)));
+        // The one class of failure where retrying is almost always right.
+        expect(classified.code).toBe('network');
+        expect(classified.retryable).toBe(true);
+    });
+    it('finds a timeout errno under a wrapper', () => {
+        const timedOut = Object.assign(new Error('headers timeout'), {
+            code: 'UND_ERR_HEADERS_TIMEOUT',
+        });
+        expect(classifyProviderError(wrap('failed', timedOut)).code).toBe('timeout');
+    });
+});
+describe('retry-after through the chain', () => {
+    it('reads the header off the link that carries it', () => {
+        const limited = Object.assign(new Error('rate limited'), {
+            status: 429,
+            headers: { 'retry-after': '30' },
+        });
+        expect(classifyProviderError(wrap('failed', limited)).retryAfterMs).toBe(30_000);
+    });
+});
+describe('message through the chain', () => {
+    it('reads a window overflow off an inner message', () => {
+        const overflow = new Error('prompt is too long for this model');
+        // A wrapper's message is usually generic, so matching only the outer
+        // text looks at the one string least likely to say anything.
+        expect(classifyProviderError(wrap('request failed', overflow)).code).toBe('context_length_exceeded');
+    });
+    it('lets a status anywhere on the chain beat message text', () => {
+        const badRequest = Object.assign(new Error('bad request'), { status: 400 });
+        const classified = classifyProviderError(wrap('the operation timed out', badRequest));
+        // Status is the more reliable signal, wherever it sits; a wrapper
+        // whose prose says "timed out" must not overrule it.
+        expect(classified.code).toBe('invalid_request');
+    });
+});
+describe('safety', () => {
+    it('terminates on a cause cycle', () => {
+        const a = { message: 'a' };
+        const b = { message: 'b', cause: a };
+        a.cause = b;
+        // Easy to build by accident when errors are re-wrapped in a retry
+        // loop; without a seen-set the walk never returns.
+        expect(classifyProviderError(a).code).toBe('unknown');
+    });
+    it('handles a chain that ends in a non-object', () => {
+        expect(classifyProviderError(wrap('failed', 'a string cause')).code).toBe('unknown');
+    });
+    it('leaves an already-classified error alone', () => {
+        const classified = classifyProviderError(Object.assign(new Error('x'), { status: 429 }));
+        expect(classifyProviderError(wrap('outer', classified))).not.toBe(classified);
+        expect(classifyProviderError(classified)).toBe(classified);
+    });
+    it('classifies an unwrapped error exactly as before', () => {
+        for (const [err, code] of [
+            [Object.assign(new Error('x'), { status: 401 }), 'auth'],
+            [Object.assign(new Error('x'), { status: 404 }), 'not_found'],
+            [Object.assign(new Error('x'), { status: 529 }), 'overloaded'],
+            [new Error('nothing recognisable'), 'unknown'],
+        ]) {
+            expect(classifyProviderError(err).code).toBe(code);
+        }
+    });
+});
+//# sourceMappingURL=cause-chain.test.js.map

package/dist/types/provider/__tests__/cause-chain.test.js.map

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

package/dist/types/provider/__tests__/declared-retryable.test.d.ts

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

package/dist/types/provider/__tests__/declared-retryable.test.d.ts.map

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

package/dist/types/provider/__tests__/declared-retryable.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { ProviderError, classifyProviderError, declaredRetryable } from '../errors.js';
+/**
+ * Retryability was derived solely from namzu's own code set, so a vendor
+ * SDK that says outright "this one is safe to retry" was not listened to.
+ * That set is a second-hand inference from status and wording, and it
+ * necessarily lags every new failure shape a provider invents — a failure
+ * nobody has characterised yet lands on `unknown`, which is treated as
+ * non-retryable, even when its own author flagged it retryable.
+ *
+ * The classification still decides WHAT went wrong. Only the retry verdict
+ * defers to a first-hand statement.
+ */
+describe('a retryable flag declared upstream', () => {
+    it('is read off the error itself', () => {
+        const err = Object.assign(new Error('something new'), { retryable: true });
+        expect(classifyProviderError(err).retryable).toBe(true);
+    });
+    it('is read off a wrapped cause', () => {
+        // Wrapping is the normal case, not an edge one: vendor SDKs wrap
+        // their transport errors and the runtime wraps again on the way out.
+        const inner = Object.assign(new Error('inner'), { retryable: true });
+        const outer = new Error('request failed', { cause: inner });
+        expect(classifyProviderError(outer).retryable).toBe(true);
+    });
+    it('can also say a failure is NOT retryable', () => {
+        // A 503 that the provider knows is permanent for this request.
+        const err = Object.assign(new Error('permanently unavailable'), {
+            status: 503,
+            retryable: false,
+        });
+        const classified = classifyProviderError(err);
+        expect(classified.code).toBe('overloaded');
+        // The code still says what it is; only the verdict changed.
+        expect(classified.retryable).toBe(false);
+    });
+    it('does not change the classification, only the verdict', () => {
+        const err = Object.assign(new Error('bad request'), { status: 400, retryable: true });
+        const classified = classifyProviderError(err);
+        expect(classified.code).toBe('invalid_request');
+        expect(classified.retryable).toBe(true);
+    });
+    it('takes the outermost declaration when links disagree', () => {
+        // The outer layer made the more recent statement, knowing what the
+        // inner one said.
+        const inner = Object.assign(new Error('inner'), { retryable: true });
+        const outer = Object.assign(new Error('outer'), { retryable: false, cause: inner });
+        expect(declaredRetryable(outer)).toBe(false);
+    });
+    it('leaves the code in charge when nothing declared anything', () => {
+        expect(declaredRetryable(new Error('plain'))).toBeUndefined();
+        expect(classifyProviderError(Object.assign(new Error('x'), { status: 429 })).retryable).toBe(true);
+        expect(classifyProviderError(Object.assign(new Error('x'), { status: 401 })).retryable).toBe(false);
+    });
+    it('ignores a non-boolean flag rather than coercing it', () => {
+        // `retryable: 'yes'` is a foreign object's field, not a contract.
+        // Coercing it would let any truthy value silently enable retries.
+        expect(declaredRetryable({ retryable: 'yes' })).toBeUndefined();
+        expect(declaredRetryable({ retryable: 1 })).toBeUndefined();
+    });
+    it('is honoured when a ProviderError is constructed directly', () => {
+        const err = new ProviderError({
+            code: 'invalid_request',
+            message: 'x',
+            retryable: true,
+        });
+        expect(err.retryable).toBe(true);
+    });
+});
+//# sourceMappingURL=declared-retryable.test.js.map

package/dist/types/provider/__tests__/declared-retryable.test.js.map

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

package/dist/types/provider/__tests__/overflow-classification.test.d.ts

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

package/dist/types/provider/__tests__/overflow-classification.test.d.ts.map

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

package/dist/types/provider/__tests__/overflow-classification.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { classifyProviderError } from '../errors.js';
+/**
+ * Overflow is the one 4xx the runtime can act on: it sheds history and
+ * retries. Everything else in the 400 family is surfaced. So the rescue is
+ * gated on the code being EXACTLY `context_length_exceeded`, and anything
+ * that misses that gate dies holding the remedy.
+ *
+ * Detection was a substring search over five phrases. The structural code —
+ * the one field a provider has for saying what went wrong — was extracted
+ * from the cause chain and then fed only to the two transport-errno sets,
+ * so a provider that said `context_length_exceeded` in so many words was
+ * answered with a phrase search that did not match.
+ */
+const overflowReaches = (err) => classifyProviderError(err).code === 'context_length_exceeded';
+describe('the structural code', () => {
+    it('is believed over the status that carries it', () => {
+        // A 400 is a category; the code is the diagnosis.
+        expect(overflowReaches(Object.assign(new Error('Bad request'), { status: 400, code: 'context_length_exceeded' }))).toBe(true);
+    });
+    it('is read from a gateway body discriminator too', () => {
+        expect(overflowReaches(Object.assign(new Error('Bad request'), { status: 400, type: 'context_length_exceeded' }))).toBe(true);
+    });
+    it('is read from a nested error envelope', () => {
+        expect(overflowReaches(Object.assign(new Error('Bad request'), {
+            status: 400,
+            error: { type: 'context_window_exceeded' },
+        }))).toBe(true);
+    });
+    it('is found under a wrapper', () => {
+        const inner = Object.assign(new Error('Bad request'), { code: 'max_tokens_exceeded' });
+        expect(overflowReaches(new Error('request failed', { cause: inner }))).toBe(true);
+    });
+    it('classifies a rate limit from the code alone', () => {
+        const classified = classifyProviderError(Object.assign(new Error('Bad request'), { status: 400, code: 'rate_limit_exceeded' }));
+        expect(classified.code).toBe('rate_limit');
+        expect(classified.retryable).toBe(true);
+    });
+    it('leaves a code it does not recognise to the other signals', () => {
+        const classified = classifyProviderError(Object.assign(new Error('nope'), { status: 404, code: 'some_vendor_specific_thing' }));
+        expect(classified.code).toBe('not_found');
+    });
+});
+describe('wordings that used to miss', () => {
+    it.each([
+        'Input is too long for requested model.',
+        'This request exceeds the maximum length for this model',
+        'The input is too large for the context window',
+        'payload too large for the selected model',
+    ])('%s', (message) => {
+        expect(overflowReaches(Object.assign(new Error(message), { status: 400 }))).toBe(true);
+    });
+    it('still recognises the wordings that already worked', () => {
+        for (const message of [
+            'prompt is too long',
+            'maximum context length exceeded',
+            'too many tokens in request',
+        ]) {
+            expect(overflowReaches(Object.assign(new Error(message), { status: 400 }))).toBe(true);
+        }
+    });
+    it('does not fire on an ordinary bad request', () => {
+        const classified = classifyProviderError(Object.assign(new Error('The model id is not valid'), { status: 400 }));
+        // Overreaching here would send a run into compaction it cannot be
+        // rescued by, and hide the real error behind a retry.
+        expect(classified.code).toBe('invalid_request');
+    });
+});
+describe('an already-classified error', () => {
+    it('is not re-examined, which is why a driver must not guess', () => {
+        // The classifier short-circuits on a typed error. That is correct —
+        // a driver knows its own vendor best — but it means a driver that
+        // pre-files a name whose meaning depends on the body makes the body
+        // unreadable.
+        const preFiled = classifyProviderError(Object.assign(new Error('Input is too long for requested model.'), { status: 400 }));
+        expect(preFiled.code).toBe('context_length_exceeded');
+        expect(classifyProviderError(preFiled)).toBe(preFiled);
+    });
+});
+//# sourceMappingURL=overflow-classification.test.js.map

package/dist/types/provider/__tests__/overflow-classification.test.js.map

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

package/dist/types/provider/chat.d.ts

@@ -1,5 +1,5 @@
 import type { TokenUsage } from '../common/index.js';
-import type { Message, ToolCall } from '../message/index.js';
+import type { Message, ReasoningBlock, ToolCall } from '../message/index.js';
 import type { LLMToolSchema } from '../tool/index.js';
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     type: 'function';
@@ -55,6 +55,28 @@ export interface ChatCompletionParams {
     presencePenalty?: number;
     repetitionPenalty?: number;
     responseFormat?: ResponseFormat;
+    /**
+     * Extended-thinking request.
+     *
+     * Absent from this struct entirely before, and `buildCreateParams`
+     * assembles the request body key-by-key with no passthrough, so
+     * thinking could not be *requested* — while on models where it is on by
+     * default the runtime received blocks it then discarded. Neither half
+     * was expressible.
+     *
+     * Drivers that do not support it ignore the field.
+     */
+    thinking?: ThinkingConfig;
+}
+export interface ThinkingConfig {
+    type: 'enabled' | 'disabled';
+    /** Token allowance for the thinking pass. */
+    budgetTokens?: number;
+    /**
+     * Whether the provider should return full thinking text or a summary.
+     * Purely a request hint; the runtime stores whatever comes back.
+     */
+    display?: 'full' | 'summarized';
 }
 export interface ChatCompletionResponse {
     id: string;
@@ -63,6 +85,10 @@ export interface ChatCompletionResponse {
         role: 'assistant';
         content: string | null;
         toolCalls?: ToolCall[];
+        /** Reasoning blocks the model emitted, in original block order. */
+        reasoning?: readonly ReasoningBlock[];
+        /** Passages this turn cites, in the order the model made them. */
+        citations?: readonly import('../message/index.js').Citation[];
     };
     finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter';
     usage: TokenUsage;

package/dist/types/provider/chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/types/provider/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,MAAM,MAAM,UAAU,GACnB,MAAM,GACN,MAAM,GACN,UAAU,GACV;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACA,IAAI,EAAE,aAAa,CAAA;IACnB,WAAW,EAAE;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC/B,MAAM,CAAC,EAAE,OAAO,CAAA;KAChB,CAAA;CACA,CAAA;AAEJ,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;IACvB;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IAEf;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QACR,IAAI,EAAE,WAAW,CAAA;QACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;QACtB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;KACtB,CAAA;IACD,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IACjE,KAAK,EAAE,UAAU,CAAA;CACjB"}
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/types/provider/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,MAAM,MAAM,UAAU,GACnB,MAAM,GACN,MAAM,GACN,UAAU,GACV;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACA,IAAI,EAAE,aAAa,CAAA;IACnB,WAAW,EAAE;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC/B,MAAM,CAAC,EAAE,OAAO,CAAA;KAChB,CAAA;CACA,CAAA;AAEJ,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;IACvB;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IAEf;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,cAAc,CAAC,EAAE,cAAc,CAAA;IAE/B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;CACzB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,SAAS,GAAG,UAAU,CAAA;IAC5B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QACR,IAAI,EAAE,WAAW,CAAA;QACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;QACtB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;QACtB,mEAAmE;QACnE,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;QACrC,kEAAkE;QAClE,SAAS,CAAC,EAAE,SAAS,OAAO,qBAAqB,EAAE,QAAQ,EAAE,CAAA;KAC7D,CAAA;IACD,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IACjE,KAAK,EAAE,UAAU,CAAA;CACjB"}

package/dist/types/provider/config.d.ts

@@ -24,11 +24,85 @@ export type ProviderType = keyof ProviderConfigRegistry & string;
 export type ProviderFactoryConfig = {
     [K in ProviderType]: ProviderConfigRegistry[K];
 }[ProviderType];
-export interface MockProviderConfig {
-    type: 'mock';
+/** One scripted tool call within a {@link MockTurn}. */
+export interface MockToolCall {
+    name: string;
+    /** Serialized to JSON and streamed in fragments. */
+    args?: Record<string, unknown>;
+    /** Defaults to a deterministic `call_<turn>_<index>`. */
+    id?: string;
+    /** Fragment size for the argument JSON; smaller exercises more buffering. */
+    argChunkSize?: number;
+    /**
+     * Omit the block-close signal and stop mid-JSON, reproducing the
+     * provider cutting a tool call off at `max_tokens`. The consumer should
+     * mark the call `inputTruncated` rather than crashing on a parse.
+     */
+    truncateArguments?: boolean;
+    /**
+     * Emit this raw string as the argument payload instead of serializing
+     * `args`. For scripting malformed or partial JSON the model could
+     * plausibly produce.
+     */
+    rawArguments?: string;
+    /**
+     * Throw after the argument fragments, mid-tool-block.
+     *
+     * This is the failure the truncated-tool-input recovery path exists
+     * for — a provider going idle while streaming tool JSON — so it has to
+     * be scriptable, or that path can only be tested by hand-rolling a
+     * provider.
+     */
+    throwAfterArguments?: string;
+}
+/** One assistant turn the mock provider plays. */
+export interface MockTurn {
+    text?: string;
+    toolCalls?: MockToolCall[];
+    /** Passages this scripted turn cites, emitted before its text. */
+    citations?: import('../message/index.js').Citation[];
+    finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter';
+    usage?: Partial<import('../common/index.js').TokenUsage>;
+    /** Text fragment size. */
+    chunkSize?: number;
+    /** Fail the request outright, before any chunk — e.g. a 429. */
+    error?: {
+        message: string;
+        status?: number;
+    };
+    /** Fail mid-stream after N text chunks, to exercise recovery paths. */
+    throwAfterChunks?: number;
+    throwMessage?: string;
+}
+/**
+ * The scripted behavior itself, without the registry discriminant, so a
+ * test can `new MockLLMProvider({ turns: [...] })` directly.
+ */
+export interface MockScript {
     model?: string;
+    /** Shorthand for a single text-only turn. */
     responseText?: string;
     responseDelayMs?: number;
+    /**
+     * Scripted turns. A script shorter than the run repeats its last entry,
+     * so a loop bug shows up as repetition rather than a crash.
+     */
+    turns?: MockTurn[];
+    /** Full control: decide each turn from the request that triggered it. */
+    nextTurn?: (params: import('./chat.js').ChatCompletionParams, turnIndex: number) => MockTurn;
+    /**
+     * Override the capability declaration for this instance.
+     *
+     * Capability negotiation degrades a run when a driver says it cannot do
+     * something, and testing that path means being able to SAY it — a fixed
+     * registry-level declaration cannot express "a driver with no vision".
+     */
+    capabilities?: ProviderCapabilities;
+    /** Observe every request (assert on tools, toolChoice, cacheControl…). */
+    onRequest?: (params: import('./chat.js').ChatCompletionParams) => void;
+}
+export interface MockProviderConfig extends MockScript {
+    type: 'mock';
 }
 /**
  * What a provider DRIVER actually does with the request — not what the
@@ -52,6 +126,13 @@ export interface ProviderCapabilities {
      * default — the runtime only warns when a driver explicitly says no).
      */
     supportsVision?: boolean;
+    /**
+     * Whether the driver maps user-message DOCUMENT attachments into the
+     * provider request. Separate from vision because the two are separate
+     * wire shapes and a driver can map one without the other. Absent ⇒
+     * treated as capable, same permissive default.
+     */
+    supportsDocuments?: boolean;
     maxOutputTokens?: number;
 }
 export interface ProviderFactoryResult {