c0de-agent 0.0.0 → 1.0.0

package/dist/llm/protocols/utils/tool-stream.js

@@ -0,0 +1,94 @@
+import { isLLMError, llmError, reasonMessage } from '../../schema/errors.js';
+const empty = () => ({});
+/**
+ * Append a tool-call delta. If the index is new, emit a `tool-input-start`
+ * (using the delta's id/name if present, else synthesized). Then emit a
+ * `tool-input-delta` when an argument fragment is present.
+ */
+const appendOrStart = (state, delta) => {
+    const current = state[delta.index];
+    const events = [];
+    let next;
+    if (current === undefined) {
+        const id = delta.id;
+        const name = delta.name;
+        // 无效 id/name（缺失或空字符串）：丢弃该 delta 而非抛错。部分兼容
+        // provider 把 tool call 的 arguments 流式片段拆成多个独立 delta，每片
+        // id/name 为空。接受空值会产生空 id 的 tool call，导致下一轮
+        // invalid tool_call_id；抛错则让整个流崩溃。跳过最稳妥。
+        if (!id || !name) {
+            return { state, events };
+        }
+        next = { id, name, input: '', started: false };
+        const start = { type: 'tool-input-start', id, name };
+        events.push(start);
+        next.started = true;
+    }
+    else {
+        next = { ...current };
+    }
+    if (delta.argumentsDelta !== undefined && delta.argumentsDelta.length > 0) {
+        next.input += delta.argumentsDelta;
+        const d = {
+            type: 'tool-input-delta',
+            id: next.id,
+            name: next.name,
+            text: delta.argumentsDelta,
+        };
+        events.push(d);
+    }
+    return { state: { ...state, [delta.index]: next }, events };
+};
+/** Parse a raw JSON arguments string; empty string becomes `{}`. */
+const parseToolInput = (raw) => {
+    const source = raw.length === 0 ? '{}' : raw;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        throw llmError('ProviderShared', 'stream', {
+            _tag: 'InvalidProviderOutput',
+            message: `Invalid JSON tool arguments: ${source}`,
+            raw: source,
+        });
+    }
+};
+/**
+ * Finalize all pending tool calls (OpenAI Chat style — no per-tool stop event).
+ * Emits `tool-input-end` + parsed `tool-call` for each, and clears state.
+ */
+const finishAll = (state) => {
+    const events = [];
+    const tools = [];
+    for (const key of Object.keys(state)) {
+        const tool = state[Number(key)];
+        if (tool === undefined)
+            continue;
+        const end = { type: 'tool-input-end', id: tool.id, name: tool.name };
+        events.push(end);
+        // 解析失败不抛错：模型可能输出不完整 JSON（流被截断/提前结束）。
+        // 标记 _parseError + _raw 让流完整结束，由 agent loop 把错误反馈给模型重试，
+        // 而非让整个会话崩溃。对齐 oh-my-pi 的 __parseError 容错（agent-loop.ts:1741）。
+        let input;
+        try {
+            input = parseToolInput(tool.input);
+        }
+        catch (e) {
+            // parseToolInput 抛的是 llmError（普通对象，非 Error 实例），直接 String(e)
+            // 会退化成 "[object Object]"。按错误类型提取可读消息。
+            input = {
+                _parseError: isLLMError(e)
+                    ? reasonMessage(e.reason)
+                    : e instanceof Error
+                        ? e.message
+                        : String(e),
+                _raw: tool.input,
+            };
+        }
+        tools.push({ id: tool.id, name: tool.name, input });
+        const call = { type: 'tool-call', id: tool.id, name: tool.name, input };
+        events.push(call);
+    }
+    return { state: {}, events, tools };
+};
+export { appendOrStart, empty, finishAll, parseToolInput };

package/dist/llm/provider-error.d.ts

@@ -0,0 +1,5 @@
+/** True when a provider error message indicates the input exceeded the context window. */
+declare const isContextOverflow: (message: string) => boolean;
+/** True when a thrown/produced value represents a context-overflow failure. */
+declare const isContextOverflowFailure: (failure: unknown) => boolean;
+export { isContextOverflow, isContextOverflowFailure };

package/dist/llm/provider-error.js

@@ -0,0 +1,33 @@
+import { isLLMError } from './schema/errors.js';
+const patterns = [
+    /prompt is too long/i,
+    /input is too long for requested model/i,
+    /exceeds the context window/i,
+    /input token count.*exceeds the maximum/i,
+    /maximum prompt length is \d+/i,
+    /reduce the length of the messages/i,
+    /maximum context length is \d+ tokens/i,
+    /exceeds the limit of \d+/i,
+    /exceeds the available context size/i,
+    /greater than the context length/i,
+    /context window exceeds limit/i,
+    /exceeded model token limit/i,
+    /context[_ ]length[_ ]exceeded/i,
+    /request entity too large/i,
+    /context length is only \d+ tokens/i,
+    /input length.*exceeds.*context length/i,
+    /prompt too long; exceeded (?:max )?context length/i,
+    /too large for model with \d+ maximum context length/i,
+    /model_context_window_exceeded/i,
+];
+/** True when a provider error message indicates the input exceeded the context window. */
+const isContextOverflow = (message) => patterns.some((pattern) => pattern.test(message)) ||
+    /^4(00|13)\s*(status code)?\s*\(no body\)/i.test(message);
+/** True when a thrown/produced value represents a context-overflow failure. */
+const isContextOverflowFailure = (failure) => {
+    if (!isLLMError(failure))
+        return false;
+    const reason = failure.reason;
+    return reason._tag === 'InvalidRequest' && reason.classification === 'context-overflow';
+};
+export { isContextOverflow, isContextOverflowFailure };

package/dist/llm/provider.d.ts

@@ -0,0 +1,32 @@
+import type { ChatMessage, ChatRequest, StreamChunk } from '../shared/types/llm.js';
+import type { Registry } from './registry.js';
+import type { FallbackChain } from './routing.js';
+import type { StreamEvent } from './schema/events.js';
+import type { InternalRequest, Message } from './schema/messages.js';
+type ProviderContext = {
+    registry: Registry;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+};
+/** Map a shared ChatMessage to the internal Message shape. */
+declare const toInternalMessage: (msg: ChatMessage) => Message;
+/** Map a rich StreamEvent to the shared, agent-facing StreamChunk. */
+declare const toStreamChunk: (event: StreamEvent) => StreamChunk | null;
+type ChatOptions = {
+    provider: string;
+    model: string;
+    fallback?: FallbackChain;
+    /** Override sleep for retry testing. */
+    sleep?: (ms: number) => Promise<void>;
+};
+declare const buildInternalRequest: (request: ChatRequest, provider: string, modelId: string) => InternalRequest;
+/**
+ * Stream a chat request incrementally as agent-facing StreamChunk values.
+ * Retries/falls over only BEFORE the first chunk is yielded; once streaming
+ * begins, errors propagate to the caller (per spec §7.6 fall-over policy).
+ */
+declare const chatStream: (ctx: ProviderContext, request: ChatRequest, options: ChatOptions) => AsyncGenerator<StreamChunk, void, unknown>;
+/** Non-streaming chat: consume the stream and return the final text. */
+declare const chat: (ctx: ProviderContext, request: ChatRequest, options: ChatOptions) => Promise<string>;
+export type { ChatOptions, ProviderContext };
+export { buildInternalRequest, chat, chatStream, toInternalMessage, toStreamChunk };

package/dist/llm/provider.js

@@ -0,0 +1,191 @@
+import { bodyFrom, finalizeStream, initialStepState, parseChunk, step, } from './protocols/openai-compat.js';
+import { resolveRoute } from './registry.js';
+import { withRetry } from './retry.js';
+import { shouldFallOver } from './routing.js';
+import { model as makeModel } from './schema/options.js';
+import { httpPost, sseFraming } from './transport.js';
+const safeParseArgs = (raw) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+};
+/** Map a shared ChatMessage to the internal Message shape. */
+const toInternalMessage = (msg) => {
+    // tool role messages carry tool result text — MUST handle before the
+    // string-content early return below, because context.ts serialises tool
+    // result output to a JSON string (msg.content is a string for tool msgs).
+    // If this runs after the early return, toolCallId is lost and the provider
+    // receives a tool message without tool_call_id → "invalid tool_call_id".
+    if (msg.role === 'tool' && msg.toolCallId !== undefined) {
+        const text = typeof msg.content === 'string'
+            ? msg.content
+            : msg.content.map((p) => (p.type === 'text' ? p.text : '')).join('');
+        return {
+            role: 'tool',
+            content: [
+                {
+                    type: 'tool-result',
+                    id: msg.toolCallId,
+                    name: 'tool',
+                    result: { type: 'text', value: text },
+                },
+            ],
+        };
+    }
+    if (typeof msg.content === 'string') {
+        return { role: msg.role, content: [{ type: 'text', text: msg.content }] };
+    }
+    const parts = msg.content.map((p) => {
+        if (p.type === 'text')
+            return { type: 'text', text: p.text };
+        return { type: 'text', text: `[image: ${p.mediaType}]` };
+    });
+    // assistant messages may carry tool_calls
+    if (msg.role === 'assistant' && msg.toolCalls !== undefined) {
+        const toolParts = msg.toolCalls.map((tc) => ({
+            type: 'tool-call',
+            id: tc.id,
+            name: tc.name,
+            input: safeParseArgs(tc.arguments),
+        }));
+        return { role: 'assistant', content: [...parts, ...toolParts] };
+    }
+    return { role: msg.role, content: parts };
+};
+const toInternalTool = (tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.parameters,
+});
+/** Map a rich StreamEvent to the shared, agent-facing StreamChunk. */
+const toStreamChunk = (event) => {
+    switch (event.type) {
+        case 'text-delta':
+            return { _tag: 'text', text: event.text };
+        case 'tool-input-start':
+            return { _tag: 'tool_call_start', id: event.id, name: event.name };
+        case 'tool-input-delta':
+            return { _tag: 'tool_call_delta', id: event.id, argumentsDelta: event.text };
+        case 'tool-input-end':
+            // Redundant: the finalized `tool-call` event below carries the complete
+            // parsed input and maps to tool_call_end. Emitting both would duplicate
+            // the end signal per tool call.
+            return null;
+        case 'tool-call':
+            return { _tag: 'tool_call_end', id: event.id, argumentsFinal: JSON.stringify(event.input) };
+        case 'reasoning-delta':
+            return { _tag: 'thinking', text: event.text };
+        case 'step-finish':
+            if (event.usage !== undefined) {
+                return {
+                    _tag: 'usage',
+                    inputTokens: event.usage.inputTokens ?? 0,
+                    outputTokens: event.usage.outputTokens ?? 0,
+                    cacheRead: event.usage.cacheReadInputTokens,
+                };
+            }
+            return null;
+        case 'finish':
+            return { _tag: 'done', finishReason: event.reason };
+        case 'provider-error':
+            return {
+                _tag: 'error',
+                error: { message: event.message, retryable: event.retryable ?? false },
+            };
+        default:
+            return null;
+    }
+};
+const buildInternalRequest = (request, provider, modelId) => ({
+    model: makeModel(modelId, provider),
+    system: request.system !== undefined ? [{ type: 'text', text: request.system }] : [],
+    messages: request.messages.map(toInternalMessage),
+    tools: (request.tools ?? []).map(toInternalTool),
+    generation: {
+        ...(request.maxTokens !== undefined ? { maxTokens: request.maxTokens } : {}),
+        ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+    },
+    toolChoice: request.tools !== undefined && request.tools.length > 0 ? { type: 'auto' } : undefined,
+});
+const resolveChain = (options) => options.fallback ?? {
+    primary: { provider: options.provider, model: options.model },
+    fallbacks: [],
+    maxRetries: 3,
+    retryDelay: 2000,
+    sleep: options.sleep,
+};
+/** Open a (retryable) connection to one target route and stream its StreamChunks. */
+const streamTarget = async function* (ctx, request, target, chain) {
+    const resolved = resolveRoute(ctx.registry, target.provider, target.model);
+    const internal = buildInternalRequest(request, target.provider, target.model);
+    const body = bodyFrom(internal);
+    const url = `${resolved.route.baseURL}${resolved.route.path}`;
+    const authHeader = resolved.route.auth.type === 'bearer' ? resolved.route.auth.apiKey : '';
+    // Retry only the connection (the fetch). Once streaming begins, errors propagate.
+    const stream = await withRetry(() => httpPost({
+        url,
+        body,
+        headers: { authorization: `Bearer ${authHeader}`, ...resolved.route.headers() },
+        signal: ctx.signal,
+        fetchImpl: ctx.fetchImpl,
+    }), { maxRetries: chain.maxRetries, sleep: chain.sleep });
+    let state = initialStepState();
+    for await (const frame of sseFraming(stream)) {
+        const chunk = parseChunk(resolved.route.id, frame);
+        const result = step(state, chunk);
+        state = result.state;
+        for (const event of result.events) {
+            const sc = toStreamChunk(event);
+            if (sc !== null)
+                yield sc;
+        }
+    }
+    // Stream ended without a trailing usage chunk — finalize (no-op if already finished).
+    for (const event of finalizeStream(state).events) {
+        const sc = toStreamChunk(event);
+        if (sc !== null)
+            yield sc;
+    }
+};
+/**
+ * Stream a chat request incrementally as agent-facing StreamChunk values.
+ * Retries/falls over only BEFORE the first chunk is yielded; once streaming
+ * begins, errors propagate to the caller (per spec §7.6 fall-over policy).
+ */
+const chatStream = async function* (ctx, request, options) {
+    const chain = resolveChain(options);
+    const targets = [chain.primary, ...chain.fallbacks];
+    let started = false;
+    let lastError;
+    for (const target of targets) {
+        if (target === undefined)
+            continue;
+        resolveRoute(ctx.registry, target.provider, target.model); // fail-fast NoRoute
+        try {
+            for await (const sc of streamTarget(ctx, request, target, chain)) {
+                started = true;
+                yield sc;
+            }
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (started || !shouldFallOver(error))
+                throw error;
+        }
+    }
+    throw lastError;
+};
+/** Non-streaming chat: consume the stream and return the final text. */
+const chat = async (ctx, request, options) => {
+    let text = '';
+    for await (const chunk of chatStream(ctx, request, options)) {
+        if (chunk._tag === 'text')
+            text += chunk.text;
+    }
+    return text;
+};
+export { buildInternalRequest, chat, chatStream, toInternalMessage, toStreamChunk };

package/dist/llm/registry.d.ts

@@ -0,0 +1,44 @@
+import type { ModelCapabilities, ModelRole } from '../shared/types/llm.js';
+import { openAICompatRoute } from './protocols/openai-compat.js';
+import type { Model } from './schema/options.js';
+type RouteEntry = ReturnType<typeof openAICompatRoute> & {
+    models: Record<string, ModelCapabilities>;
+};
+type Registry = {
+    routes: Map<string, RouteEntry>;
+    roles: Map<string, {
+        provider: string;
+        model: string;
+    }>;
+};
+declare const createRegistry: () => Registry;
+type ProviderInput = {
+    name: string;
+    baseURL: string;
+    apiKey: string;
+    headers?: () => Record<string, string>;
+    path?: string;
+    models?: Record<string, ModelCapabilities>;
+};
+declare const registerProvider: (registry: Registry, input: ProviderInput) => void;
+type ResolveResult = {
+    route: RouteEntry;
+    model: Model;
+    capabilities: ModelCapabilities;
+};
+/**
+ * Resolve a (provider, modelId) pair into a route + typed model.
+ * Throws NoRoute when the provider is unknown.
+ */
+declare const resolveRoute: (registry: Registry, provider: string, modelId: string) => ResolveResult;
+/** Resolve the (provider, model) configured for a given role. */
+declare const resolveModelByRole: (registry: Registry, role: ModelRole) => {
+    provider: string;
+    model: string;
+};
+/** Bind a role to a (provider, model) pair. */
+declare const setRole: (registry: Registry, role: ModelRole, provider: string, model: string) => void;
+/** Default role + a starter catalog of well-known models. */
+declare const builtinCapabilities: Record<string, Record<string, ModelCapabilities>>;
+export type { ProviderInput, Registry, ResolveResult, RouteEntry };
+export { builtinCapabilities, createRegistry, registerProvider, resolveModelByRole, resolveRoute, setRole, };

package/dist/llm/registry.js

@@ -0,0 +1,107 @@
+import { openAICompatRoute } from './protocols/openai-compat.js';
+import { llmError } from './schema/errors.js';
+import { model as makeModel } from './schema/options.js';
+const createRegistry = () => ({ routes: new Map(), roles: new Map() });
+const registerProvider = (registry, input) => {
+    registry.routes.set(input.name, {
+        ...openAICompatRoute({
+            id: input.name,
+            provider: input.name,
+            baseURL: input.baseURL,
+            apiKey: input.apiKey,
+            headers: input.headers,
+            path: input.path,
+        }),
+        models: input.models ?? {},
+    });
+};
+/**
+ * Resolve a (provider, modelId) pair into a route + typed model.
+ * Throws NoRoute when the provider is unknown.
+ */
+const resolveRoute = (registry, provider, modelId) => {
+    const route = registry.routes.get(provider);
+    if (route === undefined) {
+        throw llmError('LLM', 'resolve', {
+            _tag: 'NoRoute',
+            route: `${provider}`,
+            provider,
+            model: modelId,
+        });
+    }
+    const capabilities = route.models[modelId] ??
+        {
+            contextWindow: 8192,
+            maxOutput: 4096,
+            supportsTools: true,
+            supportsVision: false,
+            supportsThinking: false,
+            costPer1kInput: 0,
+            costPer1kOutput: 0,
+        };
+    return {
+        route,
+        model: makeModel(modelId, provider, {
+            context: capabilities.contextWindow,
+            output: capabilities.maxOutput,
+        }),
+        capabilities,
+    };
+};
+/** Resolve the (provider, model) configured for a given role. */
+const resolveModelByRole = (registry, role) => {
+    const key = role._tag;
+    const entry = registry.roles.get(key);
+    if (entry === undefined) {
+        const fallback = registry.roles.get('default');
+        if (fallback === undefined) {
+            throw llmError('LLM', 'resolve', {
+                _tag: 'NoRoute',
+                route: `role:${key}`,
+                provider: 'unknown',
+                model: 'unknown',
+            });
+        }
+        return fallback;
+    }
+    return entry;
+};
+/** Bind a role to a (provider, model) pair. */
+const setRole = (registry, role, provider, model) => {
+    registry.roles.set(role._tag, { provider, model });
+};
+/** Default role + a starter catalog of well-known models. */
+const builtinCapabilities = {
+    openai: {
+        'gpt-4o': {
+            contextWindow: 128000,
+            maxOutput: 16384,
+            supportsTools: true,
+            supportsVision: true,
+            supportsThinking: false,
+            costPer1kInput: 0.0025,
+            costPer1kOutput: 0.01,
+        },
+    },
+    deepseek: {
+        'deepseek-chat': {
+            contextWindow: 64000,
+            maxOutput: 8192,
+            supportsTools: true,
+            supportsVision: false,
+            supportsThinking: false,
+            costPer1kInput: 0.00014,
+            costPer1kOutput: 0.00028,
+        },
+        'deepseek-reasoner': {
+            contextWindow: 64000,
+            maxOutput: 8192,
+            supportsTools: false,
+            supportsVision: false,
+            supportsThinking: true,
+            costPer1kInput: 0.00055,
+            costPer1kOutput: 0.00219,
+        },
+    },
+};
+export { builtinCapabilities, createRegistry, registerProvider, resolveModelByRole, resolveRoute, setRole, };

package/dist/llm/retry.d.ts

@@ -0,0 +1,37 @@
+import type { LLMErrorReason } from './schema/errors.js';
+declare const RETRY_INITIAL_DELAY = 2000;
+declare const RETRY_MAX_DELAY_NO_HEADERS = 30000;
+declare const RETRY_MAX_DELAY = 2147483647;
+/**
+ * Compute the delay before the next retry attempt (ms).
+ * Honors retry-after / retry-after-ms headers when present, else exponential backoff.
+ */
+declare const delay: (attempt: number, error?: unknown) => number;
+/** A normalized, retryable error descriptor for the session layer. */
+type Retryable = {
+    message: string;
+    reason: LLMErrorReason;
+};
+/**
+ * Decide whether a thrown error is retryable. Returns undefined when not retryable
+ * (e.g. context overflow, auth, invalid request).
+ */
+declare const retryable: (error: unknown) => Retryable | undefined;
+type RetryOptions = {
+    maxRetries: number;
+    /** Override sleep for testing. Defaults to setTimeout-based sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Called with each retry attempt metadata. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+};
+/**
+ * Run an async operation with retry. Retries only on retryable LLM errors.
+ * Non-retryable errors (including context overflow) are re-thrown immediately.
+ */
+declare const withRetry: <T>(fn: () => Promise<T>, options: RetryOptions) => Promise<T>;
+export type { Retryable, RetryOptions };
+export { delay, RETRY_INITIAL_DELAY, RETRY_MAX_DELAY, RETRY_MAX_DELAY_NO_HEADERS, retryable, withRetry, };

package/dist/llm/retry.js

@@ -0,0 +1,82 @@
+import { isLLMError, reasonRetryAfterMs, reasonRetryable } from './schema/errors.js';
+const RETRY_INITIAL_DELAY = 2_000;
+const RETRY_BACKOFF_FACTOR = 2;
+const RETRY_MAX_DELAY_NO_HEADERS = 30_000;
+const RETRY_MAX_DELAY = 2_147_483_647;
+/** Extract response headers from an LLMError's http context (if any). */
+const errorHeaders = (error) => {
+    if (!isLLMError(error))
+        return undefined;
+    const reason = error.reason;
+    if ('http' in reason && reason.http?.response) {
+        return reason.http.response.headers;
+    }
+    return undefined;
+};
+/** Cap a delay to the 32-bit safe ceiling. */
+const capDelay = (ms) => Math.min(ms, RETRY_MAX_DELAY);
+/**
+ * Compute the delay before the next retry attempt (ms).
+ * Honors retry-after / retry-after-ms headers when present, else exponential backoff.
+ */
+const delay = (attempt, error) => {
+    const headers = errorHeaders(error);
+    if (headers) {
+        const retryAfterMs = headers['retry-after-ms'];
+        if (retryAfterMs !== undefined) {
+            const parsedMs = Number.parseFloat(retryAfterMs);
+            if (!Number.isNaN(parsedMs))
+                return capDelay(parsedMs);
+        }
+        const retryAfter = headers['retry-after'];
+        if (retryAfter !== undefined) {
+            const parsedSeconds = Number.parseFloat(retryAfter);
+            if (!Number.isNaN(parsedSeconds))
+                return capDelay(Math.ceil(parsedSeconds * 1000));
+            const parsed = Date.parse(retryAfter) - Date.now();
+            if (!Number.isNaN(parsed) && parsed > 0)
+                return capDelay(Math.ceil(parsed));
+        }
+        return capDelay(RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR ** (attempt - 1));
+    }
+    return capDelay(Math.min(RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_MAX_DELAY_NO_HEADERS));
+};
+/**
+ * Decide whether a thrown error is retryable. Returns undefined when not retryable
+ * (e.g. context overflow, auth, invalid request).
+ */
+const retryable = (error) => {
+    if (!isLLMError(error))
+        return undefined;
+    const reason = error.reason;
+    if (!reasonRetryable(reason))
+        return undefined;
+    return { message: error.message, reason };
+};
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Run an async operation with retry. Retries only on retryable LLM errors.
+ * Non-retryable errors (including context overflow) are re-thrown immediately.
+ */
+const withRetry = async (fn, options) => {
+    const sleep = options.sleep ?? defaultSleep;
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const canRetry = retryable(error);
+            if (!canRetry || attempt >= options.maxRetries)
+                throw error;
+            attempt += 1;
+            const fallbackReason = isLLMError(error)
+                ? error.reason
+                : { _tag: 'InvalidRequest', message: '' };
+            const delayMs = reasonRetryAfterMs(fallbackReason) ?? delay(attempt, error);
+            options.onRetry?.({ attempt, delayMs, error });
+            await sleep(delayMs);
+        }
+    }
+};
+export { delay, RETRY_INITIAL_DELAY, RETRY_MAX_DELAY, RETRY_MAX_DELAY_NO_HEADERS, retryable, withRetry, };

package/dist/llm/routing.d.ts

@@ -0,0 +1,36 @@
+import type { Registry } from './registry.js';
+type FallbackChain = {
+    primary: {
+        provider: string;
+        model: string;
+    };
+    fallbacks: {
+        provider: string;
+        model: string;
+    }[];
+    maxRetries: number;
+    retryDelay: number;
+    /** Override sleep for testing. */
+    sleep?: (ms: number) => Promise<void>;
+};
+type RunFn<T> = (provider: string, model: string) => Promise<T>;
+/**
+ * Run `run` against the primary route first. If it throws a retryable error
+ * that exhausts retries, try each fallback in order. Non-retryable errors
+ * (context overflow, auth, invalid request) propagate immediately without
+ * trying fallbacks.
+ */
+declare const runWithFallback: <T>(registry: Registry, chain: FallbackChain, run: RunFn<T>) => Promise<{
+    result: T;
+    provider: string;
+    model: string;
+}>;
+/**
+ * Whether an error should trigger a fallback after retries are exhausted.
+ * Per spec §7.6: RateLimit (after retries), ProviderInternal, and Authentication
+ * fall over to the next route. Context-overflow, invalid request, and transport
+ * errors propagate without trying fallbacks.
+ */
+declare const shouldFallOver: (error: unknown) => boolean;
+export type { FallbackChain };
+export { runWithFallback, shouldFallOver };