@namzu/sdk 2.0.0 → 3.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/provider/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,kBAAkB,CAAA;CACxB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,sBAAsB,GAAG,MAAM,CAAA;AAEhE,MAAM,MAAM,qBAAqB,GAAG;KAClC,CAAC,IAAI,YAAY,GAAG,sBAAsB,CAAC,CAAC,CAAC;CAC9C,CAAC,YAAY,CAAC,CAAA;AAEf,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACpC,aAAa,EAAE,OAAO,CAAA;IACtB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,uBAAuB,EAAE,OAAO,CAAA;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,WAAW,CAAA;IACrB,YAAY,EAAE,oBAAoB,CAAA;CAClC;AAED,MAAM,WAAW,eAAe;IAC/B,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC9C,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,WAAW,CAAA;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAA;CACnC;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAA;AAElF,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC3D;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAA;CACnC;AAED,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,MAAM,EAAE,CAAC,KAAK,WAAW,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/provider/config.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,102 @@
+/**
+ * Provider failure taxonomy.
+ *
+ * Every driver throws whatever its underlying vendor SDK threw, which
+ * means the runtime cannot tell a 429 from a malformed request from a
+ * dead socket — and therefore cannot decide whether to back off, fail
+ * fast, or compact and retry. Classification is the substrate the retry
+ * policy stands on; without it "add a retry" is unimplementable.
+ *
+ * The union is deliberately small. It answers exactly three questions the
+ * runtime asks: is it worth retrying, should the delay come from the
+ * server, and is this a context problem the run could recover from by
+ * shedding history.
+ */
+export type ProviderErrorCode = 
+/** 429. Back off; honour `retryAfterMs` when the server sent one. */
+'rate_limit'
+/** 529 / 503 — the model is up but saturated. Back off. */
+ | 'overloaded'
+/** Any other 5xx. Back off. */
+ | 'server_error'
+/** The request timed out in transit. Retry. */
+ | 'timeout'
+/** Socket/DNS/TLS failure before a response. Retry. */
+ | 'network'
+/** 401 / 403. A retry cannot help. */
+ | 'auth'
+/** 400 and friends. A retry cannot help. */
+ | 'invalid_request'
+/** The prompt exceeds the model window. Retrying verbatim cannot help. */
+ | 'context_length_exceeded'
+/** The provider refused on safety grounds. */
+ | 'content_filter'
+/** 404 — unknown model or endpoint. */
+ | 'not_found'
+/** Unclassifiable. Treated as non-retryable. */
+ | 'unknown';
+export interface ProviderErrorInit {
+    readonly code: ProviderErrorCode;
+    readonly message: string;
+    readonly providerId?: string;
+    readonly status?: number;
+    /** Server-directed backoff, derived from a `Retry-After` header. */
+    readonly retryAfterMs?: number;
+    /**
+     * Override the code's own verdict on retryability.
+     *
+     * Omit and the code decides, which is the normal path. Set it when
+     * something closer to the failure already said so — see
+     * {@link declaredRetryable}.
+     */
+    readonly retryable?: boolean;
+    readonly cause?: unknown;
+}
+/**
+ * A `retryable` flag declared anywhere on the cause chain.
+ *
+ * Retryability was derived solely from namzu's own code set, so a provider
+ * that says outright "this one is safe to retry" was not listened to —
+ * and the code set is a second-hand inference from status and wording that
+ * necessarily lags every new failure shape a vendor invents. Read
+ * duck-typed rather than through an interface, because the flag arrives on
+ * a foreign SDK's error object that namzu does not control.
+ *
+ * The FIRST link that declares one wins: the outermost declaration is the
+ * most recent statement about the failure, made by whichever layer knew
+ * enough to make it.
+ */
+export declare function declaredRetryable(err: unknown): boolean | undefined;
+export declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    readonly providerId: string | undefined;
+    readonly status: number | undefined;
+    readonly retryAfterMs: number | undefined;
+    readonly retryable: boolean;
+    constructor(init: ProviderErrorInit);
+}
+export declare function isProviderError(err: unknown): err is ProviderError;
+/**
+ * An abort is a control-flow signal, not a provider failure: the run loop
+ * settles it as `cancelled`. It must never be reclassified or retried.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Turn whatever a driver threw into a {@link ProviderError}.
+ *
+ * Precedence is deliberate: a STRUCTURAL code is the most specific
+ * signal, then HTTP status, then transport errno, then message text. `context_length_exceeded` is checked
+ * ahead of the generic 400 mapping because it is the one 4xx the runtime
+ * can actually act on (shed history and retry) rather than surface.
+ *
+ * Every signal is read across the WHOLE cause chain, not off the error
+ * handed in. Wrapping is the normal case — a vendor SDK wraps its
+ * transport error and the runtime wraps again on the way out — and reading
+ * only the outer link meant a rate limit wrapped once classified as
+ * `unknown`, which is non-retryable. The retry policy was therefore dead
+ * for every failure that was not the outermost throwable.
+ *
+ * Aborts are passed through untouched — see {@link isAbortError}.
+ */
+export declare function classifyProviderError(err: unknown, providerId?: string, now?: number): ProviderError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/types/provider/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB;AAC5B,qEAAqE;AACnE,YAAY;AACd,2DAA2D;GACzD,YAAY;AACd,+BAA+B;GAC7B,cAAc;AAChB,+CAA+C;GAC7C,SAAS;AACX,uDAAuD;GACrD,SAAS;AACX,sCAAsC;GACpC,MAAM;AACR,4CAA4C;GAC1C,iBAAiB;AACnB,0EAA0E;GACxE,yBAAyB;AAC3B,8CAA8C;GAC5C,gBAAgB;AAClB,uCAAuC;GACrC,WAAW;AACb,gDAAgD;GAC9C,SAAS,CAAA;AAEZ,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAMnE;AAWD,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;gBAEf,IAAI,EAAE,iBAAiB;CAenC;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,aAAa,CAElE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOlD;AA6ND;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACpC,GAAG,EAAE,OAAO,EACZ,UAAU,CAAC,EAAE,MAAM,EACnB,GAAG,GAAE,MAAmB,GACtB,aAAa,CAuGf"}

package/dist/types/provider/errors.js

@@ -0,0 +1,393 @@
+/**
+ * A `retryable` flag declared anywhere on the cause chain.
+ *
+ * Retryability was derived solely from namzu's own code set, so a provider
+ * that says outright "this one is safe to retry" was not listened to —
+ * and the code set is a second-hand inference from status and wording that
+ * necessarily lags every new failure shape a vendor invents. Read
+ * duck-typed rather than through an interface, because the flag arrives on
+ * a foreign SDK's error object that namzu does not control.
+ *
+ * The FIRST link that declares one wins: the outermost declaration is the
+ * most recent statement about the failure, made by whichever layer knew
+ * enough to make it.
+ */
+export function declaredRetryable(err) {
+    for (const link of causeChain(err)) {
+        const declared = link.retryable;
+        if (typeof declared === 'boolean')
+            return declared;
+    }
+    return undefined;
+}
+/** Codes for which sending the identical request again may succeed. */
+const RETRYABLE = new Set([
+    'rate_limit',
+    'overloaded',
+    'server_error',
+    'timeout',
+    'network',
+]);
+export class ProviderError extends Error {
+    code;
+    providerId;
+    status;
+    retryAfterMs;
+    retryable;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = 'ProviderError';
+        this.code = init.code;
+        this.providerId = init.providerId;
+        this.status = init.status;
+        this.retryAfterMs = init.retryAfterMs;
+        // The code decides, unless something upstream already declared
+        // otherwise. A vendor SDK that sets `retryable` on its own error is
+        // making a first-hand statement about a failure it produced; namzu's
+        // code set is a second-hand inference from status and wording, and
+        // it necessarily lags every new failure shape a provider invents.
+        // Deriving solely from the code discarded the better signal.
+        this.retryable = init.retryable ?? RETRYABLE.has(init.code);
+    }
+}
+export function isProviderError(err) {
+    return err instanceof ProviderError;
+}
+/**
+ * An abort is a control-flow signal, not a provider failure: the run loop
+ * settles it as `cancelled`. It must never be reclassified or retried.
+ */
+export function isAbortError(err) {
+    if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError')) {
+        return true;
+    }
+    // DOMException-shaped aborts from fetch, and raw `signal.reason` values.
+    const name = err?.name;
+    return name === 'AbortError';
+}
+/**
+ * Every throwable on the cause chain, outermost first.
+ *
+ * A signal was only ever read off the error handed in, so one layer of
+ * wrapping hid it — and wrapping is the normal case, not an edge one:
+ * vendor SDKs wrap their transport errors and the runtime wraps again on
+ * the way out. A rate limit wrapped once classified as `unknown`, which is
+ * treated as non-retryable, so the retry policy was dead for every failure
+ * that was not the outermost throwable.
+ *
+ * The `seen` set is not defensive decoration: a cause cycle is easy to
+ * build by accident when errors are re-wrapped in a retry loop, and
+ * without it this walk never terminates.
+ */
+function* causeChain(err) {
+    const seen = new Set();
+    let current = err;
+    while (current !== null && typeof current === 'object' && !seen.has(current)) {
+        seen.add(current);
+        yield current;
+        current = current.cause;
+    }
+}
+function readStatus(err) {
+    for (const link of causeChain(err)) {
+        const e = link;
+        for (const candidate of [
+            e.status,
+            e.statusCode,
+            e.response?.status,
+            e.$metadata?.httpStatusCode,
+        ]) {
+            if (typeof candidate === 'number' && Number.isFinite(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * `Retry-After` is either delta-seconds or an HTTP date. Both appear in
+ * the wild; most providers send seconds.
+ */
+function readRetryAfterMs(err, now) {
+    for (const link of causeChain(err)) {
+        const headers = link.headers;
+        if (!headers)
+            continue;
+        let raw;
+        if (typeof headers.get === 'function') {
+            raw = headers.get('retry-after') ?? undefined;
+        }
+        else if (typeof headers === 'object') {
+            const bag = headers;
+            const value = bag['retry-after'] ?? bag['Retry-After'];
+            if (typeof value === 'string' || typeof value === 'number')
+                raw = String(value);
+        }
+        if (raw === undefined)
+            continue;
+        const seconds = Number(raw);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return Math.round(seconds * 1000);
+        const at = Date.parse(raw);
+        if (Number.isFinite(at))
+            return Math.max(0, at - now);
+    }
+    return undefined;
+}
+function readErrnoCode(err) {
+    // The whole chain, not one level down. A transport failure is usually
+    // the innermost link and everything above it is context, so stopping at
+    // depth one meant a socket reset behind two wrappers read as unknown —
+    // which is non-retryable, for the one class of failure where retrying
+    // is almost always right.
+    for (const link of causeChain(err)) {
+        if (typeof link.code === 'string')
+            return link.code;
+    }
+    return undefined;
+}
+/** Every message on the chain, outermost first. */
+function chainMessages(err) {
+    const out = [];
+    for (const link of causeChain(err)) {
+        if (typeof link.message === 'string' && link.message.length > 0)
+            out.push(link.message);
+    }
+    return out;
+}
+/** Node/undici transport failures that mean "never reached the model". */
+const NETWORK_ERRNOS = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ECONNABORTED',
+    'EPIPE',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EPROTO',
+    'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_RESPONSE_STATUS_CODE',
+]);
+const TIMEOUT_ERRNOS = new Set([
+    'ETIMEDOUT',
+    'ESOCKETTIMEDOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+]);
+function codeFromStatus(status) {
+    if (status === 429)
+        return 'rate_limit';
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 404)
+        return 'not_found';
+    if (status === 408)
+        return 'timeout';
+    if (status === 529 || status === 503)
+        return 'overloaded';
+    if (status >= 500)
+        return 'server_error';
+    if (status >= 400)
+        return 'invalid_request';
+    return 'unknown';
+}
+/**
+ * Message sniffing is the LAST resort, used only when there is no status
+ * and no errno. Vendors that tunnel a 400 through a 200 body (several
+ * gateways do) are only reachable this way.
+ */
+function codeFromMessage(message) {
+    const m = message.toLowerCase();
+    if (m.includes('context length') ||
+        m.includes('context_length') ||
+        m.includes('maximum context') ||
+        m.includes('too many tokens') ||
+        m.includes('prompt is too long') ||
+        // Real wordings that missed every phrase above and so classified as
+        // a plain invalid request — which is not retryable, and which the
+        // overflow rescue tests for by exact equality. The run died holding
+        // the remedy.
+        m.includes('too long for') ||
+        m.includes('maximum length') ||
+        m.includes('exceeds the maximum') ||
+        m.includes('input is too large') ||
+        m.includes('too large for')) {
+        return 'context_length_exceeded';
+    }
+    if (m.includes('rate limit') || m.includes('rate_limit') || m.includes('too many requests')) {
+        return 'rate_limit';
+    }
+    if (m.includes('overloaded'))
+        return 'overloaded';
+    if (m.includes('content filter') ||
+        m.includes('content_filter') ||
+        m.includes('content policy')) {
+        return 'content_filter';
+    }
+    if (m.includes('timed out') || m.includes('timeout'))
+        return 'timeout';
+    if (m.includes('unauthorized') || m.includes('invalid api key') || m.includes('authentication')) {
+        return 'auth';
+    }
+    return undefined;
+}
+/**
+ * Structural failure codes providers put on the error itself, or on the
+ * `type` discriminator of a gateway's error body.
+ *
+ * These were extracted and then thrown away: the walked `code` fed only
+ * the two transport-errno sets, so a provider that said
+ * `context_length_exceeded` in the one field designed to say it was
+ * answered with a substring search that did not match, filed as a plain
+ * invalid request, and never reached the rescue that exists for exactly
+ * this failure.
+ *
+ * A code is checked BEFORE the status because it is strictly more
+ * specific: a 400 is a category, `context_length_exceeded` is the
+ * diagnosis. Only unambiguous codes belong here — anything whose meaning
+ * depends on the body stays with the message pass.
+ */
+const STRUCTURAL_CODES = {
+    context_length_exceeded: 'context_length_exceeded',
+    context_window_exceeded: 'context_length_exceeded',
+    max_tokens_exceeded: 'context_length_exceeded',
+    string_above_max_length: 'context_length_exceeded',
+    rate_limit_exceeded: 'rate_limit',
+    rate_limit_error: 'rate_limit',
+    insufficient_quota: 'rate_limit',
+    overloaded_error: 'overloaded',
+    content_filter: 'content_filter',
+    content_policy_violation: 'content_filter',
+    invalid_api_key: 'auth',
+    authentication_error: 'auth',
+    permission_error: 'auth',
+    model_not_found: 'not_found',
+};
+function codeFromStructure(err) {
+    for (const link of causeChain(err)) {
+        for (const field of [link.code, link.type, link.error?.type]) {
+            if (typeof field !== 'string')
+                continue;
+            const mapped = STRUCTURAL_CODES[field.toLowerCase()];
+            if (mapped)
+                return mapped;
+        }
+    }
+    return undefined;
+}
+/**
+ * Turn whatever a driver threw into a {@link ProviderError}.
+ *
+ * Precedence is deliberate: a STRUCTURAL code is the most specific
+ * signal, then HTTP status, then transport errno, then message text. `context_length_exceeded` is checked
+ * ahead of the generic 400 mapping because it is the one 4xx the runtime
+ * can actually act on (shed history and retry) rather than surface.
+ *
+ * Every signal is read across the WHOLE cause chain, not off the error
+ * handed in. Wrapping is the normal case — a vendor SDK wraps its
+ * transport error and the runtime wraps again on the way out — and reading
+ * only the outer link meant a rate limit wrapped once classified as
+ * `unknown`, which is non-retryable. The retry policy was therefore dead
+ * for every failure that was not the outermost throwable.
+ *
+ * Aborts are passed through untouched — see {@link isAbortError}.
+ */
+export function classifyProviderError(err, providerId, now = Date.now()) {
+    if (isProviderError(err))
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    const status = readStatus(err);
+    const errno = readErrnoCode(err);
+    const retryAfterMs = readRetryAfterMs(err, now);
+    // Message sniffing also reads the chain. The wording that identifies a
+    // failure sits on the link that produced it, and a wrapper's message is
+    // usually generic ("request failed") — so matching only the outer text
+    // looks at the one string least likely to say anything.
+    const messages = chainMessages(err);
+    const fromMessage = messages.map(codeFromMessage).find((code) => code !== undefined);
+    // A first-hand statement from whoever produced the failure, if there
+    // is one. It outranks the code's inference, not the code itself: the
+    // classification still says WHAT went wrong.
+    const declared = declaredRetryable(err);
+    // The structural code first: it is the one field designed to say what
+    // went wrong, and it is more specific than the status carrying it. A
+    // 400 is a category; `context_length_exceeded` is the diagnosis.
+    const structural = codeFromStructure(err);
+    if (structural !== undefined) {
+        return new ProviderError({
+            code: structural,
+            message,
+            providerId,
+            ...(status !== undefined ? { status } : {}),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            ...(declared !== undefined ? { retryable: declared } : {}),
+            cause: err,
+        });
+    }
+    // A 400 that is really a window overflow must not be filed as a plain
+    // invalid_request: the caller can recover from one and not the other.
+    if (messages.some((m) => codeFromMessage(m) === 'context_length_exceeded')) {
+        return new ProviderError({
+            code: 'context_length_exceeded',
+            message,
+            providerId,
+            status,
+            ...(declared !== undefined ? { retryable: declared } : {}),
+            cause: err,
+        });
+    }
+    if (status !== undefined) {
+        return new ProviderError({
+            code: codeFromStatus(status),
+            message,
+            providerId,
+            status,
+            retryAfterMs,
+            ...(declared !== undefined ? { retryable: declared } : {}),
+            cause: err,
+        });
+    }
+    if (errno !== undefined) {
+        if (TIMEOUT_ERRNOS.has(errno)) {
+            return new ProviderError({
+                code: 'timeout',
+                message,
+                providerId,
+                retryable: declared,
+                cause: err,
+            });
+        }
+        if (NETWORK_ERRNOS.has(errno)) {
+            return new ProviderError({
+                code: 'network',
+                message,
+                providerId,
+                retryable: declared,
+                cause: err,
+            });
+        }
+    }
+    // `fetch` rejects with a bare TypeError on transport failure.
+    if (err instanceof TypeError && /fetch|network/i.test(message)) {
+        return new ProviderError({
+            code: 'network',
+            message,
+            providerId,
+            retryable: declared,
+            cause: err,
+        });
+    }
+    // The unclassified tail is where a declared flag matters most: a
+    // failure nobody has characterised lands on `unknown`, which is treated
+    // as non-retryable — even when its own author said otherwise.
+    return new ProviderError({
+        code: fromMessage ?? 'unknown',
+        message,
+        providerId,
+        retryAfterMs,
+        retryable: declared,
+        cause: err,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/types/provider/errors.js.map

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

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

@@ -1,7 +1,8 @@
-export type { ToolChoice, ResponseFormat, CacheControl, ChatCompletionParams, ChatCompletionResponse, } from './chat.js';
+export type { ToolChoice, ResponseFormat, CacheControl, ChatCompletionParams, ChatCompletionResponse, ThinkingConfig, } from './chat.js';
 export type { StreamChunk } from './stream.js';
 export type { ModelInfo } from './model.js';
 export type { LLMProvider } from './interface.js';
 export type { ProviderErrorInfo, ProviderErrorKind, ProviderRequestErrorInit, } from './error.js';
-export type { ProviderConfigRegistry, ProviderType, MockProviderConfig, ProviderFactoryConfig, ProviderCapabilities, ProviderFactoryResult, RegisterOptions, LazyProviderModule, LazyProviderLoader, RegisterLazyOptions, LLMProviderConstructor, } from './config.js';
+export type { ProviderConfigRegistry, ProviderType, MockProviderConfig, MockScript, MockToolCall, MockTurn, ProviderFactoryConfig, ProviderCapabilities, ProviderFactoryResult, RegisterOptions, LazyProviderModule, LazyProviderLoader, RegisterLazyOptions, LLMProviderConstructor, } from './config.js';
+export type { ProviderErrorCode, ProviderErrorInit } from './errors.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/provider/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,GACtB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/provider/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,GACd,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

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

@@ -14,9 +14,9 @@ export interface StreamChunk {
         }>;
         /**
          * Provider signal that a tool-use content block has finished
-         * streaming arguments. Translates from Anthropic's
-         * `content_block_stop` (for tool_use blocks) and from the
-         * equivalent end-of-tool-arguments boundary on other providers.
+         * streaming arguments. Translates from whatever a provider uses to
+         * close a tool-use block, and from the equivalent
+         * end-of-tool-arguments boundary elsewhere.
          *
          * The orchestrator uses this to emit `tool_input_completed` per
          * tool as soon as its block closes, rather than waiting for
@@ -30,9 +30,65 @@ export interface StreamChunk {
             index: number;
             id: string;
         };
+        /**
+         * A fragment of a reasoning block.
+         *
+         * There was no channel for this at all, so `thinking_delta` and
+         * `signature_delta` fell through the driver's `default: // ignore`
+         * and the blocks could not be stored even in principle — which is
+         * what made the verbatim-echo contract unsatisfiable and left the
+         * streaming UI with a multi-second stall and zero events.
+         *
+         * `index` groups fragments belonging to the same block, exactly as
+         * `toolCalls[].index` does. `done` closes it.
+         */
+        reasoning?: {
+            index: number;
+            type?: 'thinking' | 'redacted_thinking';
+            text?: string;
+            /** Arrives once, at the end of the block. */
+            signature?: string;
+            /** Opaque payload for a redacted block. */
+            encrypted?: string;
+            done?: boolean;
+        };
+        /**
+         * A passage the model is citing, as it arrives.
+         *
+         * Its own channel rather than a field on `content`, because a
+         * citation is not text the reader sees: it lands on the assistant
+         * message beside the prose. Drivers that cannot report one leave
+         * this undefined and the answer simply carries none.
+         */
+        citation?: import('../message/index.js').Citation;
     };
     finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter';
     usage?: TokenUsage;
     error?: string;
+    /**
+     * The call failed and is about to be retried after a backoff.
+     *
+     * Emitted by the retry decorator, never by a driver. It rides the
+     * stream because that is the only channel open while the decorator is
+     * sleeping: the consumer is blocked inside the provider's iterator, so
+     * an out-of-band callback could not reach it until the backoff was
+     * already over — which is exactly the window a host needs to be told
+     * about. A retry chunk carries no delta and must not be treated as
+     * output.
+     */
+    retry?: ProviderRetryNotice;
+}
+/** See {@link StreamChunk.retry}. */
+export interface ProviderRetryNotice {
+    /** 1-based attempt that just failed. */
+    readonly attempt: number;
+    readonly maxRetries: number;
+    /** How long the decorator is about to sleep. */
+    readonly delayMs: number;
+    /** Classified failure code, as `classifyProviderError` reports it. */
+    readonly code: string;
+    readonly status?: number;
+    /** The delay came from the server's own `Retry-After`, not backoff. */
+    readonly serverDirected: boolean;
 }
 //# sourceMappingURL=stream.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/types/provider/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,SAAS,CAAC,EAAE,KAAK,CAAC;YACjB,KAAK,EAAE,MAAM,CAAA;YACb,EAAE,CAAC,EAAE,MAAM,CAAA;YACX,IAAI,CAAC,EAAE,UAAU,CAAA;YACjB,QAAQ,CAAC,EAAE;gBACV,IAAI,CAAC,EAAE,MAAM,CAAA;gBACb,SAAS,CAAC,EAAE,MAAM,CAAA;aAClB,CAAA;SACD,CAAC,CAAA;QACF;;;;;;;;;;;;;WAaG;QACH,WAAW,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAA;YACb,EAAE,EAAE,MAAM,CAAA;SACV,CAAA;KACD,CAAA;IACD,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IAClE,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/types/provider/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,SAAS,CAAC,EAAE,KAAK,CAAC;YACjB,KAAK,EAAE,MAAM,CAAA;YACb,EAAE,CAAC,EAAE,MAAM,CAAA;YACX,IAAI,CAAC,EAAE,UAAU,CAAA;YACjB,QAAQ,CAAC,EAAE;gBACV,IAAI,CAAC,EAAE,MAAM,CAAA;gBACb,SAAS,CAAC,EAAE,MAAM,CAAA;aAClB,CAAA;SACD,CAAC,CAAA;QACF;;;;;;;;;;;;;WAaG;QACH,WAAW,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAA;YACb,EAAE,EAAE,MAAM,CAAA;SACV,CAAA;QAED;;;;;;;;;;;WAWG;QACH,SAAS,CAAC,EAAE;YACX,KAAK,EAAE,MAAM,CAAA;YACb,IAAI,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAAA;YACvC,IAAI,CAAC,EAAE,MAAM,CAAA;YACb,6CAA6C;YAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;YAClB,2CAA2C;YAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;YAClB,IAAI,CAAC,EAAE,OAAO,CAAA;SACd,CAAA;QAED;;;;;;;WAOG;QACH,QAAQ,CAAC,EAAE,OAAO,qBAAqB,EAAE,QAAQ,CAAA;KACjD,CAAA;IACD,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IAClE,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAC3B;AAED,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IACnC,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CAChC"}

package/dist/types/rag/embedding.d.ts

@@ -10,8 +10,17 @@ export interface EmbeddingConfig {
     dimensions?: number;
     batchSize?: number;
 }
-export interface OpenRouterEmbeddingConfig extends EmbeddingConfig {
+/**
+ * Config for {@link HttpEmbeddingProvider}.
+ *
+ * `baseUrl` is REQUIRED. It used to default to one vendor's host, which
+ * meant a caller who never named an endpoint still sent its text to one —
+ * a default network destination is a decision the caller has to make out
+ * loud.
+ */
+export interface HttpEmbeddingConfig extends EmbeddingConfig {
     apiKey: string;
-    baseUrl?: string;
+    /** Root of an embeddings API; `/embeddings` is appended. */
+    baseUrl: string;
 }
 //# sourceMappingURL=embedding.d.ts.map

package/dist/types/rag/embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../../src/types/rag/embedding.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC3C,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAC5C;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,yBAA0B,SAAQ,eAAe;IACjE,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB"}
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../../src/types/rag/embedding.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC3C,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAC5C;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC3D,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;CACf"}