@xzzpig/pi-subagents 0.13.0 → 0.15.0

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 (202) hide show
  1. package/CHANGELOG.md +243 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +93 -15
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +67 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +19 -0
  19. package/node_modules/@xzzpig/pi-components/README.md +28 -0
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +46 -4
  21. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +65 -17
  22. package/node_modules/@xzzpig/pi-components/package.json +1 -1
  23. package/node_modules/@xzzpig/pi-components/src/transcript.ts +107 -14
  24. package/package.json +10 -5
  25. package/prompts/parallel-review.md +1 -1
  26. package/runner-peer-loader.mjs +24 -0
  27. package/runner-peer-preload.mjs +36 -0
  28. package/skills/pi-subagents/SKILL.md +34 -22
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  30. package/skills/pi-subagents/references/execution-controls.md +27 -8
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  33. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  34. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  35. package/src/agents/advertised-agent-prompt.ts +94 -0
  36. package/src/agents/agent-management.ts +71 -59
  37. package/src/agents/agent-serializer.ts +6 -3
  38. package/src/agents/agents.ts +198 -72
  39. package/src/agents/builtin-names.ts +1 -0
  40. package/src/agents/chain-serializer.ts +5 -0
  41. package/src/agents/runtime-agent-registry.ts +7 -6
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +110 -71
  44. package/src/api/required-child-extensions.ts +6 -0
  45. package/src/api/shared-types.ts +3 -1
  46. package/src/api/workflow-resources.ts +6 -0
  47. package/src/extension/config.ts +14 -37
  48. package/src/extension/fanout-child.ts +68 -5
  49. package/src/extension/herdr-pi-bridge.ts +164 -0
  50. package/src/extension/index.ts +141 -51
  51. package/src/extension/public-execution.ts +7 -6
  52. package/src/extension/rpc.ts +8 -21
  53. package/src/extension/schemas.ts +86 -84
  54. package/src/extension/tool-description.ts +32 -79
  55. package/src/inspectors/actions.ts +148 -0
  56. package/src/inspectors/ghostty/actions.ts +74 -0
  57. package/src/inspectors/ghostty/plugin.ts +17 -0
  58. package/src/inspectors/herdr/actions.ts +99 -179
  59. package/src/inspectors/herdr/plugin.ts +20 -0
  60. package/src/inspectors/herdr/project-panes.ts +4 -1
  61. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  62. package/src/inspectors/plugins.ts +8 -0
  63. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  64. package/src/inspectors/types.ts +51 -0
  65. package/src/integrations/pi-web-session-liveness.ts +73 -0
  66. package/src/intercom/intercom-bridge.ts +50 -8
  67. package/src/intercom/native-supervisor-channel.ts +142 -115
  68. package/src/intercom/supervisor-ui.ts +3 -2
  69. package/src/missions/workflow-state.ts +37 -16
  70. package/src/policy/authority.ts +4 -0
  71. package/src/profiles/profiles.ts +12 -6
  72. package/src/runs/background/active-async-capacity.ts +22 -18
  73. package/src/runs/background/active-run-index.ts +17 -1
  74. package/src/runs/background/async-execution.ts +359 -176
  75. package/src/runs/background/async-job-tracker.ts +41 -7
  76. package/src/runs/background/async-resume.ts +19 -12
  77. package/src/runs/background/async-retention.ts +20 -0
  78. package/src/runs/background/async-status-snapshot.ts +10 -12
  79. package/src/runs/background/async-status.ts +32 -13
  80. package/src/runs/background/auto-drain.ts +59 -35
  81. package/src/runs/background/binary-bootstrap.ts +38 -0
  82. package/src/runs/background/chain-append.ts +1 -1
  83. package/src/runs/background/chain-root-attachment.ts +22 -33
  84. package/src/runs/background/control-channel.ts +78 -44
  85. package/src/runs/background/fleet-view.ts +30 -2
  86. package/src/runs/background/notify.ts +193 -19
  87. package/src/runs/background/owned-process-tree.ts +35 -8
  88. package/src/runs/background/process-terminal.ts +23 -23
  89. package/src/runs/background/result-files.ts +8 -4
  90. package/src/runs/background/result-watcher.ts +19 -2
  91. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  92. package/src/runs/background/run-child-session.ts +118 -41
  93. package/src/runs/background/run-status.ts +78 -5
  94. package/src/runs/background/runner-aliases.ts +22 -5
  95. package/src/runs/background/runner-child-launch.ts +93 -0
  96. package/src/runs/background/runner-child-sessions.ts +5 -4
  97. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  98. package/src/runs/background/scheduled-runs.ts +51 -18
  99. package/src/runs/background/stale-run-reconciler.ts +38 -12
  100. package/src/runs/background/steering.ts +20 -2
  101. package/src/runs/background/subagent-runner.ts +766 -432
  102. package/src/runs/background/subagent-wait.ts +179 -28
  103. package/src/runs/background/wait-completions.ts +79 -27
  104. package/src/runs/background/wait-subscriptions.ts +9 -3
  105. package/src/runs/background/wait-tool.ts +5 -3
  106. package/src/runs/foreground/async-steering-action.ts +37 -7
  107. package/src/runs/foreground/async-stop-action.ts +93 -3
  108. package/src/runs/foreground/execution.ts +174 -194
  109. package/src/runs/foreground/foreground-history.ts +5 -2
  110. package/src/runs/foreground/prompt-audit.ts +12 -6
  111. package/src/runs/foreground/subagent-executor.ts +896 -397
  112. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  113. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  114. package/src/runs/shared/acceptance.ts +54 -14
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +172 -78
  117. package/src/runs/shared/capability-ceiling.ts +2 -0
  118. package/src/runs/shared/child-hooks.ts +167 -3
  119. package/src/runs/shared/child-launch-plan.ts +15 -3
  120. package/src/runs/shared/child-launch.ts +44 -16
  121. package/src/runs/shared/child-lifecycle.ts +6 -3
  122. package/src/runs/shared/child-runtime-config.ts +8 -1
  123. package/src/runs/shared/child-session.ts +130 -24
  124. package/src/runs/shared/child-tool-plan.ts +145 -14
  125. package/src/runs/shared/completion-evidence.ts +2 -2
  126. package/src/runs/shared/completion-guard.ts +6 -3
  127. package/src/runs/shared/dynamic-fanout.ts +2 -2
  128. package/src/runs/shared/effective-system-prompt.ts +33 -0
  129. package/src/runs/shared/external-cli-contract.ts +11 -1
  130. package/src/runs/shared/external-cli-preflight.ts +6 -2
  131. package/src/runs/shared/external-cli-runner.ts +9 -7
  132. package/src/runs/shared/herdr-connection.ts +134 -0
  133. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  134. package/src/runs/shared/herdr-machine.ts +279 -0
  135. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  136. package/src/runs/shared/herdr-placed-run.ts +263 -0
  137. package/src/runs/shared/host-step-status.ts +11 -11
  138. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  139. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  140. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  141. package/src/runs/shared/model-scope.ts +1 -1
  142. package/src/runs/shared/nested-events.ts +19 -10
  143. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  144. package/src/runs/shared/parallel-handoff.ts +57 -12
  145. package/src/runs/shared/parallel-utils.ts +10 -4
  146. package/src/runs/shared/pi-spawn.ts +10 -0
  147. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  148. package/src/runs/shared/run-fanout-budget.ts +8 -8
  149. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  150. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  151. package/src/runs/shared/task-intent.ts +46 -13
  152. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  153. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  154. package/src/runs/shared/worktree-setup-command.ts +213 -0
  155. package/src/runs/shared/worktree.ts +437 -214
  156. package/src/shared/child-cache-retention.ts +43 -0
  157. package/src/shared/fork-context.ts +15 -72
  158. package/src/shared/launch-contract.ts +70 -8
  159. package/src/shared/model-response-aliases.ts +13 -0
  160. package/src/shared/opencode-session-headers.ts +30 -0
  161. package/src/shared/pruned-fork.ts +1 -1
  162. package/src/shared/required-child-extensions.ts +81 -0
  163. package/src/shared/settings.ts +5 -2
  164. package/src/shared/shortcuts.ts +0 -4
  165. package/src/shared/types.ts +164 -90
  166. package/src/shared/utils.ts +10 -2
  167. package/src/shared/watch-strategy.ts +2 -0
  168. package/src/shared/workflow-child-permit.ts +18 -13
  169. package/src/slash/delegation-adapters.ts +3 -1
  170. package/src/slash/delegation-request.ts +14 -0
  171. package/src/slash/slash-commands.ts +2 -7
  172. package/src/slash/subagents-admin.ts +31 -14
  173. package/src/tui/fleet-native-transcript.ts +50 -6
  174. package/src/tui/fleet-status.ts +165 -20
  175. package/src/tui/fleet.ts +52 -21
  176. package/src/tui/render.ts +210 -50
  177. package/src/watchdog/child-status.ts +28 -28
  178. package/src/watchdog/lsp-diagnostics.ts +1 -1
  179. package/src/watchdog/model-selection.ts +21 -1
  180. package/src/watchdog/permission-arbiter.ts +5 -2
  181. package/src/watchdog/register-child.ts +10 -2
  182. package/src/watchdog/register-main.ts +39 -35
  183. package/src/watchdog/render.ts +1 -1
  184. package/src/watchdog/review.ts +122 -74
  185. package/src/watchdog/rules.ts +1 -1
  186. package/src/watchdog/runtime.ts +100 -27
  187. package/src/watchdog/scope.ts +1 -1
  188. package/src/watchdog/settings.ts +3 -0
  189. package/src/watchdog/tool-actions.ts +13 -12
  190. package/src/watchdog/turn-delta.ts +23 -0
  191. package/src/watchdog/types.ts +5 -3
  192. package/src/watchdog/warning-format.ts +1 -1
  193. package/src/workflows/chat-progress.ts +3 -3
  194. package/src/workflows/scripted-workflow.ts +349 -26
  195. package/src/workflows/workflow-checklist.ts +17 -20
  196. package/src/workflows/workflow-child-summary.ts +57 -8
  197. package/src/workflows/workflow-preflight.ts +19 -19
  198. package/src/workflows/workflow-receipt.ts +24 -6
  199. package/src/workflows/workflow-resources.ts +108 -22
  200. package/src/workflows/workflow-settlement.ts +3 -0
  201. package/src/runs/shared/model-exclusions.ts +0 -373
  202. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -1,6 +1,6 @@
1
- import type { AsyncJobStep, HostStepNodeV1, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../shared/types.ts";
1
+ import type { AsyncJobStep, HostStepNode, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowPreflightLane, WorkflowPreflight } from "../shared/types.ts";
2
2
  import { sanitizeDisplayText } from "../shared/display-text.ts";
3
- import { workflowPreflightLaneForRuntimeKey } from "./workflow-preflight.ts";
3
+ import { workflowPreflightLaneForRuntimeKey as laneFor } from "./workflow-preflight.ts";
4
4
 
5
5
  export type WorkflowChecklistState = "complete" | "running" | "queued" | "blocked" | "failed" | "paused" | "stopped";
6
6
 
@@ -62,12 +62,12 @@ export interface WorkflowChecklistItem {
62
62
  toolCount?: number;
63
63
  outputName?: string;
64
64
  error?: string;
65
- preflight?: WorkflowPreflightLaneV1;
65
+ preflight?: WorkflowPreflightLane;
66
66
  kind?: "child" | "host";
67
- monitorKind?: HostStepNodeV1["monitorKind"];
67
+ monitorKind?: HostStepNode["monitorKind"];
68
68
  provider?: string;
69
69
  role?: string;
70
- verdict?: HostStepNodeV1["verdict"];
70
+ verdict?: HostStepNode["verdict"];
71
71
  target?: string;
72
72
  reasonCode?: string;
73
73
  stale?: boolean;
@@ -106,8 +106,8 @@ export interface WorkflowChecklistProjection {
106
106
  export interface WorkflowChecklistInput {
107
107
  graph?: WorkflowGraphSnapshot;
108
108
  steps?: readonly WorkflowChecklistStep[] | readonly AsyncJobStep[];
109
- hostSteps?: readonly HostStepNodeV1[];
110
- preflight?: WorkflowPreflightV1;
109
+ hostSteps?: readonly HostStepNode[];
110
+ preflight?: WorkflowPreflight;
111
111
  trace?: readonly WorkflowChecklistTraceEntry[];
112
112
  now?: number;
113
113
  }
@@ -186,19 +186,15 @@ function duration(step: Pick<WorkflowChecklistStep, "durationMs" | "startedAt" |
186
186
  const startedAt = finite(step.startedAt);
187
187
  if (explicit !== undefined) return Math.max(0, explicit);
188
188
  if (startedAt === undefined) return undefined;
189
- const end = state === "running" ? now : finite(step.endedAt) ?? now;
189
+ const end = state === "running" ? now : finite(step.endedAt);
190
190
  return end === undefined ? undefined : Math.max(0, end - startedAt);
191
191
  }
192
192
 
193
- function laneFor(preflight: WorkflowPreflightV1 | undefined, key: string, preferredKeys: readonly (string | undefined)[] = []): WorkflowPreflightLaneV1 | undefined {
194
- return workflowPreflightLaneForRuntimeKey(preflight, key, preferredKeys);
195
- }
196
-
197
193
  function stepKey(step: WorkflowChecklistStep): string | undefined {
198
194
  return step.key ?? step.workflowKey ?? step.runId;
199
195
  }
200
196
 
201
- function stepItem(step: WorkflowChecklistStep, index: number, phase: string, key = stepKey(step) ?? `step-${index + 1}`, label = step.label ?? step.description ?? stepKey(step) ?? step.agent ?? key, preflight?: WorkflowPreflightLaneV1): WorkflowChecklistItem {
197
+ function stepItem(step: WorkflowChecklistStep, index: number, phase: string, key = stepKey(step) ?? `step-${index + 1}`, label = step.label ?? step.description ?? stepKey(step) ?? step.agent ?? key, preflight?: WorkflowPreflightLane): WorkflowChecklistItem {
202
198
  const state = checklistState(step);
203
199
  return {
204
200
  key: keyText(key, `step-${index + 1}`),
@@ -219,7 +215,7 @@ function stepItem(step: WorkflowChecklistStep, index: number, phase: string, key
219
215
  };
220
216
  }
221
217
 
222
- function hostItem(host: HostStepNodeV1, phase: string, key = host.id): WorkflowChecklistItem {
218
+ function hostItem(host: HostStepNode, phase: string, key = host.id): WorkflowChecklistItem {
223
219
  const state = checklistState({ status: host.state, verdict: host.verdict, stale: host.freshness?.stale });
224
220
  return {
225
221
  key: keyText(key, "host-step"),
@@ -264,7 +260,7 @@ function traceSources(trace: readonly WorkflowChecklistTraceEntry[] | undefined)
264
260
  return [...latest.values()];
265
261
  }
266
262
 
267
- function traceItem(entry: WorkflowChecklistTraceEntry, index: number, preflight: WorkflowPreflightLaneV1 | undefined): WorkflowChecklistItem {
263
+ function traceItem(entry: WorkflowChecklistTraceEntry, index: number, preflight: WorkflowPreflightLane | undefined): WorkflowChecklistItem {
268
264
  const phase = keyText(preflight?.key ?? entry.generatedLaneKey ?? entry.phase, "Workflow");
269
265
  const item = stepItem({ key: entry.key, label: entry.label, phase, agent: entry.agent, status: entry.state === "started" ? "running" : entry.state, durationMs: entry.durationMs, error: entry.error }, index, phase, entry.key, entry.label ?? entry.key, preflight);
270
266
  if (entry.operation === "host") item.kind = "host";
@@ -284,7 +280,7 @@ function add(phases: Map<string, WorkflowChecklistPhase>, phase: string, item: W
284
280
  phaseFor(phases, phase).items.push(item);
285
281
  }
286
282
 
287
- function mergeNodeStep(node: WorkflowGraphNode, step: WorkflowChecklistStep, phase: string, trace: WorkflowChecklistTraceEntry | undefined, preflight: WorkflowPreflightLaneV1 | undefined): WorkflowChecklistItem {
283
+ function mergeNodeStep(node: WorkflowGraphNode, step: WorkflowChecklistStep, phase: string, trace: WorkflowChecklistTraceEntry | undefined, preflight: WorkflowPreflightLane | undefined): WorkflowChecklistItem {
288
284
  const state = checklistState(step);
289
285
  const nodeState = checklistState({ status: node.status, acceptance: node.acceptanceStatus ? { status: node.acceptanceStatus } : undefined });
290
286
  const status = TERMINAL_STATES.has(nodeState) && !TERMINAL_STATES.has(state)
@@ -300,7 +296,7 @@ function priority(item: WorkflowChecklistItem): number {
300
296
  }
301
297
 
302
298
  function applyNow(item: WorkflowChecklistItem, now: number | undefined): WorkflowChecklistItem {
303
- return item.durationMs === undefined && item.startedAt !== undefined && now !== undefined ? { ...item, durationMs: Math.max(0, now - item.startedAt) } : item;
299
+ return item.state === "running" && item.startedAt !== undefined && now !== undefined ? { ...item, durationMs: Math.max(0, now - item.startedAt) } : item;
304
300
  }
305
301
 
306
302
  function finalize(phase: WorkflowChecklistPhase): void {
@@ -402,11 +398,12 @@ export function formatWorkflowChecklistPhase(phase: WorkflowChecklistPhase): str
402
398
  return counts.length ? `${phase.label} ${counts.join(" · ")}` : phase.label;
403
399
  }
404
400
 
405
- export function formatWorkflowChecklistBottleneck(item: WorkflowChecklistItem | undefined, options: { includeOutput?: boolean } = {}): string | undefined {
401
+ export function formatWorkflowChecklistBottleneck(item: WorkflowChecklistItem | undefined, options: { includeOutput?: boolean; includeError?: boolean } = {}): string | undefined {
406
402
  if (!item) return undefined;
407
403
  const identity = [item.label, item.agent && item.agent !== item.label ? item.agent : undefined].filter((value): value is string => Boolean(value)).join(" · ") || item.key;
408
404
  const includeOutput = options.includeOutput ?? true;
409
- const details = [item.context ? `(${item.context})` : undefined, item.currentTool ? `${item.currentTool}${item.durationMs !== undefined ? ` ${formatDurationText(item.durationMs)}` : ""}` : undefined, !item.currentTool && item.currentPath ? item.currentPath : undefined, !item.currentTool && item.durationMs !== undefined ? formatDurationText(item.durationMs) : undefined, item.toolCount !== undefined ? `${item.toolCount} tools` : undefined, includeOutput && item.outputName ? `out:${item.outputName}` : undefined, item.error ? `error:${item.error.replace(/\bOutput:/g, "output:")}` : undefined].filter((value): value is string => Boolean(value));
405
+ const includeError = options.includeError ?? true;
406
+ const details = [item.context ? `(${item.context})` : undefined, item.currentTool ? `${item.currentTool}${item.durationMs !== undefined ? ` ${formatDurationText(item.durationMs)}` : ""}` : undefined, !item.currentTool && item.currentPath ? item.currentPath : undefined, !item.currentTool && item.durationMs !== undefined ? formatDurationText(item.durationMs) : undefined, item.toolCount !== undefined ? `${item.toolCount} tools` : undefined, includeOutput && item.outputName ? `out:${item.outputName}` : undefined, includeError && item.error ? `error:${item.error.replace(/\bOutput:/g, "output:")}` : undefined].filter((value): value is string => Boolean(value));
410
407
  return [identity, ...details].join(" · ");
411
408
  }
412
409
 
@@ -433,7 +430,7 @@ export function formatWorkflowChecklistText(projection: WorkflowChecklistProject
433
430
  lines.push(`${indent} ${marker} ${formatWorkflowChecklistItem(item)}`);
434
431
  }
435
432
  }
436
- const bottleneck = formatWorkflowChecklistBottleneck(projection.bottleneck);
433
+ const bottleneck = formatWorkflowChecklistBottleneck(projection.bottleneck, { includeError: options.includeItems === false });
437
434
  if (bottleneck) lines.push(`${indent} bottleneck · ${bottleneck}`);
438
435
  return lines;
439
436
  }
@@ -1,9 +1,42 @@
1
- import type { AsyncStatus, WorkflowChildSummaryV1 } from "../shared/types.ts";
1
+ import type { AgentProgress, AsyncStatus, WorkflowChildActivity, WorkflowChildSummary } from "../shared/types.ts";
2
2
  import type { WorkflowScriptChildResult, WorkflowScriptTraceEntry } from "./scripted-workflow.ts";
3
3
 
4
4
  const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
5
5
  const TERMINAL_STATES = new Set(["completed", "failed", "paused", "stopped", "rejected", "detached"]);
6
6
  const MAX_REQUIRED_ID_BYTES = 4_096;
7
+ const ACTIVITY_COUNTERS = ["currentToolStartedAt", "lastActivityAt", "durationMs", "toolCount", "turnCount", "tokens", "inputTokens", "outputTokens"] as const;
8
+ type WorkflowChildLiveProgress = WorkflowChildActivity & Pick<AgentProgress, "agent" | "sessionName" | "model" | "thinking">;
9
+
10
+ export function workflowChildProgress(progress: AgentProgress): WorkflowChildLiveProgress {
11
+ return {
12
+ ...workflowChildActivity(progress),
13
+ agent: bounded(progress.agent, 256) ?? "",
14
+ ...(bounded(progress.sessionName, 256) ? { sessionName: progress.sessionName } : {}),
15
+ ...(bounded(progress.model, 256) ? { model: progress.model } : {}),
16
+ ...(bounded(progress.thinking, 32) ? { thinking: progress.thinking } : {}),
17
+ };
18
+ }
19
+
20
+ /** Fixed field count and a 256 UTF-8 byte tool name keep JSON activity below 2 KiB, including escaping. */
21
+ export function workflowChildActivity(progress: WorkflowChildActivity): WorkflowChildActivity {
22
+ const activity: WorkflowChildActivity = {};
23
+ if (bounded(progress.currentTool, 256)) activity.currentTool = progress.currentTool;
24
+ for (const field of ACTIVITY_COUNTERS) {
25
+ const value = progress[field];
26
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) activity[field] = value;
27
+ }
28
+ return activity;
29
+ }
30
+
31
+ function parseActivity(value: unknown): WorkflowChildActivity | undefined {
32
+ if (value === undefined) return undefined;
33
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("workflowChildren child activity is invalid.");
34
+ const input = value as Record<string, unknown>;
35
+ for (const [key, value] of Object.entries(input)) {
36
+ if (key === "currentTool" ? !bounded(value, 256) : !ACTIVITY_COUNTERS.includes(key as typeof ACTIVITY_COUNTERS[number]) || typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error("workflowChildren child activity is invalid.");
37
+ }
38
+ return { ...input } as WorkflowChildActivity;
39
+ }
7
40
 
8
41
  function bounded(value: unknown, maxBytes: number): string | undefined {
9
42
  if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value, "utf8") > maxBytes) return undefined;
@@ -19,13 +52,15 @@ function requiredId(value: string, label: string): string {
19
52
  export function workflowChildSummary(input: {
20
53
  parentToolCallId: string;
21
54
  workflowRunId: string;
22
- workflowState: WorkflowChildSummaryV1["workflowState"];
55
+ workflowState: WorkflowChildSummary["workflowState"];
23
56
  inventoryComplete: boolean;
24
57
  trace?: WorkflowScriptTraceEntry[];
25
58
  children?: WorkflowScriptChildResult[];
26
59
  steps?: NonNullable<AsyncStatus["steps"]>;
27
- }): WorkflowChildSummaryV1 {
28
- const rows = new Map<string, WorkflowChildSummaryV1["children"][number]>();
60
+ /** In-memory snapshots from synchronous child callbacks, keyed by workflow key. */
61
+ progress?: ReadonlyMap<string, WorkflowChildLiveProgress>;
62
+ }): WorkflowChildSummary {
63
+ const rows = new Map<string, WorkflowChildSummary["children"][number]>();
29
64
  for (const entry of input.trace ?? []) {
30
65
  if (entry.operation !== "run" || !KEY_PATTERN.test(entry.key)) continue;
31
66
  const previous = rows.get(entry.key);
@@ -83,6 +118,18 @@ export function workflowChildSummary(input: {
83
118
  if (!TERMINAL_STATES.has(row.state)) rows.set(key, { ...row, state: input.workflowState === "stopped" ? "stopped" : "failed" });
84
119
  }
85
120
  }
121
+ for (const [key, progress] of input.progress ?? []) {
122
+ const row = rows.get(key);
123
+ if (!row || row.state !== "running") continue;
124
+ rows.set(key, {
125
+ ...row,
126
+ ...(bounded(progress.agent, 256) ? { agent: progress.agent } : {}),
127
+ ...(bounded(progress.sessionName, 256) ? { sessionName: progress.sessionName } : {}),
128
+ ...(bounded(progress.model, 256) ? { model: progress.model } : {}),
129
+ ...(bounded(progress.thinking, 32) ? { thinking: progress.thinking } : {}),
130
+ activity: workflowChildActivity(progress),
131
+ });
132
+ }
86
133
  return {
87
134
  version: 1,
88
135
  parentToolCallId: requiredId(input.parentToolCallId, "parentToolCallId"),
@@ -93,7 +140,7 @@ export function workflowChildSummary(input: {
93
140
  };
94
141
  }
95
142
 
96
- export function parseWorkflowChildSummary(value: unknown): WorkflowChildSummaryV1 | undefined {
143
+ export function parseWorkflowChildSummary(value: unknown): WorkflowChildSummary | undefined {
97
144
  if (value === undefined) return undefined;
98
145
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("workflowChildren must be an object.");
99
146
  const input = value as Record<string, unknown>;
@@ -102,17 +149,19 @@ export function parseWorkflowChildSummary(value: unknown): WorkflowChildSummaryV
102
149
  if (input.version !== 1 || typeof input.inventoryComplete !== "boolean" || !Array.isArray(input.children)) throw new Error("workflowChildren is invalid.");
103
150
  const workflowState = input.workflowState;
104
151
  if (workflowState !== "queued" && workflowState !== "running" && workflowState !== "completed" && workflowState !== "failed" && workflowState !== "paused" && workflowState !== "stopped") throw new Error("workflowChildren.workflowState is invalid.");
105
- const children = input.children.map((row): WorkflowChildSummaryV1["children"][number] => {
152
+ const children = input.children.map((row): WorkflowChildSummary["children"][number] => {
106
153
  if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error("workflowChildren child row is invalid.");
107
154
  const child = row as Record<string, unknown>;
108
- if (Object.keys(child).some((key) => !["childId", "runId", "agent", "sessionName", "model", "thinking", "state"].includes(key))) throw new Error("workflowChildren child row has unsupported fields.");
155
+ if (Object.keys(child).some((key) => !["childId", "runId", "agent", "sessionName", "model", "thinking", "state", "activity"].includes(key))) throw new Error("workflowChildren child row has unsupported fields.");
109
156
  if (typeof child.childId !== "string" || !KEY_PATTERN.test(child.childId)) throw new Error("workflowChildren childId is invalid.");
110
157
  const state = child.state;
111
158
  if (state !== "pending" && state !== "running" && state !== "completed" && state !== "failed" && state !== "paused" && state !== "stopped" && state !== "rejected" && state !== "detached") throw new Error("workflowChildren child state is invalid.");
112
159
  for (const [field, maxBytes] of [["runId", 256], ["agent", 256], ["sessionName", 256], ["model", 256], ["thinking", 32]] as const) {
113
160
  if (child[field] !== undefined && bounded(child[field], maxBytes) === undefined) throw new Error(`workflowChildren child ${field} is invalid.`);
114
161
  }
115
- return { childId: child.childId, state, ...(child.runId ? { runId: child.runId as string } : {}), ...(child.agent ? { agent: child.agent as string } : {}), ...(child.sessionName ? { sessionName: child.sessionName as string } : {}), ...(child.model ? { model: child.model as string } : {}), ...(child.thinking ? { thinking: child.thinking as string } : {}) };
162
+ const activity = parseActivity(child.activity);
163
+ if (activity && state !== "running") throw new Error("workflowChildren child activity requires running state.");
164
+ return { childId: child.childId, state, ...(activity ? { activity } : {}), ...(child.runId ? { runId: child.runId as string } : {}), ...(child.agent ? { agent: child.agent as string } : {}), ...(child.sessionName ? { sessionName: child.sessionName as string } : {}), ...(child.model ? { model: child.model as string } : {}), ...(child.thinking ? { thinking: child.thinking as string } : {}) };
116
165
  });
117
166
  if (new Set(children.map((child) => child.childId)).size !== children.length) throw new Error("workflowChildren has duplicate childId values.");
118
167
  if (typeof input.parentToolCallId !== "string") throw new Error("workflowChildren.parentToolCallId is invalid.");
@@ -1,4 +1,4 @@
1
- import type { WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../shared/types.ts";
1
+ import type { WorkflowPreflightLane, WorkflowPreflight } from "../shared/types.ts";
2
2
 
3
3
  export const WORKFLOW_PREFLIGHT_VERSION = 1 as const;
4
4
  export const WORKFLOW_PREFLIGHT_MAX_LANES = 64;
@@ -11,7 +11,7 @@ export const WORKFLOW_PREFLIGHT_MAX_WARNINGS = 16;
11
11
  const WORKFLOW_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
12
12
  const PREFLIGHT_FIELDS = new Set(["version", "coverage", "lanes"]);
13
13
  const LANE_FIELDS = new Set(["key", "mode", "decision", "claims", "expectedOutput", "independence"]);
14
- const PREFLIGHT_MODES = new Set<WorkflowPreflightLaneV1["mode"]>(["mutation", "review", "scout", "gate"]);
14
+ const PREFLIGHT_MODES = new Set<WorkflowPreflightLane["mode"]>(["mutation", "review", "scout", "gate"]);
15
15
 
16
16
  type WorkflowTraceLike = {
17
17
  operation: string;
@@ -23,7 +23,7 @@ type WorkflowTraceLike = {
23
23
 
24
24
  export interface WorkflowPreflightValidationResult {
25
25
  ok: boolean;
26
- preflight?: WorkflowPreflightV1;
26
+ preflight?: WorkflowPreflight;
27
27
  error?: string;
28
28
  }
29
29
 
@@ -60,18 +60,18 @@ function normalizeDisplayString(value: unknown, path: string): string {
60
60
  return normalized;
61
61
  }
62
62
 
63
- function normalizeLane(value: unknown, index: number): WorkflowPreflightLaneV1 {
63
+ function normalizeLane(value: unknown, index: number): WorkflowPreflightLane {
64
64
  const path = `preflight.lanes[${index}]`;
65
65
  assertPlainObject(value, path);
66
66
  assertKnownFields(value, LANE_FIELDS, path);
67
67
  const key = normalizeDisplayString(value.key, `${path}.key`);
68
68
  if (!WORKFLOW_KEY_PATTERN.test(key)) throw new Error(`${path}.key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.`);
69
- let mode: WorkflowPreflightLaneV1["mode"];
69
+ let mode: WorkflowPreflightLane["mode"];
70
70
  if (value.mode !== undefined) {
71
- if (typeof value.mode !== "string" || !PREFLIGHT_MODES.has(value.mode as WorkflowPreflightLaneV1["mode"])) {
71
+ if (typeof value.mode !== "string" || !PREFLIGHT_MODES.has(value.mode as WorkflowPreflightLane["mode"])) {
72
72
  throw new Error(`${path}.mode must be one of: mutation, review, scout, gate.`);
73
73
  }
74
- mode = value.mode as WorkflowPreflightLaneV1["mode"];
74
+ mode = value.mode as WorkflowPreflightLane["mode"];
75
75
  }
76
76
  let claims: string[] | undefined;
77
77
  if (value.claims !== undefined) {
@@ -97,7 +97,7 @@ function normalizeLane(value: unknown, index: number): WorkflowPreflightLaneV1 {
97
97
  * independent of workflowScript parsing: callers may describe dynamic fanout
98
98
  * without making the metadata a second execution graph.
99
99
  */
100
- export function normalizeWorkflowPreflight(input: unknown): WorkflowPreflightV1 | undefined {
100
+ export function normalizeWorkflowPreflight(input: unknown): WorkflowPreflight | undefined {
101
101
  if (input === undefined) return undefined;
102
102
  assertPlainObject(input, "preflight");
103
103
  assertKnownFields(input, PREFLIGHT_FIELDS, "preflight");
@@ -115,7 +115,7 @@ export function normalizeWorkflowPreflight(input: unknown): WorkflowPreflightV1
115
115
  if (seenKeys.has(lane.key)) throw new Error(`preflight.lanes contains duplicate key '${lane.key}'.`);
116
116
  seenKeys.add(lane.key);
117
117
  }
118
- const normalized = { version: WORKFLOW_PREFLIGHT_VERSION, coverage, lanes } satisfies WorkflowPreflightV1;
118
+ const normalized = { version: WORKFLOW_PREFLIGHT_VERSION, coverage, lanes } satisfies WorkflowPreflight;
119
119
  const depth = 1 + (lanes.length > 0 ? 1 : 0) + (lanes.some((lane) => lane.claims !== undefined) ? 1 : 0);
120
120
  if (depth > WORKFLOW_PREFLIGHT_MAX_DEPTH) throw new Error(`preflight exceeds the maximum nesting depth of ${WORKFLOW_PREFLIGHT_MAX_DEPTH}.`);
121
121
  const bytes = Buffer.byteLength(JSON.stringify(normalized), "utf8");
@@ -138,7 +138,7 @@ function warningLimit(messages: string[]): string[] {
138
138
  return [...messages.slice(0, WORKFLOW_PREFLIGHT_MAX_WARNINGS - 1), `Preflight advisory: ${omitted} additional mismatch warning(s) omitted.`];
139
139
  }
140
140
 
141
- function declaredKeys(preflight: WorkflowPreflightV1): Set<string> {
141
+ function declaredKeys(preflight: WorkflowPreflight): Set<string> {
142
142
  return new Set(preflight.lanes.map((lane) => lane.key));
143
143
  }
144
144
 
@@ -152,15 +152,15 @@ export function workflowKeyMatchesPreflightLane(key: string, laneKey: string, ge
152
152
 
153
153
  /** Select the most specific advisory lane without allowing declaration order to override an exact runtime key. */
154
154
  export function workflowPreflightLaneForRuntimeKey(
155
- preflight: WorkflowPreflightV1 | undefined,
155
+ preflight: WorkflowPreflight | undefined,
156
156
  key: string,
157
157
  preferredKeys: readonly (string | undefined)[] = [],
158
- ): WorkflowPreflightLaneV1 | undefined {
158
+ ): WorkflowPreflightLane | undefined {
159
159
  const lanes = preflight?.lanes;
160
160
  if (!lanes) return undefined;
161
161
  const exact = lanes.find((lane) => lane.key === key);
162
162
  if (exact) return exact;
163
- let closestRoot: WorkflowPreflightLaneV1 | undefined;
163
+ let closestRoot: WorkflowPreflightLane | undefined;
164
164
  for (const lane of lanes) {
165
165
  if (key.startsWith(`${lane.key}.`) && (!closestRoot || lane.key.length > closestRoot.key.length)) closestRoot = lane;
166
166
  }
@@ -203,7 +203,7 @@ function unlaunchedWarning(key: string): string {
203
203
 
204
204
  /** Return bounded advisory mismatch warnings; these never reject a child launch. */
205
205
  export function workflowPreflightWarnings(
206
- preflight: WorkflowPreflightV1 | undefined,
206
+ preflight: WorkflowPreflight | undefined,
207
207
  trace: readonly WorkflowTraceLike[],
208
208
  options: { settled?: boolean } = {},
209
209
  ): string[] {
@@ -218,7 +218,7 @@ export function workflowPreflightWarnings(
218
218
  }
219
219
 
220
220
  /** Attach the first undeclared-key warning to its first trace row for status/debug views. */
221
- export function annotateWorkflowPreflightTrace<T extends WorkflowTraceLike>(trace: readonly T[], preflight: WorkflowPreflightV1 | undefined): T[] {
221
+ export function annotateWorkflowPreflightTrace<T extends WorkflowTraceLike>(trace: readonly T[], preflight: WorkflowPreflight | undefined): T[] {
222
222
  if (!preflight) return [...trace];
223
223
  const declared = declaredKeys(preflight);
224
224
  const warned = new Set<string>();
@@ -235,14 +235,14 @@ function laneCell(value: string | undefined): string {
235
235
 
236
236
  const WORKFLOW_PREFLIGHT_PLAN_LABEL_LENGTH = 96;
237
237
 
238
- function planLaneLabel(lane: WorkflowPreflightLaneV1): string {
238
+ function planLaneLabel(lane: WorkflowPreflightLane): string {
239
239
  const value = lane.decision?.trim() || lane.key;
240
240
  if (value.length <= WORKFLOW_PREFLIGHT_PLAN_LABEL_LENGTH) return value;
241
241
  return `${value.slice(0, WORKFLOW_PREFLIGHT_PLAN_LABEL_LENGTH - 1).trimEnd()}…`;
242
242
  }
243
243
 
244
244
  /** Render the detailed bounded table reserved for tool output and expanded/debug views. */
245
- export function formatWorkflowPreflight(preflight: WorkflowPreflightV1 | undefined, options: { indent?: string } = {}): string {
245
+ export function formatWorkflowPreflight(preflight: WorkflowPreflight | undefined, options: { indent?: string } = {}): string {
246
246
  if (!preflight) return "";
247
247
  const indent = options.indent ?? "";
248
248
  const count = preflight.lanes.length;
@@ -263,7 +263,7 @@ export function formatWorkflowPreflight(preflight: WorkflowPreflightV1 | undefin
263
263
  return lines.join("\n");
264
264
  }
265
265
 
266
- export function formatWorkflowPreflightSummary(preflight: WorkflowPreflightV1 | undefined): string {
266
+ export function formatWorkflowPreflightSummary(preflight: WorkflowPreflight | undefined): string {
267
267
  if (!preflight) return "";
268
268
  const keys = preflight.lanes.slice(0, 4).map((lane) => lane.key).join(", ");
269
269
  const remainder = preflight.lanes.length > 4 ? `, +${preflight.lanes.length - 4}` : "";
@@ -271,7 +271,7 @@ export function formatWorkflowPreflightSummary(preflight: WorkflowPreflightV1 |
271
271
  }
272
272
 
273
273
  /** Render the operator-facing one-line plan shown in routine status views. */
274
- export function formatWorkflowPreflightPlanSummary(preflight: WorkflowPreflightV1 | undefined, options: { indent?: string } = {}): string {
274
+ export function formatWorkflowPreflightPlanSummary(preflight: WorkflowPreflight | undefined, options: { indent?: string } = {}): string {
275
275
  if (!preflight) return "";
276
276
  const indent = options.indent ?? "";
277
277
  const count = preflight.lanes.length;
@@ -1,7 +1,7 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
3
  import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
4
- import type { AcceptanceRecoveryMetadata, ExternalCliReceiptMetadata, WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState, WorkflowRecoveryAction, WorkflowResourceProvenanceV1, WorkflowTerminalOutcome, WorkflowTerminalResolution } from "../shared/types.ts";
4
+ import type { AcceptanceRecoveryMetadata, ExternalCliReceiptMetadata, WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState, WorkflowRecoveryAction, WorkflowResourceProvenance, WorkflowTerminalOutcome, WorkflowTerminalResolution } from "../shared/types.ts";
5
5
  import type { WorkflowReceiptResumeReference, WorkflowScriptChildResult } from "./scripted-workflow.ts";
6
6
  import { parseWorkflowChildSummary } from "./workflow-child-summary.ts";
7
7
  import { HOST_STEP_MAX_COUNT, assertUniqueHostStepIds, parseHostStepNode } from "../runs/shared/host-step-status.ts";
@@ -37,13 +37,15 @@ export function buildWorkflowReceipt(input: {
37
37
  workflowRunId: string;
38
38
  state: WorkflowReceiptState;
39
39
  children: WorkflowScriptChildResult[];
40
+ argsDigest?: string;
40
41
  hostSteps?: WorkflowReceipt["hostSteps"];
41
42
  workflowChildren?: WorkflowReceipt["workflowChildren"];
42
- resource?: WorkflowResourceProvenanceV1;
43
+ resource?: WorkflowResourceProvenance;
43
44
  terminalOutcome?: WorkflowTerminalOutcome;
44
45
  createdAt?: number;
45
46
  }): WorkflowReceipt {
46
47
  const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
48
+ if (input.argsDigest !== undefined && !/^[a-f0-9]{64}$/u.test(input.argsDigest)) throw new Error("workflow receipt argsDigest must be a lowercase SHA-256 digest.");
47
49
  if (input.workflowChildren?.workflowRunId !== undefined && input.workflowChildren.workflowRunId !== workflowRunId) throw new Error("workflowChildren workflowRunId does not match its receipt.");
48
50
  const entries: Record<string, WorkflowReceiptEntry> = Object.create(null) as Record<string, WorkflowReceiptEntry>;
49
51
  for (const child of input.children) {
@@ -75,7 +77,7 @@ export function buildWorkflowReceipt(input: {
75
77
  const hostSteps = input.hostSteps?.map((hostStep, index) => parseHostStepNode(hostStep, `workflow receipt hostSteps[${index}]`));
76
78
  if (hostSteps) assertUniqueHostStepIds(hostSteps, "workflow receipt");
77
79
  const resource = parseWorkflowResource(input.resource, "workflow receipt");
78
- return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
80
+ return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(input.argsDigest ? { argsDigest: input.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
79
81
  }
80
82
 
81
83
  export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt): string {
@@ -115,12 +117,26 @@ const EXTERNAL_CLI_CAPABILITIES = {
115
117
  extensionBindings: false,
116
118
  } as const;
117
119
 
120
+ function parseExternalCliMachine(value: unknown, label: string): void {
121
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}.machine must be an object.`);
122
+ const machine = value as Record<string, unknown>;
123
+ const unknownMachine = Object.keys(machine).filter((field) => !["provider", "id", "label", "target", "session", "cwd", "remoteGit"].includes(field));
124
+ if (unknownMachine.length > 0) throw new Error(`${label}.machine has unsupported fields: ${unknownMachine.join(", ")}.`);
125
+ if (machine.provider !== "herdr" || typeof machine.id !== "string" || !machine.id.trim() || typeof machine.target !== "string" || !machine.target.trim() || typeof machine.cwd !== "string" || !machine.cwd.trim()) throw new Error(`${label}.machine is invalid.`);
126
+ for (const field of ["label", "session"] as const) if (machine[field] !== undefined && (typeof machine[field] !== "string" || !machine[field].trim())) throw new Error(`${label}.machine.${field} is invalid.`);
127
+ if (machine.remoteGit === undefined) return;
128
+ if (!machine.remoteGit || typeof machine.remoteGit !== "object" || Array.isArray(machine.remoteGit)) throw new Error(`${label}.machine.remoteGit must be an object.`);
129
+ const remoteGit = machine.remoteGit as Record<string, unknown>;
130
+ const unknownRemoteGit = Object.keys(remoteGit).filter((field) => !["head", "branch", "dirty"].includes(field));
131
+ if (unknownRemoteGit.length > 0 || (remoteGit.head !== undefined && (typeof remoteGit.head !== "string" || !remoteGit.head.trim())) || (remoteGit.branch !== undefined && (typeof remoteGit.branch !== "string" || !remoteGit.branch.trim())) || (remoteGit.dirty !== undefined && typeof remoteGit.dirty !== "boolean")) throw new Error(`${label}.machine.remoteGit is invalid.`);
132
+ }
133
+
118
134
  function parseExternalCliReceiptMetadata(value: unknown, key: string, source: string): ExternalCliReceiptMetadata | undefined {
119
135
  if (value === undefined) return undefined;
120
136
  const label = `Invalid workflow receipt '${source}': entry '${key}' externalAdapter`;
121
137
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
122
138
  const metadata = value as Record<string, unknown>;
123
- const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
139
+ const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "machine", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
124
140
  if (unknownMetadata.length > 0) throw new Error(`${label} has unsupported fields: ${unknownMetadata.join(", ")}.`);
125
141
  const adapter = metadata.adapter;
126
142
  if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) throw new Error(`${label}.adapter must be an object.`);
@@ -136,6 +152,7 @@ function parseExternalCliReceiptMetadata(value: unknown, key: string, source: st
136
152
  for (const [capability, expected] of Object.entries(EXTERNAL_CLI_CAPABILITIES)) {
137
153
  if (capabilityRecord[capability] !== expected) throw new Error(`${label}.capabilities.${capability} is invalid.`);
138
154
  }
155
+ if (metadata.machine !== undefined) parseExternalCliMachine(metadata.machine, label);
139
156
  const safety = metadata.safety;
140
157
  if (adapterRecord.id === "codex-exec") {
141
158
  if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
@@ -262,7 +279,7 @@ function parseWorkflowResolution(value: unknown, source: string): WorkflowTermin
262
279
  return value;
263
280
  }
264
281
 
265
- function parseWorkflowResource(value: unknown, source: string): WorkflowResourceProvenanceV1 | undefined {
282
+ function parseWorkflowResource(value: unknown, source: string): WorkflowResourceProvenance | undefined {
266
283
  if (value === undefined) return undefined;
267
284
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid workflow receipt '${source}': resource must be an object.`);
268
285
  const resource = value as Record<string, unknown>;
@@ -330,10 +347,11 @@ export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string)
330
347
  assertUniqueHostStepIds(hostSteps, receiptPath);
331
348
  }
332
349
  const workflowResolution = parseWorkflowResolution(receipt.workflowResolution, receiptPath);
350
+ if (receipt.argsDigest !== undefined && (typeof receipt.argsDigest !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.argsDigest))) throw new Error(`Invalid workflow receipt '${receiptPath}': argsDigest is invalid.`);
333
351
  const resource = parseWorkflowResource(receipt.resource, receiptPath);
334
352
  const terminalOutcome = parseTerminalOutcome(receipt.terminalOutcome, `Invalid workflow receipt '${receiptPath}': terminalOutcome`);
335
353
  const recovery = parseRecovery(receipt.recovery, workflowRunId, entries, receiptPath);
336
- return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
354
+ return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(receipt.argsDigest ? { argsDigest: receipt.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
337
355
  }
338
356
 
339
357
  export function resolveWorkflowReceiptResumeEntry(input: {