@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
@@ -1,9 +1,10 @@
1
- import { U as KodaXGoalState, f as AgentMessage, b0 as StopHookFn, a4 as KodaXSessionLineage, W as KodaXJsonValue, P as KodaXExtensionSessionRecord, a9 as KodaXSessionScope, aa as KodaXSessionStorage, Q as KodaXExtensionSessionState, C as ChildTaskRegistry, bl as WorkflowEventCorrelation, s as CompactionUpdate, bx as WorkflowProcessEvent, m as AskUserQuestionOptions, k as AskUserMultiOptions, y as Guardrail, bo as WorkflowIsolation, Y as KodaXSessionArtifactLedgerEntry, aN as SessionErrorMetadata, v as DiscoveredInstance, b4 as TaskAbortRegistry } from './process.d-BZncyzEj.js';
2
- import { Z as KodaXTokenUsage, j as KodaXMessage, a6 as KodaXWireReasoningEffort, E as KodaXReasoningMode, g as KodaXHarnessProfile, T as KodaXTaskWorkIntent, I as KodaXReviewScale, P as KodaXTaskComplexity, b as KodaXChildFanoutClass, R as KodaXTaskRoutingDecision, S as KodaXTaskType, J as KodaXRiskLevel, e as KodaXExecutionMode } from './types.d-6VOXvF88.js';
1
+ import { W as KodaXGoalState, g as AgentMessage, b8 as StopHookFn, aa as KodaXSessionLineage, a0 as KodaXJsonValue, Q as KodaXExtensionSessionRecord, bw as WorkflowIsolation, R as KodaXExtensionSessionState, a2 as KodaXSessionArtifactLedgerEntry, aV as SessionErrorMetadata, af as KodaXSessionScope, ag as KodaXSessionStorage, _ as KodaXInputArtifact, C as ChildTaskRegistry, bt as WorkflowEventCorrelation, t as CompactionUpdate, bF as WorkflowProcessEvent, bs as WorkflowEvent, n as AskUserQuestionOptions, l as AskUserMultiOptions, z as Guardrail, w as DiscoveredInstance, bc as TaskAbortRegistry } from './process.d-BOrAxjvM.js';
2
+ import { Z as KodaXTokenUsage, j as KodaXMessage, a6 as KodaXWireReasoningEffort, R as KodaXTaskRoutingDecision, S as KodaXTaskType, T as KodaXTaskWorkIntent, P as KodaXTaskComplexity, J as KodaXRiskLevel, g as KodaXHarnessProfile, e as KodaXExecutionMode, b as KodaXChildFanoutClass, E as KodaXReasoningMode, I as KodaXReviewScale } from './types.d-Ci5YPFEh.js';
3
+ import { d as SkillDynamicContextExecutor } from './types.d-vJExiRje.js';
3
4
  import { Diagnostic, Position, Location, Hover, DocumentSymbol, SymbolInformation, WorkspaceSymbol, CallHierarchyItem, CallHierarchyIncomingCall, CallHierarchyOutgoingCall } from 'vscode-languageserver-protocol';
5
+ import { K as KodaXLlmTimeoutConfig, a as CostTracker } from './cost-tracker.d-CBLk1fiD.js';
4
6
  import { C as CapabilityKind, b as CapabilityResult } from './capability.d-3C62G8Eq.js';
5
- import { K as KodaXBaseProvider } from './base.d-BnjQrSVf.js';
6
- import { a as CostTracker } from './cost-tracker.d-wRtyEW9d.js';
7
+ import { K as KodaXBaseProvider } from './base.d-BA9Doaj_.js';
7
8
 
8
9
  /**
9
10
  * FEATURE_192 v0.7.44 Phase C — Goal-tools execution context.
@@ -408,26 +409,41 @@ interface TodoStore {
408
409
  }
409
410
 
410
411
  type WorkflowInvocationSource = 'natural-language' | 'command';
411
- type WorkflowInvocationAction = 'none' | 'suggest' | 'auto-start';
412
- type WorkflowInvocationTrigger = 'explicit' | 'complexity' | 'negated' | 'none';
412
+ type WorkflowInvocationAction = 'none' | 'suggest';
413
413
  type WorkflowStartOutcome = 'started' | 'declined' | 'cancelled' | 'failed';
414
+ /**
415
+ * Host-owned execution ceilings for a workflow run (FEATURE_229). These clamp
416
+ * the run-manager / runner (maxAgents, concurrency, token budget); they do not
417
+ * affect whether a workflow launches — that is decided by the source alone
418
+ * (ADR-047).
419
+ */
414
420
  interface WorkflowHostPolicy {
415
- readonly autoStart?: 'off' | 'confirm' | 'on';
416
421
  readonly maxAgents?: number;
417
422
  readonly maxConcurrency?: number;
418
423
  readonly tokenBudget?: number;
419
424
  }
420
425
  interface WorkflowInvocationPolicyInput {
421
- readonly agentMode: KodaXAgentMode;
422
426
  readonly source: WorkflowInvocationSource;
423
- readonly input: string;
424
- readonly hostPolicy?: WorkflowHostPolicy;
425
427
  }
426
428
  interface WorkflowInvocationPolicyDecision {
427
429
  readonly action: WorkflowInvocationAction;
428
- readonly trigger: WorkflowInvocationTrigger;
429
- readonly reason: string;
430
430
  }
431
+ /**
432
+ * Decide whether the REPL host should launch a workflow before the agent runs.
433
+ *
434
+ * FEATURE_246 A5 (ADR-047): the host only launches workflows for an explicit
435
+ * `/workflow` command (`'suggest'`). Natural language is never intercepted in
436
+ * any mode (`'none'`) — in AMA/AMAW the Worker owns the decision through the
437
+ * `run_workflow` tool, which scouts the codebase first and authors a script
438
+ * from real findings (file paths, the actual sub-problems, a concrete
439
+ * outputSchema). A blind host-side generator cannot investigate, so pre-empting
440
+ * NL here produced shallow, disjointed workflows. SA has no workflow host.
441
+ *
442
+ * The decision is the source alone, so this takes no agent mode or input text:
443
+ * the earlier NL detection (explicit/complexity/negation regexes) existed only
444
+ * to gate the removed auto-start path — that judgment now belongs to the Worker
445
+ * with full context, not a keyword match.
446
+ */
431
447
  declare function decideWorkflowInvocation(input: WorkflowInvocationPolicyInput): WorkflowInvocationPolicyDecision;
432
448
  declare function workflowStartOutcomeConsumesTurn(input: {
433
449
  readonly outcome: WorkflowStartOutcome;
@@ -900,6 +916,22 @@ interface KodaXManualSource {
900
916
  readonly label: string;
901
917
  readonly path: string;
902
918
  }
919
+ interface KodaXManualTopic {
920
+ readonly id: KodaXManualTopicId;
921
+ /** Human title, shown as the answer heading. */
922
+ readonly title: string;
923
+ /** Lookup aliases (English + Chinese high-frequency terms). */
924
+ readonly aliases: readonly string[];
925
+ /** One-line summary, shown in the index listing. */
926
+ readonly summary: string;
927
+ /**
928
+ * Bounded topic body. Built at module load — dynamic parts (e.g. the
929
+ * provider list) read live constants so the manual cannot drift from code.
930
+ */
931
+ readonly body: string;
932
+ readonly sources: readonly KodaXManualSource[];
933
+ readonly nextTopics: readonly KodaXManualTopicId[];
934
+ }
903
935
  interface ResolveKodaXManualInput {
904
936
  /** Exact topic id or alias. Takes precedence over `query`. */
905
937
  readonly topic?: string;
@@ -924,10 +956,24 @@ interface KodaXManualTopicInput {
924
956
  }
925
957
  /** Per-call resolver options — consumer topic injection + product re-branding. */
926
958
  interface ResolveKodaXManualOptions {
927
- /** Injected consumer topics, merged over the KodaX base (override by id). */
959
+ /** Injected consumer topics, merged over the seeded base (override by id, then append). */
928
960
  readonly extraTopics?: readonly KodaXManualTopicInput[];
929
961
  /** Product name used in the scope anchor (default "KodaX"). */
930
962
  readonly productName?: string;
963
+ /**
964
+ * FEATURE_221 — which KodaX base topics to SEED before `extraTopics` is
965
+ * layered on top. Orthogonal to `extraTopics` (whose override-by-id/append
966
+ * semantics are unchanged).
967
+ *
968
+ * - `undefined` → seed all base topics (`MANUAL_TOPIC_IDS`). Today's exact
969
+ * behavior (byte-identical default).
970
+ * - `[]` → seed ZERO base topics; only `extraTopics` populate the manual
971
+ * (full white-label replace).
972
+ * - `KodaXManualTopicId[]` → seed exactly this curated subset (e.g.
973
+ * `KODAX_UNDERLYING_CAPABILITY_TOPICS`), so a replacing consumer can still
974
+ * keep the mechanism topics its product inherits from KodaX.
975
+ */
976
+ readonly baseTopics?: readonly KodaXManualTopicId[];
931
977
  }
932
978
  interface ResolveKodaXManualResult {
933
979
  /** A topic id (KodaX base or injected consumer topic), or 'index'. */
@@ -1070,16 +1116,6 @@ interface ProviderResiliencePolicy extends ProviderResilienceConfig {
1070
1116
  provider: string;
1071
1117
  }
1072
1118
 
1073
- interface KodaXLlmTimeoutConfig {
1074
- /** Main provider request hard timeout, in seconds. Default 600s. */
1075
- readonly requestTimeoutSec?: number;
1076
- /** Idle timeout between stream deltas, in seconds. Set 0 to disable. Default 0. */
1077
- readonly streamIdleTimeoutSec?: number;
1078
- /** Per stream chunk timeout, in seconds. Default 30s. */
1079
- readonly chunkTimeoutSec?: number;
1080
- /** Maximum retry delay, in seconds. Default 60s. */
1081
- readonly maxRetryDelaySec?: number;
1082
- }
1083
1119
  interface KodaXWorkflowTimeoutConfig {
1084
1120
  /** Workflow harness generation LLM call timeout, in seconds. Default 120s. */
1085
1121
  readonly generationTimeoutSec?: number;
@@ -1092,10 +1128,6 @@ interface KodaXTimeoutConfig {
1092
1128
  readonly llm?: KodaXLlmTimeoutConfig;
1093
1129
  readonly workflow?: KodaXWorkflowTimeoutConfig;
1094
1130
  }
1095
- declare function timeoutSecToMs(value: number | undefined, label: string, opts?: {
1096
- readonly allowZero?: boolean;
1097
- }): number | undefined;
1098
- declare function parseTimeoutSecEnvMs(raw: string | undefined): number | undefined;
1099
1131
  declare function providerResilienceConfigFromTimeouts(timeouts: KodaXTimeoutConfig | undefined): ProviderResilienceConfig | undefined;
1100
1132
 
1101
1133
  /**
@@ -1156,6 +1188,58 @@ interface ExtensionRuntimeContract extends CapabilityRuntimeContract {
1156
1188
  hydrateSession?(sessionId: string): Promise<void>;
1157
1189
  }
1158
1190
 
1191
+ /**
1192
+ * v0.7.42 — Declarative tool side-effect class.
1193
+ *
1194
+ * FEATURE_247: extracted into this leaf module (from `tools/types.ts`) so the
1195
+ * main `coding/src/types.ts` can import `ToolSideEffect` for the tool-visibility
1196
+ * policy WITHOUT forming a type-level import cycle with `tools/types.ts` (which
1197
+ * imports `KodaXToolExecutionContext` back from `types.ts`). This file imports
1198
+ * nothing from the coding type graph.
1199
+ *
1200
+ * Required field on every {@link import('./types.js').LocalToolDefinition}. Used by:
1201
+ * - Plan mode: tools with `sideEffect !== 'readonly'` are blocked unless
1202
+ * they explicitly opt in via `planModeAllowed: true` (e.g.
1203
+ * `exit_plan_mode`, `task_stop`).
1204
+ * - SDK embedders (KodaX Space etc.): iterate `getAllRegisteredTools()`
1205
+ * and build their own blocklist by category — replaces the previous
1206
+ * practice of hardcoding a `Set<string>` of tool names, which silently
1207
+ * drifted whenever KodaX added a new tool.
1208
+ * - Internal permission system: `FILE_MODIFICATION_TOOLS` and
1209
+ * `MODIFICATION_TOOLS` exports in `@kodax-ai/repl` are now computed
1210
+ * from this metadata at module load time, so adding a new
1211
+ * `'mutates-fs'` tool here automatically reaches every callsite
1212
+ * that consumes those sets.
1213
+ *
1214
+ * Categories (mutually exclusive; pick the dominant effect):
1215
+ * - `'readonly'` — produces no observable side effect, just reads
1216
+ * local state (FS, registry, computed views).
1217
+ * - `'mutates-fs'` — writes to the local filesystem (write, edit,
1218
+ * multi-edit, undo, worktree-*, construction
1219
+ * artifacts). Bash is NOT in this bucket; it has
1220
+ * its own.
1221
+ * - `'mutates-shell'` — invokes an arbitrary shell command (bash).
1222
+ * - `'reads-network'` — FEATURE_247: performs a network request whose
1223
+ * LLM-facing semantics are read-only, i.e. no remote
1224
+ * mutation (web_search, mcp_read_resource,
1225
+ * mcp_get_prompt). Distinct from `'mutates-network'`
1226
+ * so a permission broker can allow web research while
1227
+ * still blocking mutating network calls. Plan-mode
1228
+ * eligibility is still driven by `planModeAllowed`,
1229
+ * unchanged.
1230
+ * - `'mutates-network'` — performs a network request that may mutate remote
1231
+ * state (web_fetch with a mutating method, mcp_call).
1232
+ * - `'mutates-state'` — changes internal session/agent state without
1233
+ * FS or shell side effects (todo_update,
1234
+ * send_message, dispatch_child_task,
1235
+ * exit_plan_mode, emit_managed_protocol).
1236
+ *
1237
+ * Pick the dominant effect when a tool touches multiple. e.g. `dispatch_
1238
+ * child_task` may transitively run any tool, but its own direct effect is
1239
+ * spawning a child agent (`mutates-state`).
1240
+ */
1241
+ type ToolSideEffect = 'readonly' | 'reads-network' | 'mutates-fs' | 'mutates-shell' | 'mutates-network' | 'mutates-state';
1242
+
1159
1243
  /**
1160
1244
  * FEATURE_200 Phase F (v0.7.45) — Todo domain types extracted from types.ts.
1161
1245
  * Self-contained (no other coding-type deps); re-exported from ../types.ts
@@ -1304,6 +1388,28 @@ interface KodaXActivityEventMeta extends KodaXWorkflowEventMeta {
1304
1388
  readonly childAgentName?: string;
1305
1389
  readonly parentToolId?: string;
1306
1390
  readonly liveOnly?: boolean;
1391
+ /**
1392
+ * FEATURE_247 (R8) — session id this event belongs to. Lets a host that runs
1393
+ * concurrent Partner/Coder sessions attribute a streamed event to the right
1394
+ * session. Absent on paths that do not yet thread the resolved session id.
1395
+ */
1396
+ readonly sessionId?: string;
1397
+ /**
1398
+ * FEATURE_247 (R8) — SDK-consumer agent profile that produced this event.
1399
+ * Absent ⇒ default Coding Agent (or an event emitted before a profile is known).
1400
+ */
1401
+ readonly agentProfile?: KodaXAgentProfile;
1402
+ }
1403
+ /**
1404
+ * ADR-049: a single workflow child agent reached a terminal/summary state during
1405
+ * an inline `run_workflow` run. The raw `WorkflowEvent` is forwarded (not a
1406
+ * pre-formatted string) so the REPL renders it with its own
1407
+ * `formatWorkflowAgentDigest` — keeping digest formatting in the UI layer and the
1408
+ * coding layer free of presentation logic.
1409
+ */
1410
+ interface KodaXWorkflowAgentDigestEvent {
1411
+ readonly runId: string;
1412
+ readonly event: WorkflowEvent;
1307
1413
  }
1308
1414
  interface KodaXToolEventMeta extends KodaXActivityEventMeta {
1309
1415
  readonly toolId?: string;
@@ -1317,6 +1423,17 @@ interface KodaXSidecarMessageEvent {
1317
1423
  readonly content: string;
1318
1424
  readonly suggestedFix?: string;
1319
1425
  readonly trace?: string;
1426
+ /**
1427
+ * FEATURE_247 (R3/R8) — session id the verdict belongs to, so a host running
1428
+ * concurrent Partner/Coder sessions can correlate a sidecar verdict to the
1429
+ * right session. Absent when the resolved session id is not available.
1430
+ */
1431
+ readonly sessionId?: string;
1432
+ /**
1433
+ * FEATURE_247 (R3/R8) — SDK-consumer agent profile whose output was verified.
1434
+ * Absent ⇒ default Coding Agent.
1435
+ */
1436
+ readonly agentProfile?: KodaXAgentProfile;
1320
1437
  }
1321
1438
  interface KodaXTodoDriftWarningEvent {
1322
1439
  readonly kind: 'work_started_without_claimed_todo';
@@ -1441,9 +1558,10 @@ interface KodaXEvents {
1441
1558
  maxAttempts: number;
1442
1559
  }, meta?: KodaXActivityEventMeta) => void;
1443
1560
  /**
1444
- * Passive capability learning fired when a provider HARD-rejects a
1445
- * reasoning-effort value. The REPL records it in `capability-cache.json` so
1446
- * the rung is narrowed out of the ladder and never offered/sent again.
1561
+ * Passive capability learning: fired when a provider HARD-rejects a
1562
+ * reasoning-effort value. Hosts can record it via the agent-layer capability
1563
+ * cache so the rung is narrowed out of the ladder and never offered/sent
1564
+ * again.
1447
1565
  */
1448
1566
  onReasoningEffortRejected?: (event: {
1449
1567
  provider: string;
@@ -1483,8 +1601,24 @@ interface KodaXEvents {
1483
1601
  onComplete?: () => void;
1484
1602
  onError?: (error: Error) => void;
1485
1603
  onManagedTaskStatus?: (status: KodaXManagedTaskStatusEvent) => void;
1604
+ /**
1605
+ * FEATURE_247 (R4) — fired once at managed-task start with the effective
1606
+ * profile / tool scope / verification snapshot. Lets an SDK embedder confirm
1607
+ * the intended profile (e.g. Partner) actually entered the SDK managed task
1608
+ * and diagnose the tools + verification constraints it was given.
1609
+ */
1610
+ onEffectiveConfig?: (config: KodaXEffectiveTaskConfig) => void;
1486
1611
  /** FEATURE_229: workflow process snapshot stream for SDK/host panels. */
1487
1612
  onWorkflowProcessEvent?: (event: WorkflowProcessEvent) => void;
1613
+ /**
1614
+ * ADR-049: per-agent digest stream for the inline `run_workflow` path. Fires
1615
+ * once per workflow child agent reaching a terminal/summary state
1616
+ * (`agent_completed` / `agent_unverified` / `agent_failed` /
1617
+ * `agent_summary_updated`). The REPL formats each via `formatWorkflowAgentDigest`
1618
+ * and writes it to the transcript — matching the slash `/workflow` path and
1619
+ * `dispatch_child_task` children, whose summaries persist in scrollback.
1620
+ */
1621
+ onWorkflowAgentDigest?: (event: KodaXWorkflowAgentDigestEvent) => void;
1488
1622
  /**
1489
1623
  * Fired when Scout's managed-task completion is inferred but the harness
1490
1624
  * detected suspicious signals (mutation expected but none happened, budget
@@ -1522,10 +1656,11 @@ interface KodaXEvents {
1522
1656
  };
1523
1657
  /** Tool execution hook - called before tool execution, return false to block - 工具执行前回调 */
1524
1658
  beforeToolExecute?: (tool: string, input: Record<string, unknown>, meta?: KodaXToolEventMeta) => Promise<boolean | string>;
1525
- /** Ask user a question interactively - Issue 069 - 交互式向用户提问 */
1526
- askUser?: (options: AskUserQuestionOptions, meta?: KodaXToolEventMeta) => Promise<string>;
1659
+ /** Ask user a question interactively - Issue 069 - 交互式向用户提问. Multi-select
1660
+ * (options.multiSelect) resolves string[]; single-select resolves string. */
1661
+ askUser?: (options: AskUserQuestionOptions, meta?: KodaXToolEventMeta) => Promise<string | string[]>;
1527
1662
  /** Ask user multiple independent questions sequentially - 澶氶棶棰橀『搴忔彁闂?*/
1528
- askUserMulti?: (options: AskUserMultiOptions, meta?: KodaXToolEventMeta) => Promise<Record<string, string> | undefined>;
1663
+ askUserMulti?: (options: AskUserMultiOptions, meta?: KodaXToolEventMeta) => Promise<Record<string, string | string[]> | undefined>;
1529
1664
  /** Ask user for free-text input - 自由文本输入 (Issue 112) */
1530
1665
  askUserInput?: (options: {
1531
1666
  question: string;
@@ -1672,10 +1807,52 @@ interface KodaXTaskVerificationContract {
1672
1807
  requiredEvidence?: string[];
1673
1808
  requiredChecks?: string[];
1674
1809
  capabilityHints?: KodaXTaskCapabilityHint[];
1675
- rubricFamily?: 'code-review' | 'frontend' | 'product-completeness' | 'functionality' | 'code-quality';
1810
+ rubricFamily?: 'code-review' | 'frontend' | 'product-completeness' | 'functionality' | 'code-quality' | 'partner-research';
1676
1811
  criteria?: KodaXTaskVerificationCriterion[];
1677
1812
  runtime?: KodaXRuntimeVerificationContract;
1678
1813
  }
1814
+ /**
1815
+ * FEATURE_247 — SDK-consumer agent profile identity (e.g. KodaX-Space Partner).
1816
+ *
1817
+ * The SDK core treats this as OPAQUE attribution: it is echoed onto results,
1818
+ * events, the effective-config snapshot, session runtimeInfo, and tool context
1819
+ * so an embedder can confirm which profile actually ran and can attribute
1820
+ * concurrent Partner/Coder sessions. Absent ⇒ the default Coding Agent, with no
1821
+ * behavioral change anywhere.
1822
+ *
1823
+ * Only two fields carry behavior, both additive and gated on their own presence:
1824
+ * - `instructions` — on the SA path the embedder sets
1825
+ * `context.systemPromptOverride`; the AMA/AMAW path builds role prompts
1826
+ * internally, so when this is set the Worker role prompt PREPENDS this block
1827
+ * (absent ⇒ byte-identical default coding role prompt).
1828
+ * - `verification` — a profile-default verifier standard the Sidecar Verifier
1829
+ * applies; per-task `context.taskVerification` still overrides/augments it.
1830
+ *
1831
+ * Everything else (`surface`/`id`/`version`/`name`) is pure identity passthrough.
1832
+ */
1833
+ interface KodaXAgentProfile {
1834
+ /** Surface/profile label, e.g. `'code'` | `'partner'`. Opaque to the core. */
1835
+ readonly surface?: string;
1836
+ /** Stable profile id (UUID or stable name). Opaque to the core. */
1837
+ readonly id?: string;
1838
+ /** Profile version. Opaque to the core. */
1839
+ readonly version?: string;
1840
+ /** Human-facing display name. Opaque to the core. */
1841
+ readonly name?: string;
1842
+ /**
1843
+ * Partner behavior instructions injected into the AMA/AMAW Worker role prompt
1844
+ * (prepended). The SA path uses `context.systemPromptOverride` instead — this
1845
+ * field is the AMA-path equivalent so a Partner profile behaves consistently
1846
+ * across both execution modes.
1847
+ */
1848
+ readonly instructions?: string;
1849
+ /**
1850
+ * Profile-default verification standard. Merged with per-task
1851
+ * `context.taskVerification` (per-task fields win) before reaching the Sidecar
1852
+ * Verifier.
1853
+ */
1854
+ readonly verification?: KodaXTaskVerificationContract;
1855
+ }
1679
1856
  type KodaXSkillProjectionConfidence = 'high' | 'medium' | 'low';
1680
1857
  interface KodaXSkillInvocationContext {
1681
1858
  name: string;
@@ -1756,6 +1933,13 @@ interface KodaXChildContextBundle {
1756
1933
  model?: string;
1757
1934
  /** Optional per-dispatch reasoning effort. Omit to inherit the parent effort. */
1758
1935
  effort?: KodaXWireReasoningEffort;
1936
+ /**
1937
+ * FEATURE_246 Part B — optional JSON Schema (opaque) for the child's
1938
+ * structured output. When set, the child briefing asks for a fenced JSON
1939
+ * block matching it; the child executor parses + validates the result (with
1940
+ * one bounded repair turn) and surfaces it on `KodaXChildAgentResult.structured`.
1941
+ */
1942
+ outputSchema?: unknown;
1759
1943
  }
1760
1944
  /**
1761
1945
  * FEATURE_120 v0.7.39 Phase 4 — model tier hint. Tier semantics:
@@ -1802,6 +1986,13 @@ interface KodaXChildAgentResult {
1802
1986
  * and consumed by dispatch-child-tasks' empty-summary fallback.
1803
1987
  */
1804
1988
  interrupted?: boolean;
1989
+ /**
1990
+ * FEATURE_246 Part B — schema-validated structured output parsed from the
1991
+ * child's final text (present only when the bundle carried `outputSchema`
1992
+ * and a JSON value was parseable). Surfaced to the workflow runtime as
1993
+ * `WorkflowTaskResult.structured`.
1994
+ */
1995
+ structured?: unknown;
1805
1996
  }
1806
1997
  interface KodaXParentReductionContract {
1807
1998
  owner: 'parent';
@@ -1851,6 +2042,11 @@ interface KodaXManagedLiveEvent {
1851
2042
  interface KodaXManagedTaskStatusEvent {
1852
2043
  agentMode: KodaXAgentMode;
1853
2044
  harnessProfile: KodaXHarnessProfile;
2045
+ /**
2046
+ * FEATURE_247 — SDK-consumer agent profile driving this managed task, echoed
2047
+ * from `options.context.agentProfile`. Absent ⇒ default Coding Agent.
2048
+ */
2049
+ agentProfile?: KodaXAgentProfile;
1854
2050
  activeWorkerId?: string;
1855
2051
  activeWorkerTitle?: string;
1856
2052
  childFanoutClass?: KodaXChildFanoutClass;
@@ -1898,6 +2094,29 @@ interface KodaXManagedTaskStatusEvent {
1898
2094
  */
1899
2095
  idleWaitingPendingCount?: number;
1900
2096
  }
2097
+ /**
2098
+ * FEATURE_247 (R4) — effective managed-task configuration snapshot, emitted once
2099
+ * at run start via {@link KodaXEvents.onEffectiveConfig} so an SDK embedder can
2100
+ * (a) assert the intended profile actually entered the SDK managed task and
2101
+ * (b) diagnose which tools + verification standard are in force.
2102
+ */
2103
+ interface KodaXEffectiveTaskConfig {
2104
+ readonly agentMode: KodaXAgentMode;
2105
+ /** SDK-consumer profile driving the run; undefined ⇒ default Coding Agent. */
2106
+ readonly agentProfile?: KodaXAgentProfile;
2107
+ /** Tool names visible to the model for this run. */
2108
+ readonly toolScope: readonly string[];
2109
+ /**
2110
+ * Effective verification standard reaching the Sidecar Verifier — the profile
2111
+ * default merged with per-task `context.taskVerification` (per-task wins).
2112
+ */
2113
+ readonly verification?: KodaXTaskVerificationContract;
2114
+ /** Resolved Sidecar Verifier provider/model, when the verifier is active. */
2115
+ readonly verifier?: {
2116
+ readonly provider?: string;
2117
+ readonly model?: string;
2118
+ };
2119
+ }
1901
2120
  interface KodaXVerificationScorecardCriterion {
1902
2121
  id: string;
1903
2122
  label: string;
@@ -1986,6 +2205,29 @@ interface ManagedMutationTracker {
1986
2205
  /** Set to true after scope reflection has been injected once. Prevents repeated injection. */
1987
2206
  reflectionInjected?: boolean;
1988
2207
  }
2208
+ /**
2209
+ * FEATURE_247 (R2) — a minimal, stable per-tool view handed to a
2210
+ * {@link KodaXToolVisibilityPolicy}. Only the load-bearing declarative metadata
2211
+ * is exposed (never the handler / full schema) so the contract stays stable as
2212
+ * tools evolve. `sideEffect` distinguishes readonly / reads-network /
2213
+ * mutates-* classes; `planModeAllowed` marks query-shaped tools.
2214
+ */
2215
+ interface KodaXToolVisibilityMeta {
2216
+ readonly name: string;
2217
+ readonly sideEffect: ToolSideEffect;
2218
+ readonly planModeAllowed: boolean;
2219
+ }
2220
+ /**
2221
+ * FEATURE_247 (R2) — an SDK-consumer predicate evaluated for every candidate
2222
+ * tool BEFORE the model-visible tool list is built. Return `false` to hide a
2223
+ * tool from the model. Space uses this to express profile-scoped rules such as
2224
+ * "only readonly + reads-network visible" and to default-deny anything it does
2225
+ * not explicitly recognize, without enumerating a name list that drifts as the
2226
+ * SDK adds tools. Covers SDK builtin + host-registered + extension + MCP tools
2227
+ * uniformly (each carries a required `sideEffect`). A tool with no resolvable
2228
+ * metadata is hidden (fail-closed).
2229
+ */
2230
+ type KodaXToolVisibilityPolicy = (tool: KodaXToolVisibilityMeta) => boolean;
1989
2231
  interface KodaXContextOptions {
1990
2232
  /** Project root used for project-scoped prompts, permissions, and path policy. */
1991
2233
  gitRoot?: string | null;
@@ -2048,6 +2290,13 @@ interface KodaXContextOptions {
2048
2290
  mutationTracker?: ManagedMutationTracker;
2049
2291
  /** FEATURE_067 v3: Tool names to exclude from API-level tool list (child agents). */
2050
2292
  excludeTools?: readonly string[];
2293
+ /**
2294
+ * FEATURE_247 (R2) — profile-scoped tool visibility predicate applied when the
2295
+ * model-visible tool list is built (in addition to `excludeTools`). Tools for
2296
+ * which it returns `false` are hidden from the model. Absent ⇒ no policy (only
2297
+ * `excludeTools` applies) — the default Coding Agent path is unchanged.
2298
+ */
2299
+ toolVisibilityPolicy?: KodaXToolVisibilityPolicy;
2051
2300
  /**
2052
2301
  * FEATURE_067 v3: Override the entire system prompt for this run.
2053
2302
  * When set, buildSystemPromptSnapshot is skipped — only this string is used.
@@ -2058,6 +2307,13 @@ interface KodaXContextOptions {
2058
2307
  taskMetadata?: Record<string, KodaXJsonValue>;
2059
2308
  /** Optional structured verification contract carried into managed tasks. */
2060
2309
  taskVerification?: KodaXTaskVerificationContract;
2310
+ /**
2311
+ * FEATURE_247 — SDK-consumer agent profile (KodaX-Space Partner et al).
2312
+ * Opaque identity + optional AMA-path instructions + optional default verifier
2313
+ * standard. Absent ⇒ the default Coding Agent (no behavioral change). See
2314
+ * {@link KodaXAgentProfile}.
2315
+ */
2316
+ agentProfile?: KodaXAgentProfile;
2061
2317
  /**
2062
2318
  * FEATURE_074: Plan-mode block predicate provided by the parent REPL. The predicate
2063
2319
  * closes over live parent state so mid-run mode toggles propagate to in-flight
@@ -2123,12 +2379,25 @@ interface KodaXContextOptions {
2123
2379
  * FEATURE_221 — an SDK consumer (a product built on KodaX, e.g. KodaX-Space)
2124
2380
  * injects its own product manual so that when ITS users ask "how do I use /
2125
2381
  * configure <product>?", the kodax_manual tool answers with the consumer's
2126
- * topics. `topics` extend the KodaX base (override by id); `productName`
2127
- * re-brands the routing rule + scope anchor. Topics are still byte-capped.
2382
+ * topics. `topics` extend the seeded base (override by id, then append);
2383
+ * `productName` re-brands the routing rule + scope anchor. Topics are still
2384
+ * byte-capped.
2385
+ *
2386
+ * `baseTopics` controls how much of KodaX's own manual is present underneath:
2387
+ * omit it for the default full base, `[]` for a full white-label replace, or a
2388
+ * curated subset (e.g. `KODAX_UNDERLYING_CAPABILITY_TOPICS`) to keep only the
2389
+ * mechanism topics a product built on KodaX inherits. For build-time docs, a
2390
+ * consumer can import `MANUAL_REGISTRY` to read the base topic bodies directly.
2128
2391
  */
2129
2392
  interface KodaXSelfManualConfig {
2130
2393
  readonly productName?: string;
2131
2394
  readonly topics?: readonly KodaXManualTopicInput[];
2395
+ /**
2396
+ * Which KodaX base topics to seed before `topics` is layered on. `undefined`
2397
+ * ⇒ all base topics (default). `[]` ⇒ none (full replace). A subset ⇒ exactly
2398
+ * those ids. See {@link ResolveKodaXManualOptions.baseTopics}.
2399
+ */
2400
+ readonly baseTopics?: readonly KodaXManualTopicId[];
2132
2401
  }
2133
2402
  /**
2134
2403
  * SDK-consumer auto-compaction override. When a field is provided it wins
@@ -2147,6 +2416,21 @@ interface KodaXCompactionOverride {
2147
2416
  /** Set false to disable automatic compaction for this run. */
2148
2417
  enabled?: boolean;
2149
2418
  }
2419
+ /**
2420
+ * FEATURE_222 skill security — host policy for a skill's `!`cmd`` dynamic-context
2421
+ * tokens. By default (both fields unset) the LLM-triggered `skill` tool runs
2422
+ * those commands via the built-in allowlist + `execSync` — fine for the trusted
2423
+ * standalone CLI, but an embedder host (KodaX-Space) wants every shell touch to
2424
+ * go through its own permission broker. Set `execute` to route each `!`cmd``
2425
+ * through the host, or `disable: true` to refuse them outright.
2426
+ */
2427
+ interface KodaXSkillDynamicContextPolicy {
2428
+ /** Host hook run for each `!`cmd`` token (command, cwd) → stdout. Mediate via
2429
+ * the host's permission broker; throw to refuse a command. */
2430
+ execute?: SkillDynamicContextExecutor;
2431
+ /** When true, every `!`cmd`` token is refused without executing anything. */
2432
+ disable?: boolean;
2433
+ }
2150
2434
  interface KodaXOptions {
2151
2435
  provider: string;
2152
2436
  model?: string;
@@ -2162,8 +2446,62 @@ interface KodaXOptions {
2162
2446
  extensionRuntime?: ExtensionRuntimeContract;
2163
2447
  /** FEATURE_229: host-owned policy for workflow auto-start and ceilings. */
2164
2448
  workflowHostPolicy?: WorkflowHostPolicy;
2449
+ /**
2450
+ * FEATURE_246 Part A2 (ADR-046): durable run-graph base dir for workflow runs
2451
+ * the model launches via `run_workflow`. The host (REPL / SDK) resolves it
2452
+ * (e.g. `getAgentConfigPath('workflow-runs', projectKey)`); when set + the
2453
+ * agent mode is ama/amaw, the tool-execution context wires `ctx.workflowHost`.
2454
+ */
2455
+ workflowRunsBaseDir?: string;
2456
+ /**
2457
+ * M2 — per-agent model TIERS for the workflow / dispatch `model_hint`. An
2458
+ * embedder maps the semantic tiers to concrete models; a workflow script /
2459
+ * dispatch then expresses intent via `modelHint: 'fast' | 'deep'` (NOT a
2460
+ * concrete model name — the authoring model has no cognition of the
2461
+ * embedder's configured providers). 'fast' routes read-only children only
2462
+ * (write/codegen stays on the parent — a quality guard); 'deep' routes any
2463
+ * child; an unset tier inherits the parent provider/model. Carried run-scoped
2464
+ * (AsyncLocalStorage) by runManagedTask so concurrent SDK sessions never
2465
+ * clobber each other; KODAX_FAST/DEEP_PROVIDER/MODEL is the env fallback used
2466
+ * by the CLI / config.json path.
2467
+ */
2468
+ modelTiers?: {
2469
+ readonly fast?: {
2470
+ readonly provider?: string;
2471
+ readonly model?: string;
2472
+ };
2473
+ readonly deep?: {
2474
+ readonly provider?: string;
2475
+ readonly model?: string;
2476
+ };
2477
+ };
2478
+ /**
2479
+ * Config-surface SDK peers for settings the llm layer otherwise reads via env.
2480
+ * Carried run-scoped (AsyncLocalStorage) by runManagedTask so concurrent SDK
2481
+ * sessions are isolated; the KODAX_* env vars are the CLI/config.json fallback.
2482
+ * `maxOutputTokens` caps every provider call; `disablePromptCache` turns off
2483
+ * Anthropic prompt caching; `lsp: false` disables LSP-assisted diagnostics.
2484
+ */
2485
+ maxOutputTokens?: number;
2486
+ disablePromptCache?: boolean;
2487
+ lsp?: boolean;
2488
+ /**
2489
+ * Workflow engine run-scoped overrides. `maxConcurrency` caps how many child
2490
+ * agents a `run_workflow` fans out at once (default 8, clamped to [1, 32]); the
2491
+ * `KODAX_WORKFLOW_MAX_CONCURRENCY` env var (bridged from config.json) is the
2492
+ * CLI fallback. Carried run-scoped so concurrent SDK sessions stay isolated.
2493
+ */
2494
+ workflow?: {
2495
+ readonly maxConcurrency?: number;
2496
+ };
2165
2497
  /** FEATURE_221: SDK-consumer self-manual injection (product name + topics). */
2166
2498
  selfManual?: KodaXSelfManualConfig;
2499
+ /**
2500
+ * FEATURE_222 skill security: host policy for skill `!`cmd`` dynamic-context.
2501
+ * Absent → built-in allowlist+execSync (trusted-CLI default). See
2502
+ * {@link KodaXSkillDynamicContextPolicy}.
2503
+ */
2504
+ skillDynamicContext?: KodaXSkillDynamicContextPolicy;
2167
2505
  /**
2168
2506
  * FEATURE_092 (v0.7.33): caller-supplied run-scoped guardrails forwarded
2169
2507
  * to `Runner.run` via `RunOptions.guardrails`. Merged with the START
@@ -2267,34 +2605,6 @@ interface KodaXTaskEvidenceArtifact {
2267
2605
  path: string;
2268
2606
  description?: string;
2269
2607
  }
2270
- type KodaXImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
2271
- type KodaXVideoMediaType = 'video/mp4' | 'video/mpeg' | 'video/quicktime' | 'video/x-msvideo' | 'video/x-flv' | 'video/webm' | 'video/x-ms-wmv' | 'video/3gpp';
2272
- type KodaXInputArtifactSource = 'user-inline' | 'clipboard' | 'drag-drop' | 'file-picker';
2273
- interface KodaXImageInputArtifact {
2274
- readonly kind: 'image';
2275
- readonly path: string;
2276
- readonly mediaType?: KodaXImageMediaType;
2277
- readonly source?: KodaXInputArtifactSource;
2278
- readonly description?: string;
2279
- }
2280
- interface KodaXFileInputArtifact {
2281
- readonly kind: 'file';
2282
- readonly path: string;
2283
- readonly mediaType?: string;
2284
- readonly mimeType?: string;
2285
- readonly name?: string;
2286
- readonly source?: KodaXInputArtifactSource;
2287
- readonly description?: string;
2288
- }
2289
- interface KodaXVideoInputArtifact {
2290
- readonly kind: 'video';
2291
- readonly path: string;
2292
- readonly mediaType: KodaXVideoMediaType;
2293
- readonly name?: string;
2294
- readonly source?: KodaXInputArtifactSource;
2295
- readonly description?: string;
2296
- }
2297
- type KodaXInputArtifact = KodaXImageInputArtifact | KodaXFileInputArtifact | KodaXVideoInputArtifact;
2298
2608
  interface KodaXTaskEvidenceEntry {
2299
2609
  assignmentId: string;
2300
2610
  role: KodaXTaskRole;
@@ -2435,6 +2745,12 @@ interface KodaXResult {
2435
2745
  signalDebugReason?: string;
2436
2746
  messages: KodaXMessage[];
2437
2747
  sessionId: string;
2748
+ /**
2749
+ * FEATURE_247 — the agent profile this run executed under, echoed verbatim from
2750
+ * `options.context.agentProfile`. Lets an embedder confirm the running profile
2751
+ * was Partner (not the default Coding Agent). Absent ⇒ default Coding Agent.
2752
+ */
2753
+ agentProfile?: KodaXAgentProfile;
2438
2754
  /** Internal raw protocol output retained for artifact persistence after compacting visible failure text. */
2439
2755
  protocolRawText?: string;
2440
2756
  /** Structured managed-task protocol payload separated from visible text. */
@@ -2471,8 +2787,36 @@ interface KodaXToolExecutionContext {
2471
2787
  backups: Map<string, string>;
2472
2788
  /** Git root directory - Git 鏍圭洰褰?*/
2473
2789
  gitRoot?: string;
2790
+ /**
2791
+ * FEATURE_247 (R7) — runtime-resolved session id for the run that owns this
2792
+ * tool call. Lets host-registered tools (Space artifact/source/KB) attribute a
2793
+ * call to the right session when multiple Partner/Coder sessions run
2794
+ * concurrently, without AsyncLocalStorage. Absent on paths that do not resolve
2795
+ * a session id (e.g. isolated tool tests).
2796
+ */
2797
+ sessionId?: string;
2798
+ /**
2799
+ * FEATURE_247 (R7) — id of the LLM `tool_use` block this execution backs
2800
+ * (same value surfaced as `KodaXToolEventMeta.toolId`). Lets a host correlate a
2801
+ * tool handler invocation to its event stream and de-duplicate retries.
2802
+ */
2803
+ toolCallId?: string;
2804
+ /**
2805
+ * FEATURE_247 (R7) — task surface/profile label forwarded from
2806
+ * `options.context.taskSurface`, so a tool handler can tell a Partner call from
2807
+ * a Coder call. Absent ⇒ not set by the caller.
2808
+ */
2809
+ taskSurface?: KodaXTaskSurface;
2810
+ /**
2811
+ * FEATURE_247 (R7) — SDK-consumer agent profile owning this tool call, echoed
2812
+ * from `options.context.agentProfile`. Absent ⇒ default Coding Agent.
2813
+ */
2814
+ agentProfile?: KodaXAgentProfile;
2474
2815
  /** FEATURE_221: SDK-consumer self-manual injection, forwarded from KodaXOptions. */
2475
2816
  selfManual?: KodaXSelfManualConfig;
2817
+ /** FEATURE_222 skill security — host policy for skill `!`cmd`` dynamic-context,
2818
+ * forwarded from `KodaXOptions.skillDynamicContext`. Consumed by the `skill` tool. */
2819
+ skillDynamicContext?: KodaXSkillDynamicContextPolicy;
2476
2820
  /** Working directory used to resolve relative paths and execute shell commands. */
2477
2821
  executionCwd?: string;
2478
2822
  /** Session-scoped directory for helper scripts and scratch outputs. */
@@ -2491,10 +2835,11 @@ interface KodaXToolExecutionContext {
2491
2835
  workflowWorktreeBaseDir?: string;
2492
2836
  /** Shared extension capability runtime used by retrieval-family tools. */
2493
2837
  extensionRuntime?: CapabilityRuntimeContract;
2494
- /** Ask user a question interactively (select mode) - 交互式向用户提问 (Issue 069) */
2495
- askUser?: (options: AskUserQuestionOptions) => Promise<string>;
2838
+ /** Ask user a question interactively (select mode) - 交互式向用户提问 (Issue 069).
2839
+ * Multi-select resolves string[]; single-select resolves string. */
2840
+ askUser?: (options: AskUserQuestionOptions) => Promise<string | string[]>;
2496
2841
  /** Ask user multiple independent questions sequentially - 澶氶棶棰橀『搴忔彁闂?*/
2497
- askUserMulti?: (options: AskUserMultiOptions) => Promise<Record<string, string> | undefined>;
2842
+ askUserMulti?: (options: AskUserMultiOptions) => Promise<Record<string, string | string[]> | undefined>;
2498
2843
  /** Ask user for free-text input - 自由文本输入 (Issue 112) */
2499
2844
  askUserInput?: (options: {
2500
2845
  question: string;
@@ -2773,6 +3118,107 @@ interface KodaXToolExecutionContext {
2773
3118
  * See `packages/coding/src/goal/tools-context.ts`.
2774
3119
  */
2775
3120
  goalContext?: GoalToolsContext;
3121
+ /**
3122
+ * FEATURE_246 Part A2 (ADR-046): narrow capability the `run_workflow` tool
3123
+ * uses to start a managed workflow run. Wired by tool-execution-context (via
3124
+ * a lazy import of the coding WorkflowHost) only when the session enables it;
3125
+ * absent in SA / when no runs dir is configured, so the tool fails closed.
3126
+ */
3127
+ workflowHost?: WorkflowToolHost;
3128
+ /**
3129
+ * Gap A — run-level progress getters keyed by a background workflow's runId.
3130
+ * The async `run_workflow` path registers a getter here on start and removes
3131
+ * it when the run settles, so `task_output(runId)` can render live workflow
3132
+ * progress (phase + active/finished agents) while it is in flight, instead of
3133
+ * `not_found`. Same lifetime as `childAbortControllers` (per ctx). Undefined
3134
+ * outside the async/idle-yield path.
3135
+ */
3136
+ workflowRunProgress?: Map<string, () => WorkflowRunProgressView | undefined>;
3137
+ }
3138
+ /** Result of a model-launched workflow run (FEATURE_246 Part A2). */
3139
+ interface WorkflowToolHostResult {
3140
+ readonly kind: 'declined' | 'started';
3141
+ /** declined: why the host/generator declined to run. */
3142
+ readonly reason?: string;
3143
+ /** started: the minted run id. */
3144
+ readonly runId?: string;
3145
+ /** started: terminal status once the run settled. */
3146
+ readonly status?: string;
3147
+ /** started: the run's displayable result text, when completed. */
3148
+ readonly resultText?: string;
3149
+ /** started: terminal error message, when failed. */
3150
+ readonly error?: string;
3151
+ /** started: names of child agents that completed but FAILED their sidecar
3152
+ * verification in warn-only mode (`agent_unverified`). The overall run still
3153
+ * settles as `completed`, so without surfacing these the Worker would act on
3154
+ * the result unaware that some verification failed. Empty/omitted = all
3155
+ * completed children verified (or none were verified). */
3156
+ readonly verificationWarnings?: readonly string[];
3157
+ }
3158
+ /**
3159
+ * Narrow ctx capability for launching workflows from a tool. Intentionally free
3160
+ * of any workflow-layer type import (keeps `types.ts` dependency-light); the
3161
+ * concrete implementation lives behind a lazy import in tool-execution-context.
3162
+ */
3163
+ interface WorkflowToolHostInlineInput {
3164
+ readonly manifest: unknown;
3165
+ readonly source: string;
3166
+ readonly args?: unknown;
3167
+ readonly resumeFromRunId?: string;
3168
+ /**
3169
+ * Per-run abort signal, combined with the session signal. Lets the Worker stop
3170
+ * THIS running workflow (via task_stop on its task_id) without aborting the
3171
+ * whole session — so it can change the goal, stop, and re-run an improved script.
3172
+ */
3173
+ readonly signal?: AbortSignal;
3174
+ }
3175
+ /**
3176
+ * Compact live view of a running workflow. Surfaced so the Worker can peek at a
3177
+ * background `run_workflow`'s progress via `task_output(runId)` while it is still
3178
+ * in flight (gap A) — otherwise it only ever sees the final `<task-completed>`.
3179
+ * Derived on demand from the run's process snapshot; deliberately free of any
3180
+ * workflow-layer type import so this module stays dependency-light.
3181
+ */
3182
+ interface WorkflowRunProgressView {
3183
+ readonly status: 'running' | 'completed' | 'failed' | 'stopped';
3184
+ readonly workflowName: string;
3185
+ /** Active phase title (e.g. "Verify"), when the script uses phases. */
3186
+ readonly phase?: string;
3187
+ readonly phaseIndex?: number;
3188
+ readonly phaseTotal?: number;
3189
+ /** Names of the agents currently running. */
3190
+ readonly activeAgents: readonly string[];
3191
+ readonly completedAgents: number;
3192
+ readonly failedAgents: number;
3193
+ readonly stoppedAgents: number;
3194
+ readonly totalSpawned: number;
3195
+ readonly plannedAgents?: number;
3196
+ readonly elapsedMs?: number;
3197
+ }
3198
+ /** ADR-049: a started-but-not-awaited workflow handle. `done` resolves with the
3199
+ * terminal result when the run settles — the async run_workflow path registers it
3200
+ * in the Worker's childTaskRegistry so the idle-yield loop resumes the Worker with
3201
+ * the synthesis instead of blocking the turn. */
3202
+ type WorkflowToolHostStartResult = {
3203
+ readonly kind: 'declined';
3204
+ readonly reason?: string;
3205
+ } | {
3206
+ readonly kind: 'started';
3207
+ readonly runId: string;
3208
+ readonly done: Promise<WorkflowToolHostResult>;
3209
+ /** Gap A: on-demand live progress for a `task_output(runId)` peek while the
3210
+ * run is in flight. Absent when the host cannot snapshot the run. */
3211
+ readonly getProgress?: () => WorkflowRunProgressView | undefined;
3212
+ };
3213
+ interface WorkflowToolHost {
3214
+ /** Start an inline-authored workflow ({manifest, source}) and await its result.
3215
+ * `resumeFromRunId` (FEATURE_246 Part D) seeds the result cache from a prior
3216
+ * run so unchanged effects replay and only changed ones re-run live. */
3217
+ runInline(input: WorkflowToolHostInlineInput): Promise<WorkflowToolHostResult>;
3218
+ /** ADR-049: start the workflow and return immediately with a `done` promise,
3219
+ * without blocking the calling turn. The async/idle-yield run_workflow path uses
3220
+ * this; `runInline` is just `startInline` + `await done`. */
3221
+ startInline(input: WorkflowToolHostInlineInput): Promise<WorkflowToolHostStartResult>;
2776
3222
  }
2777
3223
 
2778
3224
  /**
@@ -2924,5 +3370,5 @@ interface CreateBashPrefixExtractorOptions {
2924
3370
  */
2925
3371
  declare function createBashPrefixExtractor(opts: CreateBashPrefixExtractorOptions): BashPrefixExtractor;
2926
3372
 
2927
- export { BASH_POLICY_SPEC as B, extractCommandPrefix as a$, buildGoalRuntimeBinding as aY, createBashPrefixExtractor as aZ, decideWorkflowInvocation as a_, LSP_SERVERS as aw, LspService as ay, getDefaultLspService as b0, makeDisabledGoalToolsContext as b1, parseTimeoutSecEnvMs as b2, providerResilienceConfigFromTimeouts as b3, shutdownDefaultLspService as b4, timeoutSecToMs as b5, withGoalBeforeNextTurn as b6, withGoalStopHook as b7, workflowStartOutcomeConsumesTurn as b8 };
2928
- export type { KodaXResult as $, KodaXInputArtifactSource as A, CapabilityRuntimeContract as C, DiagnosticsRequest as D, ExtensionRuntimeContract as E, FailureStage as F, GoalBlockedResult as G, KodaXLlmTimeoutConfig as H, KodaXManagedBudgetSnapshot as I, KodaXManagedProtocolPayload as J, KodaXActivityEventMeta as K, KodaXManagedTask as L, KodaXManagedTaskRuntimeState as M, KodaXManagedTaskStatusEvent as N, KodaXManualTopicId as O, KodaXManualTopicInput as P, KodaXMemoryStrategy as Q, KodaXOptions as R, KodaXOrchestrationVerdict as S, KodaXParentReductionContract as T, KodaXProviderPolicyHints as U, KodaXRepoIntelligenceCapability as V, KodaXRepoIntelligenceMode as W, KodaXRepoIntelligenceResolvedMode as X, KodaXRepoIntelligenceTrace as Y, KodaXRepoIntelligenceTraceEvent as Z, KodaXRepoRoutingSignals as _, BashPrefixExtractor as a, KodaXRoleRoundSummary as a0, KodaXRuntimeVerificationContract as a1, KodaXSelfManualConfig as a2, KodaXSessionControl as a3, KodaXSessionMutators as a4, KodaXSessionOptions as a5, KodaXSidecarMessageEvent as a6, KodaXSkillInvocationContext as a7, KodaXSkillMap as a8, KodaXSkillProjectionConfidence as a9, ProviderExecutionState as aA, ProviderRecoveryEvent as aB, ProviderResilienceConfig as aC, ProviderResiliencePolicy as aD, RecoveryAction as aE, RecoveryDecision as aF, RecoveryLadderStep as aG, RecoveryResult as aH, ResilienceClassification as aI, ResilienceErrorClass as aJ, ResolveKodaXManualInput as aK, ResolveKodaXManualOptions as aL, ResolveKodaXManualResult as aM, RuntimeDefaultsSnapshot as aN, TodoItem as aO, TodoList as aP, TodoStatus as aQ, WorkflowHostPolicy as aR, WorkflowInvocationAction as aS, WorkflowInvocationPolicyDecision as aT, WorkflowInvocationPolicyInput as aU, WorkflowInvocationSource as aV, WorkflowInvocationTrigger as aW, WorkflowStartOutcome as aX, KodaXTaskCapabilityHint as aa, KodaXTaskContract as ab, KodaXTaskEvidenceArtifact as ac, KodaXTaskEvidenceBundle as ad, KodaXTaskEvidenceEntry as ae, KodaXTaskRole as af, KodaXTaskRoleAssignment as ag, KodaXTaskStatus as ah, KodaXTaskSurface as ai, KodaXTaskToolPolicy as aj, KodaXTaskVerificationContract as ak, KodaXTaskVerificationCriterion as al, KodaXTaskWorkItem as am, KodaXTimeoutConfig as an, KodaXToolEventMeta as ao, KodaXToolExecutionContext as ap, KodaXVerificationScorecard as aq, KodaXVerificationScorecardCriterion as ar, KodaXVideoInputArtifact as as, KodaXVideoMediaType as at, KodaXWorkflowEventMeta as au, KodaXWorkflowTimeoutConfig as av, LspServerInfo as ax, LspServiceConfig as az, BashPrefixResult as b, BoundExtensionRuntimeController as c, ChildSnapshotEvent as d, CreateBashPrefixExtractorOptions as e, ExtractCommandPrefixOptions as f, GoalCompleteResult as g, GoalCreateInput as h, GoalLifecycleContext as i, GoalRuntimeBinding as j, GoalRuntimeBindingDeps as k, GoalToolsContext as l, KodaXAgentMode as m, KodaXBudgetDisclosureZone as n, KodaXBudgetExtensionRequest as o, KodaXChildAgentResult as p, KodaXChildContextBundle as q, KodaXChildExecutionResult as r, KodaXCompactionOverride as s, KodaXContextOptions as t, KodaXContextTokenSnapshot as u, KodaXEvents as v, KodaXFileInputArtifact as w, KodaXImageInputArtifact as x, KodaXImageMediaType as y, KodaXInputArtifact as z };
3373
+ export { BASH_POLICY_SPEC as B, LSP_SERVERS as aw, LspService as ay, buildGoalRuntimeBinding as b1, createBashPrefixExtractor as b2, decideWorkflowInvocation as b3, extractCommandPrefix as b4, getDefaultLspService as b5, makeDisabledGoalToolsContext as b6, providerResilienceConfigFromTimeouts as b7, shutdownDefaultLspService as b8, withGoalBeforeNextTurn as b9, withGoalStopHook as ba, workflowStartOutcomeConsumesTurn as bb };
3374
+ export type { KodaXRuntimeVerificationContract as $, KodaXManagedTask as A, CapabilityRuntimeContract as C, DiagnosticsRequest as D, ExtensionRuntimeContract as E, FailureStage as F, GoalBlockedResult as G, KodaXManagedTaskRuntimeState as H, KodaXManagedTaskStatusEvent as I, KodaXManualSource as J, KodaXActivityEventMeta as K, KodaXManualTopic as L, KodaXManualTopicId as M, KodaXManualTopicInput as N, KodaXMemoryStrategy as O, KodaXOptions as P, KodaXOrchestrationVerdict as Q, KodaXParentReductionContract as R, KodaXProviderPolicyHints as S, KodaXRepoIntelligenceCapability as T, KodaXRepoIntelligenceMode as U, KodaXRepoIntelligenceResolvedMode as V, KodaXRepoIntelligenceTrace as W, KodaXRepoIntelligenceTraceEvent as X, KodaXRepoRoutingSignals as Y, KodaXResult as Z, KodaXRoleRoundSummary as _, BashPrefixExtractor as a, WorkflowToolHostResult as a$, KodaXSelfManualConfig as a0, KodaXSessionControl as a1, KodaXSessionMutators as a2, KodaXSessionOptions as a3, KodaXSidecarMessageEvent as a4, KodaXSkillDynamicContextPolicy as a5, KodaXSkillInvocationContext as a6, KodaXSkillMap as a7, KodaXSkillProjectionConfidence as a8, KodaXTaskCapabilityHint as a9, ProviderExecutionState as aA, ProviderRecoveryEvent as aB, ProviderResilienceConfig as aC, ProviderResiliencePolicy as aD, RecoveryAction as aE, RecoveryDecision as aF, RecoveryLadderStep as aG, RecoveryResult as aH, ResilienceClassification as aI, ResilienceErrorClass as aJ, ResolveKodaXManualInput as aK, ResolveKodaXManualOptions as aL, ResolveKodaXManualResult as aM, RuntimeDefaultsSnapshot as aN, TodoItem as aO, TodoList as aP, TodoStatus as aQ, ToolSideEffect as aR, WorkflowHostPolicy as aS, WorkflowInvocationAction as aT, WorkflowInvocationPolicyDecision as aU, WorkflowInvocationPolicyInput as aV, WorkflowInvocationSource as aW, WorkflowRunProgressView as aX, WorkflowStartOutcome as aY, WorkflowToolHost as aZ, WorkflowToolHostInlineInput as a_, KodaXTaskContract as aa, KodaXTaskEvidenceArtifact as ab, KodaXTaskEvidenceBundle as ac, KodaXTaskEvidenceEntry as ad, KodaXTaskRole as ae, KodaXTaskRoleAssignment as af, KodaXTaskStatus as ag, KodaXTaskSurface as ah, KodaXTaskToolPolicy as ai, KodaXTaskVerificationContract as aj, KodaXTaskVerificationCriterion as ak, KodaXTaskWorkItem as al, KodaXTimeoutConfig as am, KodaXToolEventMeta as an, KodaXToolExecutionContext as ao, KodaXToolVisibilityMeta as ap, KodaXToolVisibilityPolicy as aq, KodaXVerificationScorecard as ar, KodaXVerificationScorecardCriterion as as, KodaXWorkflowAgentDigestEvent as at, KodaXWorkflowEventMeta as au, KodaXWorkflowTimeoutConfig as av, LspServerInfo as ax, LspServiceConfig as az, BashPrefixResult as b, WorkflowToolHostStartResult as b0, BoundExtensionRuntimeController as c, ChildSnapshotEvent as d, CreateBashPrefixExtractorOptions as e, ExtractCommandPrefixOptions as f, GoalCompleteResult as g, GoalCreateInput as h, GoalLifecycleContext as i, GoalRuntimeBinding as j, GoalRuntimeBindingDeps as k, GoalToolsContext as l, KodaXAgentMode as m, KodaXAgentProfile as n, KodaXBudgetDisclosureZone as o, KodaXBudgetExtensionRequest as p, KodaXChildAgentResult as q, KodaXChildContextBundle as r, KodaXChildExecutionResult as s, KodaXCompactionOverride as t, KodaXContextOptions as u, KodaXContextTokenSnapshot as v, KodaXEffectiveTaskConfig as w, KodaXEvents as x, KodaXManagedBudgetSnapshot as y, KodaXManagedProtocolPayload as z };