@xzzpig/pi-subagents 0.2.0 → 0.4.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 (103) hide show
  1. package/CHANGELOG.md +96 -0
  2. package/README.md +2 -0
  3. package/agents/oracle.md +7 -5
  4. package/agents/researcher.md +1 -1
  5. package/agents/reviewer.md +2 -2
  6. package/agents/scout.md +1 -1
  7. package/agents/worker.md +1 -1
  8. package/docs/agents.md +3 -0
  9. package/docs/configuration.md +121 -10
  10. package/docs/extension-api.md +36 -0
  11. package/docs/missions.md +5 -3
  12. package/docs/observability.md +43 -3
  13. package/docs/tool-reference.md +20 -3
  14. package/docs/workflows.md +2 -2
  15. package/package.json +4 -4
  16. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  17. package/skills/pi-subagents/references/execution-controls.md +5 -4
  18. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  19. package/skills/pi-subagents/references/prompting-and-roles.md +31 -15
  20. package/src/agents/agent-serializer.ts +2 -0
  21. package/src/agents/agents.ts +46 -15
  22. package/src/api/external-runs.ts +174 -84
  23. package/src/api/preflight.ts +13 -7
  24. package/src/extension/config.ts +59 -0
  25. package/src/extension/doctor.ts +40 -0
  26. package/src/extension/index.ts +83 -9
  27. package/src/extension/public-execution.ts +37 -4
  28. package/src/extension/rpc.ts +8 -10
  29. package/src/extension/schemas.ts +12 -10
  30. package/src/extension/tool-description.ts +13 -9
  31. package/src/inspectors/herdr/actions.ts +13 -8
  32. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  33. package/src/inspectors/herdr/project-panes.ts +2 -6
  34. package/src/inspectors/herdr/shell-command.ts +16 -0
  35. package/src/intercom/intercom-bridge.ts +9 -5
  36. package/src/intercom/native-supervisor-channel.ts +19 -42
  37. package/src/missions/goal-driver.ts +3 -1
  38. package/src/missions/lifecycle.ts +4 -7
  39. package/src/missions/store.ts +12 -7
  40. package/src/missions/workflow-state.ts +6 -2
  41. package/src/runs/background/active-async-capacity.ts +431 -0
  42. package/src/runs/background/active-run-index.ts +77 -3
  43. package/src/runs/background/async-execution.ts +190 -72
  44. package/src/runs/background/async-job-tracker.ts +5 -0
  45. package/src/runs/background/async-resume.ts +21 -7
  46. package/src/runs/background/async-status-snapshot.ts +277 -0
  47. package/src/runs/background/async-status.ts +17 -6
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/chain-root-attachment.ts +2 -2
  50. package/src/runs/background/completion-replay.ts +11 -1
  51. package/src/runs/background/fleet-view.ts +21 -6
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-files.ts +437 -0
  55. package/src/runs/background/result-watcher.ts +188 -41
  56. package/src/runs/background/resume-guidance.ts +27 -7
  57. package/src/runs/background/retained-children.ts +75 -18
  58. package/src/runs/background/run-id-resolver.ts +30 -24
  59. package/src/runs/background/run-status.ts +106 -5
  60. package/src/runs/background/scheduled-runs.ts +54 -28
  61. package/src/runs/background/stale-run-reconciler.ts +30 -16
  62. package/src/runs/background/subagent-runner.ts +352 -62
  63. package/src/runs/background/subagent-wait.ts +2 -0
  64. package/src/runs/background/wait-completions.ts +5 -2
  65. package/src/runs/foreground/async-dismiss-action.ts +2 -1
  66. package/src/runs/foreground/chain-execution.ts +53 -2
  67. package/src/runs/foreground/execution.ts +309 -34
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/prompt-audit.ts +172 -0
  70. package/src/runs/foreground/subagent-executor.ts +936 -224
  71. package/src/runs/shared/acceptance.ts +13 -4
  72. package/src/runs/shared/completion-guard.ts +107 -1
  73. package/src/runs/shared/external-cli-runner.ts +4 -0
  74. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  75. package/src/runs/shared/model-fallback.ts +16 -2
  76. package/src/runs/shared/nested-events.ts +66 -62
  77. package/src/runs/shared/orca-progress-tabs.ts +375 -0
  78. package/src/runs/shared/parallel-utils.ts +4 -0
  79. package/src/runs/shared/pi-args.ts +44 -1
  80. package/src/runs/shared/run-fanout-budget.ts +280 -0
  81. package/src/runs/shared/single-output.ts +4 -2
  82. package/src/runs/shared/subagent-control.ts +15 -0
  83. package/src/runs/shared/subagent-prompt-runtime.ts +1 -9
  84. package/src/runs/shared/subagent-startup-retry.ts +12 -0
  85. package/src/runs/shared/task-intent.ts +19 -3
  86. package/src/runs/shared/tool-timeout.ts +93 -0
  87. package/src/runs/shared/worktree.ts +17 -5
  88. package/src/shared/agent-stream-options.ts +5 -0
  89. package/src/shared/artifacts.ts +2 -6
  90. package/src/shared/display-text.ts +50 -0
  91. package/src/shared/node-executable.ts +21 -0
  92. package/src/shared/types.ts +143 -5
  93. package/src/shared/utils.ts +3 -1
  94. package/src/slash/slash-commands.ts +34 -25
  95. package/src/slash/slash-live-state.ts +3 -0
  96. package/src/tui/fleet-status.ts +164 -47
  97. package/src/tui/fleet-transcript.ts +1 -48
  98. package/src/tui/fleet.ts +352 -27
  99. package/src/tui/render.ts +122 -44
  100. package/src/watchdog/permission-arbiter.ts +2 -1
  101. package/src/watchdog/review.ts +4 -3
  102. package/src/workflows/chat-progress.ts +10 -2
  103. package/src/workflows/scripted-workflow.ts +292 -79
@@ -4,15 +4,23 @@ const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
4
4
 
5
5
  const WORKER_SOURCE = String.raw`
6
6
  const { parentPort } = require("node:worker_threads");
7
+ const { promiseHooks } = require("node:v8");
7
8
  const vm = require("node:vm");
8
9
  const { inspect } = require("node:util");
9
10
 
11
+ if (!promiseHooks || typeof promiseHooks.createHook !== "function") throw new Error("workflowScript requires node:v8 promiseHooks.createHook support.");
12
+
10
13
  let nextCallId = 0;
14
+ let topLevelWorkflowPromise;
15
+ let suppressNativePromiseConsumption = 0;
16
+ const activeNativePromises = [];
11
17
  const pending = new Map();
12
18
  const runKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
13
- const trackedPromisePatch = Symbol("trackedPromisePatch");
14
- const trackedPromiseObservations = new WeakMap();
15
- let suppressRunObservation = 0;
19
+ const trackedPromiseTrackers = new WeakMap();
20
+ const trackedPromiseTargets = new WeakMap();
21
+ let nativePromiseTrackers = new WeakMap();
22
+ let nativePromiseParents = new WeakMap();
23
+ const observedRunCallIds = new Set();
16
24
 
17
25
  function stableRunJson(value) {
18
26
  if (Array.isArray(value)) return "[" + value.map(stableRunJson).join(",") + "]";
@@ -23,15 +31,47 @@ function stableRunJson(value) {
23
31
  function isDirectWorkflowScriptPromiseHandlerCall() {
24
32
  const stack = new Error().stack;
25
33
  if (typeof stack !== "string") return false;
26
- const frame = stack.split("\n").slice(1).map((line) => line.trim()).find((line) =>
27
- line &&
28
- !line.includes("isDirectWorkflowScriptPromiseHandlerCall") &&
29
- !line.includes("markObserved") &&
30
- !line.includes("promise.then") &&
31
- !line.includes("promise.catch") &&
32
- !line.includes("promise.finally")
33
- );
34
- return frame ? frame.includes("workflow-script.js") && !frame.includes("at async ") : false;
34
+ return stack.split("\n").some((line) => line.includes("workflow-script.js") && !line.includes("at async "));
35
+ }
36
+
37
+ function nativePromiseTracker(promise) {
38
+ if (!promise || (typeof promise !== "object" && typeof promise !== "function")) return undefined;
39
+ let tracker = nativePromiseTrackers.get(promise);
40
+ if (!tracker) {
41
+ tracker = { observations: [], consumed: false, dependencies: [] };
42
+ nativePromiseTrackers.set(promise, tracker);
43
+ }
44
+ return tracker;
45
+ }
46
+
47
+ function promiseObservationTracker(value) {
48
+ if (!value || (typeof value !== "object" && typeof value !== "function")) return undefined;
49
+ return trackedPromiseTrackers.get(value) ?? nativePromiseTrackers.get(value);
50
+ }
51
+
52
+ function addTrackerDependency(tracker, dependency) {
53
+ if (!dependency) return;
54
+ tracker.dependencies ??= [];
55
+ if (!tracker.dependencies.includes(dependency)) tracker.dependencies.push(dependency);
56
+ if (tracker.consumed) markTrackedObservationsConsumed(dependency);
57
+ }
58
+
59
+ function descendsFromTopLevelWorkflow(promise) {
60
+ const seen = new Set();
61
+ for (let current = promise; current && !seen.has(current); current = nativePromiseParents.get(current)) {
62
+ if (current === topLevelWorkflowPromise) return true;
63
+ seen.add(current);
64
+ }
65
+ return false;
66
+ }
67
+
68
+ function withSuppressedNativePromiseConsumption(callback) {
69
+ suppressNativePromiseConsumption++;
70
+ try {
71
+ return callback();
72
+ } finally {
73
+ suppressNativePromiseConsumption--;
74
+ }
35
75
  }
36
76
 
37
77
  function mergeObservations(...groups) {
@@ -47,63 +87,107 @@ function mergeObservations(...groups) {
47
87
  return merged;
48
88
  }
49
89
 
50
- function trackedObservations(value) {
51
- return value && (typeof value === "object" || typeof value === "function") ? trackedPromiseObservations.get(value) ?? [] : [];
90
+ function trackedObservationTracker(value) {
91
+ return value && (typeof value === "object" || typeof value === "function") ? trackedPromiseTrackers.get(value) : undefined;
52
92
  }
53
93
 
54
- function withSuppressedRunObservation(callback) {
55
- suppressRunObservation += 1;
56
- try {
57
- return callback();
58
- } finally {
59
- suppressRunObservation -= 1;
94
+ function trackedPromiseTarget(value) {
95
+ return value && (typeof value === "object" || typeof value === "function") ? trackedPromiseTargets.get(value) ?? value : value;
96
+ }
97
+
98
+ function addTrackedObservations(tracker, observations) {
99
+ tracker.observations = mergeObservations(tracker.observations, observations);
100
+ if (!tracker.consumed) return;
101
+ for (const observation of tracker.observations) {
102
+ if (observedRunCallIds.has(observation.callId)) continue;
103
+ observedRunCallIds.add(observation.callId);
104
+ parentPort.postMessage({ type: "runObserved", callId: observation.callId, key: observation.key });
60
105
  }
61
106
  }
62
107
 
108
+ function markTrackedObservationsConsumed(tracker, seen = new Set()) {
109
+ if (seen.has(tracker)) return;
110
+ seen.add(tracker);
111
+ tracker.consumed = true;
112
+ addTrackedObservations(tracker, []);
113
+ for (const dependency of tracker.dependencies ?? []) markTrackedObservationsConsumed(dependency, seen);
114
+ }
115
+
116
+ function consumeTrackedObservations(tracker) {
117
+ if (isDirectWorkflowScriptPromiseHandlerCall()) return;
118
+ const activePromise = activeNativePromises.at(-1);
119
+ if (activePromise === topLevelWorkflowPromise || descendsFromTopLevelWorkflow(activePromise)) {
120
+ markTrackedObservationsConsumed(tracker);
121
+ } else if (activePromise) {
122
+ addTrackerDependency(nativePromiseTracker(activePromise), tracker);
123
+ } else {
124
+ markTrackedObservationsConsumed(tracker);
125
+ }
126
+ }
127
+
128
+ function trackObservationTracker(tracker, promise, allowFutureObservations = false) {
129
+ const target = trackedPromiseTarget(promise);
130
+ if ((!allowFutureObservations && tracker.observations.length === 0) || !target || typeof target.then !== "function") return promise;
131
+
132
+ const tracked = new Proxy(target, {
133
+ get(promiseTarget, prop) {
134
+ if (prop === "then") return function promiseThen(onFulfilled, onRejected) {
135
+ consumeTrackedObservations(tracker);
136
+ return trackObservationTracker({ observations: tracker.observations, consumed: false, dependencies: [tracker] }, promiseTarget.then(onFulfilled, onRejected), true);
137
+ };
138
+ if (prop === "catch") return function promiseCatch(onRejected) {
139
+ consumeTrackedObservations(tracker);
140
+ return trackObservationTracker({ observations: tracker.observations, consumed: false, dependencies: [tracker] }, promiseTarget.catch(onRejected), true);
141
+ };
142
+ if (prop === "finally") return function promiseFinally(onFinally) {
143
+ consumeTrackedObservations(tracker);
144
+ return trackObservationTracker({ observations: tracker.observations, consumed: false, dependencies: [tracker] }, promiseTarget.finally(onFinally), true);
145
+ };
146
+ return Reflect.get(promiseTarget, prop, promiseTarget);
147
+ },
148
+ });
149
+ trackedPromiseTrackers.set(tracked, tracker);
150
+ trackedPromiseTargets.set(tracked, target);
151
+ return tracked;
152
+ }
153
+
63
154
  function trackRunObservation(observations, promise) {
64
- const merged = mergeObservations(trackedObservations(promise), observations);
65
- if (merged.length === 0 || !promise || typeof promise.then !== "function") return promise;
66
- trackedPromiseObservations.set(promise, merged);
67
- if (promise[trackedPromisePatch]) return promise;
68
-
69
- const observedCallIds = new Set();
70
- const markObserved = () => {
71
- if (suppressRunObservation > 0 || isDirectWorkflowScriptPromiseHandlerCall()) return;
72
- for (const observation of trackedObservations(promise)) {
73
- if (observedCallIds.has(observation.callId)) continue;
74
- observedCallIds.add(observation.callId);
75
- parentPort.postMessage({ type: "runObserved", callId: observation.callId, key: observation.key });
76
- }
77
- };
78
- const originalThen = promise.then.bind(promise);
79
- const originalCatch = promise.catch.bind(promise);
80
- const originalFinally = promise.finally.bind(promise);
81
- Object.defineProperty(promise, trackedPromisePatch, { value: true });
82
- promise.then = (onFulfilled, onRejected) => {
83
- markObserved();
84
- return trackRunObservation(trackedObservations(promise), originalThen(onFulfilled, onRejected));
85
- };
86
- promise.catch = (onRejected) => {
87
- markObserved();
88
- return trackRunObservation(trackedObservations(promise), originalCatch(onRejected));
89
- };
90
- promise.finally = (onFinally) => {
91
- markObserved();
92
- return trackRunObservation(trackedObservations(promise), originalFinally(onFinally));
93
- };
94
- return promise;
155
+ const tracker = trackedObservationTracker(promise) ?? { observations: [], consumed: false };
156
+ addTrackedObservations(tracker, observations);
157
+ return trackObservationTracker(tracker, promise);
95
158
  }
96
159
 
97
160
  function trackPromiseCombinator(items, createPromise) {
98
161
  const values = Array.from(items);
99
- const observations = mergeObservations(...values.map(trackedObservations));
100
- const promise = withSuppressedRunObservation(() => createPromise(values));
101
- return observations.length > 0 ? trackRunObservation(observations, promise) : promise;
162
+ const dependencies = [...new Set(values.map(promiseObservationTracker).filter(Boolean))];
163
+ const promise = withSuppressedNativePromiseConsumption(() => createPromise(values.map(trackedPromiseTarget)));
164
+ if (dependencies.length === 0) return promise;
165
+ return trackObservationTracker({ observations: [], consumed: false, dependencies }, promise, true);
102
166
  }
103
167
 
104
168
  const workflowPromise = new Proxy(Promise, {
105
- construct(target, args) {
106
- return new target(...args);
169
+ construct(target, [executor]) {
170
+ if (typeof executor !== "function") return new target(executor);
171
+ const tracker = { observations: [], consumed: false };
172
+ const promise = new target((resolve, reject) => {
173
+ let settled = false;
174
+ try {
175
+ executor((value) => {
176
+ if (settled) return;
177
+ settled = true;
178
+ addTrackerDependency(tracker, promiseObservationTracker(value));
179
+ resolve(trackedPromiseTarget(value));
180
+ }, (reason) => {
181
+ if (settled) return;
182
+ settled = true;
183
+ reject(reason);
184
+ });
185
+ } catch (error) {
186
+ settled = true;
187
+ throw error;
188
+ }
189
+ });
190
+ return trackObservationTracker(tracker, promise, true);
107
191
  },
108
192
  get(target, prop) {
109
193
  if (prop === "all") return (items) => trackPromiseCombinator(items, (values) => target.all(values));
@@ -111,9 +195,10 @@ const workflowPromise = new Proxy(Promise, {
111
195
  if (prop === "race") return (items) => trackPromiseCombinator(items, (values) => target.race(values));
112
196
  if (prop === "any") return (items) => trackPromiseCombinator(items, (values) => target.any(values));
113
197
  if (prop === "resolve") return (value) => {
114
- const observations = trackedObservations(value);
115
- const promise = withSuppressedRunObservation(() => target.resolve(value));
116
- return observations.length > 0 ? trackRunObservation(observations, promise) : promise;
198
+ const dependency = promiseObservationTracker(value);
199
+ const promise = withSuppressedNativePromiseConsumption(() => target.resolve(trackedPromiseTarget(value)));
200
+ if (!dependency) return promise;
201
+ return trackObservationTracker({ observations: [], consumed: false, dependencies: [dependency] }, promise, true);
117
202
  };
118
203
  const value = target[prop];
119
204
  return typeof value === "function" ? value.bind(target) : value;
@@ -131,11 +216,11 @@ function hostCall(method, args, observation) {
131
216
  : promise;
132
217
  }
133
218
 
134
- function runHostCall(key, params, collectFailure) {
219
+ function runHostCall(key, params, collectFailure, batch) {
135
220
  const callId = ++nextCallId;
136
221
  const promise = new Promise((resolve, reject) => {
137
222
  pending.set(callId, { resolve, reject });
138
- parentPort.postMessage({ type: "call", callId, method: "run", args: { key, params, ...(collectFailure ? { collectFailure: true } : {}) } });
223
+ parentPort.postMessage({ type: "call", callId, method: "run", args: { key, params, ...(collectFailure ? { collectFailure: true } : {}), ...(batch ? { batch } : {}) } });
139
224
  });
140
225
  return { key, callId, promise };
141
226
  }
@@ -188,7 +273,8 @@ const runs = Object.freeze({
188
273
  calls.push({ key, params });
189
274
  }
190
275
  for (const { key, params } of calls) runFingerprints.set(key, stableRunJson(params));
191
- const launched = calls.map(({ key, params }) => runHostCall(key, params, true));
276
+ const batch = { id: "batch-" + (++nextCallId), calls };
277
+ const launched = calls.map(({ key, params }) => runHostCall(key, params, true, batch));
192
278
  return trackRunObservation(launched.map(({ key, callId }) => ({ key, callId })), Promise.all(launched.map(({ promise }) => promise)));
193
279
  },
194
280
  status(keyOrRunId) { return hostCall("status", { keyOrRunId }); },
@@ -288,7 +374,11 @@ parentPort.on("message", async (message) => {
288
374
  if (!entry) return;
289
375
  pending.delete(message.callId);
290
376
  if (message.ok) entry.resolve(message.value);
291
- else entry.reject(new Error(message.error));
377
+ else {
378
+ const error = new Error(message.error);
379
+ if (message.errorKind === "detached-child") error.workflowErrorKind = "detached-child";
380
+ entry.reject(error);
381
+ }
292
382
  return;
293
383
  }
294
384
  if (message.type !== "start") return;
@@ -305,12 +395,68 @@ parentPort.on("message", async (message) => {
305
395
  parentPort.postMessage({ type: "error", error: formatWorkflowScriptSyntaxError(error) });
306
396
  return;
307
397
  }
308
- const value = await compiled.runInContext(context);
398
+ const nativePromisePrototype = vm.runInContext("(async () => {})().constructor.prototype", context);
399
+ const nativeThenDescriptor = Object.getOwnPropertyDescriptor(nativePromisePrototype, "then");
400
+ if (!nativeThenDescriptor || typeof nativeThenDescriptor.value !== "function") throw new Error("workflowScript could not inspect the VM Promise.prototype.then method.");
401
+ const nativeThen = nativeThenDescriptor.value;
402
+ let stopWorkflowPromiseHook;
403
+ let value;
404
+ try {
405
+ Object.defineProperty(nativePromisePrototype, "then", {
406
+ ...nativeThenDescriptor,
407
+ value: function workflowPromiseThen(...args) {
408
+ if (isDirectWorkflowScriptPromiseHandlerCall() || suppressNativePromiseConsumption > 0) {
409
+ return withSuppressedNativePromiseConsumption(() => Reflect.apply(nativeThen, this, args));
410
+ }
411
+ return Reflect.apply(nativeThen, this, args);
412
+ },
413
+ });
414
+ stopWorkflowPromiseHook = promiseHooks.createHook({
415
+ before(promise) {
416
+ activeNativePromises.push(promise);
417
+ },
418
+ after(promise) {
419
+ const index = activeNativePromises.lastIndexOf(promise);
420
+ if (index !== -1) activeNativePromises.splice(index, 1);
421
+ },
422
+ init(promise, parent) {
423
+ const childTracker = nativePromiseTracker(promise);
424
+ if (!parent) return;
425
+ nativePromiseParents.set(promise, parent);
426
+ const parentTracker = nativePromiseTracker(parent);
427
+ addTrackerDependency(childTracker, parentTracker);
428
+ const activePromise = activeNativePromises.at(-1);
429
+ if (activePromise && activePromise !== parent) {
430
+ addTrackerDependency(nativePromiseTracker(activePromise), parentTracker);
431
+ } else if (!activePromise && suppressNativePromiseConsumption === 0) {
432
+ markTrackedObservationsConsumed(parentTracker);
433
+ }
434
+ },
435
+ });
436
+ const workflowResultPromise = compiled.runInContext(context);
437
+ topLevelWorkflowPromise = workflowResultPromise;
438
+ markTrackedObservationsConsumed(nativePromiseTracker(workflowResultPromise));
439
+ value = await workflowResultPromise;
440
+ } finally {
441
+ try {
442
+ stopWorkflowPromiseHook?.();
443
+ } finally {
444
+ try {
445
+ Object.defineProperty(nativePromisePrototype, "then", nativeThenDescriptor);
446
+ } finally {
447
+ topLevelWorkflowPromise = undefined;
448
+ activeNativePromises.length = 0;
449
+ suppressNativePromiseConsumption = 0;
450
+ nativePromiseTrackers = new WeakMap();
451
+ nativePromiseParents = new WeakMap();
452
+ }
453
+ }
454
+ }
309
455
  const persistedValue = value === undefined ? null : omitUndefinedWorkflowValues(value);
310
456
  assertJsonValue(persistedValue, "return");
311
457
  parentPort.postMessage({ type: "complete", value: persistedValue });
312
458
  } catch (error) {
313
- parentPort.postMessage({ type: "error", error: error && error.stack ? error.stack : String(error) });
459
+ parentPort.postMessage({ type: "error", error: error && error.stack ? error.stack : String(error), ...(error && error.workflowErrorKind === "detached-child" ? { errorKind: "detached-child" } : {}) });
314
460
  }
315
461
  });
316
462
  `;
@@ -323,6 +469,7 @@ export interface WorkflowScriptChildResult {
323
469
  runId?: string;
324
470
  output: string;
325
471
  error?: string;
472
+ detached?: boolean;
326
473
  structuredOutput?: unknown;
327
474
  artifactPaths: string[];
328
475
  results?: unknown[];
@@ -331,7 +478,7 @@ export interface WorkflowScriptChildResult {
331
478
  export interface WorkflowScriptTraceEntry {
332
479
  operation: "run" | "status";
333
480
  key: string;
334
- state: "started" | "completed" | "failed" | "reused";
481
+ state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused";
335
482
  /** Canonical child agent name when resolved launch or result data is available. */
336
483
  agent?: string;
337
484
  runId?: string;
@@ -351,11 +498,13 @@ export interface WorkflowScriptResult {
351
498
 
352
499
  export class WorkflowScriptError extends Error {
353
500
  readonly partial: Omit<WorkflowScriptResult, "value">;
501
+ readonly errorKind?: "detached-child";
354
502
 
355
- constructor(message: string, partial: Omit<WorkflowScriptResult, "value">) {
503
+ constructor(message: string, partial: Omit<WorkflowScriptResult, "value">, errorKind?: "detached-child") {
356
504
  super(message);
357
505
  this.name = "WorkflowScriptError";
358
506
  this.partial = partial;
507
+ this.errorKind = errorKind;
359
508
  }
360
509
  }
361
510
 
@@ -363,7 +512,8 @@ export interface RunWorkflowScriptOptions {
363
512
  script: string;
364
513
  timeoutMs?: number;
365
514
  signal?: AbortSignal;
366
- launch: (key: string, params: Record<string, unknown>, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
515
+ admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
516
+ launch: (key: string, params: Record<string, unknown>, signal: AbortSignal, admission: { admitted: boolean }) => Promise<WorkflowScriptChildResult>;
367
517
  status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
368
518
  state?: {
369
519
  get: (key: string) => unknown | Promise<unknown>;
@@ -490,6 +640,8 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
490
640
  const children = new Map<string, WorkflowScriptChildResult>();
491
641
  const childOrder: string[] = [];
492
642
  const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult>; observed: boolean }>();
643
+ const stoppedLaunches = new Set<string>();
644
+ const batchAdmissions = new Map<string, Promise<void>>();
493
645
  const observedRunCalls = new Set<number>();
494
646
  const childController = new AbortController();
495
647
  let settled = false;
@@ -501,7 +653,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
501
653
  const traceChanged = () => options.onTrace?.([...trace]);
502
654
 
503
655
  return await new Promise<WorkflowScriptResult>((resolve, reject) => {
504
- const finish = (outcome: { value: unknown } | { error: Error }) => {
656
+ const finish = (outcome: { value: unknown } | { error: Error & { workflowErrorKind?: unknown } }) => {
505
657
  if (settled) return;
506
658
  settled = true;
507
659
  if (timer) clearTimeout(timer);
@@ -512,11 +664,34 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
512
664
  ? new Error(`workflowScript completed with unawaited runs.run launch(es): ${unobservedKeys.map((key) => `'${key}'`).join(", ")}. Await or return each launch.`)
513
665
  : undefined;
514
666
  childController.abort("error" in outcome ? outcome.error : completionError ?? new Error("Workflow script completed."));
515
- if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial()));
667
+ if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial(), outcome.error.workflowErrorKind === "detached-child" ? "detached-child" : undefined));
516
668
  else if (completionError) reject(new WorkflowScriptError(completionError.message, partial()));
517
669
  else resolve({ value: outcome.value, ...partial() });
518
670
  };
519
- const onAbort = () => finish({ error: new Error("Workflow script aborted.") });
671
+ const onAbort = () => {
672
+ const signalReason = options.signal?.reason;
673
+ const error = signalReason instanceof Error
674
+ ? signalReason
675
+ : typeof signalReason === "string"
676
+ ? new Error(signalReason)
677
+ : new Error("Workflow script aborted.");
678
+ for (const key of launches.keys()) {
679
+ if (children.has(key)) continue;
680
+ stoppedLaunches.add(key);
681
+ const started = trace.findLast((entry) => entry.operation === "run" && entry.key === key && entry.state === "started");
682
+ trace.push({
683
+ operation: "run",
684
+ key,
685
+ state: "stopped",
686
+ ...(started?.agent ? { agent: started.agent } : {}),
687
+ ...(started?.phase ? { phase: started.phase } : {}),
688
+ ...(started?.label ? { label: started.label } : {}),
689
+ error: error.message,
690
+ });
691
+ }
692
+ traceChanged();
693
+ finish({ error });
694
+ };
520
695
  const timer = options.timeoutMs === undefined
521
696
  ? undefined
522
697
  : setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
@@ -528,6 +703,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
528
703
  if (!settled && code !== 0) finish({ error: new Error(`Workflow worker exited with code ${code}.`) });
529
704
  });
530
705
  worker.on("message", (message: Record<string, unknown>) => {
706
+ if (settled) return;
531
707
  if (message.type === "emit") {
532
708
  try {
533
709
  assertWorkflowJsonValue(message.value, "emit");
@@ -557,7 +733,11 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
557
733
  }
558
734
  return finish({ value: message.value });
559
735
  }
560
- if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Workflow script failed.") });
736
+ if (message.type === "error") {
737
+ const workflowError = new Error(typeof message.error === "string" ? message.error : "Workflow script failed.") as Error & { workflowErrorKind?: "detached-child" };
738
+ if (message.errorKind === "detached-child") workflowError.workflowErrorKind = "detached-child";
739
+ return finish({ error: workflowError });
740
+ }
561
741
  if (message.type === "runObserved" && typeof message.callId === "number") {
562
742
  const key = typeof message.key === "string" ? message.key : undefined;
563
743
  const launch = key ? launches.get(key) : undefined;
@@ -573,7 +753,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
573
753
  if (!settled) worker.postMessage({ type: "response", callId: message.callId, ok: true, value: omitUndefinedWorkflowValues(value) });
574
754
  },
575
755
  (error: unknown) => {
576
- if (!settled) worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error) });
756
+ if (!settled) worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error), ...(error instanceof Error && (error as { workflowErrorKind?: unknown }).workflowErrorKind === "detached-child" ? { errorKind: "detached-child" } : {}) });
577
757
  },
578
758
  );
579
759
  };
@@ -614,7 +794,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
614
794
  const target = known?.runId ?? keyOrRunId;
615
795
  trace.push({ operation: "status", key: keyOrRunId, state: "started", ...(known?.runId ? { runId: known.runId } : {}) });
616
796
  traceChanged();
797
+ if (settled) return;
617
798
  respond(options.status(target, childController.signal).then((result) => {
799
+ if (settled) return result;
618
800
  trace.push({ operation: "status", key: keyOrRunId, state: result.ok ? "completed" : "failed", ...(result.runId ? { runId: result.runId } : {}), ...(!result.ok ? { error: result.output } : {}) });
619
801
  traceChanged();
620
802
  if (!result.ok) throw new Error(`Status '${keyOrRunId}' failed: ${result.output}`);
@@ -663,7 +845,11 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
663
845
  const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
664
846
  ? promise
665
847
  : promise.then((result) => {
666
- if (!result.ok) throw new Error(`Run '${key}' failed: ${result.error ?? result.output}`);
848
+ if (!result.ok) {
849
+ const childError = new Error(result.detached ? `Run '${key}' detached: ${result.error ?? result.output}` : `Run '${key}' failed: ${result.error ?? result.output}`) as Error & { workflowErrorKind?: "detached-child" };
850
+ if (result.detached) childError.workflowErrorKind = "detached-child";
851
+ throw childError;
852
+ }
667
853
  return result;
668
854
  });
669
855
  const fingerprint = stableJson(params);
@@ -677,24 +863,51 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
677
863
  }
678
864
 
679
865
  const startedAt = Date.now();
680
- childOrder.push(key);
681
- trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
682
- traceChanged();
683
- const promise = Promise.resolve().then(() => options.launch(key, { ...params, async: params.async ?? false }, childController.signal)).then((result) => {
866
+ const batch = isRecord(message.args.batch) && typeof message.args.batch.id === "string" && Array.isArray(message.args.batch.calls)
867
+ ? { id: message.args.batch.id, calls: message.args.batch.calls.filter((call): call is { key: string; params: Record<string, unknown> } => isRecord(call) && typeof call.key === "string" && isRecord(call.params)) }
868
+ : undefined;
869
+ let admission = batch ? batchAdmissions.get(batch.id) : undefined;
870
+ if (!admission) {
871
+ const seenKeys = new Set<string>();
872
+ const calls = (batch?.calls ?? [{ key, params }]).filter((call) => {
873
+ if (seenKeys.has(call.key) || launches.has(call.key) || call.params.resume !== undefined) return false;
874
+ seenKeys.add(call.key);
875
+ return true;
876
+ });
877
+ admission = Promise.resolve().then(() => {
878
+ if (settled) return;
879
+ return options.admit?.(calls);
880
+ });
881
+ if (batch) batchAdmissions.set(batch.id, admission);
882
+ }
883
+ const promise = admission.then(() => {
884
+ if (settled || stoppedLaunches.has(key)) {
885
+ const reason = childController.signal.reason;
886
+ const text = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.";
887
+ return { key, ok: false, output: text, error: text, artifactPaths: [] };
888
+ }
889
+ return options.launch(key, { ...params, async: params.async ?? false }, childController.signal, { admitted: true });
890
+ }).then((result) => {
684
891
  const normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
892
+ if (stoppedLaunches.has(key)) return normalized;
685
893
  children.set(key, normalized);
686
- trace.push({ operation: "run", key, state: normalized.ok ? "completed" : "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(normalized.agent ? { agent: normalized.agent } : {}), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
894
+ const state = normalized.ok ? "completed" : normalized.detached ? "detached" : "failed";
895
+ trace.push({ operation: "run", key, state, durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(normalized.agent ? { agent: normalized.agent } : {}), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
687
896
  traceChanged();
688
897
  return normalized;
689
898
  }, (error: unknown) => {
690
899
  const text = error instanceof Error ? error.message : String(error);
691
900
  const failure: WorkflowScriptChildResult = { key, ok: false, output: text, error: text, artifactPaths: [] };
901
+ if (stoppedLaunches.has(key)) return failure;
692
902
  children.set(key, failure);
693
903
  trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), error: text });
694
904
  traceChanged();
695
905
  return failure;
696
906
  });
697
907
  launches.set(key, { fingerprint, promise, observed: callObserved });
908
+ childOrder.push(key);
909
+ trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
910
+ traceChanged();
698
911
  respond(deliver(promise));
699
912
  });
700
913