@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.
- package/CHANGELOG.md +2032 -1920
- package/README.md +1228 -1219
- package/README_CN.md +647 -638
- package/dist/chunks/agent-QQCRBU4C.js +2 -0
- package/dist/chunks/argument-completer-7Q2T4YWA.js +2 -0
- package/dist/chunks/{chunk-LZKGOR2C.js → chunk-2UUOFT3Z.js} +1 -1
- package/dist/chunks/chunk-5GPJ6MB5.js +405 -0
- package/dist/chunks/chunk-BEXLPFFB.js +7 -0
- package/dist/chunks/chunk-D6QVXQNI.js +1 -0
- package/dist/chunks/chunk-D7RENPQQ.js +322 -0
- package/dist/chunks/chunk-PRIBJN5E.js +683 -0
- package/dist/chunks/chunk-S4GVQO3W.js +31 -0
- package/dist/chunks/chunk-SDSLWDAZ.js +17 -0
- package/dist/chunks/chunk-SVEJFERZ.js +326 -0
- package/dist/chunks/chunk-TBXP7FEG.js +52 -0
- package/dist/chunks/chunk-UA744TZM.js +2 -0
- package/dist/chunks/{chunk-YSVPF6SN.js → chunk-UXQILGRX.js} +262 -259
- package/dist/chunks/{chunk-4SHP3M67.js → chunk-YADBB5GN.js} +1 -1
- package/dist/chunks/chunk-Z23LK3IV.js +310 -0
- package/dist/chunks/chunk-Z3ZXV3DZ.js +18 -0
- package/dist/chunks/compaction-config-GQIPCVFD.js +2 -0
- package/dist/chunks/{construction-bootstrap-55B7Q5RX.js → construction-bootstrap-YON4ZEMO.js} +1 -1
- package/dist/chunks/dist-73L4OYPD.js +2 -0
- package/dist/chunks/dist-EZXBR6NW.js +2 -0
- package/dist/chunks/host-LO6ZNTMV.js +2 -0
- package/dist/chunks/paste-4THGP5XW.js +2 -0
- package/dist/chunks/run-manager-HTLXKU66.js +2 -0
- package/dist/chunks/utils-5XVW33SY.js +2 -0
- package/dist/index.d.ts +15 -14
- package/dist/index.js +2 -2
- package/dist/kodax_cli.js +1222 -1047
- package/dist/provider-capabilities.json +971 -986
- package/dist/sdk-agent.d.ts +156 -14
- package/dist/sdk-agent.js +1 -1
- package/dist/sdk-coding.d.ts +253 -188
- package/dist/sdk-coding.js +1 -1
- package/dist/sdk-llm.d.ts +66 -43
- package/dist/sdk-llm.js +1 -1
- package/dist/sdk-mcp.js +1 -1
- package/dist/sdk-media.d.ts +18 -2
- package/dist/sdk-media.js +1 -1
- package/dist/sdk-repl.d.ts +21 -22
- package/dist/sdk-repl.js +2 -2
- package/dist/sdk-session.d.ts +8 -7
- package/dist/sdk-session.js +1 -1
- package/dist/sdk-skills.d.ts +4 -231
- package/dist/sdk-skills.js +1 -1
- package/dist/types-chunks/{base.d-BnjQrSVf.d.ts → base.d-BA9Doaj_.d.ts} +3 -3
- package/dist/types-chunks/{bash-prefix-extractor.d-BgvMbfq6.d.ts → bash-prefix-extractor.d-BNdpV4Cf.d.ts} +515 -69
- package/dist/types-chunks/capability-learning.d-DRV80ISB.d.ts +29 -0
- package/dist/types-chunks/{cost-tracker.d-wRtyEW9d.d.ts → cost-tracker.d-CBLk1fiD.d.ts} +24 -2
- package/dist/types-chunks/{guardrail.d-C1DhxnvC.d.ts → guardrail.d-CNdKuSD_.d.ts} +4 -4
- package/dist/types-chunks/{process.d-BZncyzEj.d.ts → process.d-BOrAxjvM.d.ts} +188 -15
- package/dist/types-chunks/{resolver.d-ZvKQgl0X.d.ts → resolver.d-DFAKKUvt.d.ts} +87 -4
- package/dist/types-chunks/{capsule.d-DwJp5r63.d.ts → run-manager.d-CsJC9zYf.d.ts} +113 -5
- package/dist/types-chunks/{sdk-session-DAScB0rW.d.ts → sdk-session-ByZlwgdM.d.ts} +83 -9
- package/dist/types-chunks/{storage.d-CPvn9qI0.d.ts → storage.d-DHL3XpAL.d.ts} +2 -2
- package/dist/types-chunks/{guardrail.d-BP3yyr6u.d.ts → types.d-CE_Ter29.d.ts} +125 -3
- package/dist/types-chunks/{types.d-6VOXvF88.d.ts → types.d-Ci5YPFEh.d.ts} +39 -5
- package/dist/types-chunks/types.d-vJExiRje.d.ts +232 -0
- package/dist/types-chunks/{utils.d-CpgVIjYZ.d.ts → utils.d-D9FHU4wB.d.ts} +84 -6
- package/package.json +2 -2
- package/dist/chunks/agent-EHWQZA4C.js +0 -2
- package/dist/chunks/argument-completer-AYDAYGKL.js +0 -2
- package/dist/chunks/chunk-3WWPJGPQ.js +0 -2
- package/dist/chunks/chunk-KN6IJMTB.js +0 -636
- package/dist/chunks/chunk-MJFPFRGK.js +0 -423
- package/dist/chunks/chunk-N2N2W3AQ.js +0 -584
- package/dist/chunks/chunk-PCPFLPS4.js +0 -5
- package/dist/chunks/chunk-TCLSPUTR.js +0 -31
- package/dist/chunks/chunk-VACH6QWN.js +0 -315
- package/dist/chunks/compaction-config-TLDMFMZO.js +0 -2
- package/dist/chunks/dist-IE4HVWP7.js +0 -2
- package/dist/chunks/dist-IKOK2MJQ.js +0 -2
- package/dist/chunks/paste-WTL2XN7P.js +0 -2
- package/dist/chunks/utils-EJ2VCRTC.js +0 -2
- package/dist/types-chunks/types.d-D8WcfrOD.d.ts +0 -143
|
@@ -1,9 +1,10 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { Z as KodaXTokenUsage, j as KodaXMessage, a6 as KodaXWireReasoningEffort,
|
|
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-
|
|
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'
|
|
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
|
|
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
|
|
1445
|
-
* reasoning-effort value.
|
|
1446
|
-
* the rung is narrowed out of the ladder and never offered/sent
|
|
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
|
-
|
|
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
|
|
2127
|
-
* re-brands the routing rule + scope anchor. Topics are still
|
|
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
|
-
|
|
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,
|
|
2928
|
-
export type {
|
|
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 };
|