@kodax-ai/kodax 0.7.57 → 0.7.59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +2032 -1920
  2. package/README.md +1228 -1219
  3. package/README_CN.md +647 -638
  4. package/dist/chunks/agent-QQCRBU4C.js +2 -0
  5. package/dist/chunks/argument-completer-7Q2T4YWA.js +2 -0
  6. package/dist/chunks/{chunk-LZKGOR2C.js → chunk-2UUOFT3Z.js} +1 -1
  7. package/dist/chunks/chunk-5GPJ6MB5.js +405 -0
  8. package/dist/chunks/chunk-BEXLPFFB.js +7 -0
  9. package/dist/chunks/chunk-D6QVXQNI.js +1 -0
  10. package/dist/chunks/chunk-D7RENPQQ.js +322 -0
  11. package/dist/chunks/chunk-PRIBJN5E.js +683 -0
  12. package/dist/chunks/chunk-S4GVQO3W.js +31 -0
  13. package/dist/chunks/chunk-SDSLWDAZ.js +17 -0
  14. package/dist/chunks/chunk-SVEJFERZ.js +326 -0
  15. package/dist/chunks/chunk-TBXP7FEG.js +52 -0
  16. package/dist/chunks/chunk-UA744TZM.js +2 -0
  17. package/dist/chunks/{chunk-YSVPF6SN.js → chunk-UXQILGRX.js} +262 -259
  18. package/dist/chunks/{chunk-4SHP3M67.js → chunk-YADBB5GN.js} +1 -1
  19. package/dist/chunks/chunk-Z23LK3IV.js +310 -0
  20. package/dist/chunks/chunk-Z3ZXV3DZ.js +18 -0
  21. package/dist/chunks/compaction-config-GQIPCVFD.js +2 -0
  22. package/dist/chunks/{construction-bootstrap-55B7Q5RX.js → construction-bootstrap-YON4ZEMO.js} +1 -1
  23. package/dist/chunks/dist-73L4OYPD.js +2 -0
  24. package/dist/chunks/dist-EZXBR6NW.js +2 -0
  25. package/dist/chunks/host-LO6ZNTMV.js +2 -0
  26. package/dist/chunks/paste-4THGP5XW.js +2 -0
  27. package/dist/chunks/run-manager-HTLXKU66.js +2 -0
  28. package/dist/chunks/utils-5XVW33SY.js +2 -0
  29. package/dist/index.d.ts +15 -14
  30. package/dist/index.js +2 -2
  31. package/dist/kodax_cli.js +1222 -1047
  32. package/dist/provider-capabilities.json +971 -986
  33. package/dist/sdk-agent.d.ts +156 -14
  34. package/dist/sdk-agent.js +1 -1
  35. package/dist/sdk-coding.d.ts +253 -188
  36. package/dist/sdk-coding.js +1 -1
  37. package/dist/sdk-llm.d.ts +66 -43
  38. package/dist/sdk-llm.js +1 -1
  39. package/dist/sdk-mcp.js +1 -1
  40. package/dist/sdk-media.d.ts +18 -2
  41. package/dist/sdk-media.js +1 -1
  42. package/dist/sdk-repl.d.ts +21 -22
  43. package/dist/sdk-repl.js +2 -2
  44. package/dist/sdk-session.d.ts +8 -7
  45. package/dist/sdk-session.js +1 -1
  46. package/dist/sdk-skills.d.ts +4 -231
  47. package/dist/sdk-skills.js +1 -1
  48. package/dist/types-chunks/{base.d-BnjQrSVf.d.ts → base.d-BA9Doaj_.d.ts} +3 -3
  49. package/dist/types-chunks/{bash-prefix-extractor.d-BgvMbfq6.d.ts → bash-prefix-extractor.d-BNdpV4Cf.d.ts} +515 -69
  50. package/dist/types-chunks/capability-learning.d-DRV80ISB.d.ts +29 -0
  51. package/dist/types-chunks/{cost-tracker.d-wRtyEW9d.d.ts → cost-tracker.d-CBLk1fiD.d.ts} +24 -2
  52. package/dist/types-chunks/{guardrail.d-C1DhxnvC.d.ts → guardrail.d-CNdKuSD_.d.ts} +4 -4
  53. package/dist/types-chunks/{process.d-BZncyzEj.d.ts → process.d-BOrAxjvM.d.ts} +188 -15
  54. package/dist/types-chunks/{resolver.d-ZvKQgl0X.d.ts → resolver.d-DFAKKUvt.d.ts} +87 -4
  55. package/dist/types-chunks/{capsule.d-DwJp5r63.d.ts → run-manager.d-CsJC9zYf.d.ts} +113 -5
  56. package/dist/types-chunks/{sdk-session-DAScB0rW.d.ts → sdk-session-ByZlwgdM.d.ts} +83 -9
  57. package/dist/types-chunks/{storage.d-CPvn9qI0.d.ts → storage.d-DHL3XpAL.d.ts} +2 -2
  58. package/dist/types-chunks/{guardrail.d-BP3yyr6u.d.ts → types.d-CE_Ter29.d.ts} +125 -3
  59. package/dist/types-chunks/{types.d-6VOXvF88.d.ts → types.d-Ci5YPFEh.d.ts} +39 -5
  60. package/dist/types-chunks/types.d-vJExiRje.d.ts +232 -0
  61. package/dist/types-chunks/{utils.d-CpgVIjYZ.d.ts → utils.d-D9FHU4wB.d.ts} +84 -6
  62. package/package.json +2 -2
  63. package/dist/chunks/agent-EHWQZA4C.js +0 -2
  64. package/dist/chunks/argument-completer-AYDAYGKL.js +0 -2
  65. package/dist/chunks/chunk-3WWPJGPQ.js +0 -2
  66. package/dist/chunks/chunk-KN6IJMTB.js +0 -636
  67. package/dist/chunks/chunk-MJFPFRGK.js +0 -423
  68. package/dist/chunks/chunk-N2N2W3AQ.js +0 -584
  69. package/dist/chunks/chunk-PCPFLPS4.js +0 -5
  70. package/dist/chunks/chunk-TCLSPUTR.js +0 -31
  71. package/dist/chunks/chunk-VACH6QWN.js +0 -315
  72. package/dist/chunks/compaction-config-TLDMFMZO.js +0 -2
  73. package/dist/chunks/dist-IE4HVWP7.js +0 -2
  74. package/dist/chunks/dist-IKOK2MJQ.js +0 -2
  75. package/dist/chunks/paste-WTL2XN7P.js +0 -2
  76. package/dist/chunks/utils-EJ2VCRTC.js +0 -2
  77. package/dist/types-chunks/types.d-D8WcfrOD.d.ts +0 -143
@@ -0,0 +1,29 @@
1
+ import { F as KodaXReasoningProfile } from './types.d-Ci5YPFEh.js';
2
+
3
+ type CapabilityCacheSource = 'observed' | 'probed';
4
+ interface CapabilityCacheEntry {
5
+ /** Efforts this provider/model rejected; removed from the effective ladder. */
6
+ readonly rejected: readonly string[];
7
+ /** How the rejection was learned. */
8
+ readonly source: CapabilityCacheSource;
9
+ /** ISO timestamp of the last update. */
10
+ readonly updatedAt: string;
11
+ }
12
+ /** Keyed by `provider/model`. */
13
+ type CapabilityCache = Record<string, CapabilityCacheEntry>;
14
+ declare function capabilityCacheKey(provider: string, model: string | undefined): string;
15
+ /**
16
+ * Narrow a reasoning profile by learned hard rejections.
17
+ *
18
+ * Learning only removes rungs. Provider acceptance is not proof that an effort
19
+ * is semantically distinct, but a hard rejection is ground truth that the rung
20
+ * should not be sent again for this provider/model.
21
+ */
22
+ declare function narrowReasoningProfile(profile: KodaXReasoningProfile, rejected: readonly string[]): KodaXReasoningProfile;
23
+ declare function getRejectedEfforts(cache: CapabilityCache, provider: string, model: string | undefined): readonly string[];
24
+ declare function addRejectedEffort(cache: CapabilityCache, provider: string, model: string | undefined, effort: string, source: CapabilityCacheSource, updatedAt: string): CapabilityCache;
25
+ declare function removeCacheEntry(cache: CapabilityCache, provider?: string, model?: string): CapabilityCache;
26
+ declare function sanitizeCapabilityCache(raw: unknown): CapabilityCache;
27
+
28
+ export { addRejectedEffort as c, capabilityCacheKey as d, getRejectedEfforts as g, narrowReasoningProfile as n, removeCacheEntry as r, sanitizeCapabilityCache as s };
29
+ export type { CapabilityCache as C, CapabilityCacheEntry as a, CapabilityCacheSource as b };
@@ -1,3 +1,25 @@
1
+ interface KodaXLlmTimeoutConfig {
2
+ /** Main provider request hard timeout, in seconds. Default 600s. */
3
+ readonly requestTimeoutSec?: number;
4
+ /** Idle timeout between stream deltas, in seconds. Set 0 to disable. Default 0. */
5
+ readonly streamIdleTimeoutSec?: number;
6
+ /** Per stream chunk timeout, in seconds. Default 30s. */
7
+ readonly chunkTimeoutSec?: number;
8
+ /** Maximum retry delay, in seconds. Default 60s. */
9
+ readonly maxRetryDelaySec?: number;
10
+ }
11
+ interface KodaXResolvedLlmTimeoutConfig {
12
+ readonly requestTimeoutMs?: number;
13
+ readonly streamIdleTimeoutMs?: number;
14
+ readonly chunkTimeoutMs?: number;
15
+ readonly maxRetryDelayMs?: number;
16
+ }
17
+ declare function timeoutSecToMs(value: number | undefined, label: string, opts?: {
18
+ readonly allowZero?: boolean;
19
+ }): number | undefined;
20
+ declare function parseTimeoutSecEnvMs(raw: string | undefined): number | undefined;
21
+ declare function resolveLlmTimeoutConfig(timeouts: KodaXLlmTimeoutConfig | undefined): KodaXResolvedLlmTimeoutConfig | undefined;
22
+
1
23
  /**
2
24
  * KodaX Cost Rates - Multi-Provider pricing table
3
25
  *
@@ -106,5 +128,5 @@ declare function getSummary(tracker: CostTracker): SessionCostSummary;
106
128
  declare function formatCost(usd: number): string;
107
129
  declare function formatCostReport(summary: SessionCostSummary): string;
108
130
 
109
- export { DEFAULT_COST_RATES as D, createCostTracker as b, calculateCost as c, formatCostReport as d, getSummary as e, formatCost as f, getCostRate as g, recordUsage as h, recordRetry as r };
110
- export type { CostRate as C, ProviderCostSummary as P, RetryRecord as R, SessionCostSummary as S, TokenUsageRecord as T, CostTracker as a };
131
+ export { DEFAULT_COST_RATES as D, calculateCost as c, createCostTracker as d, formatCostReport as e, formatCost as f, getCostRate as g, getSummary as h, recordUsage as i, resolveLlmTimeoutConfig as j, parseTimeoutSecEnvMs as p, recordRetry as r, timeoutSecToMs as t };
132
+ export type { CostRate as C, KodaXLlmTimeoutConfig as K, ProviderCostSummary as P, RetryRecord as R, SessionCostSummary as S, TokenUsageRecord as T, CostTracker as a, KodaXResolvedLlmTimeoutConfig as b };
@@ -1,8 +1,8 @@
1
1
  import { M as McpConnectMode, a as McpServerConfig, b as McpServersConfig, c as McpTransportKind } from './config.d-CJy1WENT.js';
2
- import { K as KodaXBaseProvider } from './base.d-BnjQrSVf.js';
3
- import { a as CostTracker } from './cost-tracker.d-wRtyEW9d.js';
4
- import { aG as RunnerToolCall } from './process.d-BZncyzEj.js';
5
- import { d as ToolGuardrail } from './guardrail.d-BP3yyr6u.js';
2
+ import { K as KodaXBaseProvider } from './base.d-BA9Doaj_.js';
3
+ import { a as CostTracker } from './cost-tracker.d-CBLk1fiD.js';
4
+ import { aO as RunnerToolCall } from './process.d-BOrAxjvM.js';
5
+ import { g as ToolGuardrail } from './types.d-CE_Ter29.js';
6
6
 
7
7
  /**
8
8
  * FEATURE_200 Phase F (v0.7.45) — MCP domain types extracted from types.ts.
@@ -1,4 +1,4 @@
1
- import { j as KodaXMessage, _ as KodaXToolDefinition, E as KodaXReasoningMode, a6 as KodaXWireReasoningEffort, a0 as KodaXToolResultContentItem, V as KodaXThinkingBlock, H as KodaXRedactedThinkingBlock } from './types.d-6VOXvF88.js';
1
+ import { j as KodaXMessage, _ as KodaXToolDefinition, E as KodaXReasoningMode, a6 as KodaXWireReasoningEffort, a0 as KodaXToolResultContentItem, V as KodaXThinkingBlock, H as KodaXRedactedThinkingBlock } from './types.d-Ci5YPFEh.js';
2
2
 
3
3
  /**
4
4
  * @kodax-ai/agent Types
@@ -163,7 +163,7 @@ interface KodaXSessionTreeNode {
163
163
  active: boolean;
164
164
  }
165
165
  type KodaXSessionScope = 'user' | 'managed-task-worker';
166
- type KodaXSessionUiTextHistoryItemType = 'user' | 'assistant' | 'system' | 'thinking' | 'error' | 'event' | 'info' | 'hint';
166
+ type KodaXSessionUiTextHistoryItemType = 'user' | 'assistant' | 'system' | 'thinking' | 'error' | 'event' | 'info' | 'hint' | 'sidecar';
167
167
  type KodaXSessionUiHistoryItemType = KodaXSessionUiTextHistoryItemType | 'tool_group';
168
168
  interface KodaXSessionUiTextHistoryItem {
169
169
  type: KodaXSessionUiTextHistoryItemType;
@@ -197,6 +197,22 @@ interface KodaXSessionRuntimeInfo {
197
197
  executionCwd?: string;
198
198
  branch?: string;
199
199
  workspaceKind?: KodaXSessionWorkspaceKind;
200
+ /** SDK consumer surface/profile label, e.g. `'code'` | `'partner'`. */
201
+ surface?: string;
202
+ /** SDK consumer profile id (stable name or UUID). */
203
+ profileId?: string;
204
+ /** SDK consumer profile version. */
205
+ profileVersion?: string;
206
+ /** LLM provider alias active at session start, e.g. `'anthropic'`. */
207
+ provider?: string;
208
+ /** Model identifier active at session start. */
209
+ model?: string;
210
+ /** Reasoning mode active at session start. */
211
+ reasoningMode?: string;
212
+ /** Permission mode active at session start, e.g. `'auto'` | `'plan'`. */
213
+ permissionMode?: string;
214
+ /** Agent mode active at session start, e.g. `'sa'` | `'ama'` | `'amaw'`. */
215
+ agentMode?: string;
200
216
  }
201
217
  interface KodaXSessionData {
202
218
  messages: KodaXMessage[];
@@ -1856,6 +1872,9 @@ interface StopHookContext {
1856
1872
  * FEATURE_184 (v0.7.45) — Stop hook return surface.
1857
1873
  */
1858
1874
  type StopHookResult = undefined | string | {
1875
+ readonly reanimate: string;
1876
+ readonly source?: string;
1877
+ } | {
1859
1878
  readonly abort: true;
1860
1879
  readonly reason: string;
1861
1880
  };
@@ -2006,6 +2025,19 @@ interface AskUserQuestionItem {
2006
2025
  value: string;
2007
2026
  }>;
2008
2027
  multiSelect?: boolean;
2028
+ /**
2029
+ * FEATURE_222 — only meaningful when `multiSelect` is true. The host should
2030
+ * reject (re-prompt / show an error, do NOT resolve) a selection with fewer
2031
+ * than `minSelections` items. Absent ⇒ no lower bound.
2032
+ */
2033
+ minSelections?: number;
2034
+ /**
2035
+ * FEATURE_222 — only meaningful when `multiSelect` is true. The host should
2036
+ * reject a selection with more than `maxSelections` items. Absent ⇒ no upper
2037
+ * bound. Lets a host render + validate "pick at most N" structurally instead
2038
+ * of parsing it out of natural-language question text.
2039
+ */
2040
+ maxSelections?: number;
2009
2041
  }
2010
2042
  /** Options for multi-question mode — multiple independent questions in one call. */
2011
2043
  interface AskUserMultiOptions {
@@ -2022,8 +2054,31 @@ interface AskUserQuestionOptions {
2022
2054
  value: string;
2023
2055
  }>;
2024
2056
  multiSelect?: boolean;
2057
+ /** FEATURE_222 — see {@link AskUserQuestionItem.minSelections}. */
2058
+ minSelections?: number;
2059
+ /** FEATURE_222 — see {@link AskUserQuestionItem.maxSelections}. */
2060
+ maxSelections?: number;
2025
2061
  default?: string;
2026
2062
  }
2063
+ /**
2064
+ * FEATURE_222 — reserved option value a host may append as a synthetic option
2065
+ * (e.g. a "← Back" entry) in `askUserMulti`'s per-question flow to mean "return
2066
+ * to the previous question" instead of answering the current one. Only
2067
+ * meaningful for `questions[]` index > 0 (there is no previous before the
2068
+ * first). The coding `ask_user_question` tool rejects this as a normal
2069
+ * `option.value` supplied by the model, so a host may safely reuse it for its
2070
+ * own back-navigation UI. A host that ignores this constant simply never offers
2071
+ * back-navigation — the default multi-question flow is unaffected either way.
2072
+ */
2073
+ declare const ASK_USER_BACK_SIGNAL = "__back__";
2074
+ /**
2075
+ * FEATURE_222 — narrow an `askUser` result to a single string for the many
2076
+ * callers that only ever ask single-select questions (they never set
2077
+ * `multiSelect: true`, so the array branch is unreachable at runtime). Collapses
2078
+ * an unexpected array to its first element so a mis-configured host degrades
2079
+ * predictably instead of leaking `[object Array]` into a string comparison.
2080
+ */
2081
+ declare function asSingleSelection(answer: string | string[]): string;
2027
2082
  /**
2028
2083
  * The host-provided user-interaction surface. Each method is optional — a
2029
2084
  * headless host omits them and callers degrade gracefully. This is the single
@@ -2031,11 +2086,19 @@ interface AskUserQuestionOptions {
2031
2086
  * elicitation reverse capability.
2032
2087
  */
2033
2088
  interface UserInteraction {
2034
- /** Ask one question (select mode by default). Resolves the chosen value. */
2035
- askUser?: (options: AskUserQuestionOptions) => Promise<string>;
2036
- /** Ask several independent questions sequentially. Resolves a value map, or
2037
- * undefined when the user cancels. */
2038
- askUserMulti?: (options: AskUserMultiOptions) => Promise<Record<string, string> | undefined>;
2089
+ /**
2090
+ * Ask one question (select mode by default). Single-select (multiSelect
2091
+ * falsy) resolves the chosen value as a string unchanged. Multi-select
2092
+ * (multiSelect: true) resolves the selected values as a `string[]`. The union
2093
+ * is a backward-compatible superset: a host still returning a plain string
2094
+ * satisfies this contract, but a multi-select host SHOULD return `string[]`
2095
+ * so option values containing `, ` are not corrupted by a join.
2096
+ */
2097
+ askUser?: (options: AskUserQuestionOptions) => Promise<string | string[]>;
2098
+ /** Ask several independent questions sequentially. Resolves a per-question
2099
+ * value map (each entry a string for single-select, `string[]` for
2100
+ * multi-select), or undefined when the user cancels. */
2101
+ askUserMulti?: (options: AskUserMultiOptions) => Promise<Record<string, string | string[]> | undefined>;
2039
2102
  /** Ask for free-text input. Resolves the text, or undefined when cancelled. */
2040
2103
  askUserInput?: (options: {
2041
2104
  question: string;
@@ -2047,6 +2110,35 @@ declare function setActiveUserInteraction(interaction: UserInteraction | undefin
2047
2110
  /** The live user-interaction surface, or undefined when none is active. */
2048
2111
  declare function getActiveUserInteraction(): UserInteraction | undefined;
2049
2112
 
2113
+ type KodaXImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
2114
+ type KodaXVideoMediaType = 'video/mp4' | 'video/mpeg' | 'video/quicktime' | 'video/x-msvideo' | 'video/x-flv' | 'video/webm' | 'video/x-ms-wmv' | 'video/3gpp';
2115
+ type KodaXInputArtifactSource = 'user-inline' | 'clipboard' | 'drag-drop' | 'file-picker';
2116
+ interface KodaXImageInputArtifact {
2117
+ readonly kind: 'image';
2118
+ readonly path: string;
2119
+ readonly mediaType?: KodaXImageMediaType;
2120
+ readonly source?: KodaXInputArtifactSource;
2121
+ readonly description?: string;
2122
+ }
2123
+ interface KodaXFileInputArtifact {
2124
+ readonly kind: 'file';
2125
+ readonly path: string;
2126
+ readonly mediaType?: string;
2127
+ readonly mimeType?: string;
2128
+ readonly name?: string;
2129
+ readonly source?: KodaXInputArtifactSource;
2130
+ readonly description?: string;
2131
+ }
2132
+ interface KodaXVideoInputArtifact {
2133
+ readonly kind: 'video';
2134
+ readonly path: string;
2135
+ readonly mediaType: KodaXVideoMediaType;
2136
+ readonly name?: string;
2137
+ readonly source?: KodaXInputArtifactSource;
2138
+ readonly description?: string;
2139
+ }
2140
+ type KodaXInputArtifact = KodaXImageInputArtifact | KodaXFileInputArtifact | KodaXVideoInputArtifact;
2141
+
2050
2142
  /**
2051
2143
  * Child task registry primitive — generic fan-out tracking.
2052
2144
  *
@@ -2513,7 +2605,7 @@ interface FileOperations {
2513
2605
  * injected clock). The run graph models agent relationships as a
2514
2606
  * thread/edge/event stream, not just a final summary blob.
2515
2607
  */
2516
- type WorkflowEventType = 'workflow_started' | 'phase_started' | 'phase_finished' | 'agent_spawned' | 'agent_message_sent' | 'agent_completed' | 'agent_unverified' | 'agent_failed' | 'agent_summary_updated' | 'agent_stopped' | 'workflow_log' | 'artifact_written' | 'synthesis_completed' | 'workflow_completed' | 'workflow_stopped' | 'workflow_failed';
2608
+ type WorkflowEventType = 'workflow_started' | 'phase_started' | 'phase_finished' | 'agent_spawned' | 'agent_message_sent' | 'agent_completed' | 'agent_unverified' | 'agent_failed' | 'agent_summary_updated' | 'agent_stopped' | 'agent_replayed' | 'workflow_log' | 'artifact_written' | 'synthesis_completed' | 'workflow_completed' | 'workflow_stopped' | 'workflow_failed';
2517
2609
  interface WorkflowEvent {
2518
2610
  /** Monotonic sequence number — stable append ordering. */
2519
2611
  readonly seq: number;
@@ -2578,20 +2670,51 @@ interface WorkflowTaskVerificationResult {
2578
2670
  interface WorkflowSpawnAgentInput {
2579
2671
  /** Human-readable label for the agent — surfaces in events / UI. */
2580
2672
  readonly name: string;
2673
+ /**
2674
+ * Optional progress-group tag (FEATURE_246 Part E). When set, this agent is
2675
+ * grouped under a phase of that name in the progress display — the per-agent
2676
+ * equivalent of wrapping a block in `wf.phase(name, fn)`, matching the harness
2677
+ * `agent(..., { phase })`. The phase group is created on first use. Agents
2678
+ * with no `phase` fall under the currently-active `wf.phase(...)` block (if any).
2679
+ */
2680
+ readonly phase?: string;
2581
2681
  /** The task prompt handed to the child agent. */
2582
2682
  readonly prompt: string;
2583
2683
  /** When true, the child runs with a read-only tool whitelist. */
2584
2684
  readonly readOnly?: boolean;
2585
2685
  /** Route to a registered specialist agent (FEATURE_191). */
2586
2686
  readonly subagentType?: string;
2587
- /** Provider/model tier hint (FEATURE_120 model_hint → env tier). */
2687
+ /**
2688
+ * Per-agent model TIER (FEATURE_120 model_hint). The script expresses semantic
2689
+ * intent — 'fast' (cheap), 'deep' (strong), 'balanced' (default) — NOT a
2690
+ * concrete model name: the authoring model has no cognition of which
2691
+ * providers/models a given operator has configured. The operator maps the
2692
+ * tiers to concrete models via env (KODAX_FAST/DEEP_PROVIDER/MODEL); when a
2693
+ * tier is unconfigured the child inherits the parent provider/model, so a
2694
+ * hint is always a safe no-op at worst. 'fast' applies to read-only children
2695
+ * only (write/codegen stays on the parent tier — a quality guard).
2696
+ */
2588
2697
  readonly modelHint?: WorkflowModelHint;
2589
2698
  /** Isolation policy; defaults to `shared-cwd`. */
2590
2699
  readonly isolation?: WorkflowIsolation;
2700
+ /** Per-child reasoning effort hint (e.g. 'low' | 'medium' | 'high' | 'max').
2701
+ * The backend maps it onto the child's reasoning resolver; omit to inherit
2702
+ * the parent/default effort. Opaque string so the agent layer needs no
2703
+ * coding effort-enum dependency. */
2704
+ readonly effort?: string;
2591
2705
  /** Evidence refs (`task_id:<id>` etc.) seeded into the child context. */
2592
2706
  readonly evidenceRefs?: readonly string[];
2593
2707
  /** Optional machine-checkable postconditions for this child task. */
2594
2708
  readonly verification?: WorkflowTaskVerification;
2709
+ /**
2710
+ * Optional JSON Schema (FEATURE_246 Part B). When set, the child is asked to
2711
+ * end with a fenced JSON block matching the schema; the backend parses and
2712
+ * validates it (with one bounded repair turn on a hard miss) and returns the
2713
+ * parsed object on `WorkflowTaskResult.structured`. Orthogonal to
2714
+ * `verification` (which checks side-effects, not return shape). Carried as an
2715
+ * opaque value so the agent layer needs no JSON-Schema dependency.
2716
+ */
2717
+ readonly outputSchema?: unknown;
2595
2718
  }
2596
2719
  /** Returned by `spawnAgent` — the child is in-flight, not yet complete. */
2597
2720
  interface WorkflowTaskHandle {
@@ -2615,6 +2738,10 @@ interface WorkflowTaskResult {
2615
2738
  readonly name: string;
2616
2739
  readonly status: WorkflowTaskStatus;
2617
2740
  readonly finalText: string;
2741
+ /** Schema-validated structured result (FEATURE_246 Part B), present when the
2742
+ * spawn carried `outputSchema` and a JSON value was parsed from the child's
2743
+ * output. The workflow script consumes it directly (e.g. `result.structured`). */
2744
+ readonly structured?: unknown;
2618
2745
  /** Short user-facing digest, separate from the full finalText used for synthesis/audit. */
2619
2746
  readonly digest?: string;
2620
2747
  /** True when a digest was attempted but failed (error/timeout/empty); the UI then labels the excerpt fallback. */
@@ -2692,8 +2819,12 @@ interface WorkflowApi {
2692
2819
  phase<T>(name: string, fn: () => Promise<T>): Promise<T>;
2693
2820
  /** Start a child agent; returns immediately with a handle. */
2694
2821
  spawnAgent(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskHandle>;
2695
- /** spawnAgent + wait convenience; returns the terminal result. */
2696
- runAgent(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskResult>;
2822
+ /** spawnAgent + wait convenience; returns the terminal result, or `null` if
2823
+ * the child ended failed/stopped (FEATURE_246 Part E lenient failure — the
2824
+ * harness `agent()` semantics, so scripts can `.filter(Boolean)` instead of
2825
+ * wrapping every call in try/catch). Abort and budget/agent-cap limits still
2826
+ * throw. */
2827
+ runAgent(input: WorkflowSpawnAgentInput): Promise<WorkflowTaskResult | null>;
2697
2828
  /** Await a spawned agent's terminal result. */
2698
2829
  wait(taskId: string, opts?: WorkflowWaitOptions): Promise<WorkflowTaskResult>;
2699
2830
  /** Snapshot a (possibly running) agent. */
@@ -2707,12 +2838,36 @@ interface WorkflowApi {
2707
2838
  stop(taskId: string, reason: string): Promise<void>;
2708
2839
  /** Run lazy thunks concurrently under the concurrency gate. Thunks
2709
2840
  * MUST be `() => Promise<T>` (not already-started promises) so the
2710
- * runtime can bound concurrency. */
2711
- parallel<T>(items: readonly (() => Promise<T>)[], opts?: WorkflowParallelOptions): Promise<T[]>;
2841
+ * runtime can bound concurrency. A thunk that throws (or whose agent fails)
2842
+ * resolves to `null` in the result array — the call itself never rejects, so
2843
+ * `.filter(Boolean)` before use (FEATURE_246 Part E, harness parity). Abort
2844
+ * still tears down the whole run. */
2845
+ parallel<T>(items: readonly (() => Promise<T>)[], opts?: WorkflowParallelOptions): Promise<(T | null)[]>;
2846
+ /**
2847
+ * Stream items through ordered stages with NO barrier between stages: an
2848
+ * item advances to stage N+1 as soon as its own stage N resolves,
2849
+ * independent of other items (wall-clock = slowest single chain, not
2850
+ * sum-of-slowest-per-stage). Each stage receives `(prev, item, index)`
2851
+ * where `prev` is the previous stage's result (the original item at
2852
+ * stage 1). A stage that throws drops that item to `null` and skips its
2853
+ * remaining stages; results preserve input order. Agent spawns inside
2854
+ * stages stay bounded by the workflow `maxConcurrency` gate. Optional:
2855
+ * the restricted-script bootstrap always provides it; SDK consumers get
2856
+ * it from the runtime. */
2857
+ pipeline?(items: readonly unknown[], ...stages: readonly ((prev: unknown, item: unknown, index: number) => unknown)[]): Promise<unknown[]>;
2712
2858
  /** Synthesize across inputs. Runs as a gated agent through the runtime
2713
2859
  * (spawn → wait), so it counts toward maxAgents / concurrency / budget
2714
2860
  * and emits run-graph events — it is NOT a backend side-channel. */
2715
2861
  synthesize(input: WorkflowSynthesizeInput): Promise<WorkflowSynthesis>;
2862
+ /**
2863
+ * Run another saved/built-in workflow inline as a sub-step (FEATURE_246 Part E,
2864
+ * harness parity). Resolves the module by name via the host-injected resolver
2865
+ * and runs it under THIS run's runtime — sharing the same concurrency cap,
2866
+ * agent counter, token budget, and abort signal. **One level only**: calling
2867
+ * `workflow(...)` from inside a nested workflow throws. Returns whatever the
2868
+ * sub-workflow's `run` returns. Optional: present when a resolver is wired
2869
+ * (the restricted-script bootstrap provides it; SDK consumers may omit). */
2870
+ workflow?(name: string, args?: unknown): Promise<unknown>;
2716
2871
  /** Persist a named artifact. */
2717
2872
  artifact(name: string, value: unknown): Promise<WorkflowArtifactRef>;
2718
2873
  /** Emit a free-text progress log event. */
@@ -2788,6 +2943,13 @@ interface WorkflowRunState {
2788
2943
  type WorkflowProcessStatus = 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
2789
2944
  type WorkflowProcessItemStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped';
2790
2945
  type WorkflowProcessItemKind = 'phase' | 'agent' | 'step' | 'artifact';
2946
+ /**
2947
+ * FEATURE_246 resume telemetry — how an agent item came to be in a resumed run.
2948
+ * `ran` = executed live this run; `replayed-from-cache` = returned instantly from
2949
+ * a prior run's content-addressed result cache (resumeFromRunId). Only populated
2950
+ * on resumed runs; absent on a fresh run (treat absent as `ran`).
2951
+ */
2952
+ type WorkflowProcessItemOrigin = 'ran' | 'replayed-from-cache';
2791
2953
  type WorkflowProcessSummaryStatus = 'pending' | 'result' | 'notice' | 'unavailable';
2792
2954
  type WorkflowProcessSource = 'command' | 'amaw' | 'review' | 'sdk' | 'capsule' | 'extension' | 'automation';
2793
2955
  interface WorkflowProcessItem {
@@ -2806,6 +2968,8 @@ interface WorkflowProcessItem {
2806
2968
  readonly summary?: string;
2807
2969
  readonly summaryStatus?: WorkflowProcessSummaryStatus;
2808
2970
  readonly error?: string;
2971
+ /** FEATURE_246 resume telemetry — see {@link WorkflowProcessItemOrigin}. */
2972
+ readonly origin?: WorkflowProcessItemOrigin;
2809
2973
  }
2810
2974
  interface WorkflowEventCorrelation {
2811
2975
  readonly workflowRunId: string;
@@ -2829,6 +2993,10 @@ interface WorkflowProcessProgress {
2829
2993
  readonly stoppedAgents: number;
2830
2994
  readonly agentCap?: number;
2831
2995
  readonly plannedItems?: number;
2996
+ /** FEATURE_246 resume telemetry — count of agents that replayed from a prior
2997
+ * run's cache (origin `replayed-from-cache`). Present only when > 0, so a
2998
+ * fresh run's progress is unchanged. */
2999
+ readonly replayedAgents?: number;
2832
3000
  }
2833
3001
  interface WorkflowProcessTokenUsage {
2834
3002
  readonly spent: number;
@@ -2853,6 +3021,9 @@ interface WorkflowProcessSnapshot {
2853
3021
  readonly sourceRunId?: string;
2854
3022
  readonly sourceWorkflowName?: string;
2855
3023
  readonly revisionOf?: string;
3024
+ /** FEATURE_246 resume telemetry — the prior run this run resumed from
3025
+ * (content-addressed replay). Absent on a fresh (non-resumed) run. */
3026
+ readonly resumedFromRunId?: string;
2856
3027
  readonly hostMetadata?: Record<string, string>;
2857
3028
  readonly activePhaseId?: string;
2858
3029
  readonly activePhaseIndex?: number;
@@ -2887,6 +3058,8 @@ interface WorkflowProcessTrackerOptions {
2887
3058
  readonly sourceRunId?: string;
2888
3059
  readonly sourceWorkflowName?: string;
2889
3060
  readonly revisionOf?: string;
3061
+ /** FEATURE_246 resume telemetry — the prior run this run resumed from. */
3062
+ readonly resumedFromRunId?: string;
2890
3063
  readonly hostMetadata?: Record<string, string>;
2891
3064
  readonly phases?: readonly string[];
2892
3065
  readonly maxAgents?: number;
@@ -2911,5 +3084,5 @@ declare function isFinalWorkflowProcessStatus(status: WorkflowProcessStatus): bo
2911
3084
  declare function normalizeHostMetadata(value: unknown): Record<string, string> | undefined;
2912
3085
  declare function createWorkflowProcessTracker(options: WorkflowProcessTrackerOptions): WorkflowProcessTracker;
2913
3086
 
2914
- export { DEFAULT_SYSTEM_CAP as D, InvariantSession as M, Runner as aC, SpanImpl as aV, MAX_TOOL_LOOP_ITERATIONS as ak, _resetPresetDispatchers as b$, _resetAdmittedAgentBindings as b_, Tracer as bb, WorkflowEventRecorder as bm, buildAssistantMessageFromLlmResult as c0, buildSystemPrompt as c1, buildToolResultMessage as c2, createAgent as c3, createHandoff as c4, createInMemorySession as c5, createInvariantSessionForAgent as c6, createStateWriter as c7, createTrace as c8, createWorkflowProcessTracker as c9, defaultTracer as ca, detectInstructionsInjection as cb, discoverInstances as cc, executeRunnerToolCall as cd, extractAssistantTextFromMessage as ce, getActiveUserInteraction as cf, getAdmittedAgentBindings as cg, isFinalWorkflowProcessStatus as ch, isRunnableTool as ci, isRunnerLlmResult as cj, normalizeHostMetadata as ck, registerChildTask as cl, registerPresetDispatcher as cm, requestTaskStop as cn, runAdmissionAudit as co, setActiveUserInteraction as cp, setAdmittedAgentBindings as cq };
2915
- export type { KodaXSessionData as $, AdmissionAuditOptions as A, HandoffSpanData as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, InMemorySessionOptions as I, InstanceDiscoveryFs as J, InvariantId as K, InvariantResult as L, KodaXCompactMemoryProgress as N, KodaXCompactMemorySeed as O, KodaXExtensionSessionRecord as P, KodaXExtensionSessionState as Q, KodaXExtensionStore as R, KodaXExtensionStoreEntry as S, KodaXGoalEventType as T, KodaXGoalState as U, KodaXGoalStatus as V, KodaXJsonValue as W, KodaXSessionArchiveMarkerEntry as X, KodaXSessionArtifactLedgerEntry as Y, KodaXSessionBranchSummaryEntry as Z, KodaXSessionCompactionEntry as _, AdmissionCtx as a, StopHookContext as a$, KodaXSessionEntry as a0, KodaXSessionEntryBase as a1, KodaXSessionGoalEntry as a2, KodaXSessionLabelEntry as a3, KodaXSessionLineage as a4, KodaXSessionMessageEntry as a5, KodaXSessionMeta as a6, KodaXSessionNavigationOptions as a7, KodaXSessionRuntimeInfo as a8, KodaXSessionScope as a9, RunResult as aA, RunnableTool as aB, RunnerEvent as aD, RunnerLlmResult as aE, RunnerLlmReturn as aF, RunnerToolCall as aG, RunnerToolContext as aH, RunnerToolObserver as aI, RunnerToolResult as aJ, Session as aK, SessionDispatchResult as aL, SessionEntry as aM, SessionErrorMetadata as aN, SessionExtension as aO, SessionForkOptions as aP, SessionMeta as aQ, SessionStateSnapshot as aR, Span as aS, SpanData as aT, SpanError as aU, SpanImplOptions as aW, StartTraceOptions as aX, StateWriter as aY, StateWriterFs as aZ, StateWriterOptions as a_, KodaXSessionStorage as aa, KodaXSessionTreeNode as ab, KodaXSessionUiHistoryItem as ac, KodaXSessionUiHistoryItemType as ad, KodaXSessionUiTextHistoryItem as ae, KodaXSessionUiTextHistoryItemType as af, KodaXSessionUiToolCall as ag, KodaXSessionUiToolCallStatus as ah, KodaXSessionUiToolGroupHistoryItem as ai, KodaXSessionWorkspaceKind as aj, ManifestPatch as al, MessageEntry as am, ObserveCtx as an, PersistedSessionState as ao, PresetDispatcher as ap, PresetTracingContext as aq, QualityInvariant as ar, ReadonlyMutationTracker as as, ReadonlyRecorder as at, ReasoningDepth as au, RecentlyModifiedFile as av, RequestTaskStopOptions as aw, RequestTaskStopResult as ax, RunEvent as ay, RunOptions as az, AdmissionVerdict as b, StopHookFn as b0, StopHookResult as b1, StopHookSpanData as b2, SystemCap as b3, TaskAbortRegistry as b4, TerminalCtx as b5, ToolCallSpanData as b6, ToolCapability as b7, ToolPermission as b8, Trace as b9, WorkflowProcessItemStatus as bA, WorkflowProcessProgress as bB, WorkflowProcessSnapshot as bC, WorkflowProcessSource as bD, WorkflowProcessStatus as bE, WorkflowProcessSummaryStatus as bF, WorkflowProcessTokenUsage as bG, WorkflowProcessTracker as bH, WorkflowProcessTrackerOptions as bI, WorkflowRun as bJ, WorkflowRunState as bK, WorkflowRunStatus as bL, WorkflowSpawnAgentInput as bM, WorkflowSynthesis as bN, WorkflowSynthesizeInput as bO, WorkflowTaskHandle as bP, WorkflowTaskResult as bQ, WorkflowTaskSnapshot as bR, WorkflowTaskStatus as bS, WorkflowTaskSummaryEventUpdate as bT, WorkflowTaskSummaryKind as bU, WorkflowTaskSummaryUpdate as bV, WorkflowTaskUsage as bW, WorkflowTaskVerification as bX, WorkflowTaskVerificationResult as bY, WorkflowWaitOptions as bZ, TraceOptions as ba, TracerOptions as bc, UserInteraction as bd, WorkflowAgentBackend as be, WorkflowApi as bf, WorkflowApproval as bg, WorkflowApprovalSummary as bh, WorkflowArtifactRef as bi, WorkflowBudget as bj, WorkflowEvent as bk, WorkflowEventCorrelation as bl, WorkflowEventType as bn, WorkflowIsolation as bo, WorkflowLimits as bp, WorkflowLogEvent as bq, WorkflowMeta as br, WorkflowModelHint as bs, WorkflowModule as bt, WorkflowParallelOptions as bu, WorkflowProcessArtifact as bv, WorkflowProcessCounts as bw, WorkflowProcessEvent as bx, WorkflowProcessItem as by, WorkflowProcessItemKind as bz, AdmittedHandle as c, Agent as d, AgentManifest as e, AgentMessage as f, AgentMiddlewareDeclaration as g, AgentReasoningProfile as h, AgentSpanData as i, AgentTool as j, AskUserMultiOptions as k, AskUserQuestionItem as l, AskUserQuestionOptions as m, CompactionAnchor as n, CompactionConfig as o, CompactionDetails as p, CompactionResult as q, CompactionSpanData as r, CompactionUpdate as s, CurrentTodoSummary as t, Deliverable as u, DiscoveredInstance as v, DiscoveryOptions as w, FileOperations as x, Guardrail as y, GuardrailSpanData as z };
3087
+ export { ASK_USER_BACK_SIGNAL as A, DEFAULT_SYSTEM_CAP as D, InvariantSession as N, Runner as aK, MAX_TOOL_LOOP_ITERATIONS as as, SpanImpl as b1, Tracer as bj, WorkflowEventRecorder as bu, _resetAdmittedAgentBindings as c7, _resetPresetDispatchers as c8, asSingleSelection as c9, setAdmittedAgentBindings as cA, buildAssistantMessageFromLlmResult as ca, buildSystemPrompt as cb, buildToolResultMessage as cc, createAgent as cd, createHandoff as ce, createInMemorySession as cf, createInvariantSessionForAgent as cg, createStateWriter as ch, createTrace as ci, createWorkflowProcessTracker as cj, defaultTracer as ck, detectInstructionsInjection as cl, discoverInstances as cm, executeRunnerToolCall as cn, extractAssistantTextFromMessage as co, getActiveUserInteraction as cp, getAdmittedAgentBindings as cq, isFinalWorkflowProcessStatus as cr, isRunnableTool as cs, isRunnerLlmResult as ct, normalizeHostMetadata as cu, registerChildTask as cv, registerPresetDispatcher as cw, requestTaskStop as cx, runAdmissionAudit as cy, setActiveUserInteraction as cz };
3088
+ export type { KodaXInputArtifactSource as $, GuardrailSpanData as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, HandoffSpanData as I, InMemorySessionOptions as J, InstanceDiscoveryFs as K, InvariantId as L, InvariantResult as M, KodaXCompactMemoryProgress as O, KodaXCompactMemorySeed as P, KodaXExtensionSessionRecord as Q, KodaXExtensionSessionState as R, KodaXExtensionStore as S, KodaXExtensionStoreEntry as T, KodaXFileInputArtifact as U, KodaXGoalEventType as V, KodaXGoalState as W, KodaXGoalStatus as X, KodaXImageInputArtifact as Y, KodaXImageMediaType as Z, KodaXInputArtifact as _, AdmissionAuditOptions as a, SpanData as a$, KodaXJsonValue as a0, KodaXSessionArchiveMarkerEntry as a1, KodaXSessionArtifactLedgerEntry as a2, KodaXSessionBranchSummaryEntry as a3, KodaXSessionCompactionEntry as a4, KodaXSessionData as a5, KodaXSessionEntry as a6, KodaXSessionEntryBase as a7, KodaXSessionGoalEntry as a8, KodaXSessionLabelEntry as a9, ReadonlyMutationTracker as aA, ReadonlyRecorder as aB, ReasoningDepth as aC, RecentlyModifiedFile as aD, RequestTaskStopOptions as aE, RequestTaskStopResult as aF, RunEvent as aG, RunOptions as aH, RunResult as aI, RunnableTool as aJ, RunnerEvent as aL, RunnerLlmResult as aM, RunnerLlmReturn as aN, RunnerToolCall as aO, RunnerToolContext as aP, RunnerToolObserver as aQ, RunnerToolResult as aR, Session as aS, SessionDispatchResult as aT, SessionEntry as aU, SessionErrorMetadata as aV, SessionExtension as aW, SessionForkOptions as aX, SessionMeta as aY, SessionStateSnapshot as aZ, Span as a_, KodaXSessionLineage as aa, KodaXSessionMessageEntry as ab, KodaXSessionMeta as ac, KodaXSessionNavigationOptions as ad, KodaXSessionRuntimeInfo as ae, KodaXSessionScope as af, KodaXSessionStorage as ag, KodaXSessionTreeNode as ah, KodaXSessionUiHistoryItem as ai, KodaXSessionUiHistoryItemType as aj, KodaXSessionUiTextHistoryItem as ak, KodaXSessionUiTextHistoryItemType as al, KodaXSessionUiToolCall as am, KodaXSessionUiToolCallStatus as an, KodaXSessionUiToolGroupHistoryItem as ao, KodaXSessionWorkspaceKind as ap, KodaXVideoInputArtifact as aq, KodaXVideoMediaType as ar, ManifestPatch as at, MessageEntry as au, ObserveCtx as av, PersistedSessionState as aw, PresetDispatcher as ax, PresetTracingContext as ay, QualityInvariant as az, AdmissionCtx as b, WorkflowTaskStatus as b$, SpanError as b0, SpanImplOptions as b2, StartTraceOptions as b3, StateWriter as b4, StateWriterFs as b5, StateWriterOptions as b6, StopHookContext as b7, StopHookFn as b8, StopHookResult as b9, WorkflowModelHint as bA, WorkflowModule as bB, WorkflowParallelOptions as bC, WorkflowProcessArtifact as bD, WorkflowProcessCounts as bE, WorkflowProcessEvent as bF, WorkflowProcessItem as bG, WorkflowProcessItemKind as bH, WorkflowProcessItemOrigin as bI, WorkflowProcessItemStatus as bJ, WorkflowProcessProgress as bK, WorkflowProcessSnapshot as bL, WorkflowProcessSource as bM, WorkflowProcessStatus as bN, WorkflowProcessSummaryStatus as bO, WorkflowProcessTokenUsage as bP, WorkflowProcessTracker as bQ, WorkflowProcessTrackerOptions as bR, WorkflowRun as bS, WorkflowRunState as bT, WorkflowRunStatus as bU, WorkflowSpawnAgentInput as bV, WorkflowSynthesis as bW, WorkflowSynthesizeInput as bX, WorkflowTaskHandle as bY, WorkflowTaskResult as bZ, WorkflowTaskSnapshot as b_, StopHookSpanData as ba, SystemCap as bb, TaskAbortRegistry as bc, TerminalCtx as bd, ToolCallSpanData as be, ToolCapability as bf, ToolPermission as bg, Trace as bh, TraceOptions as bi, TracerOptions as bk, UserInteraction as bl, WorkflowAgentBackend as bm, WorkflowApi as bn, WorkflowApproval as bo, WorkflowApprovalSummary as bp, WorkflowArtifactRef as bq, WorkflowBudget as br, WorkflowEvent as bs, WorkflowEventCorrelation as bt, WorkflowEventType as bv, WorkflowIsolation as bw, WorkflowLimits as bx, WorkflowLogEvent as by, WorkflowMeta as bz, AdmissionVerdict as c, WorkflowTaskSummaryEventUpdate as c0, WorkflowTaskSummaryKind as c1, WorkflowTaskSummaryUpdate as c2, WorkflowTaskUsage as c3, WorkflowTaskVerification as c4, WorkflowTaskVerificationResult as c5, WorkflowWaitOptions as c6, AdmittedHandle as d, Agent as e, AgentManifest as f, AgentMessage as g, AgentMiddlewareDeclaration as h, AgentReasoningProfile as i, AgentSpanData as j, AgentTool as k, AskUserMultiOptions as l, AskUserQuestionItem as m, AskUserQuestionOptions as n, CompactionAnchor as o, CompactionConfig as p, CompactionDetails as q, CompactionResult as r, CompactionSpanData as s, CompactionUpdate as t, CurrentTodoSummary as u, Deliverable as v, DiscoveredInstance as w, DiscoveryOptions as x, FileOperations as y, Guardrail as z };
@@ -1,6 +1,6 @@
1
- import { E as KodaXReasoningMode, L as KodaXStableEffortIntent, a6 as KodaXWireReasoningEffort, F as KodaXReasoningProfile, W as KodaXThinkingBudgetMap, X as KodaXThinkingDepth, p as KodaXProviderConfig, A as KodaXReasoningCapability, G as KodaXReasoningRequest, m as KodaXNormalizedReasoningRequest, S as KodaXTaskType, a4 as KodaXVerifyCredentialResult, _ as KodaXToolDefinition, j as KodaXMessage, x as KodaXProviderStreamOptions, M as KodaXStreamResult, k as KodaXModelDescriptor, o as KodaXProviderCapabilityProfile, a5 as KodaXVerifyStrategy, d as KodaXCustomProviderConfig, i as KodaXListModelsResult } from './types.d-6VOXvF88.js';
1
+ import { E as KodaXReasoningMode, L as KodaXStableEffortIntent, a6 as KodaXWireReasoningEffort, F as KodaXReasoningProfile, W as KodaXThinkingBudgetMap, X as KodaXThinkingDepth, p as KodaXProviderConfig, A as KodaXReasoningCapability, G as KodaXReasoningRequest, m as KodaXNormalizedReasoningRequest, S as KodaXTaskType, a4 as KodaXVerifyCredentialResult, _ as KodaXToolDefinition, j as KodaXMessage, x as KodaXProviderStreamOptions, M as KodaXStreamResult, k as KodaXModelDescriptor, o as KodaXProviderCapabilityProfile, a5 as KodaXVerifyStrategy, d as KodaXCustomProviderConfig, i as KodaXListModelsResult } from './types.d-Ci5YPFEh.js';
2
2
  import Anthropic from '@anthropic-ai/sdk';
3
- import { K as KodaXBaseProvider } from './base.d-BnjQrSVf.js';
3
+ import { K as KodaXBaseProvider } from './base.d-BA9Doaj_.js';
4
4
  import OpenAI from 'openai';
5
5
 
6
6
  /**
@@ -86,6 +86,60 @@ declare function resolveThinkingBudget(config: KodaXProviderConfig, depth: KodaX
86
86
  declare function clampThinkingBudget(requestedBudget: number, maxOutputTokens: number, safetyReserve?: number): number;
87
87
  declare function mapDepthToOpenAIReasoningEffort(depth: KodaXThinkingDepth): 'low' | 'medium' | 'high' | undefined;
88
88
 
89
+ /**
90
+ * FEATURE_222 (R6) — canonical host-facing reasoning-effort resolver.
91
+ *
92
+ * Mapping a user's desired reasoning strength to the actual wire `effort` value
93
+ * for a provider/model means composing several pieces that already exist but
94
+ * were only wired together privately inside the REPL: the model's reasoning
95
+ * profile (`resolveModelCapabilities`), the learned hard-rejection cache
96
+ * (`narrowReasoningProfile`), and the alias/disabled/ceiling/default resolution
97
+ * (`resolveReasoningEffort`). A host that re-assembles these by hand drifts.
98
+ *
99
+ * `resolveWireEffort` is the single entry point: give it a provider/model + the
100
+ * desired effort (+ any learned rejected efforts) and it returns the legal wire
101
+ * effort — or `undefined`, which is a deliberate "omit reasoning_effort" signal
102
+ * (e.g. anthropic-adaptive, or a provider with no reasoning). It reuses the
103
+ * existing pure functions verbatim; no new resolution logic.
104
+ */
105
+ interface ResolveWireEffortInput {
106
+ /** Provider id (built-in alias or registered custom provider name). */
107
+ readonly provider: string;
108
+ /** Model id. Omit to use the provider's default model. */
109
+ readonly model?: string;
110
+ /** The desired reasoning strength (a wire effort or tier the user requested).
111
+ * Treated as a non-explicit session preference: an unsupported value falls
112
+ * back to a legal one rather than throwing. */
113
+ readonly desiredEffort?: string;
114
+ /** Learned hard-rejected efforts for this provider/model (e.g. from the agent
115
+ * layer's `getCachedRejectedEfforts`). Removed from the ladder before
116
+ * resolving, so a rejected rung is never re-selected. */
117
+ readonly rejectedEfforts?: readonly string[];
118
+ }
119
+ interface ResolvedWireEffort {
120
+ /** The legal wire effort to send, or `undefined` to omit reasoning_effort
121
+ * entirely (adaptive/none — NOT a fallback to `configuredEffort`). */
122
+ readonly effort: string | undefined;
123
+ /** What the input resolved to before profile-driven adjustment (alias/
124
+ * ceiling/disable). Useful for a "requested X → sending Y" status label. */
125
+ readonly configuredEffort: string | undefined;
126
+ /**
127
+ * True when the wire effort differs from the configured one — aliased, ceiled,
128
+ * disabled-folded, or narrowed by a rejection. NOTE: this is also true for a
129
+ * plain `desiredEffort: 'auto'` (configuredEffort `'auto'` resolves to a
130
+ * concrete rung), so do NOT read `adjusted` as "the user's explicit choice was
131
+ * overridden"; compare `configuredEffort` vs `effort` yourself if you need to
132
+ * exclude the auto→concrete case in a status label.
133
+ */
134
+ readonly adjusted: boolean;
135
+ }
136
+ /**
137
+ * Resolve the wire-level reasoning effort for a provider/model + desired
138
+ * strength, honoring alias/disabled/ceiling/default rules and learned
139
+ * rejections. Pure — no I/O, no throw.
140
+ */
141
+ declare function resolveWireEffort(input: ResolveWireEffortInput): ResolvedWireEffort;
142
+
89
143
  /**
90
144
  * KodaX Anthropic Compatible Provider
91
145
  *
@@ -141,6 +195,14 @@ declare abstract class KodaXAnthropicCompatProvider extends KodaXBaseProvider {
141
195
  * original string unchanged so prompt caching can be disabled at
142
196
  * runtime without redeploying.
143
197
  */
198
+ /**
199
+ * Run-scoped (concurrency-safe) config wins over the global env, in BOTH
200
+ * directions: an SDK caller that explicitly sets `disablePromptCache: false`
201
+ * re-enables caching even when `KODAX_DISABLE_PROMPT_CACHE=1` is set at
202
+ * startup (e.g. bridged from `config.json`). A plain `||` would let the env
203
+ * win in that re-enable case, breaking the documented SDK > env precedence.
204
+ */
205
+ private isPromptCacheDisabled;
144
206
  protected applyCacheControlToSystem(systemText: string): string | Anthropic.Messages.TextBlockParam[];
145
207
  /**
146
208
  * FEATURE_116 (v0.7.37) — Mark the last tool definition as the cache
@@ -151,6 +213,27 @@ declare abstract class KodaXAnthropicCompatProvider extends KodaXBaseProvider {
151
213
  * Returns a new array; never mutates input.
152
214
  */
153
215
  protected applyCacheControlToTools(tools: KodaXToolDefinition[]): Anthropic.Messages.Tool[];
216
+ /**
217
+ * FEATURE_116 follow-up — Place an incremental cache breakpoint on the
218
+ * conversation history (Anthropic breakpoint 3). The system prompt and
219
+ * tools already carry breakpoints 1 & 2 (applyCacheControlToSystem /
220
+ * applyCacheControlToTools); without a message-level breakpoint the whole
221
+ * growing transcript is re-billed as uncached input every turn.
222
+ *
223
+ * Strategy: mark the LAST content block of the second-to-last `user` turn.
224
+ * The most recent user turn is skipped — it is the current, still-changing
225
+ * input. The prior user turn's content is settled, so its prefix is a stable
226
+ * cache write-point that later turns read back incrementally (Anthropic caches
227
+ * the whole prefix up to and including the marked block: tools + system + all
228
+ * earlier messages). Total breakpoints stay at 3 (≤ Anthropic's limit of 4).
229
+ *
230
+ * Only anthropic-compat providers reach this path; OpenAI/ACP strip cache
231
+ * markers and rely on upstream automatic prefix caching. Escape hatch:
232
+ * `KODAX_DISABLE_PROMPT_CACHE=1` returns the array untouched.
233
+ *
234
+ * Returns a new array; never mutates input.
235
+ */
236
+ protected applyCacheControlToMessages(messages: Anthropic.Messages.MessageParam[]): Anthropic.Messages.MessageParam[];
154
237
  stream(messages: KodaXMessage[], tools: KodaXToolDefinition[], system: string, reasoning?: boolean | KodaXReasoningRequest, streamOptions?: KodaXProviderStreamOptions, signal?: AbortSignal): Promise<KodaXStreamResult>;
155
238
  supportsNonStreamingFallback(): boolean;
156
239
  complete(messages: KodaXMessage[], tools: KodaXToolDefinition[], system: string, reasoning?: boolean | KodaXReasoningRequest, streamOptions?: KodaXProviderStreamOptions, signal?: AbortSignal): Promise<KodaXStreamResult>;
@@ -565,5 +648,5 @@ declare function listProviderModels(name: string, _opts?: {
565
648
  signal?: AbortSignal;
566
649
  }): Promise<KodaXListModelsResult>;
567
650
 
568
- export { parseReasoningEffortEnv as $, getModelCapabilities as A, getProvider as B, getProviderConfiguredCapabilityProfile as C, getProviderConfiguredReasoningCapability as D, getProviderList as E, getProviderModel as F, getProviderModelDescriptors as G, getProviderModels as H, getReasoningCapability as I, getRuntimeModelProvider as J, KODAX_DEFAULT_PROVIDER as K, getRuntimeModelProviderNames as L, isCustomProviderName as M, isKnownProvider as N, isProviderConfigured as O, isProviderName as Q, isReasoningEnabled as R, isRuntimeModelProviderName as S, listAllModelCapabilities as T, listBuiltinModelCapabilities as U, listCustomProviderModelCapabilities as V, listProviderModels as W, mapDepthToOpenAIReasoningEffort as X, mapLegacyReasoningModeToEffortIntent as Y, normalizeReasoningEffortValue as Z, normalizeReasoningRequest as _, KODAX_DEFAULT_THINKING_BUDGETS as a, registerCustomProviders as a0, registerModelProvider as a1, resolveModelCapabilities as a2, resolveProvider as a3, resolveProviderModelDescriptors as a4, resolveReasoningEffort as a5, resolveReasoningEffortForModelSwitch as a6, resolveThinkingBudget as a7, validateCustomProviderConfig as a8, verifyProviderCredential as a9, KODAX_PROVIDERS as b, KODAX_PROVIDER_SNAPSHOTS as c, KODAX_REASONING_MODE_SEQUENCE as d, KODAX_REASONING_SAFETY_RESERVE as e, KODAX_STABLE_EFFORT_INTENTS as f, KodaXAnthropicCompatProvider as g, KodaXError as h, KodaXNetworkError as j, KodaXOpenAICompatProvider as k, KodaXProviderError as l, KodaXRateLimitError as m, KodaXToolCallIdError as n, clampThinkingBudget as o, clearRuntimeModelProviders as p, createCustomProvider as q, effortToLegacyReasoningMode as r, getAvailableProviderNames as s, getCustomModelCapabilities as t, getCustomProvider as u, getCustomProviderList as v, getCustomProviderModelDescriptors as w, getCustomProviderModels as x, getCustomProviderNames as y, getDefaultThinkingDepthForMode as z };
569
- export type { ProviderName as P, KodaXModelCapabilities as i };
651
+ export { normalizeReasoningEffortValue as $, getDefaultThinkingDepthForMode as A, getModelCapabilities as B, getProvider as C, getProviderConfiguredCapabilityProfile as D, getProviderConfiguredReasoningCapability as E, getProviderList as F, getProviderModel as G, getProviderModelDescriptors as H, getProviderModels as I, getReasoningCapability as J, KODAX_DEFAULT_PROVIDER as K, getRuntimeModelProvider as L, getRuntimeModelProviderNames as M, isCustomProviderName as N, isKnownProvider as O, isProviderConfigured as Q, isProviderName as S, isReasoningEnabled as T, isRuntimeModelProviderName as U, listAllModelCapabilities as V, listBuiltinModelCapabilities as W, listCustomProviderModelCapabilities as X, listProviderModels as Y, mapDepthToOpenAIReasoningEffort as Z, mapLegacyReasoningModeToEffortIntent as _, KODAX_DEFAULT_THINKING_BUDGETS as a, normalizeReasoningRequest as a0, parseReasoningEffortEnv as a1, registerCustomProviders as a2, registerModelProvider as a3, resolveModelCapabilities as a4, resolveProvider as a5, resolveProviderModelDescriptors as a6, resolveReasoningEffort as a7, resolveReasoningEffortForModelSwitch as a8, resolveThinkingBudget as a9, resolveWireEffort as aa, validateCustomProviderConfig as ab, verifyProviderCredential as ac, KODAX_PROVIDERS as b, KODAX_PROVIDER_SNAPSHOTS as c, KODAX_REASONING_MODE_SEQUENCE as d, KODAX_REASONING_SAFETY_RESERVE as e, KODAX_STABLE_EFFORT_INTENTS as f, KodaXAnthropicCompatProvider as g, KodaXError as h, KodaXNetworkError as j, KodaXOpenAICompatProvider as k, KodaXProviderError as l, KodaXRateLimitError as m, KodaXToolCallIdError as n, clampThinkingBudget as p, clearRuntimeModelProviders as q, createCustomProvider as r, effortToLegacyReasoningMode as s, getAvailableProviderNames as t, getCustomModelCapabilities as u, getCustomProvider as v, getCustomProviderList as w, getCustomProviderModelDescriptors as x, getCustomProviderModels as y, getCustomProviderNames as z };
652
+ export type { ProviderName as P, ResolveWireEffortInput as R, KodaXModelCapabilities as i, ResolvedWireEffort as o };