@xzzpig/pi-subagents 0.1.0 → 0.3.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 (108) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +4 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +343 -0
  5. package/docs/configuration.md +395 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +121 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +198 -0
  10. package/docs/tool-reference.md +343 -0
  11. package/docs/watchdog.md +176 -0
  12. package/docs/workflows.md +163 -0
  13. package/package.json +13 -11
  14. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  15. package/skills/pi-subagents/references/execution-controls.md +7 -7
  16. package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
  17. package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
  18. package/src/agents/agents.ts +53 -23
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/preflight.ts +1 -1
  22. package/src/api/project-panes.ts +30 -0
  23. package/src/extension/config.ts +54 -1
  24. package/src/extension/doctor.ts +40 -0
  25. package/src/extension/fanout-child.ts +5 -4
  26. package/src/extension/index.ts +114 -38
  27. package/src/extension/public-execution.ts +35 -4
  28. package/src/extension/rpc.ts +10 -15
  29. package/src/extension/schemas.ts +33 -11
  30. package/src/extension/subagent-guide.ts +39 -0
  31. package/src/extension/tool-description.ts +38 -18
  32. package/src/inspectors/herdr/actions.ts +11 -2
  33. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  34. package/src/inspectors/herdr/project-panes.ts +459 -63
  35. package/src/intercom/intercom-bridge.ts +7 -2
  36. package/src/intercom/native-supervisor-channel.ts +102 -4
  37. package/src/missions/actions.ts +25 -2
  38. package/src/missions/lifecycle.ts +25 -9
  39. package/src/missions/store.ts +89 -7
  40. package/src/missions/types.ts +33 -0
  41. package/src/missions/workflow-state.ts +25 -15
  42. package/src/runs/background/active-async-capacity.ts +431 -0
  43. package/src/runs/background/active-run-index.ts +46 -0
  44. package/src/runs/background/async-execution.ts +158 -71
  45. package/src/runs/background/async-job-tracker.ts +297 -133
  46. package/src/runs/background/async-resume.ts +37 -5
  47. package/src/runs/background/async-status.ts +39 -5
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/completion-replay.ts +267 -0
  50. package/src/runs/background/control-channel.ts +95 -54
  51. package/src/runs/background/fleet-view.ts +18 -5
  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-watcher.ts +113 -10
  55. package/src/runs/background/resume-guidance.ts +53 -0
  56. package/src/runs/background/retained-children.ts +14 -6
  57. package/src/runs/background/run-status.ts +119 -5
  58. package/src/runs/background/scheduled-runs.ts +25 -1
  59. package/src/runs/background/stale-run-reconciler.ts +12 -24
  60. package/src/runs/background/subagent-runner.ts +127 -41
  61. package/src/runs/background/subagent-wait.ts +5 -2
  62. package/src/runs/background/wait-completions.ts +39 -5
  63. package/src/runs/background/wait-subscriptions.ts +21 -5
  64. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  65. package/src/runs/foreground/async-steering-action.ts +7 -8
  66. package/src/runs/foreground/chain-execution.ts +40 -2
  67. package/src/runs/foreground/execution.ts +97 -19
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/foreground-history.ts +137 -0
  70. package/src/runs/foreground/prompt-audit.ts +172 -0
  71. package/src/runs/foreground/subagent-executor.ts +1274 -243
  72. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  73. package/src/runs/shared/acceptance.ts +13 -4
  74. package/src/runs/shared/completion-guard.ts +17 -1
  75. package/src/runs/shared/dynamic-fanout.ts +1 -1
  76. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  77. package/src/runs/shared/model-fallback.ts +8 -4
  78. package/src/runs/shared/model-scope.ts +12 -2
  79. package/src/runs/shared/parallel-utils.ts +3 -0
  80. package/src/runs/shared/pi-args.ts +44 -1
  81. package/src/runs/shared/run-fanout-budget.ts +280 -0
  82. package/src/runs/shared/single-output.ts +4 -2
  83. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  84. package/src/runs/shared/task-intent.ts +19 -3
  85. package/src/runs/shared/worktree.ts +20 -7
  86. package/src/shared/agent-stream-options.ts +5 -0
  87. package/src/shared/artifacts.ts +17 -21
  88. package/src/shared/display-text.ts +150 -0
  89. package/src/shared/file-coalescer.ts +9 -0
  90. package/src/shared/fork-context.ts +13 -0
  91. package/src/shared/formatters.ts +4 -6
  92. package/src/shared/node-executable.ts +21 -0
  93. package/src/shared/prompt-resources.ts +51 -0
  94. package/src/shared/settings.ts +15 -2
  95. package/src/shared/types.ts +158 -4
  96. package/src/shared/utf8.ts +11 -0
  97. package/src/shared/utils.ts +46 -34
  98. package/src/slash/prompt-workflows.ts +2 -15
  99. package/src/slash/slash-commands.ts +22 -2
  100. package/src/tui/fleet-status.ts +29 -17
  101. package/src/tui/fleet-transcript.ts +1 -48
  102. package/src/tui/fleet.ts +362 -37
  103. package/src/tui/render.ts +235 -71
  104. package/src/watchdog/change-signature.ts +4 -3
  105. package/src/watchdog/permission-arbiter.ts +2 -1
  106. package/src/watchdog/review.ts +4 -3
  107. package/src/workflows/chat-progress.ts +8 -2
  108. package/src/workflows/scripted-workflow.ts +273 -20
@@ -1,9 +1,10 @@
1
1
  import { Agent, type AgentTool, type StreamFn, type ThinkingLevel } from "@earendil-works/pi-agent-core";
2
2
  import { createReadOnlyTools, convertToLlm, type ExtensionContext } from "@earendil-works/pi-coding-agent";
3
3
  import { streamSimple } from "@earendil-works/pi-ai/compat";
4
- import type { Model } from "@earendil-works/pi-ai";
4
+ import type { Model, ProviderHeaders } from "@earendil-works/pi-ai";
5
5
  import { Type, type Static } from "typebox";
6
6
  import { resolveModelCandidate } from "../runs/shared/model-fallback.ts";
7
+ import { agentStreamOptions } from "../shared/agent-stream-options.ts";
7
8
  import { resolveEffectiveThinking, splitKnownThinkingSuffix, THINKING_LEVELS, toModelInfo } from "../shared/model-info.ts";
8
9
  import type { WatchdogReviewFunction, WatchdogReviewRequest } from "./runtime.ts";
9
10
  import {
@@ -36,7 +37,7 @@ type RegistryModel = Model<any>;
36
37
 
37
38
  interface WatchdogReviewAuth {
38
39
  apiKey?: string;
39
- headers?: Record<string, string>;
40
+ headers?: ProviderHeaders;
40
41
  env?: Record<string, string>;
41
42
  }
42
43
 
@@ -280,7 +281,7 @@ export function createMainWatchdogReview(provider: WatchdogContextProvider, opti
280
281
  tools,
281
282
  },
282
283
  convertToLlm,
283
- streamFn: streamFn,
284
+ streamFn: streamFn,
284
285
  getApiKey: (providerName) => providerName === selection.model.provider ? auth.apiKey : undefined,
285
286
  beforeToolCall: async ({ toolCall }) => WATCHDOG_ALLOWED_TOOL_NAMES.has(toolCall.name)
286
287
  ? undefined
@@ -96,7 +96,7 @@ export function resolveWorkflowChatProgress(input: ResolveWorkflowChatProgressIn
96
96
 
97
97
  export interface WorkflowChatProgressRow {
98
98
  key: string;
99
- state: "running" | "complete" | "failed";
99
+ state: "running" | "complete" | "failed" | "stopped";
100
100
  label?: string;
101
101
  phase?: string;
102
102
  runId?: string;
@@ -123,7 +123,13 @@ export function buildWorkflowChatProgressRows(trace: NonNullable<Details["workfl
123
123
  continue;
124
124
  }
125
125
  const next: WorkflowChatProgressRow = existing ?? { key: entry.key, state: "running" };
126
- next.state = entry.state === "completed" ? "complete" : entry.state === "failed" ? "failed" : "running";
126
+ next.state = entry.state === "completed"
127
+ ? "complete"
128
+ : entry.state === "failed"
129
+ ? "failed"
130
+ : entry.state === "stopped"
131
+ ? "stopped"
132
+ : "running";
127
133
  const label = cleanLabel(entry.label);
128
134
  const phase = cleanLabel(entry.phase);
129
135
  if (label) next.label = label;
@@ -10,6 +10,9 @@ const { inspect } = require("node:util");
10
10
  let nextCallId = 0;
11
11
  const pending = new Map();
12
12
  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;
13
16
 
14
17
  function stableRunJson(value) {
15
18
  if (Array.isArray(value)) return "[" + value.map(stableRunJson).join(",") + "]";
@@ -17,12 +20,124 @@ function stableRunJson(value) {
17
20
  return JSON.stringify(value) ?? "undefined";
18
21
  }
19
22
 
20
- function hostCall(method, args) {
21
- return new Promise((resolve, reject) => {
22
- const callId = ++nextCallId;
23
+ function isDirectWorkflowScriptPromiseHandlerCall() {
24
+ const stack = new Error().stack;
25
+ 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;
35
+ }
36
+
37
+ function mergeObservations(...groups) {
38
+ const seen = new Set();
39
+ const merged = [];
40
+ for (const group of groups) {
41
+ for (const observation of group) {
42
+ if (!observation || typeof observation.callId !== "number" || typeof observation.key !== "string" || seen.has(observation.callId)) continue;
43
+ seen.add(observation.callId);
44
+ merged.push(observation);
45
+ }
46
+ }
47
+ return merged;
48
+ }
49
+
50
+ function trackedObservations(value) {
51
+ return value && (typeof value === "object" || typeof value === "function") ? trackedPromiseObservations.get(value) ?? [] : [];
52
+ }
53
+
54
+ function withSuppressedRunObservation(callback) {
55
+ suppressRunObservation += 1;
56
+ try {
57
+ return callback();
58
+ } finally {
59
+ suppressRunObservation -= 1;
60
+ }
61
+ }
62
+
63
+ 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;
95
+ }
96
+
97
+ function trackPromiseCombinator(items, createPromise) {
98
+ 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;
102
+ }
103
+
104
+ const workflowPromise = new Proxy(Promise, {
105
+ construct(target, args) {
106
+ return new target(...args);
107
+ },
108
+ get(target, prop) {
109
+ if (prop === "all") return (items) => trackPromiseCombinator(items, (values) => target.all(values));
110
+ if (prop === "allSettled") return (items) => trackPromiseCombinator(items, (values) => target.allSettled(values));
111
+ if (prop === "race") return (items) => trackPromiseCombinator(items, (values) => target.race(values));
112
+ if (prop === "any") return (items) => trackPromiseCombinator(items, (values) => target.any(values));
113
+ 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;
117
+ };
118
+ const value = target[prop];
119
+ return typeof value === "function" ? value.bind(target) : value;
120
+ },
121
+ });
122
+
123
+ function hostCall(method, args, observation) {
124
+ const callId = ++nextCallId;
125
+ const promise = new Promise((resolve, reject) => {
23
126
  pending.set(callId, { resolve, reject });
24
127
  parentPort.postMessage({ type: "call", callId, method, args });
25
128
  });
129
+ return observation && typeof observation.key === "string"
130
+ ? trackRunObservation([{ key: observation.key, callId }], promise)
131
+ : promise;
132
+ }
133
+
134
+ function runHostCall(key, params, collectFailure, batch) {
135
+ const callId = ++nextCallId;
136
+ const promise = new Promise((resolve, reject) => {
137
+ pending.set(callId, { resolve, reject });
138
+ parentPort.postMessage({ type: "call", callId, method: "run", args: { key, params, ...(collectFailure ? { collectFailure: true } : {}), ...(batch ? { batch } : {}) } });
139
+ });
140
+ return { key, callId, promise };
26
141
  }
27
142
 
28
143
  function formatRef(result) {
@@ -58,7 +173,7 @@ function validateRunCall(key, params, label, fingerprints) {
58
173
  const runs = Object.freeze({
59
174
  run(key, params) {
60
175
  validateRunCall(key, params, "runs.run", runFingerprints);
61
- return hostCall("run", { key, params });
176
+ return hostCall("run", { key, params }, { key });
62
177
  },
63
178
  all(items) {
64
179
  if (!Array.isArray(items)) throw new Error("runs.all(items) requires an array.");
@@ -73,7 +188,9 @@ const runs = Object.freeze({
73
188
  calls.push({ key, params });
74
189
  }
75
190
  for (const { key, params } of calls) runFingerprints.set(key, stableRunJson(params));
76
- return Promise.all(calls.map(({ key, params }) => hostCall("run", { key, params, collectFailure: true })));
191
+ const batch = { id: "batch-" + (++nextCallId), calls };
192
+ const launched = calls.map(({ key, params }) => runHostCall(key, params, true, batch));
193
+ return trackRunObservation(launched.map(({ key, callId }) => ({ key, callId })), Promise.all(launched.map(({ promise }) => promise)));
77
194
  },
78
195
  status(keyOrRunId) { return hostCall("status", { keyOrRunId }); },
79
196
  ref: formatRef,
@@ -97,6 +214,14 @@ const state = Object.freeze({
97
214
  },
98
215
  });
99
216
 
217
+ const prompts = Object.freeze({
218
+ render(ref, vars) {
219
+ if (typeof ref !== "string" || !ref.trim()) throw new Error("prompts.render(ref, vars) requires a non-empty ref string.");
220
+ if (vars !== undefined) assertJsonValue(vars, "prompts.render vars");
221
+ return hostCall("prompts.render", { ref, vars });
222
+ },
223
+ });
224
+
100
225
  let contextObjectPrototype;
101
226
 
102
227
  const capturedConsole = Object.freeze(Object.fromEntries(
@@ -105,6 +230,17 @@ const capturedConsole = Object.freeze(Object.fromEntries(
105
230
  }]),
106
231
  ));
107
232
 
233
+ function formatWorkflowScriptSyntaxError(error) {
234
+ const details = error && error.stack ? error.stack : String(error);
235
+ return [
236
+ "workflowScript must be valid JavaScript.",
237
+ "If task text contains Markdown fences or backticks, use an array joined with \"\\n\" or escaped strings instead of a raw backtick template literal.",
238
+ "",
239
+ "Original SyntaxError:",
240
+ details,
241
+ ].join("\n");
242
+ }
243
+
108
244
  function assertJsonValue(value, path = "emit", seen = new Set()) {
109
245
  if (value === null || typeof value === "string" || typeof value === "boolean") return;
110
246
  if (typeof value === "number") {
@@ -128,6 +264,25 @@ function assertJsonValue(value, path = "emit", seen = new Set()) {
128
264
  seen.delete(value);
129
265
  }
130
266
 
267
+ function isPlainWorkflowObject(value) {
268
+ if (!value || typeof value !== "object" || Array.isArray(value)) return false;
269
+ const prototype = Object.getPrototypeOf(value);
270
+ return prototype === null || prototype === Object.prototype || prototype === contextObjectPrototype;
271
+ }
272
+
273
+ function omitUndefinedWorkflowValues(value, seen = new Set()) {
274
+ if (value === null || typeof value !== "object") return value;
275
+ if (seen.has(value)) return value;
276
+ seen.add(value);
277
+ const normalized = Array.isArray(value)
278
+ ? value.map((entry) => entry === undefined ? null : omitUndefinedWorkflowValues(entry, seen))
279
+ : isPlainWorkflowObject(value) && Object.getOwnPropertySymbols(value).length === 0
280
+ ? Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined ? [] : [[key, omitUndefinedWorkflowValues(entry, seen)]]))
281
+ : value;
282
+ seen.delete(value);
283
+ return normalized;
284
+ }
285
+
131
286
  parentPort.on("message", async (message) => {
132
287
  if (message.type === "response") {
133
288
  const entry = pending.get(message.callId);
@@ -139,13 +294,20 @@ parentPort.on("message", async (message) => {
139
294
  }
140
295
  if (message.type !== "start") return;
141
296
  try {
142
- const sandbox = { runs, emit(value) { assertJsonValue(value); parentPort.postMessage({ type: "emit", value }); }, console: capturedConsole };
297
+ const sandbox = { runs, prompts, Promise: workflowPromise, emit(value) { assertJsonValue(value); parentPort.postMessage({ type: "emit", value }); }, console: capturedConsole };
143
298
  if (message.stateEnabled) sandbox.state = state;
144
299
  const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
145
300
  contextObjectPrototype = vm.runInContext("Object.prototype", context);
146
- const compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "workflow-script.js" });
301
+ let compiled;
302
+ try {
303
+ compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "workflow-script.js" });
304
+ } catch (error) {
305
+ if (!(error instanceof SyntaxError)) throw error;
306
+ parentPort.postMessage({ type: "error", error: formatWorkflowScriptSyntaxError(error) });
307
+ return;
308
+ }
147
309
  const value = await compiled.runInContext(context);
148
- const persistedValue = value === undefined ? null : value;
310
+ const persistedValue = value === undefined ? null : omitUndefinedWorkflowValues(value);
149
311
  assertJsonValue(persistedValue, "return");
150
312
  parentPort.postMessage({ type: "complete", value: persistedValue });
151
313
  } catch (error) {
@@ -157,6 +319,8 @@ parentPort.on("message", async (message) => {
157
319
  export interface WorkflowScriptChildResult {
158
320
  key: string;
159
321
  ok: boolean;
322
+ /** Canonical child agent name when launch resolution produced one. */
323
+ agent?: string;
160
324
  runId?: string;
161
325
  output: string;
162
326
  error?: string;
@@ -168,7 +332,9 @@ export interface WorkflowScriptChildResult {
168
332
  export interface WorkflowScriptTraceEntry {
169
333
  operation: "run" | "status";
170
334
  key: string;
171
- state: "started" | "completed" | "failed" | "reused";
335
+ state: "started" | "completed" | "failed" | "stopped" | "reused";
336
+ /** Canonical child agent name when resolved launch or result data is available. */
337
+ agent?: string;
172
338
  runId?: string;
173
339
  durationMs?: number;
174
340
  phase?: string;
@@ -198,12 +364,16 @@ export interface RunWorkflowScriptOptions {
198
364
  script: string;
199
365
  timeoutMs?: number;
200
366
  signal?: AbortSignal;
201
- launch: (key: string, params: Record<string, unknown>, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
367
+ admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
368
+ launch: (key: string, params: Record<string, unknown>, signal: AbortSignal, admission: { admitted: boolean }) => Promise<WorkflowScriptChildResult>;
202
369
  status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
203
370
  state?: {
204
371
  get: (key: string) => unknown | Promise<unknown>;
205
372
  set: (key: string, value: unknown) => void | Promise<void>;
206
373
  };
374
+ prompts?: {
375
+ render: (ref: string, vars?: unknown) => string | Promise<string>;
376
+ };
207
377
  onTrace?: (trace: WorkflowScriptTraceEntry[]) => void;
208
378
  onEmit?: (emits: unknown[]) => void;
209
379
  }
@@ -301,10 +471,13 @@ function validateKey(value: unknown, owner = "runs.run"): string {
301
471
  return value;
302
472
  }
303
473
 
304
- function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowScriptTraceEntry, "phase" | "label"> {
474
+ function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowScriptTraceEntry, "phase" | "label" | "agent"> {
305
475
  return {
306
476
  ...(typeof params.phase === "string" && params.phase.trim() ? { phase: params.phase.trim() } : {}),
307
477
  ...(typeof params.label === "string" && params.label.trim() ? { label: params.label.trim() } : {}),
478
+ // Requested agent name, so a child is identifiable while it runs. Launch
479
+ // resolution overwrites this with the canonical name on the terminal entry.
480
+ ...(typeof params.agent === "string" && params.agent.trim() ? { agent: params.agent.trim() } : {}),
308
481
  };
309
482
  }
310
483
 
@@ -318,7 +491,10 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
318
491
  const trace: WorkflowScriptTraceEntry[] = [];
319
492
  const children = new Map<string, WorkflowScriptChildResult>();
320
493
  const childOrder: string[] = [];
321
- const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult> }>();
494
+ const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult>; observed: boolean }>();
495
+ const stoppedLaunches = new Set<string>();
496
+ const batchAdmissions = new Map<string, Promise<void>>();
497
+ const observedRunCalls = new Set<number>();
322
498
  const childController = new AbortController();
323
499
  let settled = false;
324
500
 
@@ -335,11 +511,39 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
335
511
  if (timer) clearTimeout(timer);
336
512
  options.signal?.removeEventListener("abort", onAbort);
337
513
  void worker.terminate();
338
- childController.abort("error" in outcome ? outcome.error : new Error("Workflow script completed; unawaited child launches are aborted."));
514
+ const unobservedKeys = "value" in outcome ? [...launches].filter(([, launch]) => !launch.observed).map(([key]) => key) : [];
515
+ const completionError = unobservedKeys.length > 0
516
+ ? new Error(`workflowScript completed with unawaited runs.run launch(es): ${unobservedKeys.map((key) => `'${key}'`).join(", ")}. Await or return each launch.`)
517
+ : undefined;
518
+ childController.abort("error" in outcome ? outcome.error : completionError ?? new Error("Workflow script completed."));
339
519
  if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial()));
520
+ else if (completionError) reject(new WorkflowScriptError(completionError.message, partial()));
340
521
  else resolve({ value: outcome.value, ...partial() });
341
522
  };
342
- const onAbort = () => finish({ error: new Error("Workflow script aborted.") });
523
+ const onAbort = () => {
524
+ const signalReason = options.signal?.reason;
525
+ const error = signalReason instanceof Error
526
+ ? signalReason
527
+ : typeof signalReason === "string"
528
+ ? new Error(signalReason)
529
+ : new Error("Workflow script aborted.");
530
+ for (const key of launches.keys()) {
531
+ if (children.has(key)) continue;
532
+ stoppedLaunches.add(key);
533
+ const started = trace.findLast((entry) => entry.operation === "run" && entry.key === key && entry.state === "started");
534
+ trace.push({
535
+ operation: "run",
536
+ key,
537
+ state: "stopped",
538
+ ...(started?.agent ? { agent: started.agent } : {}),
539
+ ...(started?.phase ? { phase: started.phase } : {}),
540
+ ...(started?.label ? { label: started.label } : {}),
541
+ error: error.message,
542
+ });
543
+ }
544
+ traceChanged();
545
+ finish({ error });
546
+ };
343
547
  const timer = options.timeoutMs === undefined
344
548
  ? undefined
345
549
  : setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
@@ -351,6 +555,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
351
555
  if (!settled && code !== 0) finish({ error: new Error(`Workflow worker exited with code ${code}.`) });
352
556
  });
353
557
  worker.on("message", (message: Record<string, unknown>) => {
558
+ if (settled) return;
354
559
  if (message.type === "emit") {
355
560
  try {
356
561
  assertWorkflowJsonValue(message.value, "emit");
@@ -381,6 +586,13 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
381
586
  return finish({ value: message.value });
382
587
  }
383
588
  if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Workflow script failed.") });
589
+ if (message.type === "runObserved" && typeof message.callId === "number") {
590
+ const key = typeof message.key === "string" ? message.key : undefined;
591
+ const launch = key ? launches.get(key) : undefined;
592
+ if (launch) launch.observed = true;
593
+ else observedRunCalls.add(message.callId);
594
+ return;
595
+ }
384
596
  if (message.type !== "call" || typeof message.callId !== "number" || typeof message.method !== "string" || !isRecord(message.args)) return;
385
597
 
386
598
  const respond = (promise: Promise<unknown>) => {
@@ -394,6 +606,17 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
394
606
  );
395
607
  };
396
608
 
609
+ if (message.method === "prompts.render") {
610
+ if (!options.prompts) return respond(Promise.reject(new Error("Workflow prompt rendering is unavailable.")));
611
+ const ref = message.args.ref;
612
+ const vars = message.args.vars;
613
+ if (typeof ref !== "string" || !ref.trim()) return respond(Promise.reject(new Error("prompts.render(ref, vars) requires a non-empty ref string.")));
614
+ return respond(Promise.resolve().then(() => options.prompts!.render(ref, vars)).then((rendered) => {
615
+ if (typeof rendered !== "string") throw new Error("prompts.render must return task text.");
616
+ return rendered;
617
+ }));
618
+ }
619
+
397
620
  if (message.method === "state.get" || message.method === "state.set") {
398
621
  if (!options.state) return respond(Promise.reject(new Error("Workflow state is unavailable without a mission.")));
399
622
  let key: string;
@@ -419,7 +642,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
419
642
  const target = known?.runId ?? keyOrRunId;
420
643
  trace.push({ operation: "status", key: keyOrRunId, state: "started", ...(known?.runId ? { runId: known.runId } : {}) });
421
644
  traceChanged();
645
+ if (settled) return;
422
646
  respond(options.status(target, childController.signal).then((result) => {
647
+ if (settled) return result;
423
648
  trace.push({ operation: "status", key: keyOrRunId, state: result.ok ? "completed" : "failed", ...(result.runId ? { runId: result.runId } : {}), ...(!result.ok ? { error: result.output } : {}) });
424
649
  traceChanged();
425
650
  if (!result.ok) throw new Error(`Status '${keyOrRunId}' failed: ${result.output}`);
@@ -464,6 +689,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
464
689
  return respond(Promise.reject(new Error(`runs.run('${key}') resume requires a non-empty task follow-up.`)));
465
690
  }
466
691
  const collectFailure = message.args.collectFailure === true;
692
+ const callObserved = observedRunCalls.delete(message.callId);
467
693
  const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
468
694
  ? promise
469
695
  : promise.then((result) => {
@@ -474,30 +700,57 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
474
700
  const existing = launches.get(key);
475
701
  if (existing) {
476
702
  if (existing.fingerprint !== fingerprint) return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
703
+ if (callObserved) existing.observed = true;
477
704
  trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
478
705
  traceChanged();
479
706
  return respond(deliver(existing.promise));
480
707
  }
481
708
 
482
709
  const startedAt = Date.now();
483
- childOrder.push(key);
484
- trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
485
- traceChanged();
486
- const promise = Promise.resolve().then(() => options.launch(key, { ...params, async: params.async ?? false }, childController.signal)).then((result) => {
710
+ const batch = isRecord(message.args.batch) && typeof message.args.batch.id === "string" && Array.isArray(message.args.batch.calls)
711
+ ? { 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)) }
712
+ : undefined;
713
+ let admission = batch ? batchAdmissions.get(batch.id) : undefined;
714
+ if (!admission) {
715
+ const seenKeys = new Set<string>();
716
+ const calls = (batch?.calls ?? [{ key, params }]).filter((call) => {
717
+ if (seenKeys.has(call.key) || launches.has(call.key) || call.params.resume !== undefined) return false;
718
+ seenKeys.add(call.key);
719
+ return true;
720
+ });
721
+ admission = Promise.resolve().then(() => {
722
+ if (settled) return;
723
+ return options.admit?.(calls);
724
+ });
725
+ if (batch) batchAdmissions.set(batch.id, admission);
726
+ }
727
+ const promise = admission.then(() => {
728
+ if (settled || stoppedLaunches.has(key)) {
729
+ const reason = childController.signal.reason;
730
+ const text = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.";
731
+ return { key, ok: false, output: text, error: text, artifactPaths: [] };
732
+ }
733
+ return options.launch(key, { ...params, async: params.async ?? false }, childController.signal, { admitted: true });
734
+ }).then((result) => {
487
735
  const normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
736
+ if (stoppedLaunches.has(key)) return normalized;
488
737
  children.set(key, normalized);
489
- trace.push({ operation: "run", key, state: normalized.ok ? "completed" : "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
738
+ 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 } : {}) });
490
739
  traceChanged();
491
740
  return normalized;
492
741
  }, (error: unknown) => {
493
742
  const text = error instanceof Error ? error.message : String(error);
494
743
  const failure: WorkflowScriptChildResult = { key, ok: false, output: text, error: text, artifactPaths: [] };
744
+ if (stoppedLaunches.has(key)) return failure;
495
745
  children.set(key, failure);
496
746
  trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), error: text });
497
747
  traceChanged();
498
748
  return failure;
499
749
  });
500
- launches.set(key, { fingerprint, promise });
750
+ launches.set(key, { fingerprint, promise, observed: callObserved });
751
+ childOrder.push(key);
752
+ trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
753
+ traceChanged();
501
754
  respond(deliver(promise));
502
755
  });
503
756