@niwa-labs/workflow 0.0.0-stage → 0.0.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 (114) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +13 -2
  3. package/package.json +55 -4
  4. package/src/actions.ts +408 -0
  5. package/src/agent.ts +211 -0
  6. package/src/ask.ts +84 -0
  7. package/src/bridge.ts +710 -0
  8. package/src/catalogue.ts +74 -0
  9. package/src/check.ts +880 -0
  10. package/src/child.ts +1378 -0
  11. package/src/cockpit/actions.ts +128 -0
  12. package/src/cockpit/catalogue-actions.ts +97 -0
  13. package/src/cockpit/dashboard.tsx +134 -0
  14. package/src/cockpit/groups.ts +45 -0
  15. package/src/cockpit/index.tsx +50 -0
  16. package/src/cockpit/launch.tsx +136 -0
  17. package/src/cockpit/plan.ts +101 -0
  18. package/src/cockpit/run-commands.tsx +102 -0
  19. package/src/cockpit/run-page.tsx +140 -0
  20. package/src/cockpit/run-summary.ts +16 -0
  21. package/src/cockpit/runs.tsx +73 -0
  22. package/src/cockpit/statistics.tsx +176 -0
  23. package/src/cockpit/track.tsx +159 -0
  24. package/src/cockpit/workflows.tsx +383 -0
  25. package/src/describe-cache.ts +122 -0
  26. package/src/describe.ts +174 -0
  27. package/src/guide.ts +213 -0
  28. package/src/index.ts +2813 -0
  29. package/src/inspect.ts +235 -0
  30. package/src/installation.ts +90 -0
  31. package/src/language.ts +217 -0
  32. package/src/records-entry.ts +63 -0
  33. package/src/records.ts +574 -0
  34. package/src/registry.ts +250 -0
  35. package/src/revise.ts +89 -0
  36. package/src/runner.ts +339 -0
  37. package/src/script-types.ts +549 -0
  38. package/src/stats.ts +460 -0
  39. package/src/status.ts +512 -0
  40. package/src/store.ts +259 -0
  41. package/src/subscriptions.ts +102 -0
  42. package/src/waiting.ts +61 -0
  43. package/test/cockpit-actions.test.ts +20 -0
  44. package/test/cockpit-groups.test.ts +42 -0
  45. package/test/cockpit-plan.test.ts +118 -0
  46. package/test/fixtures/branches-host.ts +58 -0
  47. package/test/fixtures/branches-script.js +23 -0
  48. package/test/fixtures/bridge-host.ts +23 -0
  49. package/test/fixtures/bridge-keys-script.js +15 -0
  50. package/test/fixtures/bridge-wait-script.js +8 -0
  51. package/test/fixtures/cancel-host.ts +58 -0
  52. package/test/fixtures/cancel-script.js +12 -0
  53. package/test/fixtures/crash-host.ts +61 -0
  54. package/test/fixtures/crash-script.js +14 -0
  55. package/test/fixtures/ping-records.ts +20 -0
  56. package/test/fixtures/revision-host.ts +57 -0
  57. package/test/fixtures/revision-script.js +11 -0
  58. package/test/fixtures/running-host.ts +61 -0
  59. package/test/fixtures/running-script.js +12 -0
  60. package/test/fixtures/with-data/flow.ts +2 -0
  61. package/test/fixtures/with-data/table.json +1 -0
  62. package/test/git-repo.ts +45 -0
  63. package/test/git-worktree.test.ts +413 -0
  64. package/test/question-format.test.ts +279 -0
  65. package/test/workflow-agent-caps.test.ts +91 -0
  66. package/test/workflow-agent-lifetime.test.ts +93 -0
  67. package/test/workflow-agent-options.test.ts +216 -0
  68. package/test/workflow-agent-schema.test.ts +386 -0
  69. package/test/workflow-agent-typings.test.ts +241 -0
  70. package/test/workflow-ask-resume.test.ts +145 -0
  71. package/test/workflow-branch-keys.test.ts +133 -0
  72. package/test/workflow-bridge-inproc.test.ts +230 -0
  73. package/test/workflow-bridge.test.ts +141 -0
  74. package/test/workflow-builtin-candidate.test.ts +230 -0
  75. package/test/workflow-builtin.test.ts +197 -0
  76. package/test/workflow-cancel-agent.test.ts +144 -0
  77. package/test/workflow-cancel.test.ts +166 -0
  78. package/test/workflow-chain.test.ts +84 -0
  79. package/test/workflow-check-options.test.ts +144 -0
  80. package/test/workflow-check-uses.test.ts +148 -0
  81. package/test/workflow-check.test.ts +282 -0
  82. package/test/workflow-contract.test.ts +295 -0
  83. package/test/workflow-crash-resume.test.ts +141 -0
  84. package/test/workflow-deadline.test.ts +102 -0
  85. package/test/workflow-describe-cache.test.ts +240 -0
  86. package/test/workflow-directory.test.ts +73 -0
  87. package/test/workflow-emits.test.ts +261 -0
  88. package/test/workflow-group-keys.test.ts +72 -0
  89. package/test/workflow-harnesses.test.ts +262 -0
  90. package/test/workflow-inspect.test.ts +152 -0
  91. package/test/workflow-language-types.test.ts +148 -0
  92. package/test/workflow-manifest.test.ts +93 -0
  93. package/test/workflow-manual-pause.test.ts +116 -0
  94. package/test/workflow-owners.test.ts +154 -0
  95. package/test/workflow-pause.test.ts +200 -0
  96. package/test/workflow-phases.test.ts +445 -0
  97. package/test/workflow-plugin-entries.test.ts +59 -0
  98. package/test/workflow-record-refs.test.ts +310 -0
  99. package/test/workflow-replay.test.ts +206 -0
  100. package/test/workflow-resume-once.test.ts +188 -0
  101. package/test/workflow-revision.test.ts +216 -0
  102. package/test/workflow-scope.test.ts +505 -0
  103. package/test/workflow-script-defaults.test.ts +119 -0
  104. package/test/workflow-script-error.test.ts +228 -0
  105. package/test/workflow-script-libraries.test.ts +88 -0
  106. package/test/workflow-script-packages.test.ts +119 -0
  107. package/test/workflow-stdout.test.ts +89 -0
  108. package/test/workflow-stop.test.ts +299 -0
  109. package/test/workflow-store.test.ts +220 -0
  110. package/test/workflow-visible.test.ts +136 -0
  111. package/test/workflow-wait-version.test.ts +54 -0
  112. package/test/workflow-wait.test.ts +224 -0
  113. package/test/workflow-waiting-agent.test.ts +64 -0
  114. package/tsconfig.json +15 -0
package/src/child.ts ADDED
@@ -0,0 +1,1378 @@
1
+ // The disposable process of a workflow run: it loads the script and speaks one JSON line at a time
2
+ // to the parent. It keeps nothing: every call, phase and log line goes to the parent.
3
+ //
4
+ // The protocol lines carry a prefix, and the script shares the stdout with the child: a line the
5
+ // child did not write is the script's own output and is passed through to the parent as a log.
6
+ //
7
+ // The key of a call says which branch it belongs to: the branches of a `parallel` and the stages
8
+ // of a `pipeline` are numbered, and the calls of a branch are numbered within it. A key that
9
+ // counted the calls of the whole script would be decided by the order the calls arrive in, and
10
+ // the branches would take each other's answers on a replay.
11
+ //
12
+ // The child has two modes. `run` runs the script's function with its input. `describe` only loads the
13
+ // module and prints what its `workflow({ input, output, ... }, fn)` call declares: the niwa globals
14
+ // are inert stubs there, so the top level of a module that calls one fails with a clear error, and
15
+ // the function of the script is never called.
16
+ //
17
+ // Usage: bun child.ts run <script url> <args as json>
18
+ // bun child.ts describe <script url>
19
+
20
+ import { AsyncLocalStorage } from "node:async_hooks";
21
+
22
+ import { z } from "zod";
23
+
24
+ import { JsonSchemaValue, jsonOf } from "@niwa-labs/core";
25
+ import type { Question } from "@niwa-labs/core";
26
+ import { WorktreeOption } from "@niwa-labs/git/records";
27
+ import { blocksOf, promptFromText } from "@niwa-labs/harness";
28
+ import type { OptionBlocks } from "@niwa-labs/harness";
29
+ import type { CallOptions, Duration, ScriptSession, SessionPrompt } from "@niwa-labs/script";
30
+
31
+ import { choiceQuestion, confirmQuestion, formQuestion, multiQuestion, textQuestion } from "./ask.ts";
32
+ import type { AskOption } from "./ask.ts";
33
+ import { AGENT_REQUEST_FIELDS, PROTOCOL_PREFIX, WorkflowPhases, durationMs } from "./language.ts";
34
+ import type { AgentOptions, ScriptRequest } from "./language.ts";
35
+
36
+ const [mode, scriptUrl, argsJson] = process.argv.slice(2);
37
+
38
+ let calls = 0;
39
+ let outside = 0;
40
+ const pending = new Map<number, { resolve(value: unknown): void; reject(error: Error): void; branch?: Branch | undefined; parked?: boolean; clock?: boolean }>();
41
+
42
+ /**
43
+ * Let the process end once nothing is left for it to do.
44
+ *
45
+ * A call the host parked (a wait for a record that has not arrived) is answered by a later start of
46
+ * the run, not by this process, and a wait for the deadline of a scope is answered when the process
47
+ * is gone. When every call in flight is one of those, stdin no longer holds the process: it ends
48
+ * once the script's own code has nothing more to run, and the run waits. Any other call holds it.
49
+ */
50
+ function holdWhileNeeded(): void {
51
+ const calls = [...pending.values()];
52
+ if (calls.some((one) => one.parked === true) && calls.every((one) => one.parked === true || one.clock === true)) process.stdin.unref();
53
+ else process.stdin.ref();
54
+ }
55
+
56
+ /** The branch a call belongs to: its path in the script, and the calls made in it. */
57
+ interface Branch {
58
+ /** The path of the branch: the branches of a parallel and the stages of a pipeline. */
59
+ readonly path: string;
60
+ /** The group the branch belongs to: the one whose member or whose block it is. */
61
+ readonly group?: Group;
62
+ /** The member of the group the branch runs, when it is not the block of the group. */
63
+ readonly member?: Member;
64
+ /** The streams opened in the branch and not closed yet: they close when it ends. */
65
+ readonly streams: Set<StreamHandle>;
66
+ /** How many calls the branch has made: the number of an unlabeled call within it. */
67
+ ordinal: number;
68
+ /** How many groups (a parallel or a pipeline) the branch has started: the number of the next. */
69
+ groups: number;
70
+ /** The declared phase the branch is in: the one it was made in, until it enters another. */
71
+ phase: string | undefined;
72
+ /** How many times the branch entered a phase: the number of the next change, 0 being the one it was made in. */
73
+ phases: number;
74
+ /** A call of the branch ran instead of being taken from an earlier start: the calls after it lie after a change. */
75
+ diverged: boolean;
76
+ }
77
+
78
+ /** The branch the call is made in. The script itself is the branch of no path. */
79
+ const BRANCH = new AsyncLocalStorage<Branch>();
80
+
81
+ /** How many groups the script itself has started: the script is the branch of no path. */
82
+ let outsideGroups = 0;
83
+
84
+ /** A call of the script itself ran instead of being taken from an earlier start. */
85
+ let outsideDiverged = false;
86
+
87
+ /** Whether the calls of a branch (the script itself when absent) lie after a change. */
88
+ const divergedIn = (branch: Branch | undefined): boolean => (branch === undefined ? outsideDiverged : branch.diverged);
89
+
90
+ /** The calls of a branch lie after a change from now on. */
91
+ function diverge(branch: Branch | undefined): void {
92
+ if (branch === undefined) outsideDiverged = true;
93
+ else branch.diverged = true;
94
+ }
95
+
96
+ /** The phase the script itself is in, and how many times it entered one. */
97
+ let outsidePhase: string | undefined;
98
+ let outsidePhases = 0;
99
+
100
+ /** The titles of the phases the script declares: what `phase(title)` may name. */
101
+ let declaredTitles: readonly string[] = [];
102
+
103
+ function say(message: unknown, then?: () => void): void {
104
+ process.stdout.write(`${PROTOCOL_PREFIX}${JSON.stringify(message)}\n`, then);
105
+ }
106
+
107
+ function exitWith(code: number): never {
108
+ process.exit(code);
109
+ }
110
+
111
+ /**
112
+ * Run something in a branch of its own.
113
+ *
114
+ * The path of the branch is the path of the branch it is in, plus the name of this one: a
115
+ * parallel inside a parallel keeps the two apart. The branch starts in the phase of the branch it
116
+ * is made in, and its own `phase()` changes only it; a branch that was in a phase says when it ends.
117
+ */
118
+ function inBranch<T>(group: string, name: string, body: () => T | Promise<T>): Promise<T> {
119
+ const parent = BRANCH.getStore();
120
+ const own = `${group}.${name}`;
121
+ const path = parent === undefined ? own : `${parent.path}.${own}`;
122
+ const phase = parent === undefined ? outsidePhase : parent.phase;
123
+ const branch: Branch = { path, ordinal: 0, groups: 0, phase, phases: 0, streams: new Set(), diverged: divergedIn(parent) };
124
+ return BRANCH.run(branch, async () => {
125
+ if (phase !== undefined) say({ kind: "phase", branch: path, ordinal: 0, phase });
126
+ try {
127
+ return await body();
128
+ } finally {
129
+ // A stage that ran a call leaves the stages after it after a change.
130
+ if (branch.diverged) diverge(parent);
131
+ if (branch.phase !== undefined) say({ kind: "left", branch: path });
132
+ }
133
+ });
134
+ }
135
+
136
+ /**
137
+ * The name of the next group of branches in the branch the caller is in.
138
+ *
139
+ * A script that runs two groups one after the other, or one in a loop, numbers the branches of
140
+ * each from zero: the group has a number of its own, so the branches of the second are not the
141
+ * branches of the first. The number is taken when the group starts, in the order of the script.
142
+ */
143
+ function nextGroup(kind: "p" | "s"): string {
144
+ const branch = BRANCH.getStore();
145
+ if (branch === undefined) return `${kind}${String(++outsideGroups)}`;
146
+ branch.groups += 1;
147
+ return `${kind}${String(branch.groups)}`;
148
+ }
149
+
150
+ /** The labels the script has used: one label names one call of the run. */
151
+ const labels = new Set<string>();
152
+
153
+ /**
154
+ * The key of a call.
155
+ *
156
+ * A labeled call is keyed by its label, under `label:` so that no label can be the name of a record
157
+ * the run writes itself (`finished`, `started`) or an unlabeled key. The label is the name the
158
+ * author gave the call, and it says what the call is however the script is arranged, so a label
159
+ * is used once in a run: a second call under it would be answered with the first one's answer.
160
+ * `~` is the mark of the steps a call needs besides its own, so a label does not hold one.
161
+ *
162
+ * An unlabeled call is keyed by the branch it is in and by its number within that branch: the
163
+ * key of a call of a branch does not depend on the calls of the other branches, so a branch
164
+ * that answers before another one does not take its place.
165
+ */
166
+ function keyOf(label: string | undefined): string {
167
+ if (label !== undefined) {
168
+ if (label.includes("~")) throw new Error(`the label "${label}" holds "~", which is kept for the steps of a call`);
169
+ if (labels.has(label)) throw new Error(`the label "${label}" is used twice in this run: a label names one call`);
170
+ labels.add(label);
171
+ // In a scope the key of a labeled call starts with the path of its branch, so a cancel of the branch holds it.
172
+ const inScope = BRANCH.getStore();
173
+ return inScope !== undefined && inScope.path.includes("@") ? `${inScope.path}.label:${label}` : `label:${label}`;
174
+ }
175
+ const branch = BRANCH.getStore();
176
+ if (branch === undefined) return `call-${String(++outside)}`;
177
+ branch.ordinal += 1;
178
+ return `${branch.path}.call-${String(branch.ordinal)}`;
179
+ }
180
+
181
+ const globals = globalThis as Record<string, unknown>;
182
+
183
+ // zod is a global of the script, as the language functions are: a script writes `z.object({ ... })`
184
+ // with no import.
185
+ globals.z = z;
186
+
187
+ /** The phase of the branch the caller is in. */
188
+ function currentPhase(): string | undefined {
189
+ const branch = BRANCH.getStore();
190
+ return branch === undefined ? outsidePhase : branch.phase;
191
+ }
192
+
193
+ /**
194
+ * Ask the parent to do something and wait for the answer.
195
+ *
196
+ * Every request takes its key here, in the branch it is made in, so the key does not depend on
197
+ * which branch the parent answered first. The phase of the branch goes beside the request, not in
198
+ * it: the parent records it against the key.
199
+ */
200
+ function request(body: ScriptRequest, label: string | undefined): Promise<unknown> {
201
+ const phase = currentPhase();
202
+ const ordinal = ++calls;
203
+ let key: string;
204
+ try {
205
+ key = keyOf(label);
206
+ } catch (error) {
207
+ return Promise.reject(error);
208
+ }
209
+ // A labeled call outside a scope is keyed by its label alone: a cancel of its branch names it while it is in flight.
210
+ const branch = BRANCH.getStore();
211
+ if (branch !== undefined && key.startsWith("label:")) inflightLabels.set(key, branch.path);
212
+ const after = divergedIn(branch);
213
+ return new Promise((resolve, reject) => {
214
+ pending.set(ordinal, { resolve, reject, branch });
215
+ holdWhileNeeded();
216
+ say({ kind: "call", ordinal, key, ...(phase === undefined ? {} : { phase }), ...(after ? { after: true } : {}), request: body });
217
+ }).finally(() => inflightLabels.delete(key));
218
+ }
219
+
220
+ /** The labeled calls in flight outside any scope, by key: the path of the branch each one is in. */
221
+ const inflightLabels = new Map<string, string>();
222
+
223
+ /** Ask the parent something about a group, under a key the group gives it: it takes no number from the calls. */
224
+ function requestAt(body: ScriptRequest, key: string): Promise<unknown> {
225
+ const ordinal = ++calls;
226
+ return new Promise((resolve, reject) => {
227
+ pending.set(ordinal, { resolve, reject, ...(body.op === "scope-deadline" ? { clock: true } : {}) });
228
+ holdWhileNeeded();
229
+ say({ kind: "call", ordinal, key, request: body });
230
+ });
231
+ }
232
+
233
+ /**
234
+ * The JSON Schema of the answer a zod schema describes, which is what travels to the host.
235
+ *
236
+ * The agent writes the input shape of the schema; the script gets the output shape, after the
237
+ * transforms and defaults of the schema, so the schema is read as an input here and parsed
238
+ * with here when the answer comes back.
239
+ */
240
+ function answerSchema(schema: z.ZodType): JsonSchemaValue {
241
+ return JsonSchemaValue.parse(z.toJSONSchema(schema, { io: "input" }));
242
+ }
243
+
244
+ function launch(opts: AgentOptions, prompt?: SessionPrompt): Promise<unknown> {
245
+ let schema: JsonSchemaValue | undefined;
246
+ let blocks: OptionBlocks;
247
+ let worktree: WorktreeOption | undefined;
248
+ let stuckAfter: number | undefined;
249
+ try {
250
+ stuckAfter = opts.stuckAfter === undefined ? undefined : durationMs(opts.stuckAfter);
251
+ schema = opts.schema === undefined ? undefined : answerSchema(opts.schema);
252
+ blocks = blocksOf(opts, AGENT_REQUEST_FIELDS);
253
+ worktree = opts.worktree === undefined ? undefined : WorktreeOption.parse(opts.worktree);
254
+ } catch (error) {
255
+ return Promise.reject(error);
256
+ }
257
+ const answer = request(
258
+ {
259
+ op: "agent",
260
+ input: {
261
+ ...(prompt === undefined ? {} : { prompt }),
262
+ ...(opts.harness === undefined ? {} : { harness: opts.harness }),
263
+ ...(opts.label === undefined ? {} : { label: opts.label }),
264
+ ...(opts.tools === undefined ? {} : { tools: opts.tools }),
265
+ ...(opts.visible === undefined ? {} : { visible: opts.visible }),
266
+ ...(opts.model === undefined ? {} : { model: opts.model }),
267
+ ...(opts.effort === undefined ? {} : { effort: opts.effort }),
268
+ ...(opts.mode === undefined ? {} : { mode: opts.mode }),
269
+ ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
270
+ ...(worktree === undefined ? {} : { worktree }),
271
+ ...(stuckAfter === undefined ? {} : { stuckAfter }),
272
+ ...(opts.box === undefined ? {} : { box: opts.box }),
273
+ ...blocks,
274
+ ...(schema === undefined ? {} : { schema }),
275
+ },
276
+ },
277
+ opts.label,
278
+ );
279
+ const wanted = opts.schema;
280
+ if (wanted === undefined) return answer;
281
+ // A worktree that was kept rides along with the answer: the schema is the answer's alone.
282
+ return answer.then(async (value) => {
283
+ const { worktree, ...rest } = (value ?? {}) as { worktree?: unknown };
284
+ const parsed: unknown = await wanted.parseAsync(opts.worktree === undefined ? value : rest);
285
+ return opts.worktree === undefined || worktree === undefined ? parsed : { ...(parsed as object), worktree };
286
+ });
287
+ }
288
+
289
+ globals.agent = function (name: string) {
290
+ if (arguments.length !== 1 || typeof name !== "string" || !name.trim()) {
291
+ throw new TypeError("agent(name) takes the name of a mailbox agent");
292
+ }
293
+ return { tell: (text: string, opts?: CallOptions) => callOf("agent.tell", { agent: name, text }, opts) };
294
+ };
295
+
296
+ async function openSession(options: AgentOptions): Promise<ScriptSession> {
297
+ if (!options || typeof options !== "object" || options.schema !== undefined) {
298
+ throw new TypeError("session(options) takes launch options; pass the answer schema to its ask method");
299
+ }
300
+ const started = await launch(options) as { session: string; ref: string; worktree?: ScriptSession["worktree"] };
301
+ const id = started.session;
302
+ const separator = started.ref.indexOf(" ");
303
+ let ending: Promise<void> | undefined;
304
+ let previous: Promise<unknown> = Promise.resolve();
305
+ const askTurn = (prompt: SessionPrompt, opts: { schema?: z.ZodType; label?: string } = {}) => {
306
+ if (ending !== undefined) return Promise.reject(new Error("this workflow session has ended"));
307
+ // A harness has one conversation. Order concurrent turns even when its adapter accepts both.
308
+ const turn = async () => {
309
+ const schema = opts.schema ?? z.object({ answer: z.string() });
310
+ const content = typeof prompt === "string" ? promptFromText(prompt) : prompt;
311
+ const output = await callOf("session.ask", { session: id, prompt: content, schema: answerSchema(schema) }, opts) as { value: unknown };
312
+ return schema.parseAsync(output.value);
313
+ };
314
+ previous = previous.then(turn, turn);
315
+ return previous;
316
+ };
317
+ return {
318
+ id,
319
+ ref: started.ref,
320
+ address: { kind: "session", harness: started.ref.slice(0, separator), id: started.ref.slice(separator + 1) },
321
+ ...(started.worktree === undefined ? {} : { worktree: started.worktree }),
322
+ ask: askTurn as ScriptSession["ask"],
323
+ end(opts) {
324
+ const close = async () => {
325
+ await callOf("session.end", { session: id, reason: "workflow session ended" }, opts);
326
+ };
327
+ return ending ??= previous.then(close, close);
328
+ },
329
+ };
330
+ }
331
+
332
+ globals.session = (options: AgentOptions) => {
333
+ let opened: Promise<ScriptSession> | undefined;
334
+ let ended = false;
335
+ const open = () => {
336
+ if (ended) throw new Error("this workflow session has ended");
337
+ return opened ??= openSession(options);
338
+ };
339
+ return {
340
+ // Awaiting a session opens it when the script needs its address before its first turn.
341
+ then: (resolve: (session: ScriptSession) => unknown, reject: (error: unknown) => unknown) =>
342
+ Promise.resolve().then(open).then(resolve, reject),
343
+ ask: async (prompt: SessionPrompt, opts?: { label?: string; schema?: z.ZodType }) => {
344
+ const session = await open();
345
+ return opts?.schema === undefined ? session.ask(prompt, opts) : session.ask(prompt, { ...opts, schema: opts.schema });
346
+ },
347
+ end: async (opts?: CallOptions) => {
348
+ ended = true;
349
+ if (opened !== undefined) await (await opened).end(opts);
350
+ },
351
+ };
352
+ };
353
+
354
+ /** The reason a call carries, when it has one. */
355
+ const reasonOf = (opts: CallOptions | undefined): { reason?: string } =>
356
+ opts?.reason === undefined ? {} : { reason: opts.reason };
357
+
358
+ /** The call of an action: an input that has no JSON form is a rejection, as any other failure of a call is. */
359
+ function callOf(action: string, input: unknown, opts: CallOptions | undefined): Promise<unknown> {
360
+ let body: ScriptRequest;
361
+ try {
362
+ body = { op: "call", action, input: jsonOf(input), ...reasonOf(opts) };
363
+ } catch (error) {
364
+ return Promise.reject(error);
365
+ }
366
+ return request(body, opts?.label);
367
+ }
368
+
369
+ globals.call = (name: string, input: unknown, opts: CallOptions = {}): Promise<unknown> => callOf(name, input, opts);
370
+
371
+ /**
372
+ * `niwa.task.create` is the action `task.create`: a group is a path, and a call of the path is
373
+ * the call of the action of that name. The names are not listed here: an action nobody serves
374
+ * is a failed step, as it is for `call`. A group is never thenable, so `await niwa.task` is the
375
+ * group and not a call of an action named `task.then`.
376
+ */
377
+ function group(path: readonly string[]): unknown {
378
+ const target = (input?: unknown, opts?: CallOptions): Promise<unknown> => {
379
+ if (path.length === 0) throw new TypeError("niwa is a group of actions: call niwa.<group>.<action>(input)");
380
+ return callOf(path.join("."), input, opts);
381
+ };
382
+ return new Proxy(target, {
383
+ get: (_target, name) => (typeof name === "symbol" || name === "then" ? undefined : group([...path, name])),
384
+ });
385
+ }
386
+ globals.niwa = group([]);
387
+
388
+ /** A record type a plugin declares, as a script imports it from the plugin's records entry: its name and version. */
389
+ interface RecordRef {
390
+ readonly kind: "record";
391
+ readonly name: string;
392
+ readonly version: number;
393
+ }
394
+
395
+ const isRecordRef = (value: unknown): value is RecordRef =>
396
+ typeof value === "object" &&
397
+ value !== null &&
398
+ (value as { kind?: unknown }).kind === "record" &&
399
+ typeof (value as { name?: unknown }).name === "string" &&
400
+ typeof (value as { version?: unknown }).version === "number";
401
+
402
+ /**
403
+ * The name of a type a wait or a read names, and the version a reference holds: the host waits for and
404
+ * reads the type it knows, and refuses a reference to a version it does not write.
405
+ */
406
+ function typeNamed(type: unknown, call: string): { name: string; version?: number } {
407
+ if (typeof type === "string") return { name: type };
408
+ if (isRecordRef(type)) return { name: type.name, version: type.version };
409
+ if (isDeclaredRecord(type)) {
410
+ throw new TypeError(`${call}: "${type.name}" is a record a script writes: name its type as text, "wf.<name>.${type.name}"`);
411
+ }
412
+ throw new TypeError(`${call}: a type is a name, or a record type imported from the records entry of a plugin`);
413
+ }
414
+
415
+ /** What a wait is given besides its type. */
416
+ interface WaitOptions {
417
+ filter?: Record<string, unknown>;
418
+ from?: number;
419
+ timeout?: Duration;
420
+ label?: string;
421
+ }
422
+
423
+ /**
424
+ * The type of a wait and what it is given: a type, or a query of one type, as a plugin's query builder gives it, whose
425
+ * filter and position are the wait's (the options say the position when they say one).
426
+ */
427
+ function waitOf(first: unknown, opts: WaitOptions): { named: { name: string; version?: number }; filter?: Record<string, unknown>; from?: number } {
428
+ const query = typeof first === "object" && first !== null && "types" in first ? (first as { types?: unknown; filter?: Record<string, unknown>; from?: number; stream?: unknown }) : undefined;
429
+ if (query === undefined) {
430
+ return { named: typeNamed(first, "wait(type)"), ...(opts.filter === undefined ? {} : { filter: opts.filter }), ...(opts.from === undefined ? {} : { from: opts.from }) };
431
+ }
432
+ if (!Array.isArray(query.types) || query.types.length !== 1) throw new TypeError("wait(query): a wait waits for one type, and the query names " + (Array.isArray(query.types) ? String(query.types.length) : "none"));
433
+ if (query.stream !== undefined) throw new TypeError("wait(query): a wait looks at every stream, and the query names one");
434
+ const filter = query.filter === undefined && opts.filter === undefined ? undefined : { ...query.filter, ...opts.filter };
435
+ const from = opts.from ?? query.from;
436
+ return { named: typeNamed(query.types[0], "wait(query)"), ...(filter === undefined ? {} : { filter }), ...(from === undefined ? {} : { from }) };
437
+ }
438
+
439
+ globals.wait = (type: unknown, opts: WaitOptions = {}): Promise<unknown> => {
440
+ let wanted: ReturnType<typeof waitOf>;
441
+ try {
442
+ wanted = waitOf(type, opts);
443
+ } catch (error) {
444
+ return Promise.reject(error);
445
+ }
446
+ return request(
447
+ {
448
+ op: "wait",
449
+ type: wanted.named.name,
450
+ ...(wanted.named.version === undefined ? {} : { version: wanted.named.version }),
451
+ ...(wanted.filter === undefined ? {} : { filter: wanted.filter }),
452
+ ...(wanted.from === undefined ? {} : { from: wanted.from }),
453
+ ...(opts.timeout === undefined ? {} : { timeoutMs: durationMs(opts.timeout) }),
454
+ },
455
+ opts.label,
456
+ );
457
+ };
458
+
459
+ globals.sleep = (duration: Duration, opts: CallOptions = {}): Promise<unknown> =>
460
+ request({ op: "sleep", ms: durationMs(duration) }, opts.label);
461
+
462
+ /** What an `ask.<kind>` call may carry. */
463
+ interface AskOptions {
464
+ timeout?: Duration;
465
+ label?: string;
466
+ }
467
+
468
+ /** Put a question to the owner. The host gives the typed value back: the id, the ids, a boolean, a text, the form. */
469
+ function askOwner(question: Question, opts: AskOptions): Promise<unknown> {
470
+ return request(
471
+ { op: "ask", question, ...(opts.timeout === undefined ? {} : { timeoutMs: durationMs(opts.timeout) }) },
472
+ opts.label,
473
+ );
474
+ }
475
+
476
+ globals.ask = Object.assign((options: AgentOptions, prompt: SessionPrompt) => {
477
+ if (!options || typeof options !== "object" || prompt === undefined) {
478
+ throw new TypeError("ask(options, prompt) takes launch options and a prompt");
479
+ }
480
+ return launch(options, prompt);
481
+ }, {
482
+ choice: (text: string, options: readonly AskOption[], opts: AskOptions = {}): Promise<unknown> =>
483
+ askOwner(choiceQuestion(text, options), opts),
484
+ multi: (text: string, options: readonly AskOption[], opts: AskOptions = {}): Promise<unknown> =>
485
+ askOwner(multiQuestion(text, options), opts),
486
+ confirm: (text: string, opts: AskOptions = {}): Promise<unknown> => askOwner(confirmQuestion(text), opts),
487
+ text: (text: string, opts: AskOptions = {}): Promise<unknown> => askOwner(textQuestion(text), opts),
488
+ /** The value passes the schema the owner was shown, and again the zod schema of the script, here. */
489
+ form: async (text: string, schema: z.ZodType, opts: AskOptions = {}): Promise<unknown> =>
490
+ schema.parseAsync(await askOwner(formQuestion(text, answerSchema(schema)), opts)),
491
+ });
492
+
493
+ /** What `record(name, schema)` gives: a record type a script declares in `emits` and writes with `emit`. */
494
+ interface DeclaredRecord {
495
+ readonly niwaRecord: true;
496
+ readonly name: string;
497
+ readonly schema: z.ZodType;
498
+ }
499
+
500
+ const isDeclaredRecord = (value: unknown): value is DeclaredRecord =>
501
+ typeof value === "object" && value !== null && (value as { niwaRecord?: unknown }).niwaRecord === true;
502
+
503
+ /** The short name of a record a script declares: one or more words joined by dots, written under the script's own `wf.<name>.`. */
504
+ const RECORD_NAME = /^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/;
505
+
506
+ globals.record = (name: string, schema: z.ZodType): DeclaredRecord => {
507
+ if (typeof name !== "string" || !RECORD_NAME.test(name)) throw new TypeError(`record(name, schema): "${String(name)}" is not a record name (words joined by dots)`);
508
+ if (!isZod(schema)) throw new TypeError(`record("${name}", schema): the schema is a zod schema`);
509
+ return { niwaRecord: true, name, schema };
510
+ };
511
+
512
+ /** The records the script declares in `emits`: set when the module is loaded, so `emit` writes only those. */
513
+ let declaredEmits: readonly unknown[] = [];
514
+
515
+ globals.emit = async (declared: unknown, data: unknown, opts: CallOptions = {}): Promise<unknown> => {
516
+ if (!isDeclaredRecord(declared) || !declaredEmits.includes(declared)) {
517
+ throw new TypeError("emit(record, data): the record is one the script lists in workflow({ emits })");
518
+ }
519
+ const parsed = await declared.schema.parseAsync(data);
520
+ return request({ op: "emit", record: declared.name, data: parsed ?? null }, opts.label);
521
+ };
522
+
523
+ /**
524
+ * The query of a read with its types as names, and the versions its references hold: `read.records(Type, query)`
525
+ * is `read.records({ ...query, types: [Type] })`.
526
+ */
527
+ function readQuery(first: unknown, second: unknown): { query: Record<string, unknown>; versions: Record<string, number> } {
528
+ const given = (isRecordRef(first) ? { ...(second as Record<string, unknown> | undefined), types: [first] } : (first ?? {})) as Record<string, unknown>;
529
+ if (!Array.isArray(given.types)) return { query: given, versions: {} };
530
+ const versions: Record<string, number> = {};
531
+ const types = given.types.map((type: unknown) => {
532
+ const named = typeNamed(type, "read.records({ types })");
533
+ if (named.version !== undefined) versions[named.name] = named.version;
534
+ return named.name;
535
+ });
536
+ return { query: { ...given, types }, versions };
537
+ }
538
+
539
+ globals.read = {
540
+ state: (plugin: string, opts: CallOptions = {}): Promise<unknown> => request({ op: "read-state", plugin }, opts.label),
541
+ records: (first: unknown, second?: unknown, third?: CallOptions): Promise<unknown> => {
542
+ const opts = (isRecordRef(first) ? third : (second as CallOptions | undefined)) ?? {};
543
+ let read: ReturnType<typeof readQuery>;
544
+ try {
545
+ read = readQuery(first, second);
546
+ } catch (error) {
547
+ return Promise.reject(error);
548
+ }
549
+ const versions = Object.keys(read.versions).length === 0 ? {} : { versions: read.versions };
550
+ return request({ op: "read-records", query: read.query, ...versions }, opts.label);
551
+ },
552
+ };
553
+
554
+ globals.now = (opts: CallOptions = {}): Promise<unknown> => request({ op: "now" }, opts.label);
555
+ globals.random = (opts: CallOptions = {}): Promise<unknown> => request({ op: "random" }, opts.label);
556
+
557
+ // --- groups of branches ------------------------------------------------------------------
558
+ //
559
+ // A group is a scope of structured concurrency: the branches started in it never outlive it.
560
+ // Leaving the block waits for the branches (`onExit: "wait"`) or cancels them (`"cancel"`); a
561
+ // block that throws cancels them. The host keeps the group: its branches, their outcomes in the
562
+ // order they were committed, its deadline and whether it is shielded, so a replay meets the
563
+ // outcomes in the order the script met them.
564
+
565
+ /** How a branch ended, as the script sees it. */
566
+ type Settled = { ok: true; value: unknown } | { ok: false; error: { name: string; message: string } };
567
+
568
+ /** A branch of a group. */
569
+ interface Member {
570
+ readonly key: string;
571
+ /** The key prefix of the branch: the path of the group and the key. */
572
+ readonly path: string;
573
+ /** The outcome, once the branch ended and the host committed it. */
574
+ result?: Settled;
575
+ /** The error the branch threw, as it was thrown: what `parallel` throws again. */
576
+ error?: unknown;
577
+ /** The place of the outcome among the outcomes of the group. */
578
+ order?: number;
579
+ /** Why the branch was cancelled, when it was. */
580
+ cancelled?: string;
581
+ /** Ends when the branch has ended and its outcome is committed. */
582
+ done: Promise<Settled>;
583
+ }
584
+
585
+ /** What `scope()` takes. */
586
+ interface ScopeOptions {
587
+ concurrency?: number;
588
+ onExit?: "wait" | "cancel";
589
+ deadline?: Duration;
590
+ onDeadline?: "skip" | "fail";
591
+ shield?: boolean;
592
+ }
593
+
594
+ /** What the host answers when a group opens. */
595
+ interface OpenAnswer {
596
+ concurrency?: number;
597
+ deadline?: number;
598
+ known: Array<{ key: string; order: number; outcome: string }>;
599
+ closed?: "done" | "failed" | "deadline";
600
+ }
601
+
602
+ /** A group the script opened. */
603
+ interface Group {
604
+ readonly path: string;
605
+ readonly segments: readonly string[];
606
+ /** The branch the group was opened in; the script itself when absent. */
607
+ readonly within: Branch | undefined;
608
+ readonly shield: boolean;
609
+ readonly members: Map<string, Member>;
610
+ /** The outcomes committed in this process, by their place. */
611
+ readonly settled: Map<number, Member>;
612
+ /** The places the run committed before for branches that have not ended in this process yet: key by place. */
613
+ readonly expected: Map<number, string>;
614
+ /** The places already given to the script. */
615
+ readonly given: Set<number>;
616
+ readonly listeners: Set<() => void>;
617
+ readonly queue: Array<() => void>;
618
+ limit: number;
619
+ running: number;
620
+ /** Why the whole group, its block with it, was cancelled. */
621
+ cancelled: string | undefined;
622
+ /** Why the branches of the group were cancelled: a branch started after that starts cancelled. */
623
+ branchesCancelled: string | undefined;
624
+ /** An error that pauses the run, met by a branch: the group throws it to whoever reads it. */
625
+ pausedBy: unknown;
626
+ /** A branch of the group ran a call: once the group closes, what comes after it lies after a change. */
627
+ diverged: boolean;
628
+ open: boolean;
629
+ requests: number;
630
+ }
631
+
632
+ /** A stream: a group whose branches are listened to one outcome at a time, closed when it is disposed. */
633
+ interface StreamHandle {
634
+ /** Close it, and throw the error of its opening when it had one. */
635
+ close(): Promise<void>;
636
+ /** Close it as the end of its branch or of the script does: an error of its opening that a read gave already is not thrown again. */
637
+ release(): Promise<void>;
638
+ }
639
+
640
+ /** The error a scope with `onDeadline: "fail"` throws when it runs out of time. */
641
+ class DeadlineExceeded extends Error {
642
+ override name = "DeadlineExceeded";
643
+ }
644
+ globals.DeadlineExceeded = DeadlineExceeded;
645
+
646
+ /** The errors that pause the run: a step did not complete. A branch that meets one does not end with it; its group throws it. */
647
+ const pausing = new WeakSet<object>();
648
+
649
+ /** Whether an error pauses the run. */
650
+ const pausesRun = (error: unknown): boolean => typeof error === "object" && error !== null && pausing.has(error);
651
+
652
+ /** The paths of the groups opened in this run: a path names one group. */
653
+ const opened = new Set<string>();
654
+
655
+ /** A key of a branch, or a name of a scope: one part of a key prefix, so none of the marks a key is made of. */
656
+ function checkPart(part: unknown, what: string): string {
657
+ if (typeof part !== "string" || part === "") throw new TypeError(`${what} is a text that is not empty`);
658
+ if (/[.~/:\s]/.test(part) || part.startsWith("@") || /^call-\d+$/.test(part)) {
659
+ throw new TypeError(`${what} "${part}" may not hold ".", "~", "/", ":" or a space, start with "@" or be call-<n>`);
660
+ }
661
+ return part;
662
+ }
663
+
664
+ /** Why the branches of a group are cancelled from outside it: the group's own cancel, or one above it up to a shield. */
665
+ function groupCancelled(group: Group): string | undefined {
666
+ return group.cancelled ?? (group.shield ? undefined : cancelledFor(group.within));
667
+ }
668
+
669
+ /** Why a branch is cancelled: its own cancel, its group's, or a cancel of the branch its group is in, up to a shield. */
670
+ function cancelledFor(branch: Branch | undefined): string | undefined {
671
+ for (let at = branch; at !== undefined; ) {
672
+ if (at.member?.cancelled !== undefined) return at.member.cancelled;
673
+ const group = at.group;
674
+ if (group === undefined) return undefined;
675
+ if (group.cancelled !== undefined) return group.cancelled;
676
+ if (group.shield) return undefined;
677
+ at = group.within;
678
+ }
679
+ return undefined;
680
+ }
681
+
682
+ /** Tell those who wait on a group that something changed in it. */
683
+ function changed(group: Group): void {
684
+ for (const listener of [...group.listeners]) listener();
685
+ }
686
+
687
+ /** Wait until something changes in the group. */
688
+ function nextChange(group: Group): Promise<void> {
689
+ return new Promise((resolve) => {
690
+ const listener = (): void => {
691
+ group.listeners.delete(listener);
692
+ resolve();
693
+ };
694
+ group.listeners.add(listener);
695
+ });
696
+ }
697
+
698
+ /** Take a place to run a branch: a group with a limit runs no more branches than that at once. */
699
+ async function enter(group: Group): Promise<void> {
700
+ if (group.running < group.limit) {
701
+ group.running += 1;
702
+ return;
703
+ }
704
+ // The place is handed on by the branch that leaves it.
705
+ await new Promise<void>((resolve) => group.queue.push(resolve));
706
+ }
707
+
708
+ function leave(group: Group): void {
709
+ const next = group.queue.shift();
710
+ if (next !== undefined) next();
711
+ else group.running -= 1;
712
+ }
713
+
714
+ /** Run the block or a branch of a group in a branch of its own, with the path it is keyed under. */
715
+ function inGroup<T>(group: Group, path: string, member: Member | undefined, body: () => T | Promise<T>): Promise<T> {
716
+ const parent = BRANCH.getStore();
717
+ const phase = parent === undefined ? outsidePhase : parent.phase;
718
+ const branch: Branch = {
719
+ path,
720
+ ordinal: 0,
721
+ groups: 0,
722
+ phase,
723
+ phases: 0,
724
+ group,
725
+ ...(member === undefined ? {} : { member }),
726
+ streams: new Set(),
727
+ diverged: divergedIn(parent),
728
+ };
729
+ // The block of a group is the branch it was opened in, as far as phases go: only a member is a branch with a phase of its own.
730
+ const own = member !== undefined;
731
+ return BRANCH.run(branch, async () => {
732
+ if (own && phase !== undefined) say({ kind: "phase", branch: path, ordinal: 0, phase });
733
+ try {
734
+ return await body();
735
+ } finally {
736
+ await closeStreams(branch.streams);
737
+ if (branch.diverged) group.diverged = true;
738
+ if (own && branch.phase !== undefined) say({ kind: "left", branch: path });
739
+ }
740
+ });
741
+ }
742
+
743
+ /** Close the streams a branch left open: nothing started in a branch outlives it. */
744
+ async function closeStreams(streams: Set<StreamHandle>): Promise<void> {
745
+ for (const stream of [...streams]) await stream.release();
746
+ }
747
+
748
+ /** What a thrown value says as an outcome: a cancel when the branch was cancelled or a step of it was. */
749
+ function failureOf(error: unknown, cancelled: string | undefined): Settled {
750
+ const name = error instanceof Error ? error.name : "Error";
751
+ const message = error instanceof Error ? error.message : String(error);
752
+ if (name === "StepCancelled" || cancelled !== undefined) return { ok: false, error: { name: "Cancelled", message: cancelled ?? message } };
753
+ return { ok: false, error: { name, message } };
754
+ }
755
+
756
+ /** Start a branch of a group: it joins the group at once, and runs when the group has a place for it. */
757
+ function startMember(group: Group, key: string, fn: () => unknown): Member {
758
+ checkPart(key, "the key of a branch");
759
+ if (!group.open) throw new Error(`the scope "${group.segments.join("/")}" is closed: start its branches inside its block`);
760
+ if (group.members.has(key)) throw new Error(`the scope "${group.segments.join("/")}" has a branch "${key}" already: a key names one branch`);
761
+ const path = `${group.path}.${key}`;
762
+ say({ kind: "branched", scope: group.path, key });
763
+ const member: Member = { key, path, done: Promise.resolve({ ok: true, value: undefined }) };
764
+ if (group.branchesCancelled !== undefined) member.cancelled = group.branchesCancelled;
765
+ group.members.set(key, member);
766
+ member.done = (async (): Promise<Settled> => {
767
+ let result: Settled;
768
+ await enter(group);
769
+ try {
770
+ const cancelled = member.cancelled ?? groupCancelled(group);
771
+ if (cancelled !== undefined) result = { ok: false, error: { name: "Cancelled", message: cancelled } };
772
+ else result = { ok: true, value: await inGroup(group, path, member, () => Promise.resolve().then(fn)) };
773
+ } catch (error) {
774
+ member.error = error;
775
+ result = failureOf(error, member.cancelled ?? groupCancelled(group));
776
+ } finally {
777
+ leave(group);
778
+ }
779
+ if (pausesRun(member.error)) {
780
+ // The run pauses on a step of the branch: the branch has no outcome, and the group throws the error to whoever reads it.
781
+ group.pausedBy ??= member.error;
782
+ changed(group);
783
+ return result;
784
+ }
785
+ const outcome = result.ok ? "done" : result.error.name === "Cancelled" ? "cancelled" : "failed";
786
+ const committed = (await requestAt(
787
+ { op: "scope-settled", scope: group.path, key, outcome, ...(result.ok ? {} : { error: result.error }) },
788
+ `${path}~settled`,
789
+ )) as { order: number };
790
+ member.result = result;
791
+ member.order = committed.order;
792
+ for (const [order, expected] of group.expected) if (expected === key) group.expected.delete(order);
793
+ group.settled.set(committed.order, member);
794
+ changed(group);
795
+ return result;
796
+ })();
797
+ return member;
798
+ }
799
+
800
+ /**
801
+ * The next outcome of a group, in the order the host committed them.
802
+ *
803
+ * A place the run committed before for a branch that is going is waited for: the outcomes come
804
+ * in the order the script met them the first time, whichever branch ends first now.
805
+ */
806
+ async function nextOf(group: Group): Promise<{ key: string; result: Settled } | null> {
807
+ for (;;) {
808
+ if (group.pausedBy !== undefined) throw group.pausedBy;
809
+ let best: number | undefined;
810
+ for (const order of group.settled.keys()) if (!group.given.has(order) && (best === undefined || order < best)) best = order;
811
+ for (const [order, key] of group.expected) {
812
+ const member = group.members.get(key);
813
+ if (member !== undefined && member.result === undefined && (best === undefined || order < best)) best = order;
814
+ }
815
+ const member = best === undefined ? undefined : group.settled.get(best);
816
+ if (best !== undefined && member?.result !== undefined) {
817
+ group.given.add(best);
818
+ return { key: member.key, result: member.result };
819
+ }
820
+ if (best === undefined && [...group.members.values()].every((one) => one.result !== undefined)) return null;
821
+ await nextChange(group);
822
+ }
823
+ }
824
+
825
+ /** Record what the group sees now, so a replay sees the same. */
826
+ async function snapshot(group: Group, keys: string[]): Promise<string[]> {
827
+ return (await requestAt({ op: "scope-snapshot", scope: group.path, keys }, `snapshot:${group.path}:${String(++group.requests)}`)) as string[];
828
+ }
829
+
830
+ /**
831
+ * Cancel branches of a group: the host ends their steps, and those of the groups inside them up to a shield.
832
+ *
833
+ * The prefixes are a step the host checks on a replay, so they are what the script decided and not
834
+ * which branches happen to have ended by now: a branch that ended keeps its recorded outcome under a
835
+ * cancel. Only the branches still going are marked cancelled here.
836
+ */
837
+ async function cancelMembers(group: Group, reason: string, targets: readonly Member[], whole: boolean): Promise<void> {
838
+ const prefixes = whole ? [group.path] : targets.map((member) => member.path);
839
+ for (const member of targets) if (member.result === undefined) member.cancelled ??= reason;
840
+ if (prefixes.length === 0) return;
841
+ for (const [key, path] of inflightLabels) {
842
+ if (prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}.`))) prefixes.push(key);
843
+ }
844
+ await requestAt({ op: "scope-cancel", scope: group.path, prefixes, reason }, `cancel:${group.path}:${String(++group.requests)}`);
845
+ }
846
+
847
+ /** The scope a block of a group is given. */
848
+ function scopeApi(group: Group) {
849
+ const branchOf = (member: Member) => ({
850
+ key: member.key,
851
+ settled: async (): Promise<Settled> => {
852
+ const result = await member.done;
853
+ if (group.pausedBy !== undefined) throw group.pausedBy;
854
+ return result;
855
+ },
856
+ value: async (): Promise<unknown> => {
857
+ const result = await member.done;
858
+ if (group.pausedBy !== undefined) throw group.pausedBy;
859
+ if (result.ok) return result.value;
860
+ throw member.error ?? Object.assign(new Error(result.error.message), { name: result.error.name });
861
+ },
862
+ });
863
+ const api = {
864
+ path: group.segments,
865
+ start: (key: string, fn: () => unknown) => branchOf(startMember(group, key, fn)),
866
+ run: (key: string, child: { id: string; version?: string; args?: unknown }) => {
867
+ if (typeof child?.id !== "string") throw new TypeError("run(key, { id, args }): the child is a registered workflow, by its id");
868
+ return branchOf(startMember(group, key, () => callOf(`flow.${child.id}`, child.args ?? {}, undefined)));
869
+ },
870
+ next: () => nextOf(group),
871
+ ready: async (): Promise<Array<{ key: string; result: Settled }>> => {
872
+ const now = [...group.settled.entries()].filter(([order]) => !group.given.has(order)).sort(([a], [b]) => a - b);
873
+ const keys = await snapshot(group, now.map(([, member]) => member.key));
874
+ const out: Array<{ key: string; result: Settled }> = [];
875
+ for (const key of keys) {
876
+ const member = group.members.get(key);
877
+ if (member === undefined) continue;
878
+ const result = await member.done;
879
+ if (group.pausedBy !== undefined) throw group.pausedBy;
880
+ if (member.order !== undefined) group.given.add(member.order);
881
+ out.push({ key, result });
882
+ }
883
+ return out;
884
+ },
885
+ rest: async (): Promise<Record<string, Settled>> => {
886
+ // A key is any text a branch may have, `__proto__` among them: the outcomes are kept in a map and then made properties.
887
+ const all = new Map<string, Settled>();
888
+ for (const member of [...group.members.values()]) {
889
+ all.set(member.key, await member.done);
890
+ if (group.pausedBy !== undefined) throw group.pausedBy;
891
+ if (member.order !== undefined) group.given.add(member.order);
892
+ }
893
+ return Object.fromEntries(all);
894
+ },
895
+ pending: (): Promise<string[]> =>
896
+ snapshot(group, [...group.members.values()].filter((member) => member.result === undefined).map((member) => member.key)),
897
+ cancel: async (reason?: string, keys?: string[]): Promise<void> => {
898
+ const why = reason ?? "cancelled by the script";
899
+ if (keys === undefined) group.branchesCancelled ??= why;
900
+ const targets = (keys ?? [...group.members.keys()]).flatMap((key) => {
901
+ const member = group.members.get(key);
902
+ return member === undefined ? [] : [member];
903
+ });
904
+ await cancelMembers(group, why, targets, false);
905
+ },
906
+ };
907
+ groups.set(api, group);
908
+ return api;
909
+ }
910
+
911
+ type ScopeApi = ReturnType<typeof scopeApi>;
912
+
913
+ /**
914
+ * Open a group under a path, run its block, and close it: nothing started in it outlives it.
915
+ *
916
+ * The block runs keyed under the path of the group, so a cancel of the whole group (its deadline)
917
+ * holds the block's own steps as well as those of its branches.
918
+ */
919
+ async function runGroup<T>(path: string, segments: readonly string[], opts: ScopeOptions, fn: (s: ScopeApi) => Promise<T>): Promise<T | undefined> {
920
+ if (opened.has(path)) throw new Error(`the scope "${segments.join("/")}" is opened twice: give each scope its own name`);
921
+ opened.add(path);
922
+ const within = BRANCH.getStore();
923
+ const onExit = opts.onExit ?? "wait";
924
+ const answer = (await requestAt(
925
+ {
926
+ op: "scope-open",
927
+ scope: path,
928
+ onExit,
929
+ ...(opts.deadline === undefined ? {} : { deadlineMs: durationMs(opts.deadline) }),
930
+ ...(opts.onDeadline === undefined ? {} : { onDeadline: opts.onDeadline }),
931
+ ...(opts.shield === true ? { shield: true } : {}),
932
+ ...(opts.concurrency === undefined ? {} : { concurrency: opts.concurrency }),
933
+ },
934
+ `${path}~open`,
935
+ )) as OpenAnswer;
936
+ const group: Group = {
937
+ path,
938
+ segments,
939
+ within,
940
+ shield: opts.shield === true,
941
+ members: new Map(),
942
+ settled: new Map(),
943
+ expected: new Map(answer.known.map((known) => [known.order, known.key])),
944
+ given: new Set(),
945
+ listeners: new Set(),
946
+ queue: [],
947
+ limit: Math.min(opts.concurrency ?? Number.POSITIVE_INFINITY, answer.concurrency ?? Number.POSITIVE_INFINITY),
948
+ running: 0,
949
+ cancelled: undefined,
950
+ branchesCancelled: undefined,
951
+ pausedBy: undefined,
952
+ diverged: false,
953
+ open: true,
954
+ requests: 0,
955
+ };
956
+ let blockDone = false;
957
+ // The deadline is the host's: it answers when its clock reaches the moment, and a group that closed before keeps how it closed.
958
+ let ranOut = answer.closed === "deadline";
959
+ if (ranOut) group.cancelled = "the deadline passed";
960
+ if (answer.deadline !== undefined && answer.closed === undefined) {
961
+ void requestAt({ op: "scope-deadline", scope: path, at: answer.deadline }, `${path}~deadline`).then(async (reply) => {
962
+ if (blockDone || (reply as { fired?: boolean }).fired !== true) return;
963
+ ranOut = true;
964
+ group.cancelled = "the deadline passed";
965
+ changed(group);
966
+ await cancelMembers(group, "the deadline passed", [...group.members.values()].filter((member) => member.result === undefined), true);
967
+ });
968
+ }
969
+ let result: T | undefined;
970
+ let failure: unknown;
971
+ let failed = false;
972
+ try {
973
+ result = await inGroup(group, path, undefined, () => fn(scopeApi(group)));
974
+ } catch (error) {
975
+ failed = true;
976
+ failure = error;
977
+ }
978
+ blockDone = true;
979
+ // A step did not complete and the run pauses on it: nothing is waited for, the script ends here.
980
+ if (failed && pausesRun(failure)) throw failure;
981
+ if (group.pausedBy !== undefined) throw group.pausedBy;
982
+ if (failed || onExit === "cancel") {
983
+ // The branches the script was not given an outcome of: the outcomes are given in the order the run committed them, on a replay too.
984
+ const left = [...group.members.values()].filter((member) => member.order === undefined || !group.given.has(member.order));
985
+ group.branchesCancelled ??= failed ? "the scope failed" : "the scope was left";
986
+ await cancelMembers(group, group.branchesCancelled, left, false);
987
+ }
988
+ group.open = false;
989
+ while (group.pausedBy === undefined && [...group.members.values()].some((member) => member.result === undefined)) await nextChange(group);
990
+ // A step of a branch did not complete: the run pauses on it, and the group does not close.
991
+ if (group.pausedBy !== undefined) throw group.pausedBy;
992
+ const outcome = ranOut ? "deadline" : failed ? "failed" : "done";
993
+ await requestAt({ op: "scope-close", scope: path, outcome }, `${path}~close`);
994
+ // A branch that ran a call leaves what comes after the group after a change.
995
+ if (group.diverged) diverge(within);
996
+ if (ranOut) {
997
+ if (opts.onDeadline === "fail") throw new DeadlineExceeded(`the scope "${segments.join("/")}" ran out of time`);
998
+ return undefined;
999
+ }
1000
+ if (failed) throw failure;
1001
+ return result;
1002
+ }
1003
+
1004
+ /** The path of a named scope opened where the caller is, and its segments. */
1005
+ function namedPath(name: string): { path: string; segments: string[] } {
1006
+ checkPart(name, "the name of a scope");
1007
+ const branch = BRANCH.getStore();
1008
+ const segments = [...(branch?.group?.segments ?? []), ...(branch?.member === undefined ? [] : [branch.member.key]), name];
1009
+ return { path: branch === undefined ? `@${name}` : `${branch.path}.@${name}`, segments };
1010
+ }
1011
+
1012
+ /** The path of a numbered group (`parallel`) opened where the caller is. */
1013
+ function numberedPath(): { path: string; segments: string[] } {
1014
+ const name = nextGroup("p");
1015
+ const branch = BRANCH.getStore();
1016
+ const segments = [...(branch?.group?.segments ?? []), ...(branch?.member === undefined ? [] : [branch.member.key]), name];
1017
+ return { path: branch === undefined ? name : `${branch.path}.${name}`, segments };
1018
+ }
1019
+
1020
+ globals.scope = (name: string, opts: ScopeOptions | ((s: ScopeApi) => Promise<unknown>) | undefined, fn?: (s: ScopeApi) => Promise<unknown>): Promise<unknown> => {
1021
+ const block = typeof opts === "function" ? opts : fn;
1022
+ const options = typeof opts === "function" || opts === undefined ? {} : opts;
1023
+ if (typeof block !== "function") return Promise.reject(new TypeError("scope(name, opts, async (s) => { ... }): the block is a function"));
1024
+ try {
1025
+ const { path, segments } = namedPath(name);
1026
+ return runGroup(path, segments, options, block);
1027
+ } catch (error) {
1028
+ return Promise.reject(error);
1029
+ }
1030
+ };
1031
+
1032
+ globals.moveOnAfter = (name: string, deadline: Duration, fn: () => Promise<unknown>): Promise<unknown> =>
1033
+ (globals.scope as (n: string, o: ScopeOptions, f: () => Promise<unknown>) => Promise<unknown>)(name, { deadline, onDeadline: "skip" }, () => fn());
1034
+
1035
+ globals.failAfter = (name: string, deadline: Duration, fn: () => Promise<unknown>): Promise<unknown> =>
1036
+ (globals.scope as (n: string, o: ScopeOptions, f: () => Promise<unknown>) => Promise<unknown>)(name, { deadline, onDeadline: "fail" }, () => fn());
1037
+
1038
+ /**
1039
+ * Branches at once, keyed by the index of a list or the keys of an object. The answer is in the
1040
+ * same shape. A branch that fails cancels the others, and its error is thrown once they ended.
1041
+ */
1042
+ globals.parallel = async (branches: Array<() => unknown> | Record<string, () => unknown>, opts: { concurrency?: number } = {}): Promise<unknown> => {
1043
+ const entries: Array<[string, () => unknown]> = Array.isArray(branches)
1044
+ ? branches.map((fn, index) => [String(index), fn])
1045
+ : Object.entries(branches);
1046
+ for (const [key, fn] of entries) {
1047
+ checkPart(key, "the key of a branch");
1048
+ if (typeof fn !== "function") throw new TypeError(`parallel: the branch "${key}" is not a function`);
1049
+ }
1050
+ const { path, segments } = numberedPath();
1051
+ const results = (await runGroup(path, segments, { ...(opts.concurrency === undefined ? {} : { concurrency: opts.concurrency }) }, async (s) => {
1052
+ const members = entries.map(([key, fn]) => [key, startMember(groupOf(s), key, fn)] as const);
1053
+ const out = new Map<string, unknown>();
1054
+ for (let got = await s.next(); got !== null; got = await s.next()) {
1055
+ if (!got.result.ok) {
1056
+ const failedMember = members.find(([key]) => key === got?.key)?.[1];
1057
+ throw failedMember?.error ?? Object.assign(new Error(got.result.error.message), { name: got.result.error.name });
1058
+ }
1059
+ out.set(got.key, got.result.value);
1060
+ }
1061
+ return Object.fromEntries(out);
1062
+ })) as Record<string, unknown>;
1063
+ return Array.isArray(branches) ? entries.map(([key]) => results[key]) : results;
1064
+ };
1065
+
1066
+ /** The group behind a scope a block was given. */
1067
+ const groups = new WeakMap<object, Group>();
1068
+ function groupOf(s: ScopeApi): Group {
1069
+ const group = groups.get(s);
1070
+ if (group === undefined) throw new Error("not a scope of this script");
1071
+ return group;
1072
+ }
1073
+
1074
+ /**
1075
+ * A stream: the branches start at once, and the outcomes are read one at a time in the order the
1076
+ * host committed them. Closing it (or leaving the branch it was opened in) cancels what is left.
1077
+ */
1078
+ globals.stream = (name: string, branches: Record<string, () => unknown>, opts: { concurrency?: number } = {}) => {
1079
+ const { path, segments } = namedPath(name);
1080
+ const owner = BRANCH.getStore();
1081
+ let close: () => void = () => undefined;
1082
+ const closed = new Promise<void>((resolve) => {
1083
+ close = resolve;
1084
+ });
1085
+ let ready: (s: ScopeApi) => void = () => undefined;
1086
+ let refuse: (error: unknown) => void = () => undefined;
1087
+ const begun = new Promise<ScopeApi>((resolve, reject) => {
1088
+ ready = resolve;
1089
+ refuse = reject;
1090
+ });
1091
+ // A stream that could not be opened gives every read the error of its opening, and a read that has is the one that saw it.
1092
+ let opening = true;
1093
+ let openFailed = false;
1094
+ let seen = false;
1095
+ begun.catch(() => undefined);
1096
+ const opened = async (): Promise<ScopeApi> => {
1097
+ try {
1098
+ return await begun;
1099
+ } catch (error) {
1100
+ seen = true;
1101
+ throw error;
1102
+ }
1103
+ };
1104
+ const done = runGroup(path, segments, { onExit: "cancel", ...(opts.concurrency === undefined ? {} : { concurrency: opts.concurrency }) }, async (s) => {
1105
+ for (const [key, fn] of Object.entries(branches)) s.start(key, fn);
1106
+ opening = false;
1107
+ ready(s);
1108
+ await closed;
1109
+ });
1110
+ done.catch((error: unknown) => {
1111
+ if (!opening) return;
1112
+ openFailed = true;
1113
+ refuse(error);
1114
+ });
1115
+ const streams = owner?.streams ?? rootStreams;
1116
+ const finish = async (explicit: boolean): Promise<void> => {
1117
+ streams.delete(handle);
1118
+ close();
1119
+ try {
1120
+ await done;
1121
+ } catch (error) {
1122
+ // Leaving the branch the stream was opened in, or the script, does not say again what a read said already.
1123
+ if (explicit || !openFailed || !seen) throw error;
1124
+ }
1125
+ };
1126
+ const handle = {
1127
+ next: async () => (await opened()).next(),
1128
+ ready: async () => (await opened()).ready(),
1129
+ rest: async () => (await opened()).rest(),
1130
+ pending: async () => (await opened()).pending(),
1131
+ cancel: async (keys?: string[]) => (await opened()).cancel("cancelled by the script", keys),
1132
+ close: (): Promise<void> => finish(true),
1133
+ release: (): Promise<void> => finish(false),
1134
+ async *[Symbol.asyncIterator]() {
1135
+ for (let got = await handle.next(); got !== null; got = await handle.next()) yield got;
1136
+ },
1137
+ [Symbol.asyncDispose]: (): Promise<void> => finish(false),
1138
+ };
1139
+ streams.add(handle);
1140
+ return handle;
1141
+ };
1142
+
1143
+ /** The streams the script itself opened and did not close: they close when the script ends. */
1144
+ const rootStreams = new Set<StreamHandle>();
1145
+
1146
+ /** The first branch to succeed: its key and value. The others are cancelled; when every branch fails, the first error is thrown. */
1147
+ globals.race = (name: string, branches: Record<string, () => unknown>): Promise<unknown> => {
1148
+ try {
1149
+ const { path, segments } = namedPath(name);
1150
+ return runGroup(path, segments, { onExit: "cancel" }, async (s) => {
1151
+ const group = groupOf(s);
1152
+ for (const [key, fn] of Object.entries(branches)) startMember(group, key, fn);
1153
+ let first: unknown;
1154
+ for (let got = await s.next(); got !== null; got = await s.next()) {
1155
+ if (got.result.ok) return { key: got.key, value: got.result.value };
1156
+ first ??= group.members.get(got.key)?.error ?? new Error(got.result.error.message);
1157
+ }
1158
+ throw first ?? new Error(`race "${name}": no branch to run`);
1159
+ });
1160
+ } catch (error) {
1161
+ return Promise.reject(error);
1162
+ }
1163
+ };
1164
+
1165
+ globals.pipeline = async (thunks: Array<(previous: unknown) => unknown>): Promise<unknown[]> => {
1166
+ const group = nextGroup("s");
1167
+ const results: unknown[] = [];
1168
+ let previous: unknown;
1169
+ for (const [index, thunk] of thunks.entries()) {
1170
+ previous = await inBranch(group, String(index), () => thunk(previous));
1171
+ results.push(previous);
1172
+ }
1173
+ return results;
1174
+ };
1175
+
1176
+ /**
1177
+ * Enter a declared phase. The script itself enters it for the steps after; a branch enters it for itself only.
1178
+ * A title the script does not declare is an error of the script, here, where it is named.
1179
+ */
1180
+ globals.phase = (title: string): void => {
1181
+ if (!declaredTitles.includes(title)) {
1182
+ throw new Error(
1183
+ declaredTitles.length === 0
1184
+ ? `phase("${title}"): the script declares no phases: declare them in workflow({ phases })`
1185
+ : `phase("${title}"): the script does not declare it: it declares ${declaredTitles.map((one) => `"${one}"`).join(", ")}`,
1186
+ );
1187
+ }
1188
+ const branch = BRANCH.getStore();
1189
+ if (branch === undefined) {
1190
+ outsidePhase = title;
1191
+ say({ kind: "phase", branch: "", ordinal: ++outsidePhases, phase: title });
1192
+ return;
1193
+ }
1194
+ branch.phase = title;
1195
+ say({ kind: "phase", branch: branch.path, ordinal: ++branch.phases, phase: title });
1196
+ };
1197
+ globals.log = (text: string): void => say({ kind: "log", text });
1198
+
1199
+ /** What `workflow({ ... }, fn)` gives: the declaration, and the function that is run. */
1200
+ interface Declared {
1201
+ readonly niwaWorkflow: true;
1202
+ readonly declaration: {
1203
+ readonly name?: unknown;
1204
+ readonly description?: unknown;
1205
+ readonly input?: unknown;
1206
+ readonly output?: unknown;
1207
+ readonly on?: unknown;
1208
+ readonly emits?: unknown;
1209
+ readonly phases?: unknown;
1210
+ };
1211
+ readonly run: (...input: unknown[]) => unknown;
1212
+ }
1213
+
1214
+ globals.workflow = (declaration: Declared["declaration"], run: Declared["run"]): Declared => {
1215
+ if (typeof declaration !== "object" || declaration === null) throw new TypeError("workflow(declaration, fn): the declaration is an object");
1216
+ if (typeof run !== "function") throw new TypeError("workflow(declaration, fn): fn is the function of the script");
1217
+ return { niwaWorkflow: true, declaration, run };
1218
+ };
1219
+
1220
+ const isDeclared = (value: unknown): value is Declared =>
1221
+ typeof value === "object" && value !== null && (value as { niwaWorkflow?: unknown }).niwaWorkflow === true;
1222
+
1223
+ /** The module of the script, and what it exports as its default: it must be what `workflow()` gave. */
1224
+ async function loadScript(): Promise<Declared> {
1225
+ const loaded = (await import(scriptUrl as string)) as { default?: unknown };
1226
+ if (!isDeclared(loaded.default)) throw new Error("the script must export default workflow({ ... }, async (input) => { ... })");
1227
+ const { emits, phases } = loaded.default.declaration;
1228
+ declaredEmits = Array.isArray(emits) ? emits : [];
1229
+ const parsed = WorkflowPhases.safeParse(phases ?? []);
1230
+ declaredTitles = parsed.success ? parsed.data.map((phase) => phase.title) : [];
1231
+ return loaded.default;
1232
+ }
1233
+
1234
+ const isZod = (value: unknown): value is z.ZodType => typeof value === "object" && value !== null && "_zod" in value;
1235
+
1236
+ /** One schema of a declaration: its JSON Schema, or what stops it from being one. */
1237
+ type Declaration = { schema: Record<string, unknown> } | { problem: string };
1238
+
1239
+ /** Does the JSON Schema hold a schema that says nothing (`{}`): what `z.unknown()` and `z.any()` give? */
1240
+ function holdsAnything(schema: unknown): boolean {
1241
+ if (Array.isArray(schema)) return schema.some(holdsAnything);
1242
+ if (typeof schema !== "object" || schema === null) return false;
1243
+ const keys = Object.keys(schema).filter((key) => key !== "$schema");
1244
+ if (keys.length === 0) return true;
1245
+ const subschemas = (value: unknown): unknown[] =>
1246
+ typeof value === "object" && value !== null ? (Array.isArray(value) ? value : Object.values(value)) : [];
1247
+ for (const [key, value] of Object.entries(schema)) {
1248
+ if (["properties", "$defs", "patternProperties"].includes(key) && subschemas(value).some(holdsAnything)) return true;
1249
+ if (["items", "additionalProperties", "propertyNames", "not", "if", "then", "else", "contains"].includes(key) && typeof value === "object" && holdsAnything(value)) return true;
1250
+ if (["anyOf", "oneOf", "allOf", "prefixItems"].includes(key) && subschemas(value).some(holdsAnything)) return true;
1251
+ }
1252
+ return false;
1253
+ }
1254
+
1255
+ /**
1256
+ * The JSON Schema of a schema of the declaration, which says everything the schema says.
1257
+ *
1258
+ * A schema JSON Schema cannot say (a transform, `z.custom`, a date) or one that says nothing
1259
+ * (`z.unknown()`, `z.any()`) is a problem, not a schema.
1260
+ */
1261
+ function declaredSchema(schema: unknown, as: string): Declaration {
1262
+ if (!isZod(schema)) return { problem: `${as} must be a zod schema` };
1263
+ if (as === "input" && schema._zod.def.type !== "object") return { problem: "input must be a z.object({ ... }): the fields of the flags and the form" };
1264
+ try {
1265
+ // A schema is read as an output first: that is the one that refuses a transform.
1266
+ const written = z.toJSONSchema(schema, { unrepresentable: "throw", io: "output" });
1267
+ if (holdsAnything(written)) return { problem: `${as} holds a schema that says nothing (z.unknown, z.any): say what it is` };
1268
+ const json = as === "input" ? z.toJSONSchema(schema, { unrepresentable: "throw", io: "input" }) : written;
1269
+ delete json.$schema;
1270
+ return { schema: json };
1271
+ } catch (error) {
1272
+ return { problem: `${as} cannot be written as JSON Schema: ${error instanceof Error ? error.message : String(error)}` };
1273
+ }
1274
+ }
1275
+
1276
+ /** The records of `emits`, each with its JSON Schema or what stops it from being one. */
1277
+ function declaredEmitsOf(emits: unknown): Array<{ name: string } & Declaration> | { problem: string } {
1278
+ if (!Array.isArray(emits)) return { problem: "emits must be a list of record(name, schema)" };
1279
+ const seen = new Set<string>();
1280
+ const described: Array<{ name: string } & Declaration> = [];
1281
+ for (const entry of emits) {
1282
+ if (!isDeclaredRecord(entry)) return { problem: "emits must be a list of record(name, schema)" };
1283
+ if (seen.has(entry.name)) return { problem: `emits lists the record "${entry.name}" twice` };
1284
+ seen.add(entry.name);
1285
+ described.push({ name: entry.name, ...declaredSchema(entry.schema, `the record "${entry.name}"`) });
1286
+ }
1287
+ return described;
1288
+ }
1289
+
1290
+ /** The phases of the declaration, held to their schema, or what is wrong with them. */
1291
+ function declaredPhasesOf(phases: unknown): { phases: WorkflowPhases } | { problem: string } {
1292
+ const parsed = WorkflowPhases.safeParse(phases);
1293
+ return parsed.success ? { phases: parsed.data } : { problem: `phases: ${z.prettifyError(parsed.error)}` };
1294
+ }
1295
+
1296
+ /** What the module declares, for `workflow.check` and the start of a run. */
1297
+ function describeScript(declared: Declared): Record<string, unknown> {
1298
+ const { name, description, input, output, emits, phases } = declared.declaration;
1299
+ return {
1300
+ ...(typeof name === "string" ? { name } : {}),
1301
+ ...(typeof description === "string" ? { description } : {}),
1302
+ ...(input === undefined ? {} : { input: declaredSchema(input, "input") }),
1303
+ ...(output === undefined ? {} : { output: declaredSchema(output, "output") }),
1304
+ ...(emits === undefined ? {} : { emits: declaredEmitsOf(emits) }),
1305
+ ...(phases === undefined ? {} : { phases: declaredPhasesOf(phases) }),
1306
+ };
1307
+ }
1308
+
1309
+ if (mode === "describe") {
1310
+ // The names of a script are stubs: a module that calls one at its top level fails here, with the name.
1311
+ const unavailable = (name: string): (() => never) => () => {
1312
+ throw new Error(`${name} is not available while the module is read for its schemas: call it inside the function of the script`);
1313
+ };
1314
+ for (const name of ["agent", "session", "call", "wait", "sleep", "emit", "now", "random", "scope", "parallel", "stream", "race", "moveOnAfter", "failAfter", "pipeline", "phase", "log"]) {
1315
+ globals[name] = unavailable(name);
1316
+ }
1317
+ const stub = (name: string): unknown => new Proxy(unavailable(name), { get: (_target, key) => (typeof key === "symbol" || key === "then" ? undefined : stub(`${name}.${key}`)) });
1318
+ globals.niwa = stub("niwa");
1319
+ globals.ask = stub("ask");
1320
+ globals.read = stub("read");
1321
+ try {
1322
+ say({ kind: "described", ...describeScript(await loadScript()) }, () => exitWith(0));
1323
+ } catch (error) {
1324
+ say({ kind: "failed", error: error instanceof Error ? error.message : String(error) }, () => exitWith(0));
1325
+ }
1326
+ } else {
1327
+ let buffer = "";
1328
+ process.stdin.on("data", (chunk) => {
1329
+ buffer += chunk.toString();
1330
+ for (let at = buffer.indexOf("\n"); at >= 0; at = buffer.indexOf("\n")) {
1331
+ const line = buffer.slice(0, at).trim();
1332
+ buffer = buffer.slice(at + 1);
1333
+ if (line === "") continue;
1334
+ const answer = JSON.parse(line) as { ordinal: number; ok?: boolean; parked?: boolean; value?: unknown; error?: string; name?: string; pauses?: boolean; fresh?: boolean };
1335
+ const waiter = pending.get(answer.ordinal);
1336
+ if (answer.parked === true) {
1337
+ // The call waits for a record: a later start of the run gets its answer.
1338
+ if (waiter !== undefined) waiter.parked = true;
1339
+ holdWhileNeeded();
1340
+ continue;
1341
+ }
1342
+ pending.delete(answer.ordinal);
1343
+ holdWhileNeeded();
1344
+ // The call ran instead of being taken from an earlier start: what comes after it in its branch runs too.
1345
+ if (answer.fresh === true && waiter !== undefined) diverge(waiter.branch);
1346
+ if (answer.ok) waiter?.resolve(answer.value);
1347
+ else {
1348
+ const failed = new Error(answer.error ?? "the call failed");
1349
+ if (answer.name !== undefined) failed.name = answer.name;
1350
+ if (answer.pauses === true) pausing.add(failed);
1351
+ waiter?.reject(failed);
1352
+ }
1353
+ }
1354
+ });
1355
+ // The parent is gone: nobody is left to answer, so the process ends instead of waiting for ever.
1356
+ process.stdin.on("end", () => exitWith(1));
1357
+
1358
+ // The script runs outside the top level of the module: a top level that is still waiting would hold
1359
+ // the process, and one whose calls are all parked must be free to end.
1360
+ void (async (): Promise<void> => {
1361
+ try {
1362
+ const declared = await loadScript();
1363
+ const args: unknown = JSON.parse(argsJson ?? "null");
1364
+ // A script that starts on records is given the record; any other is given its input, parsed and with the defaults put in.
1365
+ const input = isZod(declared.declaration.input) ? await declared.declaration.input.parseAsync(args) : args;
1366
+ const result = await (declared.declaration.input === undefined && declared.declaration.on === undefined ? declared.run() : declared.run(input));
1367
+ // A stream the script left open is closed: nothing it started outlives it.
1368
+ await closeStreams(rootStreams);
1369
+ say({ kind: "done", result: result ?? null }, () => exitWith(0));
1370
+ } catch (error) {
1371
+ // The name goes with the message: the host tells an `ask` that ended with no answer from any other error.
1372
+ say(
1373
+ { kind: "failed", error: error instanceof Error ? error.message : String(error), ...(error instanceof Error ? { name: error.name } : {}) },
1374
+ () => exitWith(0),
1375
+ );
1376
+ }
1377
+ })();
1378
+ }