@kodax-ai/kodax 0.7.55 → 0.7.57

package/dist/types-chunks/{base.d-BBNUF9nz.d.ts → types.d-6VOXvF88.d.ts}

@@ -1,7 +1,7 @@
 /**
  * KodaX AI Types
  *
- * AI 层类型定义 - 所有 Provider 共享的类型接口
+  * AI 层类型定义 - 所有 Provider 共享的类型接口
  */
 interface KodaXTextBlock {
     type: 'text';
@@ -120,6 +120,57 @@ interface KodaXToolDefinition {
     };
 }
 type KodaXReasoningCapability = 'native-effort' | 'native-budget' | 'native-toggle' | 'native-adaptive' | 'none' | 'prompt-only' | 'unknown';
+type KodaXStableEffortIntent = 'auto' | 'none' | 'low' | 'medium' | 'high';
+type KodaXWireReasoningEffort = string;
+type KodaXReasoningPresetName = 'zai-glm-5.2' | 'zai-glm-toggle' | 'deepseek-v4-openai' | 'deepseek-v4-anthropic' | 'deepseek-toggle' | 'kimi-k2.7-code' | 'kimi-hybrid-toggle' | 'minimax-m3' | 'minimax-m2-always' | 'mimo-v2.5-toggle' | 'qwen-hybrid-thinking' | 'openai-chat-reasoning' | 'openai-responses-reasoning' | 'codex-cli-effort' | 'claude-adaptive-xhigh' | 'claude-adaptive-max' | 'anthropic-budget' | 'generic-thinking-toggle' | 'none';
+interface KodaXReasoningEffortRequest {
+    readonly value: KodaXWireReasoningEffort;
+    readonly isExplicit: boolean;
+}
+interface KodaXReasoningEffortPreset {
+    readonly value: KodaXWireReasoningEffort;
+    readonly description?: string;
+    readonly isDefault?: boolean;
+    readonly isUserVisible?: boolean;
+}
+type KodaXReasoningEffortWireStrategy = 'openai-responses-effort' | 'openai-chat-effort' | 'codex-cli-config' | 'anthropic-output-effort' | 'provider-budget' | 'provider-toggle' | 'prompt-only' | 'none';
+type KodaXThinkingWireStrategy = 'anthropic-adaptive' | 'anthropic-budget' | 'provider-budget' | 'provider-toggle' | 'none';
+interface KodaXReasoningProfile {
+    readonly reasoningPreset?: KodaXReasoningPresetName;
+    readonly effortStrategy: KodaXReasoningEffortWireStrategy;
+    readonly thinkingStrategy?: KodaXThinkingWireStrategy;
+    readonly defaultEffort?: KodaXWireReasoningEffort;
+    readonly supportedEfforts?: readonly KodaXReasoningEffortPreset[];
+    readonly effortAliases?: Partial<Record<KodaXWireReasoningEffort, KodaXWireReasoningEffort>>;
+    readonly disabledEfforts?: readonly KodaXWireReasoningEffort[];
+    readonly localRejectEfforts?: readonly KodaXWireReasoningEffort[];
+    readonly allowCustomEffort?: boolean;
+    readonly budgetByEffort?: Partial<Record<KodaXWireReasoningEffort, number>>;
+    readonly supportsReasoningEffort?: boolean;
+    readonly supportsReasoningSummary?: boolean;
+    readonly supportsEncryptedReasoningReplay?: boolean;
+    readonly supportsAdaptiveThinking?: boolean;
+    readonly supportsManualThinkingBudget?: boolean;
+    readonly supportsDisabledThinking?: boolean;
+    readonly requiresEffortBetaHeader?: boolean;
+}
+/**
+ * Friendly reasoning declaration for CUSTOM providers / models — the canonical
+ * user-facing form. List the effort rungs the model accepts (order = the Ctrl+T
+ * ladder; include `"off"` to allow disabling thinking) plus an optional
+ * `default`. The wire strategy (effortStrategy / thinkingStrategy) is derived
+ * from the provider `protocol`, so users never touch preset names or strategy
+ * enums. Use the string `"none"` for a model with no thinking capability. For
+ * full, explicit control fall back to `reasoningProfile`.
+ *
+ * Example: `"reasoning": { "efforts": ["off", "low", "high", "max"], "default": "high" }`
+ */
+interface KodaXSimpleReasoningConfig {
+    readonly efforts: readonly string[];
+    readonly default?: string;
+}
+/** User-facing reasoning declaration: friendly form, `"none"`, or (advanced) a raw profile override. */
+type KodaXReasoningConfig = KodaXSimpleReasoningConfig | 'none' | Partial<KodaXReasoningProfile>;
 type KodaXProviderTransport = 'native-api' | 'cli-bridge';
 type KodaXProviderConversationSemantics = 'full-history' | 'last-user-message';
 type KodaXProviderMcpSupport = 'native' | 'none';
@@ -140,7 +191,6 @@ interface KodaXProviderCapabilityProfile {
     multimodalSupport?: KodaXProviderMultimodalSupport;
     evidenceSupport?: KodaXProviderEvidenceSupport;
 }
-type KodaXReasoningOverride = 'budget' | 'effort' | 'toggle' | 'adaptive' | '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';
@@ -155,23 +205,7 @@ 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[];
-}
+type KodaXChildFanoutClass = 'finding-validation' | 'evidence-scan' | 'module-triage' | 'hypothesis-check';
 interface KodaXTaskRoutingDecision {
     primaryTask: KodaXTaskType;
     secondaryTask?: KodaXTaskType;
@@ -207,18 +241,40 @@ interface KodaXThinkingBudgetMap {
 type KodaXTaskBudgetOverrides = Partial<Record<KodaXTaskType, Partial<KodaXThinkingBudgetMap>>>;
 interface KodaXReasoningRequest {
     enabled?: boolean;
-    mode?: KodaXReasoningMode;
-    depth?: KodaXThinkingDepth;
+    /**
+     * Canonical reasoning control. Reasoning single-tracking removed the legacy
+     * `mode` (KodaXReasoningMode) + `depth` (KodaXThinkingDepth) request fields —
+     * callers pass `effort` (or `enabled` as a boolean shorthand). Providers
+     * derive any thinking budget from the effort via `effortToThinkingDepth`.
+     */
+    effort?: KodaXWireReasoningEffort;
     taskType?: KodaXTaskType;
     executionMode?: KodaXExecutionMode;
 }
+interface KodaXNormalizedReasoningRequest {
+    enabled: boolean;
+    effort: KodaXWireReasoningEffort;
+    effortSource?: 'explicit' | 'legacy';
+    taskType: KodaXTaskType;
+    executionMode: KodaXExecutionMode;
+}
 interface KodaXModelDescriptor {
     id: string;
     displayName?: string;
     contextWindow?: number;
     maxOutputTokens?: number;
     thinkingBudgetCap?: number;
+    /** @deprecated Auto-migrated on load. Prefer `reasoning: { efforts, default }`. */
     reasoningCapability?: KodaXReasoningCapability;
+    /** @deprecated Internal preset name; auto-migrated on load. Prefer `reasoning`. */
+    reasoningPreset?: KodaXReasoningPresetName;
+    /**
+     * Canonical reasoning declaration: friendly `{ efforts, default }`, `"none"`,
+     * or (advanced) a raw `Partial<KodaXReasoningProfile>` override. See
+     * `KodaXReasoningConfig`.
+     */
+    reasoning?: KodaXReasoningConfig;
+    reasoningProfile?: KodaXReasoningProfile;
     /**
      * Per-model override for `replayReasoningContent`. Falls through to the
      * provider-level flag when undefined. Lets a single gateway endpoint
@@ -309,6 +365,14 @@ interface KodaXCustomProviderConfig {
     baseUrl: string;
     apiKeyEnv: string;
     model: string;
+    /** @deprecated Internal preset name; auto-migrated on load. Prefer `reasoning`. */
+    reasoningPreset?: KodaXReasoningPresetName;
+    /**
+     * Canonical reasoning declaration for this provider: friendly
+     * `{ efforts, default }`, `"none"`, or (advanced) a raw profile override.
+     * See `KodaXReasoningConfig`.
+     */
+    reasoning?: KodaXReasoningConfig;
     /**
      * Additional available models beyond the default. Accepts either a
      * plain model id string (legacy) or a KodaXModelDescriptor object
@@ -322,8 +386,11 @@ interface KodaXCustomProviderConfig {
      * - sdk: keep the upstream SDK default User-Agent
      */
     userAgentMode?: KodaXProviderUserAgentMode;
+    /** @deprecated Auto-migrated on load. Prefer `reasoning: "none"` (off) or `reasoning: { efforts, default }`. */
     supportsThinking?: boolean;
+    /** @deprecated Auto-migrated on load. Prefer `reasoning: { efforts, default }`. */
     reasoningCapability?: KodaXReasoningCapability;
+    reasoningProfile?: KodaXReasoningProfile;
     capabilityProfile?: KodaXProviderCapabilityProfile;
     contextWindow?: number;
     maxOutputTokens?: number;
@@ -370,6 +437,7 @@ interface KodaXProviderConfig {
     userAgentMode?: KodaXProviderUserAgentMode;
     supportsThinking: boolean;
     reasoningCapability?: KodaXReasoningCapability;
+    reasoningProfile?: KodaXReasoningProfile;
     capabilityProfile?: KodaXProviderCapabilityProfile;
     /** 模型的上下文窗口大小 (tokens) */
     contextWindow?: number;
@@ -471,6 +539,17 @@ interface KodaXProviderStreamOptions {
         maxAttempts: number;
     }) => void;
     /** 会话标识，用于多轮对话上下文恢复 */
+    /**
+     * Passive capability learning — fired when a provider HARD-rejects a
+     * reasoning-effort value (400/422 naming the param). The REPL records it in
+     * `capability-cache.json` so the rung is removed from the ladder and never
+     * offered or sent again (see `classifyReasoningEffortRejection`).
+     */
+    onReasoningEffortRejected?: (event: {
+        provider: string;
+        model: string;
+        effort: string;
+    }) => void;
     sessionId?: string;
     /** Override the provider's default model for a single request */
     modelOverride?: string;
@@ -482,272 +561,4 @@ interface KodaXProviderStreamOptions {
     signal?: AbortSignal;
 }
 
-/**
- * Retry-After header parsing — FEATURE_130 (v0.7.36).
- *
- * Handles the four forms KodaX's 12 provider adapters encounter when a
- * model returns 429 (rate limit) or 503/529 (overloaded):
- *
- *   1. `Retry-After: 120`               — integer seconds (HTTP 7231 standard)
- *   2. `Retry-After: <HTTP-date>`       — RFC 7231 IMF-fixdate
- *      e.g. "Wed, 21 Oct 2026 07:28:00 GMT"
- *   3. `retry-after-ms: 45000`          — Anthropic millisecond extension
- *   4. (no Retry-After header present)  — falls back to exponential backoff
- *      capped at `maxBackoffMs`, with optional jitter for the
- *      "thundering herd" protection.
- *
- * All return values are normalized to whole milliseconds and clamped to
- * a sensible upper bound — never block the user for more than 120s, and
- * never honor a header advertising a wait longer than `maxHeaderWaitMs`
- * (default 120s). Beyond that limit we still extract the header but cap
- * it; the calling provider can check `cappedFromHeader` to decide
- * whether to surface a "rate limit exceeded — please wait" error to the
- * user instead of silently sleeping for two minutes.
- *
- * Pattern-B (FEATURE_119) interaction: the helper is referentially
- * transparent and stateless — it can be invoked concurrently by N
- * parallel children without coordination. The retry loop in each
- * provider holds its own attempt counter; this helper only translates
- * headers/attempts into wait durations.
- *
- * Reference: opencode session/retry.ts:14-123 (4-form coverage).
- */
-type RetryAfterSource = 'retry-after-seconds' | 'retry-after-date' | 'retry-after-ms' | 'exponential-backoff';
-type RetryAfterResult = {
-    readonly type: 'header';
-    readonly waitMs: number;
-    readonly source: 'retry-after-seconds' | 'retry-after-date' | 'retry-after-ms';
-    /** True when the header value exceeded `maxHeaderWaitMs` and was clamped. */
-    readonly cappedFromHeader: boolean;
-} | {
-    readonly type: 'backoff';
-    readonly waitMs: number;
-    readonly source: 'exponential-backoff';
-    readonly attempt: number;
-};
-interface ParseRetryAfterOptions {
-    /** Zero-based attempt index used by the backoff branch (0 = first retry). */
-    readonly attempt: number;
-    /** Base delay for exponential backoff. Default 1000ms. */
-    readonly baseBackoffMs?: number;
-    /** Maximum exponential backoff cap. Default 30000ms. */
-    readonly maxBackoffMs?: number;
-    /** Maximum wait honored from a header. Default 120000ms. */
-    readonly maxHeaderWaitMs?: number;
-    /**
-     * Override the "now" reference used by the HTTP-date branch.
-     * Test-only escape hatch — production code should leave this undefined.
-     */
-    readonly now?: () => number;
-    /**
-     * Whether the backoff branch adds 0-25% jitter on top of the base
-     * exponential. Default true (matches the legacy `withRateLimit`
-     * jitter contract). Tests can pass `false` for deterministic output.
-     */
-    readonly withJitter?: boolean;
-}
-type HeadersLike = Headers | Record<string, string | string[] | undefined> | undefined;
-/**
- * Parse rate-limit/overload retry-after headers (4 forms) and decide
- * how long the caller should sleep before retrying. Returns either:
- *
- *  - `{type: 'header', ...}` when one of the supported headers was found
- *    and converted into a wait duration; OR
- *  - `{type: 'backoff', ...}` falling back to exponential backoff for
- *    the given `attempt` index when no header is present.
- */
-declare function parseRetryAfter(headers: HeadersLike, options: ParseRetryAfterOptions): RetryAfterResult;
-/**
- * Pull headers off a thrown error in the various shapes produced across
- * provider SDKs (Anthropic, OpenAI, fetch-based custom providers).
- * Returns `undefined` when no headers can be located — the helper then
- * falls through to exponential backoff.
- */
-declare function extractHeadersFromError(error: unknown): HeadersLike;
-
-/**
- * KodaX Base Provider
- *
- * Provider 抽象基类 - 所有 Provider 的公共基础
- */
-
-/**
- * FEATURE_130 (v0.7.36): structured payload fired through
- * `KodaXEvents.onRetryAfter` whenever a provider's `withRateLimit`
- * loop catches a 429 / 503 / 529 response and decides to wait. The
- * `source` field carries which retry-after header form (or fallback)
- * produced the wait duration so UI surfaces can show "provider asked
- * us to wait 45s" vs "no header, exp-backoff guess of 4s".
- */
-interface KodaXRetryAfterEvent {
-    readonly provider: string;
-    readonly waitMs: number;
-    readonly reason: 'rate-limit' | 'overloaded';
-    readonly source: RetryAfterSource;
-    readonly attempt: number;
-    readonly maxAttempts: number;
-}
-type KodaXOnRetryAfterCallback = (event: KodaXRetryAfterEvent) => void;
-declare abstract class KodaXBaseProvider {
-    abstract readonly name: string;
-    abstract readonly supportsThinking: boolean;
-    protected abstract readonly config: KodaXProviderConfig;
-    /**
-     * Per-request override for `max_tokens` in the next provider call. Consumed
-     * once and cleared in `withRateLimit` after the next successful response.
-     * Two callers set this:
-     *   1. Context-overflow recovery inside `withRateLimit` (reduces budget
-     *      when the model reports "prompt too long").
-     *   2. The agent loop's max_tokens escalation path, which flips this to
-     *      `KODAX_ESCALATED_MAX_OUTPUT_TOKENS` when a capped-budget turn
-     *      returns `stop_reason: max_tokens`. See `coding/src/agent.ts`.
-     */
-    protected maxOutputTokensOverride?: number;
-    /**
-     * Public setter for the one-shot override above. Callers outside the
-     * provider package (notably the agent loop's escalation branch) use this
-     * to stage a larger budget for the next stream call in the same logical
-     * turn. Pass `undefined` to clear a stale override explicitly.
-     */
-    setMaxOutputTokensOverride(value: number | undefined): void;
-    /**
-     * Returns the max_tokens value the provider will currently use on its
-     * next request. Precedence (highest to lowest):
-     *   1. One-shot override (agent escalation, context-overflow recovery)
-     *   2. User env var `KODAX_MAX_OUTPUT_TOKENS` (explicit user intent)
-     *   3. Active model descriptor's `maxOutputTokens` (FEATURE_098)
-     *   4. Provider config default
-     *   5. Global `KODAX_MAX_TOKENS` fallback
-     * Used by provider stream() paths and by the agent loop to decide
-     * whether escalation is applicable (see `coding/src/agent.ts`).
-     */
-    getEffectiveMaxOutputTokens(model?: string): number;
-    /**
-     * Hard cap on a single streaming request's wall-clock duration (ms).
-     * Returns undefined when no cap is configured. Consumed by the
-     * resilience layer to abort a doomed stream before the server-side
-     * kill window fires; routed through `non_streaming_fallback`.
-     *
-     * Cascade (highest to lowest):
-     *   1. Active model descriptor's `streamMaxDurationMs`
-     *   2. Provider config default
-     *   3. undefined (watchdog disabled)
-     */
-    getStreamMaxDurationMs(model?: string): number | undefined;
-    /**
-     * Resolves whether OpenAI-compat `reasoning_content` should echo back
-     * on replayed assistant messages for the given model. Same cascade as
-     * `getStreamMaxDurationMs`. Defaults to false when neither layer sets it.
-     */
-    getEffectiveReplayReasoningContent(model?: string): boolean;
-    /**
-     * Resolves whether Anthropic-style thinking signatures must verify
-     * strictly (Anthropic proper only). Same cascade as
-     * `getStreamMaxDurationMs`. Defaults to false (lenient) when neither
-     * layer sets it — matches third-party Anthropic-compat behavior.
-     */
-    getEffectiveStrictThinkingSignature(model?: string): boolean;
-    abstract stream(messages: KodaXMessage[], tools: KodaXToolDefinition[], system: string, reasoning?: boolean | KodaXReasoningRequest, streamOptions?: KodaXProviderStreamOptions, signal?: AbortSignal): Promise<KodaXStreamResult>;
-    supportsNonStreamingFallback(): boolean;
-    complete(_messages: KodaXMessage[], _tools: KodaXToolDefinition[], _system: string, _reasoning?: boolean | KodaXReasoningRequest, _streamOptions?: KodaXProviderStreamOptions, _signal?: AbortSignal): Promise<KodaXStreamResult>;
-    isConfigured(): boolean;
-    /**
-     * FEATURE_216 v0.7.45 — Lightweight credential verification. Returns
-     * a never-throws envelope with `ok` + categorized `error`. Concrete
-     * compat base classes (`KodaXAnthropicCompatProvider`,
-     * `KodaXOpenAICompatProvider`) override this to dispatch by the
-     * `verifyStrategy` field. The default here returns `unsupported` so
-     * Provider classes that don't extend a compat base — or future ones
-     * yet to be wired — fail safely instead of throwing.
-     *
-     * Distinct from `isConfigured()`: that one is env-only (no network);
-     * this one hits the wire (zero or ~7 tokens depending on strategy)
-     * and verifies the key is actually accepted by the upstream.
-     */
-    verifyCredential(_opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<KodaXVerifyCredentialResult>;
-    getModel(): string;
-    getAvailableModels(): string[];
-    getModelDescriptor(modelId?: string): KodaXModelDescriptor | undefined;
-    getBaseUrl(): string | undefined;
-    getApiKeyEnv(): string;
-    getCapabilityProfile(): KodaXProviderCapabilityProfile;
-    getConfiguredReasoningCapability(modelOverride?: string): KodaXReasoningCapability;
-    getReasoningCapability(modelOverride?: string): KodaXReasoningCapability;
-    getReasoningOverride(modelOverride?: string): KodaXReasoningOverride | undefined;
-    getReasoningOverrideKey(modelOverride?: string): string;
-    protected persistReasoningCapabilityOverride(capability: KodaXReasoningCapability, modelOverride?: string): void;
-    protected shouldFallbackForReasoningError(error: unknown, ...terms: string[]): boolean;
-    protected shouldFallbackForSpecificReasoningError(error: unknown, ...terms: string[]): boolean;
-    protected shouldFallbackForForcedToolChoiceError(error: unknown): boolean;
-    protected isServerError(error: unknown): boolean;
-    protected getReasoningFallbackChain(capability: KodaXReasoningCapability): KodaXReasoningCapability[];
-    /**
-     * 获取模型的上下文窗口大小
-     *
-     * Backwards-compatible no-arg form: resolves against the provider's
-     * default model descriptor. New call sites that know the active
-     * model should use `getEffectiveContextWindow(model)` directly.
-     * @returns 上下文窗口大小 (tokens)
-     */
-    getContextWindow(): number;
-    /**
-     * Resolves the context window for a specific model.
-     * Precedence (highest to lowest):
-     *   1. Active model descriptor's `contextWindow` (FEATURE_098)
-     *   2. Provider config default
-     *   3. 200_000 fallback
-     * The user-level `compaction.contextWindow` is layered on top of
-     * this at the call site, so it remains the highest-priority manual
-     * override.
-     */
-    getEffectiveContextWindow(model?: string): number;
-    protected getApiKey(): string;
-    protected shouldLogStreamDiagnostics(): boolean;
-    protected logStreamDiagnostic(...args: unknown[]): void;
-    protected normalizeReasoning(reasoning?: boolean | KodaXReasoningRequest): Required<KodaXReasoningRequest>;
-    /**
-     * Called when ECONNRESET/EPIPE is detected, indicating a stale keep-alive
-     * socket.  Subclasses should override to rebuild their HTTP client with a
-     * fresh connection pool so the next retry uses a new TCP connection.
-     */
-    protected onStaleConnection(): void;
-    protected isRateLimitError(error: unknown): boolean;
-    /**
-     * FEATURE_130: classify a rate-limit error as either a 429-style
-     * "rate-limit" or a 503/529-style "overloaded" condition. The
-     * distinction matters for UI: "rate-limit" usually surfaces a
-     * provider-supplied retry-after window; "overloaded" tends to fall
-     * through to exponential backoff with no header. Both flow through
-     * the same retry path; this only labels the event.
-     */
-    protected classifyRateLimitReason(error: unknown): 'rate-limit' | 'overloaded';
-    /**
-     * Extract Retry-After delay from error headers (429/529 responses).
-     * Returns milliseconds, or undefined when no usable header is present.
-     *
-     * FEATURE_130 (v0.7.36): now delegates to the shared `parseRetryAfter`
-     * helper so all 12 provider adapters get 4-form coverage without each
-     * adapter rolling its own parser. The 4 forms supported are:
-     *   - `Retry-After: <integer-seconds>`
-     *   - `Retry-After: <HTTP-date>`
-     *   - `retry-after-ms: <milliseconds>` (Anthropic extension)
-     *   - exponential-backoff fallback (returned via `withRateLimit`,
-     *     not through this helper — it is `undefined` here when no
-     *     header is present, which the caller then resolves to backoff)
-     */
-    protected extractRetryAfterMs(error: unknown): number | undefined;
-    /**
-     * Detect "prompt too long / context window exceeded" errors and compute
-     * a reduced max_tokens for retry.  Returns undefined if not a context
-     * overflow error.
-     */
-    protected parseContextOverflow(error: unknown): number | undefined;
-    protected isContextOverflowError(error: unknown): boolean;
-    protected withRateLimit<T>(fn: () => Promise<T>, signal?: AbortSignal, retries?: number, onRateLimit?: (attempt: number, maxRetries: number, delayMs: number) => void, onRetryAfter?: KodaXOnRetryAfterCallback): Promise<T>;
-}
-
-export { extractHeadersFromError as aa, parseRetryAfter as ab, KodaXBaseProvider as f };
-export type { KodaXToolDefinition as $, KodaXProviderMultimodalSupport as A, KodaXProviderSessionSupport as B, KodaXProviderStreamOptions 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, KodaXRetryAfterEvent as L, KodaXReviewScale as M, KodaXRiskLevel as N, KodaXStreamResult as O, KodaXTaskActionability as P, KodaXTaskBudgetOverrides as Q, KodaXTaskComplexity as R, KodaXTaskFamily as S, KodaXTaskRoutingDecision as T, KodaXTaskType as U, KodaXTaskWorkIntent as V, KodaXTextBlock as W, KodaXThinkingBlock as X, KodaXThinkingBudgetMap as Y, KodaXThinkingDepth as Z, KodaXTokenUsage as _, KodaXAmaFanoutClass as a, KodaXToolResultBlock as a0, KodaXToolResultContentItem as a1, KodaXToolResultImageItem as a2, KodaXToolResultTextItem as a3, KodaXToolUseBlock as a4, KodaXVerifyCredentialResult as a5, KodaXVerifyStrategy as a6, ParseRetryAfterOptions as a7, RetryAfterResult as a8, RetryAfterSource as a9, KodaXAmaFanoutPolicy as b, KodaXAmaProfile as c, KodaXAmaTactic as d, KodaXAssuranceIntent as e, KodaXCacheBoundary as g, KodaXContentBlock as h, KodaXCustomProviderConfig as i, KodaXExecutionMode as j, KodaXExecutionPattern as k, KodaXHarnessProfile as l, KodaXImageBlock as m, KodaXListModelsResult as n, KodaXMessage as o, KodaXModelDescriptor as p, KodaXMutationSurface as q, KodaXOnRetryAfterCallback as r, KodaXProtocolFamily as s, KodaXProviderCapabilityProfile as t, KodaXProviderConfig as u, KodaXProviderContextFidelity as v, KodaXProviderConversationSemantics as w, KodaXProviderEvidenceSupport as x, KodaXProviderLongRunningSupport as y, KodaXProviderMcpSupport as z };
+export type { KodaXToolResultBlock as $, KodaXReasoningCapability as A, KodaXReasoningEffortPreset as B, KodaXReasoningEffortRequest as C, KodaXReasoningEffortWireStrategy as D, KodaXReasoningMode as E, KodaXReasoningProfile as F, KodaXReasoningRequest as G, KodaXRedactedThinkingBlock as H, KodaXReviewScale as I, KodaXRiskLevel as J, KodaXAssuranceIntent as K, KodaXStableEffortIntent as L, KodaXStreamResult as M, KodaXTaskActionability as N, KodaXTaskBudgetOverrides as O, KodaXTaskComplexity as P, KodaXTaskFamily as Q, KodaXTaskRoutingDecision as R, KodaXTaskType as S, KodaXTaskWorkIntent as T, KodaXTextBlock as U, KodaXThinkingBlock as V, KodaXThinkingBudgetMap as W, KodaXThinkingDepth as X, KodaXThinkingWireStrategy as Y, KodaXTokenUsage as Z, KodaXToolDefinition as _, KodaXCacheBoundary as a, KodaXToolResultContentItem as a0, KodaXToolResultImageItem as a1, KodaXToolResultTextItem as a2, KodaXToolUseBlock as a3, KodaXVerifyCredentialResult as a4, KodaXVerifyStrategy as a5, KodaXWireReasoningEffort as a6, KodaXChildFanoutClass as b, KodaXContentBlock as c, KodaXCustomProviderConfig as d, KodaXExecutionMode as e, KodaXExecutionPattern as f, KodaXHarnessProfile as g, KodaXImageBlock as h, KodaXListModelsResult as i, KodaXMessage as j, KodaXModelDescriptor as k, KodaXMutationSurface as l, KodaXNormalizedReasoningRequest as m, KodaXProtocolFamily as n, KodaXProviderCapabilityProfile as o, KodaXProviderConfig as p, KodaXProviderContextFidelity as q, KodaXProviderConversationSemantics as r, KodaXProviderEvidenceSupport as s, KodaXProviderLongRunningSupport as t, KodaXProviderMcpSupport as u, KodaXProviderMultimodalSupport as v, KodaXProviderSessionSupport as w, KodaXProviderStreamOptions as x, KodaXProviderToolCallingFidelity as y, KodaXProviderTransport as z };

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

@@ -0,0 +1,143 @@
+/**
+ * @kodax-ai/agent/messaging — Message queue types
+ *
+ * FEATURE_115 (v0.7.36): agentId-scoped 2-tier priority queue infrastructure.
+ *
+ * Per ADR-021: messaging is a generic agent-platform primitive (not coding-
+ * specific). Downstream consumers:
+ *   - @kodax-ai/coding runner-driven mid-turn drain
+ *   - @kodax-ai/repl InkREPL ESC soft-pause + text injection (FEATURE_111 absorbed)
+ *   - subagent task-notification routing (FEATURE_155 idle-yield wakeup)
+ *
+ * Phase 0.6 study (`c:/tmp/claude-code-actual-usage.md`): Claude Code's
+ * `'now'` priority has zero production usage; KodaX simplifies to 2 tiers.
+ */
+type MessagePriority = 'user' | 'background';
+type MessageMode = 'prompt' | 'task-notification' | 'system-reminder';
+type QueuedInputArtifact = {
+    readonly kind: 'image';
+    readonly path: string;
+    readonly mediaType?: string;
+    readonly source?: string;
+    readonly description?: string;
+} | {
+    readonly kind: 'file';
+    readonly path: string;
+    readonly mediaType?: string;
+    readonly mimeType?: string;
+    readonly name?: string;
+    readonly source?: string;
+    readonly description?: string;
+} | {
+    readonly kind: 'video';
+    readonly path: string;
+    readonly mediaType: string;
+    readonly name?: string;
+    readonly source?: string;
+    readonly description?: string;
+};
+interface QueuedMessage {
+    /** Stable id for tracing / dedup. Format: `msg-<sequence>`. */
+    readonly id: string;
+    readonly priority: MessagePriority;
+    /**
+     * Routing key:
+     *   undefined = main thread / coordinator agent
+     *   'agent-id-XYZ' = subagent / specific consumer
+     *
+     * Drain consumers MUST filter by agentId match — undefined matches only
+     * undefined-agentId messages, not "any agent".
+     */
+    readonly agentId?: string;
+    readonly mode: MessageMode;
+    readonly content: string;
+    readonly inputArtifacts?: readonly QueuedInputArtifact[];
+    /** Wall-clock timestamp (`Date.now()`) for tracing only — not used for ordering. */
+    readonly enqueuedAt: number;
+}
+interface DequeueFilter {
+    /**
+     * Only return messages with this agentId.
+     * undefined matches messages with no agentId (main-thread messages only).
+     */
+    readonly agentId?: string;
+    /**
+     * Highest priority level included in the drain.
+     *   'user'       → only user priority drained, background stays queued
+     *   'background' → both user + background drained (Sleep-gated case)
+     */
+    readonly maxPriority: MessagePriority;
+    /**
+     * Optional cap on number of messages drained in this call.
+     * Defaults to unlimited (drains all matching).
+     */
+    readonly limit?: number;
+    /**
+     * FEATURE_159 (v0.7.40) — optional mode filter. Lets REPL split the
+     * single queue into mode-typed views (e.g. `mode:'prompt'` for user
+     * input vs `mode:'task-notification'` for child completion banners)
+     * without separate queues. When omitted, all modes match.
+     */
+    readonly mode?: MessageMode;
+    /**
+     * FEATURE_159 (v0.7.40) — optional precise-id filter. Single-message
+     * targeted removal — drives Esc-pop-this-uuid in REPL. When set, all
+     * other filters still apply (agentId / priority / mode mismatches still
+     * skip the message), so callers can't accidentally remove a message
+     * outside their scope.
+     */
+    readonly id?: string;
+    /**
+     * FEATURE_159 (v0.7.40) — optional escape-hatch predicate, AND-ed with
+     * the structured filters. Lets SDK consumers express conditions the
+     * typed fields don't cover (e.g. timestamp ranges, content-match) without
+     * forcing every new use case to extend `DequeueFilter`. KodaX-internal
+     * code should prefer the typed fields for readability; this is the
+     * "data-driven main path + predicate escape" pattern.
+     *
+     * Evaluated AFTER the typed filters succeed — so a `predicate` that
+     * inspects `message.content` never runs on messages outside the
+     * caller's `agentId` / `mode` / `id` scope.
+     */
+    readonly predicate?: (message: QueuedMessage) => boolean;
+}
+/**
+ * FEATURE_159 (v0.7.40) — structured queue event emitted to subscribers.
+ *
+ * Replaces the prior `() => void` bare-notify signal. Carries the kind +
+ * affected messages so SDK observability consumers (logging, tracing,
+ * metrics) can react per-event without re-diffing snapshots.
+ *
+ * Event granularity rules:
+ *   - `enqueued` fires ONCE per `enqueue()` call (always 1 message).
+ *   - `dequeued` fires ONCE per `dequeue()` call that removed ≥1 message,
+ *     carrying ALL drained messages in priority+FIFO order. No-op drains
+ *     (filter matched nothing) fire no event — quiet by design so the
+ *     `waitForWakeEvent` 100ms poll doesn't spam idle subscribers.
+ *   - `cleared` fires ONCE per `clear()` call that removed ≥1 message,
+ *     carrying the pre-clear messages. Empty-queue clear fires nothing.
+ *
+ * The `useSyncExternalStore` React hook ignores the event payload (it
+ * only needs the change signal); SDK / tracer consumers read the event.
+ */
+type QueueEvent = {
+    readonly kind: 'enqueued';
+    readonly message: QueuedMessage;
+} | {
+    readonly kind: 'dequeued';
+    readonly messages: readonly QueuedMessage[];
+} | {
+    readonly kind: 'cleared';
+    readonly messages: readonly QueuedMessage[];
+};
+/** FEATURE_159 — `MessageQueue.subscribe` listener signature. */
+type QueueEventListener = (event: QueueEvent) => void;
+interface EnqueueInput {
+    readonly priority: MessagePriority;
+    readonly mode: MessageMode;
+    readonly content: string;
+    readonly agentId?: string;
+    readonly inputArtifacts?: readonly QueuedInputArtifact[];
+}
+
+export type { DequeueFilter as D, EnqueueInput as E, MessageMode as M, QueueEventListener as Q, MessagePriority as a, QueuedInputArtifact as b, QueuedMessage as c };