@kodax-ai/kodax 0.7.40 → 0.7.42

package/dist/types-chunks/transport.d-DuyjG30t.d.ts

@@ -0,0 +1,180 @@
+import { a as McpServerConfig, b as McpServersConfig } from './config.d-BfJUXxC0.js';
+import { a as CapabilityProvider, C as CapabilityKind, b as CapabilityResult } from './capability.d-3C62G8Eq.js';
+
+type McpCapabilityKind = 'tool' | 'resource' | 'prompt';
+type McpCapabilityRisk = 'read' | 'write' | 'network' | 'exec';
+interface McpCatalogItem {
+    id: string;
+    serverId: string;
+    kind: McpCapabilityKind;
+    name: string;
+    title?: string;
+    summary: string;
+    tags?: string[];
+    risk?: McpCapabilityRisk;
+    annotations?: Record<string, unknown>;
+    cachedAt: string;
+}
+interface McpCapabilityDescriptor extends McpCatalogItem {
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    promptArgsSchema?: unknown;
+    uri?: string;
+    mimeType?: string;
+}
+interface McpServerCatalogSnapshot {
+    serverId: string;
+    items: McpCatalogItem[];
+    descriptors: McpCapabilityDescriptor[];
+    updatedAt: string;
+}
+interface McpCatalogSearchOptions {
+    kind?: McpCapabilityKind;
+    limit?: number;
+}
+declare function defaultMcpCacheDir(): string;
+declare function createMcpCapabilityId(serverId: string, kind: McpCapabilityKind, name: string): string;
+declare function parseMcpCapabilityId(id: string): {
+    serverId: string;
+    kind: McpCapabilityKind;
+    name: string;
+};
+declare function searchMcpCatalog(items: readonly McpCatalogItem[], query: string, options?: McpCatalogSearchOptions): McpCatalogItem[];
+declare function getMcpCachePaths(cacheDir: string, serverId: string): {
+    catalogDir: string;
+    indexPath: string;
+    itemsPath: string;
+};
+
+interface McpServerRuntimeDiagnostics {
+    serverId: string;
+    connect: 'lazy' | 'prewarm' | 'disabled';
+    status: 'idle' | 'connecting' | 'ready' | 'error' | 'disabled';
+    dirty: boolean;
+    lastError?: string;
+    cachedAt?: string;
+    tools: number;
+    resources: number;
+    prompts: number;
+}
+declare class McpServerRuntime {
+    private readonly serverId;
+    private readonly config;
+    private readonly cacheDir;
+    private transport?;
+    private readonly pending;
+    private nextRequestId;
+    private initialized;
+    private connectPromise?;
+    private catalog?;
+    private diagnostics;
+    constructor(serverId: string, config: McpServerConfig, cacheDir: string);
+    getDiagnostics(): McpServerRuntimeDiagnostics;
+    prewarmIfNeeded(): Promise<void>;
+    /** Load catalog from memory or disk only — never triggers a lazy connection. */
+    getCachedCatalog(): Promise<McpServerCatalogSnapshot | undefined>;
+    getCatalog(forceRefresh?: boolean): Promise<McpServerCatalogSnapshot>;
+    describeCapability(capabilityId: string): Promise<McpCapabilityDescriptor | undefined>;
+    callTool(name: string, args: Record<string, unknown>): Promise<{
+        content?: string;
+        structuredContent?: unknown;
+        metadata?: Record<string, unknown>;
+    }>;
+    readResource(name: string, options: Record<string, unknown>): Promise<{
+        content?: string;
+        structuredContent?: unknown;
+        metadata?: Record<string, unknown>;
+    }>;
+    getPrompt(name: string, args: Record<string, unknown>): Promise<unknown>;
+    refreshCatalog(forceReconnect?: boolean): Promise<void>;
+    /** Public teardown — clears everything including the connect lock. */
+    dispose(): Promise<void>;
+    /** Internal transport teardown — does NOT clear connectPromise so the
+     *  retry loop inside doConnect() can safely call it between attempts. */
+    private resetTransport;
+    private connect;
+    private doConnect;
+    private listDescriptors;
+    private request;
+    private notify;
+    private handleMessage;
+    private failPending;
+    private applyCatalogSnapshot;
+}
+
+/**
+ * `McpCapabilityProvider` — implements the Layer A `CapabilityProvider`
+ * contract for an MCP server fleet.
+ *
+ * FEATURE_082 (v0.7.24): moved from
+ * `@kodax-ai/coding/src/capabilities/providers/mcp/provider.ts` to this package.
+ * The coding-specific `registerConfiguredMcpCapabilityProvider` adapter (which
+ * pulls in `KodaXExtensionRuntime`) lives in
+ * `@kodax-ai/coding/src/capabilities/providers/mcp-adapter.ts`.
+ */
+
+interface McpProviderOptions {
+    cacheDir?: string;
+}
+declare class McpCapabilityProvider implements CapabilityProvider {
+    readonly id = "mcp";
+    readonly kinds: CapabilityProvider['kinds'];
+    private readonly runtimes;
+    private readonly cacheDir;
+    /**
+     * Construct an MCP capability provider.
+     *
+     * **Cache-dir capture warning (v0.7.35.1 FEATURE_145)** — when
+     * `options.cacheDir` is omitted, this constructor resolves
+     * `defaultMcpCacheDir()` ONCE at instantiation time and threads the
+     * result into every `McpServerRuntime` it spawns. If a substrate
+     * consumer plans to redirect the agent config home via
+     * `setAgentConfigHome()` from `@kodax-ai/agent`, that call MUST happen
+     * BEFORE constructing this provider. Late calls have no effect on
+     * already-constructed runtimes.
+     *
+     * To bypass the agent-home resolver entirely, pass
+     * `options.cacheDir` explicitly — that path wins unconditionally.
+     */
+    constructor(servers: McpServersConfig | undefined, options?: McpProviderOptions);
+    hasActiveServers(): boolean;
+    prewarm(): Promise<void>;
+    search(query: string, options?: {
+        kind?: CapabilityKind;
+        limit?: number;
+        server?: string;
+    }): Promise<unknown[]>;
+    describe(id: string): Promise<unknown>;
+    execute(id: string, input: Record<string, unknown>): Promise<CapabilityResult>;
+    read(id: string, options?: Record<string, unknown>): Promise<CapabilityResult>;
+    getPrompt(id: string, args?: Record<string, unknown>): Promise<unknown>;
+    getPromptContext(): Promise<string | undefined>;
+    getDiagnostics(): Record<string, unknown> | undefined;
+    refresh(): Promise<void>;
+    dispose(): Promise<void>;
+    private collectCatalogItems;
+    private listServerDiagnostics;
+    private requireRuntime;
+}
+
+interface McpTransportEvents {
+    /** Called with a complete JSON-RPC message (raw JSON string). */
+    onMessage(raw: string): void;
+    onError(error: Error): void;
+    onClose(reason: string): void;
+}
+interface McpTransport {
+    open(events: McpTransportEvents): Promise<void>;
+    /** Send a JSON string. The transport handles framing. */
+    send(json: string): Promise<void>;
+    close(): Promise<void>;
+    readonly connected: boolean;
+}
+type StdioFraming = 'content-length' | 'ndjson';
+interface McpTransportOptions {
+    stdioFraming?: StdioFraming;
+}
+declare function createMcpTransport(config: McpServerConfig, options?: McpTransportOptions): McpTransport;
+
+export { McpCapabilityProvider as b, McpServerRuntime as g, createMcpCapabilityId as k, createMcpTransport as l, defaultMcpCacheDir as m, getMcpCachePaths as n, parseMcpCapabilityId as p, searchMcpCatalog as s };
+export type { McpCapabilityDescriptor as M, McpCapabilityKind as a, McpCapabilityRisk as c, McpCatalogItem as d, McpProviderOptions as e, McpServerCatalogSnapshot as f, McpServerRuntimeDiagnostics as h, McpTransport as i, McpTransportEvents as j };

package/dist/types-chunks/types.d-B1uGoVTE.d.ts

@@ -0,0 +1,400 @@
+/**
+ * KodaX AI Types
+ *
+ * AI 层类型定义 - 所有 Provider 共享的类型接口
+ */
+interface KodaXTextBlock {
+    type: 'text';
+    text: string;
+}
+interface KodaXToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Tool-result content blocks — a structural subset of the full
+ * `KodaXContentBlock` union, restricted to what providers actually accept
+ * inside a tool_result envelope. Anthropic / OpenAI multimodal APIs accept
+ * text and image blocks inside tool_result; thinking / tool_use / nested
+ * tool_result / cache-boundary are not valid there.
+ *
+ * Carrying these as a stricter subtype (instead of the full union) lets
+ * provider serializers narrow without exhaustive type assertions and
+ * documents to tool authors what they can actually return.
+ */
+interface KodaXToolResultTextItem {
+    type: 'text';
+    text: string;
+}
+interface KodaXToolResultImageItem {
+    type: 'image';
+    /** Absolute path to the image file. Provider serializers read it into base64 at wire-send time. */
+    path: string;
+    mediaType?: string;
+}
+type KodaXToolResultContentItem = KodaXToolResultTextItem | KodaXToolResultImageItem;
+interface KodaXToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    /**
+     * Either a plain text string (backwards-compatible default) OR an array
+     * of content items. The array form lets multimodal-capable tools (e.g.
+     * `read` on an image path) emit images via tool_result, mirroring
+     * claudecode's `Read` tool behavior. Providers serialize each variant
+     * to their wire format; text-only providers (e.g. older OpenAI-compat
+     * gateways) downgrade image items to a placeholder rather than rejecting.
+     */
+    content: string | readonly KodaXToolResultContentItem[];
+    is_error?: boolean;
+}
+interface KodaXImageBlock {
+    type: 'image';
+    path: string;
+    mediaType?: string;
+}
+interface KodaXThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+}
+interface KodaXRedactedThinkingBlock {
+    type: 'redacted_thinking';
+    data: string;
+}
+/**
+ * FEATURE_116 (v0.7.37) — Cache boundary marker.
+ *
+ * Marks the end of a cacheable prefix in a request payload. Provider base
+ * classes lower this to the wire-level cache mechanism their API supports:
+ *
+ * - `KodaXAnthropicCompatProvider`: turns the marker into
+ *   `cache_control: { type: 'ephemeral' }` on the immediately preceding
+ *   block, then strips the marker itself.
+ * - `KodaXOpenAICompatProvider`: strips the marker (OpenAI / DeepSeek
+ *   auto prefix-cache; Kimi/Zhipu/通义 self-cache via separate cache_id
+ *   endpoint deferred to v0.7.45+).
+ * - `KodaXAcpProvider` (CLI bridge): strips the marker (CLI bridge does
+ *   not touch wire; avoids leaking marker into subprocess input).
+ *
+ * Place at the suffix of any stable prefix (system prompt, tools array,
+ * role prompt). The marker is purely client-side: it MUST be removed
+ * before the request is sent over the wire.
+ */
+interface KodaXCacheBoundary {
+    type: 'cache-boundary';
+    /** Optional hint identifying which logical region this boundary terminates. Diagnostic only. */
+    hint?: 'system' | 'tools' | 'role-prompt';
+}
+type KodaXContentBlock = KodaXTextBlock | KodaXToolUseBlock | KodaXToolResultBlock | KodaXImageBlock | KodaXThinkingBlock | KodaXRedactedThinkingBlock | KodaXCacheBoundary;
+interface KodaXMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string | KodaXContentBlock[];
+    /** Marks messages injected by the system (auto-continue, retry prompts). Hidden in REPL display. */
+    _synthetic?: boolean;
+}
+interface KodaXTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedReadTokens?: number;
+    cachedWriteTokens?: number;
+    thoughtTokens?: number;
+}
+interface KodaXStreamResult {
+    textBlocks: KodaXTextBlock[];
+    toolBlocks: KodaXToolUseBlock[];
+    thinkingBlocks: (KodaXThinkingBlock | KodaXRedactedThinkingBlock)[];
+    usage?: KodaXTokenUsage;
+    /** Provider stop reason: 'end_turn' (normal), 'max_tokens' (truncated), 'stop_sequence', 'tool_use', etc. */
+    stopReason?: string;
+}
+interface KodaXToolDefinition {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+type KodaXReasoningCapability = 'native-effort' | 'native-budget' | 'native-toggle' | 'none' | 'prompt-only' | 'unknown';
+type KodaXProviderTransport = 'native-api' | 'cli-bridge';
+type KodaXProviderConversationSemantics = 'full-history' | 'last-user-message';
+type KodaXProviderMcpSupport = 'native' | 'none';
+type KodaXProviderContextFidelity = 'full' | 'partial' | 'lossy';
+type KodaXProviderToolCallingFidelity = 'full' | 'limited' | 'none';
+type KodaXProviderSessionSupport = 'full' | 'limited' | 'stateless';
+type KodaXProviderLongRunningSupport = 'full' | 'limited' | 'none';
+type KodaXProviderMultimodalSupport = 'none' | 'image-input' | 'full';
+type KodaXProviderEvidenceSupport = 'full' | 'limited' | 'none';
+interface KodaXProviderCapabilityProfile {
+    transport: KodaXProviderTransport;
+    conversationSemantics: KodaXProviderConversationSemantics;
+    mcpSupport: KodaXProviderMcpSupport;
+    contextFidelity?: KodaXProviderContextFidelity;
+    toolCallingFidelity?: KodaXProviderToolCallingFidelity;
+    sessionSupport?: KodaXProviderSessionSupport;
+    longRunningSupport?: KodaXProviderLongRunningSupport;
+    multimodalSupport?: KodaXProviderMultimodalSupport;
+    evidenceSupport?: KodaXProviderEvidenceSupport;
+}
+type KodaXReasoningOverride = 'budget' | 'effort' | 'toggle' | 'none';
+type KodaXReasoningMode = 'off' | 'auto' | 'quick' | 'balanced' | 'deep';
+type KodaXThinkingDepth = 'off' | 'low' | 'medium' | 'high';
+type KodaXTaskType = 'conversation' | 'lookup' | 'review' | 'bugfix' | 'edit' | 'refactor' | 'plan' | 'qa' | 'unknown';
+type KodaXExecutionMode = 'conversation' | 'lookup' | 'pr-review' | 'strict-audit' | 'implementation' | 'planning' | 'investigation';
+type KodaXRiskLevel = 'low' | 'medium' | 'high';
+type KodaXTaskComplexity = 'simple' | 'moderate' | 'complex' | 'systemic';
+type KodaXTaskWorkIntent = 'append' | 'overwrite' | 'new';
+type KodaXTaskFamily = 'conversation' | 'lookup' | 'review' | 'implementation' | 'investigation' | 'planning' | 'ambiguous';
+type KodaXTaskActionability = 'non_actionable' | 'actionable' | 'ambiguous';
+type KodaXExecutionPattern = 'direct' | 'checked-direct' | 'coordinated';
+type KodaXMutationSurface = 'read-only' | 'docs-only' | 'code' | 'system';
+type KodaXAssuranceIntent = 'default' | 'explicit-check';
+type KodaXHarnessProfile = 'H0_DIRECT' | 'H1_EXECUTE_EVAL' | 'H2_PLAN_EXECUTE_EVAL' | 'PLANNED';
+type KodaXReviewScale = 'small' | 'large' | 'massive';
+type KodaXAmaProfile = 'tactical' | 'managed';
+type KodaXAmaTactic = 'direct' | 'child-fanout' | 'planning-pass' | 'verification-pass' | 'repair-loop';
+type KodaXAmaFanoutClass = 'finding-validation' | 'evidence-scan' | 'module-triage' | 'hypothesis-check';
+interface KodaXAmaFanoutPolicy {
+    admissible: boolean;
+    class?: KodaXAmaFanoutClass;
+    reason: string;
+    maxChildren?: number;
+    requiresReadOnly?: boolean;
+}
+interface KodaXAmaControllerDecision {
+    profile: KodaXAmaProfile;
+    tactics: KodaXAmaTactic[];
+    fanout: KodaXAmaFanoutPolicy;
+    reason: string;
+    upgradeTriggers: string[];
+}
+interface KodaXTaskRoutingDecision {
+    primaryTask: KodaXTaskType;
+    secondaryTask?: KodaXTaskType;
+    taskFamily?: KodaXTaskFamily;
+    actionability?: KodaXTaskActionability;
+    executionPattern?: KodaXExecutionPattern;
+    mutationSurface?: KodaXMutationSurface;
+    assuranceIntent?: KodaXAssuranceIntent;
+    confidence: number;
+    riskLevel: KodaXRiskLevel;
+    recommendedMode: KodaXExecutionMode;
+    recommendedThinkingDepth: KodaXThinkingDepth;
+    complexity: KodaXTaskComplexity;
+    workIntent: KodaXTaskWorkIntent;
+    requiresBrainstorm: boolean;
+    harnessProfile: KodaXHarnessProfile;
+    topologyCeiling?: KodaXHarnessProfile;
+    upgradeCeiling?: KodaXHarnessProfile;
+    reviewScale?: KodaXReviewScale;
+    reviewTarget?: 'general' | 'current-worktree' | 'compare-range';
+    soloBoundaryConfidence?: number;
+    needsIndependentQA?: boolean;
+    routingSource?: 'model' | 'fallback' | 'retried-model' | 'retried-fallback';
+    routingAttempts?: number;
+    routingNotes?: string[];
+    reason: string;
+}
+interface KodaXThinkingBudgetMap {
+    low: number;
+    medium: number;
+    high: number;
+}
+type KodaXTaskBudgetOverrides = Partial<Record<KodaXTaskType, Partial<KodaXThinkingBudgetMap>>>;
+interface KodaXReasoningRequest {
+    enabled?: boolean;
+    mode?: KodaXReasoningMode;
+    depth?: KodaXThinkingDepth;
+    taskType?: KodaXTaskType;
+    executionMode?: KodaXExecutionMode;
+}
+interface KodaXModelDescriptor {
+    id: string;
+    displayName?: string;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    thinkingBudgetCap?: number;
+    reasoningCapability?: KodaXReasoningCapability;
+    /**
+     * Per-model override for `replayReasoningContent`. Falls through to the
+     * provider-level flag when undefined. Lets a single gateway endpoint
+     * route models that need the flag (DeepSeek V4) alongside models that
+     * would 400 if the flag were on (OpenAI proper).
+     */
+    replayReasoningContent?: boolean;
+    /**
+     * Per-model override for `strictThinkingSignature`. Falls through to
+     * the provider-level flag when undefined.
+     */
+    strictThinkingSignature?: boolean;
+    /**
+     * Per-model override for `streamMaxDurationMs`. Falls through to the
+     * provider-level cap when undefined; undefined at both levels disables
+     * the watchdog.
+     */
+    streamMaxDurationMs?: number;
+}
+type KodaXProtocolFamily = 'anthropic' | 'openai';
+type KodaXProviderUserAgentMode = 'compat' | 'sdk';
+interface KodaXCustomProviderConfig {
+    name: string;
+    protocol: KodaXProtocolFamily;
+    baseUrl: string;
+    apiKeyEnv: string;
+    model: string;
+    /**
+     * Additional available models beyond the default. Accepts either a
+     * plain model id string (legacy) or a KodaXModelDescriptor object
+     * (FEATURE_098) carrying per-model `contextWindow` / `maxOutputTokens`
+     * / `thinkingBudgetCap` / `reasoningCapability` overrides.
+     */
+    models?: Array<string | KodaXModelDescriptor>;
+    /**
+     * Controls which User-Agent header compatibility providers send.
+     * - compat: send "KodaX" for gateways that block the official SDK UA
+     * - sdk: keep the upstream SDK default User-Agent
+     */
+    userAgentMode?: KodaXProviderUserAgentMode;
+    supportsThinking?: boolean;
+    reasoningCapability?: KodaXReasoningCapability;
+    capabilityProfile?: KodaXProviderCapabilityProfile;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    thinkingBudgetCap?: number;
+    /**
+     * Provider-level default for OpenAI-compat `reasoning_content` echo.
+     * Required by DeepSeek V4 thinking mode (replay 400s without it).
+     * Defaults to false — must stay false for OpenAI proper or any gateway
+     * that rejects unknown fields. Per-model values in `models[]` can
+     * override on a model-by-model basis.
+     */
+    replayReasoningContent?: boolean;
+    /**
+     * Provider-level default for strict Anthropic thinking-signature
+     * verification. Only Anthropic proper cryptographically verifies
+     * signatures — third-party Anthropic-compat gateways must keep this
+     * false (default). Per-model values in `models[]` can override.
+     */
+    strictThinkingSignature?: boolean;
+    /**
+     * Provider-level default streaming wall-clock cap (ms). Set just below
+     * a known server-side kill window (zhipu-coding 308s → 300_000). Leave
+     * unset to disable the watchdog. Per-model values in `models[]` can
+     * override.
+     */
+    streamMaxDurationMs?: number;
+}
+interface KodaXProviderConfig {
+    apiKeyEnv: string;
+    baseUrl?: string;
+    model: string;
+    /** Additional available models beyond the default */
+    models?: readonly KodaXModelDescriptor[];
+    /** Compatibility providers may override the SDK User-Agent when needed. */
+    userAgentMode?: KodaXProviderUserAgentMode;
+    supportsThinking: boolean;
+    reasoningCapability?: KodaXReasoningCapability;
+    capabilityProfile?: KodaXProviderCapabilityProfile;
+    /** 模型的上下文窗口大小 (tokens) */
+    contextWindow?: number;
+    /** Provider 允许的最大输出 token */
+    maxOutputTokens?: number;
+    /** Provider thinking budget 上限 */
+    thinkingBudgetCap?: number;
+    /** Provider 默认 thinking budget 映射 */
+    defaultThinkingBudgets?: Partial<KodaXThinkingBudgetMap>;
+    /** 按任务类型覆盖默认 budget */
+    taskBudgetOverrides?: KodaXTaskBudgetOverrides;
+    /**
+     * Echo the prior turn's `reasoning_content` back on replayed assistant
+     * messages. Required by DeepSeek V4 thinking mode (replay 400s without it).
+     * Other Chinese OpenAI-compat thinking providers use the same field, but
+     * each needs per-provider verification before opting in. Must stay false
+     * for OpenAI proper.
+     */
+    replayReasoningContent?: boolean;
+    /**
+     * Strictly verify Anthropic-style `signature` on `thinking` blocks at
+     * serialise time. Only Anthropic proper (anthropic.com) cryptographically
+     * verifies signatures — third-party Anthropic-compat servers (kimi-code /
+     * ark-coding / mimo-coding / zhipu-coding / minimax-coding) lack the
+     * signing key and accept any signature.
+     *
+     * When true, thinking blocks with empty/cross-provider signatures get
+     * converted to a `<prior_reasoning>` text block instead of being passed
+     * through (which would 400 on signature verification). Cross-provider
+     * `redacted_thinking` blocks (ciphertext signed by their origin) are
+     * dropped silently — there's no plaintext to recover and forging the
+     * field would also fail server-side decryption.
+     *
+     * When false (default), thinking blocks pass through unchanged — matches
+     * legacy behaviour and works for all third-party Anthropic-compat
+     * providers. v0.7.28.
+     */
+    strictThinkingSignature?: boolean;
+    /**
+     * Hard cap on a single streaming request's wall-clock duration (ms).
+     * When exceeded, the resilience layer aborts the stream with a
+     * StreamIncompleteError, which routes through the existing
+     * `non_streaming_fallback` path. Mirrors Claude Code's idle watchdog
+     * pattern but uses request duration (not idle time) because some
+     * providers emit keepalive pings during long tool_use generation.
+     *
+     * Set per-provider just below the known server-side kill window
+     * (e.g. zhipu-coding observed 308s → set 300s here, accounting for
+     * the ~RTT margin between client send and server kill timestamp).
+     */
+    streamMaxDurationMs?: number;
+}
+interface KodaXProviderStreamOptions {
+    onTextDelta?: (text: string) => void;
+    onThinkingDelta?: (text: string) => void;
+    onThinkingEnd?: (thinking: string) => void;
+    onToolInputDelta?: (toolName: string, partialJson: string, meta?: {
+        toolId?: string;
+    }) => void;
+    /**
+     * Fired on provider-side SSE events to manage idle timers.
+     *
+     * - Called with no argument (or `false`): reset the idle timer.
+     *   Fired on every event that indicates active data flow
+     *   (content_block_start, content_block_delta, message_delta, etc.).
+     *
+     * - Called with `true`: **pause** the idle timer (clear without restart).
+     *   Fired on `content_block_stop` when the stream has NOT yet ended,
+     *   because the server may go silent while generating the next block
+     *   (e.g. between text output and tool_use JSON generation).
+     *   The hard request timeout still guards against genuinely stuck connections.
+     */
+    onHeartbeat?: (pause?: boolean) => void;
+    /** 当底层 API 遇到 Rate Limit 进行重试时触发 */
+    onRateLimit?: (attempt: number, maxRetries: number, delayMs: number) => void;
+    /**
+     * FEATURE_130 (v0.7.36): structured retry-after callback. Carries the
+     * parsed source (`retry-after-seconds` / `retry-after-date` /
+     * `retry-after-ms` / `exponential-backoff`) so UI surfaces and the
+     * cost tracker can distinguish "provider-told us to wait" from
+     * "we're guessing with backoff". Coexists with the legacy
+     * `onRateLimit` flat callback above — both fire if both are wired.
+     */
+    onRetryAfter?: (event: {
+        provider: string;
+        waitMs: number;
+        reason: 'rate-limit' | 'overloaded';
+        source: 'retry-after-seconds' | 'retry-after-date' | 'retry-after-ms' | 'exponential-backoff';
+        attempt: number;
+        maxAttempts: number;
+    }) => void;
+    /** 会话标识，用于多轮对话上下文恢复 */
+    sessionId?: string;
+    /** Override the provider's default model for a single request */
+    modelOverride?: string;
+    /** AbortSignal for cancelling the stream request */
+    signal?: AbortSignal;
+}
+
+export type { KodaXToolResultTextItem as $, KodaXProviderToolCallingFidelity as A, KodaXProviderTransport as B, KodaXReasoningCapability as C, KodaXReasoningMode as D, KodaXReasoningOverride as E, KodaXReasoningRequest as F, KodaXRedactedThinkingBlock as G, KodaXReviewScale as H, KodaXRiskLevel as I, KodaXStreamResult as J, KodaXAmaControllerDecision as K, KodaXTaskActionability as L, KodaXTaskBudgetOverrides as M, KodaXTaskComplexity as N, KodaXTaskFamily as O, KodaXTaskRoutingDecision as P, KodaXTaskType as Q, KodaXTaskWorkIntent as R, KodaXTextBlock as S, KodaXThinkingBlock as T, KodaXThinkingBudgetMap as U, KodaXThinkingDepth as V, KodaXTokenUsage as W, KodaXToolDefinition as X, KodaXToolResultBlock as Y, KodaXToolResultContentItem as Z, KodaXToolResultImageItem as _, KodaXAmaFanoutClass as a, KodaXToolUseBlock as a0, KodaXAmaFanoutPolicy as b, KodaXAmaProfile as c, KodaXAmaTactic as d, KodaXAssuranceIntent as e, KodaXCacheBoundary as f, KodaXContentBlock as g, KodaXCustomProviderConfig as h, KodaXExecutionMode as i, KodaXExecutionPattern as j, KodaXHarnessProfile as k, KodaXImageBlock as l, KodaXMessage as m, KodaXModelDescriptor as n, KodaXMutationSurface as o, KodaXProtocolFamily as p, KodaXProviderCapabilityProfile as q, KodaXProviderConfig as r, KodaXProviderContextFidelity as s, KodaXProviderConversationSemantics as t, KodaXProviderEvidenceSupport as u, KodaXProviderLongRunningSupport as v, KodaXProviderMcpSupport as w, KodaXProviderMultimodalSupport as x, KodaXProviderSessionSupport as y, KodaXProviderStreamOptions as z };