@kodax-ai/kodax 0.7.40 → 0.7.41

package/dist/types-chunks/capability.d-BxNgd1-c.d.ts

@@ -0,0 +1,368 @@
+/**
+ * KodaX AI Types
+ *
+ * AI 层类型定义 - 所有 Provider 共享的类型接口
+ */
+interface KodaXTextBlock {
+    type: 'text';
+    text: string;
+}
+interface KodaXToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface KodaXToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    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;
+}
+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;
+}
+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;
+}
+
+/**
+ * Layer A Primitive: Capability provider contract.
+ *
+ * FEATURE_082 (v0.7.24): extracted from `@kodax-ai/coding/src/extensions/types.ts`
+ * so third-party capability sources (MCP, RAG, custom indexes, …) can
+ * implement `CapabilityProvider` without importing from the coding preset.
+ *
+ * The richer "extension runtime" concept (command registration, file
+ * contributions, logger plumbing) stays in `@kodax-ai/coding/src/extensions/`
+ * because it is coupled to the coding CLI surface.
+ */
+type CapabilityKind = 'tool' | 'resource' | 'prompt';
+interface CapabilityResult {
+    kind: CapabilityKind;
+    content?: string;
+    structuredContent?: unknown;
+    evidence?: unknown[];
+    artifacts?: unknown[];
+    metadata?: Record<string, unknown>;
+}
+interface CapabilityProvider {
+    id: string;
+    kinds: CapabilityKind[];
+    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> | string | undefined;
+    getDiagnostics?: () => Record<string, unknown> | undefined;
+    refresh?: () => Promise<void>;
+    dispose?: () => Promise<void>;
+}
+
+export type { KodaXToolResultBlock as $, KodaXProviderSessionSupport as A, KodaXProviderStreamOptions as B, CapabilityKind as C, KodaXProviderToolCallingFidelity as D, KodaXProviderTransport as E, KodaXReasoningCapability as F, KodaXReasoningMode as G, KodaXReasoningOverride as H, KodaXReasoningRequest as I, KodaXRedactedThinkingBlock as J, KodaXAmaControllerDecision as K, KodaXReviewScale as L, KodaXRiskLevel as M, KodaXStreamResult as N, KodaXTaskActionability as O, KodaXTaskBudgetOverrides as P, KodaXTaskComplexity as Q, KodaXTaskFamily as R, KodaXTaskRoutingDecision as S, KodaXTaskType as T, KodaXTaskWorkIntent as U, KodaXTextBlock as V, KodaXThinkingBlock as W, KodaXThinkingBudgetMap as X, KodaXThinkingDepth as Y, KodaXTokenUsage as Z, KodaXToolDefinition as _, CapabilityProvider as a, KodaXToolUseBlock as a0, CapabilityResult as b, KodaXAmaFanoutClass as c, KodaXAmaFanoutPolicy as d, KodaXAmaProfile as e, KodaXAmaTactic as f, KodaXAssuranceIntent as g, KodaXCacheBoundary as h, KodaXContentBlock as i, KodaXCustomProviderConfig as j, KodaXExecutionMode as k, KodaXExecutionPattern as l, KodaXHarnessProfile as m, KodaXImageBlock as n, KodaXMessage as o, KodaXModelDescriptor as p, KodaXMutationSurface as q, KodaXProtocolFamily as r, KodaXProviderCapabilityProfile as s, KodaXProviderConfig as t, KodaXProviderContextFidelity as u, KodaXProviderConversationSemantics as v, KodaXProviderEvidenceSupport as w, KodaXProviderLongRunningSupport as x, KodaXProviderMcpSupport as y, KodaXProviderMultimodalSupport as z };