@kodax-ai/kodax 0.7.57 → 0.7.58

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 (74) hide show
  1. package/CHANGELOG.md +2004 -1920
  2. package/README.md +31 -25
  3. package/README_CN.md +22 -15
  4. package/dist/chunks/agent-YJNC2755.js +2 -0
  5. package/dist/chunks/argument-completer-QGBNXTYJ.js +2 -0
  6. package/dist/chunks/chunk-526OILYL.js +2 -0
  7. package/dist/chunks/{chunk-LZKGOR2C.js → chunk-6AU6EPO6.js} +1 -1
  8. package/dist/chunks/chunk-73Z7BK5H.js +15 -0
  9. package/dist/chunks/chunk-7QB55SYG.js +326 -0
  10. package/dist/chunks/chunk-CQ6EQG7E.js +322 -0
  11. package/dist/chunks/{chunk-4SHP3M67.js → chunk-CV6JHPEO.js} +1 -1
  12. package/dist/chunks/chunk-D6QVXQNI.js +1 -0
  13. package/dist/chunks/chunk-HS2K74I4.js +31 -0
  14. package/dist/chunks/chunk-NKHXRN7G.js +403 -0
  15. package/dist/chunks/chunk-OBPB5BQ6.js +310 -0
  16. package/dist/chunks/chunk-P4VF3JEP.js +7 -0
  17. package/dist/chunks/chunk-PIQWODWN.js +18 -0
  18. package/dist/chunks/{chunk-YSVPF6SN.js → chunk-QHWXPJEG.js} +268 -264
  19. package/dist/chunks/chunk-XXEIFNBE.js +52 -0
  20. package/dist/chunks/chunk-ZZDC75H4.js +681 -0
  21. package/dist/chunks/compaction-config-OPMRZSAK.js +2 -0
  22. package/dist/chunks/{construction-bootstrap-55B7Q5RX.js → construction-bootstrap-CIXFH5SE.js} +1 -1
  23. package/dist/chunks/dist-JSE7NICF.js +2 -0
  24. package/dist/chunks/dist-SDNQOW52.js +2 -0
  25. package/dist/chunks/host-H7FQMMRC.js +2 -0
  26. package/dist/chunks/paste-Y4DVUWSM.js +2 -0
  27. package/dist/chunks/run-manager-4H5HWMVW.js +2 -0
  28. package/dist/chunks/utils-FLVVQHM7.js +2 -0
  29. package/dist/index.d.ts +14 -14
  30. package/dist/index.js +2 -2
  31. package/dist/kodax_cli.js +1206 -1036
  32. package/dist/sdk-agent.d.ts +153 -12
  33. package/dist/sdk-agent.js +1 -1
  34. package/dist/sdk-coding.d.ts +186 -186
  35. package/dist/sdk-coding.js +1 -1
  36. package/dist/sdk-llm.d.ts +66 -43
  37. package/dist/sdk-llm.js +1 -1
  38. package/dist/sdk-mcp.js +1 -1
  39. package/dist/sdk-media.d.ts +18 -2
  40. package/dist/sdk-media.js +1 -1
  41. package/dist/sdk-repl.d.ts +20 -22
  42. package/dist/sdk-repl.js +2 -2
  43. package/dist/sdk-session.d.ts +7 -7
  44. package/dist/sdk-session.js +1 -1
  45. package/dist/sdk-skills.js +1 -1
  46. package/dist/types-chunks/{base.d-BnjQrSVf.d.ts → base.d-BA9Doaj_.d.ts} +3 -3
  47. package/dist/types-chunks/{bash-prefix-extractor.d-BgvMbfq6.d.ts → bash-prefix-extractor.d-D3cddmyV.d.ts} +490 -69
  48. package/dist/types-chunks/capability-learning.d-DRV80ISB.d.ts +29 -0
  49. package/dist/types-chunks/{cost-tracker.d-wRtyEW9d.d.ts → cost-tracker.d-CBLk1fiD.d.ts} +24 -2
  50. package/dist/types-chunks/{guardrail.d-C1DhxnvC.d.ts → guardrail.d-iK7FwMdW.d.ts} +4 -4
  51. package/dist/types-chunks/{process.d-BZncyzEj.d.ts → process.d-DHow2y2G.d.ts} +169 -14
  52. package/dist/types-chunks/{resolver.d-ZvKQgl0X.d.ts → resolver.d-DDOfVYDr.d.ts} +31 -2
  53. package/dist/types-chunks/{capsule.d-DwJp5r63.d.ts → run-manager.d-ByDcJc5g.d.ts} +113 -5
  54. package/dist/types-chunks/{sdk-session-DAScB0rW.d.ts → sdk-session-21Tt3N_x.d.ts} +72 -9
  55. package/dist/types-chunks/{storage.d-CPvn9qI0.d.ts → storage.d-BsZrBPYu.d.ts} +2 -2
  56. package/dist/types-chunks/{types.d-6VOXvF88.d.ts → types.d-Ci5YPFEh.d.ts} +39 -5
  57. package/dist/types-chunks/{guardrail.d-BP3yyr6u.d.ts → types.d-D4ZA8LJV.d.ts} +125 -3
  58. package/dist/types-chunks/{utils.d-CpgVIjYZ.d.ts → utils.d-BURxOxFd.d.ts} +83 -6
  59. package/package.json +2 -2
  60. package/dist/chunks/agent-EHWQZA4C.js +0 -2
  61. package/dist/chunks/argument-completer-AYDAYGKL.js +0 -2
  62. package/dist/chunks/chunk-3WWPJGPQ.js +0 -2
  63. package/dist/chunks/chunk-KN6IJMTB.js +0 -636
  64. package/dist/chunks/chunk-MJFPFRGK.js +0 -423
  65. package/dist/chunks/chunk-N2N2W3AQ.js +0 -584
  66. package/dist/chunks/chunk-PCPFLPS4.js +0 -5
  67. package/dist/chunks/chunk-TCLSPUTR.js +0 -31
  68. package/dist/chunks/chunk-VACH6QWN.js +0 -315
  69. package/dist/chunks/compaction-config-TLDMFMZO.js +0 -2
  70. package/dist/chunks/dist-IE4HVWP7.js +0 -2
  71. package/dist/chunks/dist-IKOK2MJQ.js +0 -2
  72. package/dist/chunks/paste-WTL2XN7P.js +0 -2
  73. package/dist/chunks/utils-EJ2VCRTC.js +0 -2
  74. 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-DHow2y2G.js';
5
+ import { g as ToolGuardrail } from './types.d-D4ZA8LJV.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
  *
@@ -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. */
@@ -2911,5 +3066,5 @@ declare function isFinalWorkflowProcessStatus(status: WorkflowProcessStatus): bo
2911
3066
  declare function normalizeHostMetadata(value: unknown): Record<string, string> | undefined;
2912
3067
  declare function createWorkflowProcessTracker(options: WorkflowProcessTrackerOptions): WorkflowProcessTracker;
2913
3068
 
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 };
3069
+ 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 c6, _resetPresetDispatchers as c7, asSingleSelection as c8, buildAssistantMessageFromLlmResult as c9, buildSystemPrompt as ca, buildToolResultMessage as cb, createAgent as cc, createHandoff as cd, createInMemorySession as ce, createInvariantSessionForAgent as cf, createStateWriter as cg, createTrace as ch, createWorkflowProcessTracker as ci, defaultTracer as cj, detectInstructionsInjection as ck, discoverInstances as cl, executeRunnerToolCall as cm, extractAssistantTextFromMessage as cn, getActiveUserInteraction as co, getAdmittedAgentBindings as cp, isFinalWorkflowProcessStatus as cq, isRunnableTool as cr, isRunnerLlmResult as cs, normalizeHostMetadata as ct, registerChildTask as cu, registerPresetDispatcher as cv, requestTaskStop as cw, runAdmissionAudit as cx, setActiveUserInteraction as cy, setAdmittedAgentBindings as cz };
3070
+ 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, WorkflowTaskSummaryEventUpdate 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, WorkflowProcessItemStatus as bI, WorkflowProcessProgress as bJ, WorkflowProcessSnapshot as bK, WorkflowProcessSource as bL, WorkflowProcessStatus as bM, WorkflowProcessSummaryStatus as bN, WorkflowProcessTokenUsage as bO, WorkflowProcessTracker as bP, WorkflowProcessTrackerOptions as bQ, WorkflowRun as bR, WorkflowRunState as bS, WorkflowRunStatus as bT, WorkflowSpawnAgentInput as bU, WorkflowSynthesis as bV, WorkflowSynthesizeInput as bW, WorkflowTaskHandle as bX, WorkflowTaskResult as bY, WorkflowTaskSnapshot as bZ, WorkflowTaskStatus 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, WorkflowTaskSummaryKind as c0, WorkflowTaskSummaryUpdate as c1, WorkflowTaskUsage as c2, WorkflowTaskVerification as c3, WorkflowTaskVerificationResult as c4, WorkflowWaitOptions as c5, 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
  /**
@@ -141,6 +141,14 @@ declare abstract class KodaXAnthropicCompatProvider extends KodaXBaseProvider {
141
141
  * original string unchanged so prompt caching can be disabled at
142
142
  * runtime without redeploying.
143
143
  */
144
+ /**
145
+ * Run-scoped (concurrency-safe) config wins over the global env, in BOTH
146
+ * directions: an SDK caller that explicitly sets `disablePromptCache: false`
147
+ * re-enables caching even when `KODAX_DISABLE_PROMPT_CACHE=1` is set at
148
+ * startup (e.g. bridged from `config.json`). A plain `||` would let the env
149
+ * win in that re-enable case, breaking the documented SDK > env precedence.
150
+ */
151
+ private isPromptCacheDisabled;
144
152
  protected applyCacheControlToSystem(systemText: string): string | Anthropic.Messages.TextBlockParam[];
145
153
  /**
146
154
  * FEATURE_116 (v0.7.37) — Mark the last tool definition as the cache
@@ -151,6 +159,27 @@ declare abstract class KodaXAnthropicCompatProvider extends KodaXBaseProvider {
151
159
  * Returns a new array; never mutates input.
152
160
  */
153
161
  protected applyCacheControlToTools(tools: KodaXToolDefinition[]): Anthropic.Messages.Tool[];
162
+ /**
163
+ * FEATURE_116 follow-up — Place an incremental cache breakpoint on the
164
+ * conversation history (Anthropic breakpoint 3). The system prompt and
165
+ * tools already carry breakpoints 1 & 2 (applyCacheControlToSystem /
166
+ * applyCacheControlToTools); without a message-level breakpoint the whole
167
+ * growing transcript is re-billed as uncached input every turn.
168
+ *
169
+ * Strategy: mark the LAST content block of the second-to-last `user` turn.
170
+ * The most recent user turn is skipped — it is the current, still-changing
171
+ * input. The prior user turn's content is settled, so its prefix is a stable
172
+ * cache write-point that later turns read back incrementally (Anthropic caches
173
+ * the whole prefix up to and including the marked block: tools + system + all
174
+ * earlier messages). Total breakpoints stay at 3 (≤ Anthropic's limit of 4).
175
+ *
176
+ * Only anthropic-compat providers reach this path; OpenAI/ACP strip cache
177
+ * markers and rely on upstream automatic prefix caching. Escape hatch:
178
+ * `KODAX_DISABLE_PROMPT_CACHE=1` returns the array untouched.
179
+ *
180
+ * Returns a new array; never mutates input.
181
+ */
182
+ protected applyCacheControlToMessages(messages: Anthropic.Messages.MessageParam[]): Anthropic.Messages.MessageParam[];
154
183
  stream(messages: KodaXMessage[], tools: KodaXToolDefinition[], system: string, reasoning?: boolean | KodaXReasoningRequest, streamOptions?: KodaXProviderStreamOptions, signal?: AbortSignal): Promise<KodaXStreamResult>;
155
184
  supportsNonStreamingFallback(): boolean;
156
185
  complete(messages: KodaXMessage[], tools: KodaXToolDefinition[], system: string, reasoning?: boolean | KodaXReasoningRequest, streamOptions?: KodaXProviderStreamOptions, signal?: AbortSignal): Promise<KodaXStreamResult>;
@@ -1,6 +1,6 @@
1
- import { j as KodaXMessage } from './types.d-6VOXvF88.js';
2
- import { Q as QueueEventListener, c as QueuedMessage, E as EnqueueInput, D as DequeueFilter } from './types.d-D8WcfrOD.js';
3
- import { f as AgentMessage, aM as SessionEntry, aK as Session, aO as SessionExtension, a4 as KodaXSessionLineage, W as KodaXJsonValue, p as CompactionDetails, O as KodaXCompactMemorySeed, a0 as KodaXSessionEntry, ab as KodaXSessionTreeNode, a3 as KodaXSessionLabelEntry, a2 as KodaXSessionGoalEntry, a7 as KodaXSessionNavigationOptions, Y as KodaXSessionArtifactLedgerEntry, x as FileOperations, br as WorkflowMeta, bs as WorkflowModelHint, bt as WorkflowModule } from './process.d-BZncyzEj.js';
1
+ import { j as KodaXMessage } from './types.d-Ci5YPFEh.js';
2
+ import { Q as QueueEventListener, f as QueuedMessage, E as EnqueueInput, D as DequeueFilter } from './types.d-D4ZA8LJV.js';
3
+ import { g as AgentMessage, aU as SessionEntry, aS as Session, aW as SessionExtension, aa as KodaXSessionLineage, a0 as KodaXJsonValue, q as CompactionDetails, P as KodaXCompactMemorySeed, a6 as KodaXSessionEntry, ah as KodaXSessionTreeNode, a9 as KodaXSessionLabelEntry, a8 as KodaXSessionGoalEntry, ad as KodaXSessionNavigationOptions, a2 as KodaXSessionArtifactLedgerEntry, y as FileOperations, bz as WorkflowMeta, bA as WorkflowModelHint, bB as WorkflowModule, bQ as WorkflowProcessTrackerOptions, bs as WorkflowEvent, bK as WorkflowProcessSnapshot, bF as WorkflowProcessEvent } from './process.d-DHow2y2G.js';
4
4
 
5
5
  /**
6
6
  * @kodax-ai/agent Constants
@@ -758,6 +758,13 @@ declare const WORKFLOW_CAPSULE_API_VERSION: 1;
758
758
  type WorkflowCapsuleEnvironmentRequirement = 'git-repo' | 'worktree-capable';
759
759
  interface WorkflowCapsuleIntent {
760
760
  readonly taskClass: string;
761
+ /**
762
+ * The full set of workflow patterns the script declares (manifest.patterns).
763
+ * `taskClass` keeps only the primary pattern; this records the whole
764
+ * combination so a declared ['fan-out-and-synthesize', 'adversarial-verification']
765
+ * is preserved rather than collapsed to its first id.
766
+ */
767
+ readonly patterns?: readonly string[];
761
768
  readonly originalRequest?: string;
762
769
  readonly reusableFor?: readonly string[];
763
770
  readonly notFor?: readonly string[];
@@ -806,6 +813,107 @@ interface CreateWorkflowCapsuleInput {
806
813
  declare function validateWorkflowCapsule(value: unknown): WorkflowCapsule;
807
814
  declare function createWorkflowCapsule(input: CreateWorkflowCapsuleInput): WorkflowCapsule;
808
815
  declare function createWorkflowModuleFromCapsule(capsule: WorkflowCapsule): WorkflowModule;
816
+ /**
817
+ * Single source of truth for deriving a capsule intent from a workflow manifest.
818
+ * `taskClass` keeps the primary pattern; the full declared set is recorded on
819
+ * `patterns` so a combination like ['fan-out-and-synthesize',
820
+ * 'adversarial-verification'] is preserved rather than collapsed to its first id
821
+ * (M15). Used by every capsule-save path so the propagation logic is tested once.
822
+ */
823
+ declare function buildWorkflowCapsuleIntent(manifest: {
824
+ readonly patterns: readonly string[];
825
+ readonly name: string;
826
+ readonly description: string;
827
+ }, opts?: {
828
+ readonly originalRequest?: string;
829
+ }): WorkflowCapsuleIntent;
830
+
831
+ /**
832
+ * FEATURE_246 Part A0 (ADR-046) — neutral workflow run lifecycle manager.
833
+ *
834
+ * Domain-neutral run registry + lifecycle (pause / resume / stop), process-event
835
+ * tracking, and terminal settle — lifted out of `@kodax-ai/coding` so any agent
836
+ * (including non-coding SDK hosts) can host and manage workflow runs.
837
+ *
838
+ * It never knows HOW a run executes: the caller injects a `runFn` thunk that
839
+ * receives lifecycle hooks (`onEvent` / `signal` / `beforeSpawn`) and returns a
840
+ * caller-shaped outcome, plus a `classify` mapping that outcome to a neutral
841
+ * terminal status and an `onError` that synthesizes a failure outcome. The
842
+ * coding layer wires `runFn` to its `runWorkflowModule` / `runWorkflowFromOptions`
843
+ * (backend + run-graph + worktrees); SDK hosts wire their own. Dependency arrows
844
+ * therefore point only coding → agent — no cycle.
845
+ */
846
+
847
+ type ManagedWorkflowStatus = 'running' | 'paused' | 'completed' | 'failed' | 'denied' | 'stopped';
848
+ /** Provenance/display metadata for a run's process tracker. */
849
+ type WorkflowProcessMetadata = Pick<WorkflowProcessTrackerOptions, 'displayName' | 'goal' | 'source' | 'savedWorkflowName' | 'sourceRunId' | 'sourceWorkflowName' | 'revisionOf' | 'hostMetadata'>;
850
+ interface ManagedWorkflowSnapshot {
851
+ readonly runId: string;
852
+ readonly workflow: string;
853
+ readonly status: ManagedWorkflowStatus;
854
+ readonly totalSpawned: number;
855
+ readonly eventCount: number;
856
+ readonly startedAt: number;
857
+ readonly endedAt?: number;
858
+ readonly error?: string;
859
+ readonly resultText?: string;
860
+ }
861
+ interface ManagedWorkflowRun<TOutcome = unknown> {
862
+ readonly runId: string;
863
+ readonly done: Promise<TOutcome>;
864
+ getSnapshot(): ManagedWorkflowSnapshot | undefined;
865
+ getProcessSnapshot(): WorkflowProcessSnapshot | undefined;
866
+ }
867
+ /** Lifecycle hooks the manager injects into the caller's `runFn`. */
868
+ interface ManagedRunHooks {
869
+ /** Forward every workflow event so the manager can track spawn/progress. */
870
+ readonly onEvent: (event: WorkflowEvent) => void;
871
+ /** Abort signal owned by the manager (fires on stop()). */
872
+ readonly signal: AbortSignal;
873
+ /** Await before launching each agent so pause() can gate new spawns. */
874
+ readonly beforeSpawn: () => Promise<void>;
875
+ }
876
+ /** Neutral terminal classification of a caller-shaped outcome. */
877
+ interface ManagedRunClassification {
878
+ readonly status: 'completed' | 'failed' | 'denied';
879
+ readonly error?: Error;
880
+ readonly resultText?: string;
881
+ }
882
+ interface StartManagedRunInput<TOutcome> {
883
+ readonly runId: string;
884
+ /** Display name (usually the workflow's `meta.name`). */
885
+ readonly workflow: string;
886
+ readonly phases?: readonly string[];
887
+ readonly maxAgents?: number;
888
+ readonly plannedAgents?: number;
889
+ readonly tokenBudget?: number;
890
+ readonly processMetadata?: WorkflowProcessMetadata;
891
+ readonly signal?: AbortSignal;
892
+ /** Executes the run with the manager's lifecycle hooks injected. */
893
+ readonly runFn: (hooks: ManagedRunHooks) => Promise<TOutcome>;
894
+ /** Map the caller's terminal outcome to a neutral status for the snapshot. */
895
+ readonly classify: (outcome: TOutcome) => ManagedRunClassification;
896
+ /** Synthesize a caller-shaped outcome when `runFn` throws. */
897
+ readonly onError: (error: unknown) => TOutcome;
898
+ }
899
+ interface WorkflowRunManager {
900
+ start<TOutcome>(input: StartManagedRunInput<TOutcome>): ManagedWorkflowRun<TOutcome>;
901
+ list(): readonly ManagedWorkflowSnapshot[];
902
+ get(runId: string): ManagedWorkflowSnapshot | undefined;
903
+ subscribeWorkflowProcess(listener: (event: WorkflowProcessEvent) => void): () => void;
904
+ getWorkflowProcessSnapshot(runId: string): WorkflowProcessSnapshot | undefined;
905
+ listWorkflowProcessSnapshots(options?: {
906
+ readonly activeOnly?: boolean;
907
+ readonly limit?: number;
908
+ }): readonly WorkflowProcessSnapshot[];
909
+ pause(runId: string): boolean;
910
+ resume(runId: string): boolean;
911
+ stop(runId: string, reason?: string): boolean;
912
+ }
913
+ declare function createWorkflowRunManager(deps?: {
914
+ readonly now?: () => number;
915
+ }): WorkflowRunManager;
916
+ declare function getDefaultWorkflowRunManager(): WorkflowRunManager;
809
917
 
810
- export { extractFileOps as $, DefaultSummaryCompaction as D, appendSessionLineageLabel as I, applyLineageTruncation as J, KODAX_API_MIN_INTERVAL as K, LINEAGE_ENTRY_TYPES as L, MessageQueue as M, applySessionCompaction as N, archiveOldIslands as O, PROMISE_PATTERN as P, buildSessionTree as Q, cleanupIncompleteToolCalls as R, countActiveLineageMessages as S, countTokens as T, createSessionLineage as U, createWorkflowCapsule as V, WORKFLOW_CAPSULE_API_VERSION as W, createWorkflowModuleFromCapsule as X, estimateTokens as Y, extractArtifactLedger as Z, _resetMessageQueueForTests as _, extractTitleFromMessages as a0, findPreviousUserEntryId as a1, forkSessionLineage as a2, generateSessionId as a3, getAgentConfigHome as a4, getAgentConfigPath as a5, getAppDataDir as a6, getMessageQueue as a7, getSessionLineagePath as a8, getSessionMessagesFromLineage as a9, mergeArtifactLedger as aa, mergeFileOps as ab, resolveSessionLineageTarget as ac, rewindSessionLineage as ad, setAgentConfigHome as ae, setSessionLineageActiveEntry as af, validateAndFixToolHistory as ag, validateWorkflowCapsule as ah, validateWorkflowScriptManifest as ai, KODAX_DEFAULT_TIMEOUT as f, KODAX_HARD_TIMEOUT as g, KODAX_MAX_INCOMPLETE_RETRIES as h, KODAX_MAX_MAXTOKENS_RETRIES as i, KODAX_MAX_RETRIES as j, KODAX_MAX_TOKENS as k, KODAX_RETRY_BASE_DELAY as l, KODAX_STAGGER_DELAY as m, LineageCompaction as o, LineageExtension as r, WORKFLOW_CAPSULE_FORMAT as v, WORKFLOW_CAPSULE_VERSION as w, WORKFLOW_PATTERN_IDS as x };
811
- export type { WorkflowCapsuleInputs as A, WorkflowCapsuleIntent as B, CompactionContext as C, WorkflowCapsuleProvenance as E, WorkflowCapsuleRequirements as F, WorkflowPatternId as G, WorkflowScriptManifest as H, CompactionEntry as a, CompactionEntryPayload as b, CompactionPolicy as c, CreateWorkflowCapsuleInput as d, DefaultSummaryCompactionOptions as e, LineageArtifactLedgerPayload as n, LineageCompactionDelegates as p, LineageEntryType as q, LineageLabelPayload as s, LineageTreeNode as t, PolicyCompactionResult as u, WorkflowCapsule as y, WorkflowCapsuleEnvironmentRequirement as z };
918
+ export { buildWorkflowCapsuleIntent as $, WORKFLOW_CAPSULE_FORMAT as A, WORKFLOW_CAPSULE_VERSION as B, DefaultSummaryCompaction as D, WORKFLOW_PATTERN_IDS as E, KODAX_API_MIN_INTERVAL as K, LINEAGE_ENTRY_TYPES as L, PROMISE_PATTERN as P, appendSessionLineageLabel as U, applyLineageTruncation as V, WORKFLOW_CAPSULE_API_VERSION as W, applySessionCompaction as X, archiveOldIslands as Y, buildSessionTree as Z, _resetMessageQueueForTests as _, cleanupIncompleteToolCalls as a0, countActiveLineageMessages as a1, countTokens as a2, createSessionLineage as a3, createWorkflowCapsule as a4, createWorkflowModuleFromCapsule as a5, createWorkflowRunManager as a6, estimateTokens as a7, extractArtifactLedger as a8, extractFileOps as a9, extractTitleFromMessages as aa, findPreviousUserEntryId as ab, forkSessionLineage as ac, generateSessionId as ad, getAgentConfigHome as ae, getAgentConfigPath as af, getAppDataDir as ag, getDefaultWorkflowRunManager as ah, getMessageQueue as ai, getSessionLineagePath as aj, getSessionMessagesFromLineage as ak, mergeArtifactLedger as al, mergeFileOps as am, resolveSessionLineageTarget as an, rewindSessionLineage as ao, setAgentConfigHome as ap, setSessionLineageActiveEntry as aq, validateAndFixToolHistory as ar, validateWorkflowCapsule as as, validateWorkflowScriptManifest as at, KODAX_DEFAULT_TIMEOUT as f, KODAX_HARD_TIMEOUT as g, KODAX_MAX_INCOMPLETE_RETRIES as h, KODAX_MAX_MAXTOKENS_RETRIES as i, KODAX_MAX_RETRIES as j, KODAX_MAX_TOKENS as k, KODAX_RETRY_BASE_DELAY as l, KODAX_STAGGER_DELAY as m, LineageCompaction as o, LineageExtension as r, MessageQueue as y };
919
+ export type { CompactionContext as C, WorkflowCapsule as F, WorkflowCapsuleEnvironmentRequirement as G, WorkflowCapsuleInputs as H, WorkflowCapsuleIntent as I, WorkflowCapsuleProvenance as J, ManagedRunClassification as M, WorkflowCapsuleRequirements as N, WorkflowPatternId as O, WorkflowProcessMetadata as Q, WorkflowRunManager as R, StartManagedRunInput as S, WorkflowScriptManifest as T, CompactionEntry as a, CompactionEntryPayload as b, CompactionPolicy as c, CreateWorkflowCapsuleInput as d, DefaultSummaryCompactionOptions as e, LineageArtifactLedgerPayload as n, LineageCompactionDelegates as p, LineageEntryType as q, LineageLabelPayload as s, LineageTreeNode as t, ManagedRunHooks as u, ManagedWorkflowRun as v, ManagedWorkflowSnapshot as w, ManagedWorkflowStatus as x, PolicyCompactionResult as z };