@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/bridge.ts ADDED
@@ -0,0 +1,710 @@
1
+ /**
2
+ * What the parent does for the script: every request of the child
3
+ * becomes a step of the invocation the run is, under the key the child gave it.
4
+ *
5
+ * A step with that key is the main step of the request, and the steps it needs besides — the
6
+ * clock, the mark of the journal, the arming of a wake — are `<key>~now`, `<key>~mark` and
7
+ * `<key>~arm`. They are all a function of the key, never of the order the requests arrive in, so
8
+ * two branches that finish in another order on a replay keep their own answers.
9
+ */
10
+
11
+ import { CANCEL_STEPS_ACTION, CORE_TYPES, CatchableError, DeniedError, NOW_ACTION, RANDOM_ACTION, WAIT_ACTION, action, actionName, principalOf, currentInvocation, grantId, isSuspend, jsonOf, keyUnder, record, recordId, seq, stableJson, timestamp } from "@niwa-labs/core";
12
+ import type { Action, ActionTarget, AuthorizeHow, JournalReader, Principal, RecordType, Step, Verb } from "@niwa-labs/core";
13
+ import { owner } from "@niwa-labs/core";
14
+ import { AskAnswered, answeredBy, QuestionName, RequestCancelled, RequestExpired, requestAsk } from "@niwa-labs/requests/records";
15
+ import { TimerSlept, sleepKey, timerSleepRequest } from "@niwa-labs/timer/records";
16
+ import { sessionEnd } from "@niwa-labs/sessions/records";
17
+ import type { SessionMarked } from "@niwa-labs/sessions/records";
18
+ import { z } from "zod";
19
+
20
+ import { valueOf } from "./ask.ts";
21
+ import { ScopeClosed, ScopeOpened, ScopeSettled, StepReused } from "./records.ts";
22
+ import type { RunId } from "./records.ts";
23
+ import type { ScriptRequest } from "./language.ts";
24
+ import { holds } from "@niwa-labs/core";
25
+ import { decide } from "./revise.ts";
26
+ import type { CurrentCall, RecordedCall } from "./revise.ts";
27
+ import type { CallRequest } from "./runner.ts";
28
+
29
+ /** The action the host serves for reading the journal. */
30
+ const RECORDS_READ = actionName("niwa.records.read");
31
+
32
+ /** What the bridge is given by the run. */
33
+ export interface BridgeDeps {
34
+ /** The step of the invocation the run is. */
35
+ step: Step;
36
+ /** The run, as a principal: what a script calls is called as it, never as the handler that runs it. */
37
+ run: Principal;
38
+ /** The id of the run. */
39
+ runId: RunId;
40
+ /** The most branches a group of the run runs at once, set from outside the script. */
41
+ concurrency?: number;
42
+ /** Run `fn` when the clock of the host reaches `at`; the function returned forgets it. */
43
+ schedule(at: number, fn: () => void): () => void;
44
+ /** The step that ends a child run of a cancelled branch, with the runs below it. */
45
+ cancelChild: Action<{ run: RunId }, null, { run: string }>;
46
+ /** The sessions and the child runs that steps of the invocation under the prefixes started, and that are going. */
47
+ heldBy(
48
+ invocation: string,
49
+ prefixes: readonly string[],
50
+ except: readonly string[],
51
+ ): { sessions: Array<z.infer<typeof SessionMarked.schema>["session"]>; marks: string[]; children: RunId[] };
52
+ /** The journal, when the host is serving. */
53
+ journal(): JournalReader;
54
+ /** The action an agent call of that harness goes to. */
55
+ agentAction(harness: string | undefined): Action<any, any> | undefined;
56
+ /** The name of that action, for the message when there is none. */
57
+ agentName(harness: string | undefined): string;
58
+ /** The record types the script declares in `emits`, by their short name: it may emit only these. */
59
+ emits: ReadonlyMap<string, RecordType<unknown>>;
60
+ /** The record type the host knows by a name, at its version: what a wait for that name waits for. */
61
+ recordType(name: string): RecordType<unknown> | undefined;
62
+ /** The calls the earlier starts of the run recorded, by key. */
63
+ earlier: ReadonlyMap<string, RecordedCall>;
64
+ /** What an earlier start of the run emitted under a key: the type and the data, and the start that wrote it. */
65
+ emitted(key: string): { type: string; data: unknown; invocation: string } | undefined;
66
+ /** Run again the steps from this one on: a step key, the key prefix of a branch or a scope, or the title of a phase. */
67
+ from?: string;
68
+ /** A step of the script did not complete. */
69
+ failed(): void;
70
+ /** Hold the run to its grant for what the script is about to do: it throws when the grant does not allow it. */
71
+ authorize(verb: Verb, name: string, how?: AuthorizeHow): Promise<void>;
72
+ /** The actions a session of the run is to see must lie within the grant of the run: it throws when they do not. */
73
+ visible(masks: readonly string[]): void;
74
+ }
75
+
76
+ /** The actions a call asks a session to see: `visible` of an agent call, `visible.actions` of the sessions module's own. */
77
+ const Visible = z.object({
78
+ visible: z.union([z.array(z.string()), z.object({ actions: z.array(z.string()).optional() })]).optional(),
79
+ });
80
+
81
+ /** What a call of a session start asks its session to see; nothing for any other call. */
82
+ function visibleOf(name: string, input: unknown): readonly string[] {
83
+ if (name !== "session.start" && !name.startsWith("session.start.") && name !== "session.resume") return [];
84
+ const asked = Visible.safeParse(input);
85
+ const visible = asked.success ? asked.data.visible : undefined;
86
+ return (Array.isArray(visible) ? visible : visible?.actions) ?? [];
87
+ }
88
+
89
+ /** The wait of a script: a record of a type, or the end of its timeout. */
90
+ const WaitInput = z.object({
91
+ type: z.string().min(1),
92
+ filter: z.record(z.string(), z.unknown()).optional(),
93
+ /** The sleeping place whose wake is the timeout. */
94
+ place: z.string().optional(),
95
+ /** The wait looks for the records after this position. */
96
+ since: z.number().optional(),
97
+ });
98
+
99
+ /** The data of a state change, as the journal holds it. */
100
+ const StateChange = z.object({ name: z.string(), value: z.unknown() });
101
+
102
+ /** The name of the wait of a script as a step. */
103
+ export const WAIT_NAME = actionName("workflow.script.wait");
104
+
105
+ /**
106
+ * The wait as an action: it waits for the record, or for the wake of its timeout.
107
+ *
108
+ * The type is the one the host knows by the name, at its version and read through its schema, so a
109
+ * type at a later version answers the same wait; a name the host does not know is a type of data of
110
+ * any shape at the first version, as the records of a script are.
111
+ *
112
+ * A wake that belongs to another sleep must not end this wait: the wake is waited for with the
113
+ * key of this wait's sleeping place, and the answer names the type that arrived.
114
+ */
115
+ function waitAction(typeOf: (name: string) => RecordType<unknown> | undefined) {
116
+ return action(WAIT_NAME, {
117
+ description: "Wait for a record of a type whose data holds the filter, or for the end of the timeout.",
118
+ input: WaitInput,
119
+ output: z.union([z.object({ data: z.unknown(), at: z.number() }), z.object({ timedOut: z.literal(true) })]),
120
+ // The wait reads and waits: it may be entered again.
121
+ recovery: "repeat",
122
+ effect: "read",
123
+ world: "niwa",
124
+ run: async (input, ctx) => {
125
+ const type = typeOf(input.type) ?? record(input.type, z.unknown());
126
+ const wanted = { type, ...(input.filter === undefined ? {} : { filter: input.filter }) };
127
+ const from = input.since === undefined ? {} : { from: seq(input.since) };
128
+ if (input.place === undefined) {
129
+ const got = await ctx.wait(wanted.type, { ...wanted, ...from });
130
+ return { data: got.data, at: got.at };
131
+ }
132
+ const got = await ctx.waitAnyOf([wanted, { type: TimerSlept, filter: { key: input.place } }] as const, from);
133
+ return got.type === TimerSlept.name && input.type !== TimerSlept.name ? { timedOut: true as const } : { data: got.data, at: got.at };
134
+ },
135
+ });
136
+ }
137
+
138
+ /** The actions that read the journal: they are made with it, so the host's own is not needed. */
139
+ function readers(journal: () => JournalReader) {
140
+ return {
141
+ mark: action("workflow.mark", {
142
+ description: "Where the journal is now: a read as a step, so a replay reads the same position.",
143
+ input: z.object({}),
144
+ output: z.object({ seq: z.number() }),
145
+ recovery: "repeat",
146
+ effect: "read",
147
+ world: "niwa",
148
+ run: () => ({ seq: journal().last() }),
149
+ }),
150
+ state: action("workflow.read.state", {
151
+ description: "The state of a plugin: its values by name, as the journal holds them now.",
152
+ input: z.object({ plugin: z.string().min(1) }),
153
+ output: z.record(z.string(), z.unknown()),
154
+ recovery: "repeat",
155
+ effect: "read",
156
+ world: "niwa",
157
+ run: (input) => {
158
+ const values: Record<string, unknown> = {};
159
+ for (const row of journal().find({ type: CORE_TYPES.stateChanged, field: "plugin", equals: input.plugin })) {
160
+ const change = StateChange.safeParse(row.data);
161
+ if (change.success) values[change.data.name] = change.data.value;
162
+ }
163
+ return values;
164
+ },
165
+ }),
166
+ };
167
+ }
168
+
169
+ /** What the grant of the run said of one verb on one name: the denial as data, so a replay says the same without asking again. */
170
+ const Authorized = z.object({
171
+ allowed: z.boolean(),
172
+ reason: z.string().optional(),
173
+ denied: z.object({ grant: z.string(), missing: z.string(), record: z.string().optional() }).optional(),
174
+ });
175
+
176
+ /** What a read of records answers, as far as the versions of its records go. */
177
+ const ReadAnswer = z.looseObject({ records: z.array(z.looseObject({ type: z.string(), schema: z.number() })) });
178
+
179
+ /** The answer of a read without the records of a type named at a version that are of another version. */
180
+ function ofVersions(read: unknown, versions: Readonly<Record<string, number>>): unknown {
181
+ const answer = ReadAnswer.parse(read);
182
+ return { ...answer, records: answer.records.filter((row) => versions[row.type] === undefined || versions[row.type] === row.schema) };
183
+ }
184
+
185
+ /** The type of an emit: one the script declares in `emits`, and no other. */
186
+ function emitType(deps: BridgeDeps, name: string): RecordType<unknown> {
187
+ const type = deps.emits.get(name);
188
+ if (type === undefined) throw new Error(`the script may emit only the records it declares in emits: "${name}" is not one`);
189
+ return type;
190
+ }
191
+
192
+ /** The question of an `ask` was cancelled: the script gets this error, and it can catch it. */
193
+ export class AskCancelled extends Error {
194
+ override name = "AskCancelled";
195
+ constructor(message = "the question was cancelled") {
196
+ super(message);
197
+ }
198
+ }
199
+
200
+ /** Nobody answered the question of an `ask` within its timeout: the script gets this error, and it can catch it. */
201
+ export class AskExpired extends Error {
202
+ override name = "AskExpired";
203
+ constructor(message = "nobody answered the question in time") {
204
+ super(message);
205
+ }
206
+ }
207
+
208
+ /** How an ask ended without an answer. */
209
+ const AskEnd = z.object({ ended: z.enum(["cancelled", "expired"]) });
210
+
211
+ /** The error the script gets for an ask that ended without an answer. */
212
+ const askError = (ended: z.infer<typeof AskEnd>["ended"]): Error => (ended === "expired" ? new AskExpired() : new AskCancelled());
213
+
214
+ /** The name of the question a script puts to the owner. */
215
+ const SCRIPT_QUESTION = QuestionName.parse("workflow.ask");
216
+
217
+ /**
218
+ * The end of an ask that got no answer, written as a step under `<key>~ended`.
219
+ *
220
+ * A cancelled or expired request is thrown to the caller and leaves no outcome on the ask itself,
221
+ * so this step is what a replay finds: the script gets the same error, and the owner is not asked again.
222
+ */
223
+ const ASK_ENDED = action("workflow.ask.ended", {
224
+ description: "Write down that a question of the script ended with no answer.",
225
+ input: AskEnd,
226
+ output: AskEnd,
227
+ recovery: "repeat",
228
+ effect: "record",
229
+ world: "niwa",
230
+ run: (input) => input,
231
+ });
232
+
233
+ /** The moment a timeout ends, in milliseconds since the epoch. */
234
+ const endOf = (now: number, ms: number): number => Math.round(now + ms);
235
+
236
+ /** What a group of branches answers when it opens: the limit from outside, its deadline, and what the run knows of it already. */
237
+ export interface ScopeOpenAnswer {
238
+ concurrency?: number;
239
+ deadline?: number;
240
+ /** The outcomes the run committed for its branches before, by key: their places among the outcomes of the group. */
241
+ known: Array<{ key: string; order: number; outcome: z.infer<typeof ScopeSettled.schema>["outcome"] }>;
242
+ /** How the group closed before, when the run closed it already. */
243
+ closed?: z.infer<typeof ScopeClosed.schema>["outcome"];
244
+ }
245
+
246
+ /** What a group sees of itself at one moment, recorded so a replay sees the same. */
247
+ const SNAPSHOT = (keys: readonly string[]) =>
248
+ action("workflow.scope.snapshot", {
249
+ description: "Record the branches a group of the script sees at one moment.",
250
+ input: z.object({}),
251
+ output: z.array(z.string()),
252
+ recovery: "repeat",
253
+ effect: "read",
254
+ world: "niwa",
255
+ run: () => [...keys],
256
+ });
257
+
258
+ /** The mark of an error that pauses the run: a branch of the script that meets it does not take it as its outcome. */
259
+ const PAUSES_RUN = Symbol.for("niwa.workflow.pausesRun");
260
+
261
+ /** Mark an error as one that pauses the run. */
262
+ function pausesRun(error: unknown): unknown {
263
+ if (error instanceof Error) Object.defineProperty(error, PAUSES_RUN, { value: true });
264
+ return error;
265
+ }
266
+
267
+ /** Whether an error pauses the run: a step of the script did not complete, or a call was shown. */
268
+ export function isPausing(error: unknown): boolean {
269
+ return error instanceof Error && (error as { [PAUSES_RUN]?: boolean })[PAUSES_RUN] === true;
270
+ }
271
+
272
+ /** What a bridge is: the function that does what the script asks, and the end of the script process. */
273
+ export interface Bridge {
274
+ (request: CallRequest): Promise<unknown>;
275
+ /** The script process is gone: what waits for the clock on its behalf answers now. */
276
+ gone(): void;
277
+ /** Whether the call under the key ran instead of being taken from an earlier start of the run. */
278
+ fresh(key: string): boolean;
279
+ }
280
+
281
+ /**
282
+ * Do what a request of the script asks.
283
+ *
284
+ * A step that does not complete pauses the invocation, as it does for a handler; an error the
285
+ * caller is meant to catch (an ask that was cancelled or expired) is not a failed step.
286
+ */
287
+ export function bridge(deps: BridgeDeps): Bridge {
288
+ const { step } = deps;
289
+ const own = readers(deps.journal);
290
+ const waitFor = waitAction((name) => deps.recordType(name));
291
+ /** The open groups whose block an outer cancel waits for. */
292
+ const shields = new Set<string>();
293
+ /** The waits for a deadline that are going, each with the way to answer it now. */
294
+ const deadlines = new Set<() => void>();
295
+
296
+ /** Whether a step of the run did not complete: the run pauses on it. */
297
+ let pausing = false;
298
+ const guarded = async <T>(body: () => Promise<T>): Promise<T> => {
299
+ try {
300
+ return await body();
301
+ } catch (error) {
302
+ // A wait that suspends the run did not fail: the other branches go on, and may still cancel it.
303
+ if (!(error instanceof CatchableError) && !isSuspend(error)) {
304
+ pausing = true;
305
+ deps.failed();
306
+ throw pausesRun(error);
307
+ }
308
+ throw error;
309
+ }
310
+ };
311
+
312
+ /**
313
+ * Hold the run to its grant for one verb on one name, as a step of its own under `<key>~auth`.
314
+ *
315
+ * It is a step so that the decision is made once: the invocation that enters the call again (a
316
+ * wake, a restart) finds the answer in the journal, and the owner is not asked again nor a second
317
+ * decision written. A denial is the answer of the step, and is thrown here, outside it, so the
318
+ * script can catch it.
319
+ */
320
+ const authorized = async (key: string, verb: Verb, name: string, how?: AuthorizeHow): Promise<void> => {
321
+ const held = action("workflow.authorize", {
322
+ description: "Hold the run to its grant for one thing it is about to do.",
323
+ input: z.object({ verb: z.string(), name: z.string() }),
324
+ output: Authorized,
325
+ // A question that was cut off is asked again: nothing was decided.
326
+ recovery: "repeat",
327
+ effect: "read",
328
+ world: "niwa",
329
+ run: async (): Promise<z.infer<typeof Authorized>> => {
330
+ try {
331
+ await deps.authorize(verb, name, { ...how, step: key });
332
+ return { allowed: true };
333
+ } catch (error) {
334
+ if (!(error instanceof DeniedError)) throw error;
335
+ return { allowed: false, reason: error.reason, ...(error.denied === undefined ? {} : { denied: error.denied }) };
336
+ }
337
+ },
338
+ });
339
+ const answer = await guarded(() => step(held, { verb, name }, { key: `${key}~auth` }));
340
+ if (answer.allowed) return;
341
+ const { denied } = answer;
342
+ throw new DeniedError(
343
+ answer.reason ?? "denied",
344
+ denied === undefined
345
+ ? undefined
346
+ : {
347
+ grant: grantId(denied.grant),
348
+ missing: denied.missing,
349
+ ...(denied.record === undefined ? {} : { record: recordId(denied.record) }),
350
+ },
351
+ );
352
+ };
353
+
354
+ /** The calls that ran instead of being taken from an earlier start of the run. */
355
+ const fresh = new Set<string>();
356
+
357
+ /** What a request may take from the earlier starts: whether it lies after a change, and whether the owner asked for it to run again. */
358
+ interface Lineage {
359
+ after: boolean;
360
+ recompute: boolean;
361
+ }
362
+ const lineageOf = (key: string, phase: string | undefined, after: boolean | undefined): Lineage => ({
363
+ after: after === true,
364
+ recompute: deps.from !== undefined && (keyUnder(key, deps.from) || phase === deps.from),
365
+ });
366
+ /** The steps a request makes besides its own lie where it lies. */
367
+ const NONE: Lineage = { after: false, recompute: false };
368
+
369
+ /**
370
+ * Take a call from the earlier start that made it, or run it.
371
+ *
372
+ * A call that is taken is written down as taken, so the journal says where its answer came from. A call
373
+ * that runs while the run has earlier starts says so to the child: what comes after it runs too.
374
+ */
375
+ const takeOrRun = async <T>(key: string, before: RecordedCall | undefined, current: CurrentCall, lineage: Lineage, run: () => Promise<T>): Promise<T> => {
376
+ const decided = decide(before, current, lineage);
377
+ if (decided.taken && before !== undefined) {
378
+ await step.emit(StepReused, { run: deps.runId, key, from: before.invocation }, { key: `reused:${key}` });
379
+ return decided.outcome as T;
380
+ }
381
+ if (deps.earlier.size > 0) fresh.add(key);
382
+ return run();
383
+ };
384
+
385
+ /** The clock as a step under a key; an earlier start of the run read it already, and a replay keeps that moment. */
386
+ const clock = async (key: string, lineage: Lineage = NONE): Promise<number> =>
387
+ takeOrRun(key, deps.earlier.get(key), { key, action: NOW_ACTION, input: null }, lineage, () => guarded(() => step.now({ key })));
388
+
389
+ /** End each scope resource under a replayable key. Closing a parent grant also closes its helpers. */
390
+ const endHeld = async (invocation: string, prefixes: readonly string[], except: readonly string[], key: string, reason: string): Promise<void> => {
391
+ const held = deps.heldBy(invocation, prefixes, except);
392
+ for (const session of held.sessions) await step.outcome(sessionEnd, { session, reason }, { key: `${key}~end:${encodeURIComponent(session)}` });
393
+ for (const mark of held.marks) await step.outcome(actionName("access.grant.close"), { principal: principalOf("session", mark), reason }, { key: `${key}~close:${mark}` });
394
+ for (const child of held.children) await guarded(() => step(deps.cancelChild, { run: child }, { key: `${key}~child:${child}` }));
395
+ };
396
+
397
+ /** A call of an action, or of an agent, taken from an earlier start or made afresh. */
398
+ const act = async <I, O, In = I>(
399
+ key: string,
400
+ target: ActionTarget<I, O, In>,
401
+ name: string,
402
+ input: NoInfer<In>,
403
+ lineage: Lineage,
404
+ opts: { reason?: string; agent?: boolean; read?: boolean } = {},
405
+ ): Promise<O> => {
406
+ const { reason } = opts;
407
+ return takeOrRun(key, deps.earlier.get(key), { key, action: name, input: jsonOf(input), agent: opts.agent === true }, lineage, async () => {
408
+ // The run is held to its grant for the call (a rule that asks puts the question to the owner);
409
+ // the session it starts may see no more than the run does.
410
+ await authorized(key, "call", name, { input, ...(reason === undefined ? {} : { reason }), ...(opts.read === true ? { read: true as const } : {}) });
411
+ deps.visible(visibleOf(name, input));
412
+ return guarded(() => step(target, input, { key, as: deps.run, ...(reason === undefined ? {} : { reason }) }));
413
+ });
414
+ };
415
+
416
+ /** The sleeping place of a request: the invocation and the key, so no other sleep shares it. */
417
+ const placeOf = (key: string) => {
418
+ const scope = currentInvocation();
419
+ if (scope === undefined) throw new Error("a sleep or a wait with a timeout is a step of an invocation");
420
+ return sleepKey(`${scope.invocation}:${key}`);
421
+ };
422
+
423
+ /** Ask for a wake at the end of a timeout; the clock is read as a step, so a replay keeps the moment. */
424
+ const arm = async (key: string, ms: number, lineage: Lineage): Promise<string> => {
425
+ const place = placeOf(key);
426
+ const at = endOf(await clock(`${key}~now`, lineage), ms);
427
+ await step(timerSleepRequest, { at, key: place }, { key: `${key}~arm` });
428
+ return place;
429
+ };
430
+
431
+ const sleep = async (key: string, ms: number, lineage: Lineage): Promise<null> => {
432
+ // A sleep is the same sleep under the same key: one that ended in an earlier start is over, and is not begun again.
433
+ const before = deps.earlier.get(key);
434
+ const same = before?.action === WAIT_ACTION ? before : undefined;
435
+ return takeOrRun(key, same, { key, action: WAIT_ACTION, input: same?.input ?? null }, lineage, () => sleeping(key, ms, lineage));
436
+ };
437
+
438
+ const sleeping = async (key: string, ms: number, lineage: Lineage): Promise<null> => {
439
+ const place = placeOf(key);
440
+ const at = endOf(await clock(`${key}~now`, lineage), ms);
441
+ // The wait begins before the request is written: a wake that is written at once, for a
442
+ // moment that has passed, must not be missed.
443
+ const waiting = step.wait(TimerSlept, { filter: { key: place }, key });
444
+ const settled = waiting.then(
445
+ () => ({ refused: false as const }),
446
+ (error: unknown) => ({ refused: true as const, error }),
447
+ );
448
+ await step(timerSleepRequest, { at, key: place }, { key: `${key}~arm` });
449
+ const outcome = await settled;
450
+ if (outcome.refused) throw outcome.error;
451
+ return null;
452
+ };
453
+
454
+ const wait = async (key: string, request: Extract<ScriptRequest, { op: "wait" }>, lineage: Lineage): Promise<unknown> => {
455
+ // A wait is the same wait when it waits for the same type and filter: one that was answered in an earlier start keeps its answer.
456
+ const before = deps.earlier.get(key);
457
+ const asked = { type: request.type, filter: request.filter ?? null };
458
+ const recorded = before?.action === WAIT_NAME && before.input !== null && typeof before.input === "object" && !Array.isArray(before.input)
459
+ ? { ...before, input: { type: before.input.type ?? null, filter: before.input.filter ?? null } }
460
+ : before;
461
+ return takeOrRun(key, recorded, { key, action: WAIT_NAME, input: jsonOf(asked) }, lineage, () => waiting(key, request, lineage));
462
+ };
463
+
464
+ /**
465
+ * A type a script names by reference is the one the host knows: the same name at the same version. A reference the
466
+ * host does not know, or to a version it does not write, is refused, so a wait for it does not wait for ever.
467
+ */
468
+ const referenced = (name: string, version: number | undefined): void => {
469
+ if (version === undefined) return;
470
+ const known = deps.recordType(name);
471
+ if (known === undefined) throw new Error(`the script names the record type "${name}", which the host does not know`);
472
+ if (known.version !== version) {
473
+ throw new Error(`the script names version ${String(version)} of the record type "${name}", and the host knows version ${String(known.version)}`);
474
+ }
475
+ };
476
+
477
+ const waiting = async (key: string, request: Extract<ScriptRequest, { op: "wait" }>, lineage: Lineage): Promise<unknown> => {
478
+ // A wait reads the journal: it is held to the same right as a read of records, and a read is never asked.
479
+ await authorized(key, "call", RECORDS_READ, { read: true });
480
+ const filter = request.filter === undefined ? {} : { filter: request.filter };
481
+ // A wait from a position looks after it; one without looks after where the journal was when it
482
+ // began, so a record that arrives while the wake is being armed is not missed.
483
+ const since = request.from ?? (request.timeoutMs === undefined ? undefined : (await guarded(() => step(own.mark, {}, { key: `${key}~mark` }))).seq);
484
+ const after = since === undefined ? {} : { since };
485
+ if (request.timeoutMs === undefined) {
486
+ return guarded(() => step(waitFor, { type: request.type, ...filter, ...after }, { key }));
487
+ }
488
+ const place = await arm(key, request.timeoutMs, lineage);
489
+ return guarded(() => step(waitFor, { type: request.type, ...filter, place, ...after }, { key }));
490
+ };
491
+
492
+ const ask = async (key: string, request: Extract<ScriptRequest, { op: "ask" }>, lineage: Lineage): Promise<unknown> => {
493
+ // The same question under the same key is the same ask: an answer the owner gave in an earlier start
494
+ // is the answer, and the owner is not asked again, even after a change.
495
+ const before = deps.earlier.get(key);
496
+ const asked = (call: RecordedCall | undefined): boolean =>
497
+ call !== undefined && stableJson((call.input as { input?: unknown } | null)?.input ?? null) === stableJson(request.question);
498
+ const same = before?.action === requestAsk.name && asked(before) ? before : undefined;
499
+ const ended = deps.earlier.get(`${key}~ended`);
500
+ // An ask that ended with no answer in an earlier start ends the same way: the owner is not asked again.
501
+ if (same !== undefined && !same.finished && ended?.finished === true && ended.action === ASK_ENDED.name && !lineage.recompute) {
502
+ throw askError(AskEnd.parse(ended.outcome).ended);
503
+ }
504
+ const answer = await takeOrRun(
505
+ key,
506
+ same,
507
+ { key, action: requestAsk.name, input: same?.input ?? jsonOf(request.question) },
508
+ lineage,
509
+ async () => ({ live: await asking(key, request, lineage) }),
510
+ );
511
+ return "live" in (answer as object) ? (answer as { live: unknown }).live : valueOf(request.question, AskAnswered.parse(answer).answer);
512
+ };
513
+
514
+ const asking = async (key: string, request: Extract<ScriptRequest, { op: "ask" }>, lineage: Lineage): Promise<unknown> => {
515
+ // A run may always ask the owner, who can refuse: asking needs nothing in `uses`.
516
+ const deadline =
517
+ request.timeoutMs === undefined
518
+ ? {}
519
+ : { deadline: timestamp(endOf(await clock(`${key}~now`, lineage), request.timeoutMs)) };
520
+ try {
521
+ const { answer } = answeredBy(
522
+ await guarded(() =>
523
+ step(requestAsk, { to: owner, question: SCRIPT_QUESTION, input: request.question, ...deadline }, { key, as: deps.run }),
524
+ ),
525
+ );
526
+ return valueOf(request.question, answer);
527
+ } catch (error) {
528
+ // The owner cancelled the question, or the time ran out: the script gets an error to catch.
529
+ if (!(error instanceof RequestExpired || error instanceof RequestCancelled)) throw error;
530
+ const ended = error instanceof RequestExpired ? "expired" : "cancelled";
531
+ await guarded(() => step(ASK_ENDED, { ended }, { key: `${key}~ended` }));
532
+ throw askError(ended);
533
+ }
534
+ };
535
+
536
+ const call = async ({ key, request, phase, after }: CallRequest): Promise<unknown> => {
537
+ const lineage = lineageOf(key, phase, after);
538
+ switch (request.op) {
539
+ case "agent": {
540
+ const target = deps.agentAction(request.input.harness);
541
+ if (target === undefined) {
542
+ throw new Error(`no agent action is configured for "${deps.agentName(request.input.harness)}"`);
543
+ }
544
+ return act(key, target, target.name, request.input, lineage, { agent: request.input.prompt !== undefined });
545
+ }
546
+ case "call":
547
+ return act(key, actionName(request.action), request.action, request.input, lineage, {
548
+ ...(request.reason === undefined ? {} : { reason: request.reason }),
549
+ });
550
+ case "wait":
551
+ referenced(request.type, request.version);
552
+ return wait(key, request, lineage);
553
+ case "sleep":
554
+ return sleep(key, request.ms, lineage);
555
+ case "ask":
556
+ return ask(key, request, lineage);
557
+ case "emit": {
558
+ const type = emitType(deps, request.record);
559
+ const before = deps.emitted(key);
560
+ // Written by an earlier start of the run with the same type and data: it is not written twice. Another record runs.
561
+ const now = type.schema.safeParse(request.data);
562
+ const written: RecordedCall | undefined =
563
+ before === undefined
564
+ ? undefined
565
+ : { key, action: before.type, input: jsonOf(before.data ?? null), finished: true, outcome: null, recovery: "do-not-repeat", invocation: before.invocation };
566
+ return takeOrRun(key, written, { key, action: type.name, input: jsonOf(now.success ? (now.data ?? null) : null) }, lineage, () => emitNow(key, type, request.data));
567
+ }
568
+ case "read-state":
569
+ await authorized(key, "call", RECORDS_READ, { read: true });
570
+ return guarded(() => step(own.state, { plugin: request.plugin }, { key }));
571
+ case "read-records": {
572
+ const versions = request.versions ?? {};
573
+ for (const [name, version] of Object.entries(versions)) referenced(name, version);
574
+ // The records, and where the next read or wait goes on: a wait from `next` misses nothing.
575
+ const read = await act(key, RECORDS_READ, RECORDS_READ, request.query, lineage, { read: true });
576
+ // A type named by reference is read at its version: a record of another version is another shape.
577
+ return Object.keys(versions).length === 0 ? read : ofVersions(read, versions);
578
+ }
579
+ case "now":
580
+ return clock(key, lineage);
581
+ case "random":
582
+ return takeOrRun(key, deps.earlier.get(key), { key, action: RANDOM_ACTION, input: null }, lineage, () => guarded(() => step.random({ key })));
583
+ case "scope-open":
584
+ return openScope(request);
585
+ case "scope-settled":
586
+ return settleBranch(request);
587
+ case "scope-cancel": {
588
+ // A step of the run did not complete and the run is pausing on it: the branches are not cancelled
589
+ // for good, so a retry finds them as they were.
590
+ if (pausing) return null;
591
+ // A shielded group under a cancelled branch is spared: the cancel waits for its block to end.
592
+ const except = [...shields].filter((open) => request.prefixes.some((prefix) => open !== prefix && keyUnder(open, prefix)));
593
+ const invocation = currentInvocation()?.invocation;
594
+ if (invocation === undefined) throw new Error("a cancel of branches is a step of an invocation");
595
+ await guarded(() =>
596
+ step(CANCEL_STEPS_ACTION, { invocation, prefixes: request.prefixes, ...(except.length === 0 ? {} : { except }), reason: request.reason }, { key }),
597
+ );
598
+ // The agents the branches started are interrupted, and the runs they started are ended. Each is a step
599
+ // keyed by what it ends, so a replay meets the ones that are still going under the same keys.
600
+ await endHeld(invocation, request.prefixes, except, key, request.reason);
601
+ return null;
602
+ }
603
+ case "scope-snapshot":
604
+ return guarded(() => step(SNAPSHOT(request.keys), {}, { key }));
605
+ case "scope-deadline":
606
+ return new Promise((resolve) => {
607
+ let forget: () => void = () => undefined;
608
+ const answer = (fired: boolean): void => {
609
+ forget();
610
+ deadlines.delete(gone);
611
+ resolve({ fired });
612
+ };
613
+ const gone = (): void => answer(false);
614
+ deadlines.add(gone);
615
+ forget = deps.schedule(request.at, () => answer(true));
616
+ });
617
+ case "scope-close": {
618
+ shields.delete(request.scope);
619
+ await step.emit(ScopeClosed, { run: deps.runId, scope: request.scope, outcome: request.outcome }, { key: `scope-closed:${request.scope}` });
620
+ const invocation = currentInvocation()?.invocation;
621
+ if (invocation !== undefined) await endHeld(invocation, [request.scope], [], key, "the workflow scope ended");
622
+ return null;
623
+ }
624
+ }
625
+ };
626
+
627
+ const emitNow = async (key: string, type: RecordType<unknown>, raw: unknown): Promise<null> => {
628
+ // Data the declared schema refuses is the script's error to catch, not a failed step: the child's own parse is not trusted.
629
+ const data = type.schema.safeParse(raw);
630
+ if (!data.success) throw new Error(`emit "${type.name}": the data does not pass the record's schema: ${z.prettifyError(data.error)}`);
631
+ await authorized(key, "emit", type.name);
632
+ await guarded(() => step.emit(type, data.data, { key }));
633
+ return null;
634
+ };
635
+
636
+ /** The records of one type this run wrote for one group, in the order they were written. */
637
+ const groupRecords = <T extends { scope: string }>(type: { name: string; schema: z.ZodType<T> }, scope: string): T[] =>
638
+ deps
639
+ .journal()
640
+ .find({ type: type.name as never, field: "run", equals: deps.runId })
641
+ .map((row) => type.schema.parse(row.data))
642
+ .filter((data) => data.scope === scope);
643
+
644
+ /**
645
+ * Open a group: its deadline is read from the clock once, as a step, so a replay keeps the moment; the answer
646
+ * says what the run committed of the group before, so the order of its outcomes is the order it was.
647
+ */
648
+ const openScope = async (request: Extract<ScriptRequest, { op: "scope-open" }>): Promise<ScopeOpenAnswer> => {
649
+ const deadline = request.deadlineMs === undefined ? undefined : endOf(await clock(`scope-now:${request.scope}`), request.deadlineMs);
650
+ if (request.shield === true) shields.add(request.scope);
651
+ await step.emit(
652
+ ScopeOpened,
653
+ {
654
+ run: deps.runId,
655
+ scope: request.scope,
656
+ onExit: request.onExit,
657
+ ...(deadline === undefined ? {} : { deadline }),
658
+ ...(request.onDeadline === undefined ? {} : { onDeadline: request.onDeadline }),
659
+ ...(request.shield === true ? { shield: true } : {}),
660
+ ...(request.concurrency === undefined ? {} : { concurrency: request.concurrency }),
661
+ },
662
+ { key: `scope-open:${request.scope}` },
663
+ );
664
+ const known = new Map<string, ScopeOpenAnswer["known"][number]>();
665
+ for (const settled of groupRecords(ScopeSettled, request.scope)) known.set(settled.key, { key: settled.key, order: settled.order, outcome: settled.outcome });
666
+ const closed = groupRecords(ScopeClosed, request.scope).at(-1)?.outcome;
667
+ return {
668
+ ...(deps.concurrency === undefined ? {} : { concurrency: deps.concurrency }),
669
+ ...(deadline === undefined ? {} : { deadline }),
670
+ known: [...known.values()],
671
+ ...(closed === undefined ? {} : { closed }),
672
+ };
673
+ };
674
+
675
+ /**
676
+ * Commit the outcome of a branch and answer its place among the outcomes of its group.
677
+ *
678
+ * The place is the order of the commits, not of the ends of outside work. A branch the run committed
679
+ * before with the same outcome keeps its place, so a replay and a resume give the outcomes in the
680
+ * order the script saw them; any other outcome takes the next place.
681
+ */
682
+ const settleBranch = async (request: Extract<ScriptRequest, { op: "scope-settled" }>): Promise<{ order: number }> => {
683
+ const committed = groupRecords(ScopeSettled, request.scope);
684
+ const before = committed.filter((one) => one.key === request.key).at(-1);
685
+ const order =
686
+ before !== undefined && before.outcome === request.outcome
687
+ ? before.order
688
+ : committed.reduce((highest, one) => Math.max(highest, one.order + 1), 0);
689
+ await step.emit(
690
+ ScopeSettled,
691
+ {
692
+ run: deps.runId,
693
+ scope: request.scope,
694
+ key: request.key,
695
+ order,
696
+ outcome: request.outcome,
697
+ ...(request.error === undefined ? {} : { error: request.error }),
698
+ },
699
+ { key: `scope-settled:${request.scope}.${request.key}` },
700
+ );
701
+ return { order };
702
+ };
703
+
704
+ return Object.assign(call, {
705
+ fresh: (key: string): boolean => fresh.has(key),
706
+ gone: (): void => {
707
+ for (const answer of [...deadlines]) answer();
708
+ },
709
+ });
710
+ }