@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
@@ -0,0 +1,241 @@
1
+ // The typing of `ask()` and `pipeline` in a script: the harness is one of the
2
+ // instances the host serves a `session.start.<harness>` action for, the model and the effort are literals where the
3
+ // adapter lists them, the options block is the one the sessions module binds the harness to and no other, and a pipeline of two to four stages hands each stage the typed value of the one before.
4
+
5
+ import { afterEach, expect, test } from "bun:test";
6
+ import { mkdir, writeFile } from "node:fs/promises";
7
+ import { join } from "node:path";
8
+ import { z } from "zod";
9
+
10
+ import { action } from "@niwa-labs/core";
11
+ import type { ActionDescription, ActionName, JsonSchema } from "@niwa-labs/core";
12
+ import { NoOptions } from "@niwa-labs/harness";
13
+ import { createNiwa, describe, tempHome } from "@niwa-labs/testing";
14
+ import type { Host } from "@niwa-labs/testing";
15
+ import { sessionAgent, workflow, workflowCheck } from "../src/index.ts";
16
+
17
+ import { scriptChecker } from "../src/check.ts";
18
+ import { scriptTyping } from "../src/script-types.ts";
19
+
20
+ const homes: Array<{ cleanup(): Promise<void> }> = [];
21
+ const hosts: Host[] = [];
22
+
23
+ afterEach(async () => {
24
+ for (const host of hosts.splice(0)) await host.close().catch(() => {});
25
+ for (const home of homes.splice(0)) await home.cleanup();
26
+ });
27
+
28
+ /** An action as the host describes it, with the input given. */
29
+ function described(name: string, input: z.ZodType): ActionDescription {
30
+ const one = describe({
31
+ actions: [action(name, { description: `The action ${name}.`, input, output: z.object({}), recovery: "repeat", effect: "write", run: () => ({}) })],
32
+ types: [],
33
+ }).actions[0];
34
+ if (one === undefined) throw new Error("no description");
35
+ return one;
36
+ }
37
+
38
+ // The agent actions as the workflow module serves them, so the typing is made from the schemas a host really describes.
39
+ const catalogue = [
40
+ described("session.start.codex", sessionAgent("codex", { models: ["gpt-5", "gpt-5-mini"], efforts: ["low", "high"] }).input),
41
+ described("session.start.mcode-work", sessionAgent("mcode-work").input),
42
+ described("session.start.claude-work", sessionAgent("claude-work").input),
43
+ described("session.start.bare", sessionAgent("bare").input),
44
+ described("flow.wf-a3f9c2", z.object({ n: z.number() })),
45
+ ];
46
+ const names = catalogue.map((entry) => entry.name);
47
+ // The blocks as the sessions module binds the harnesses (`harness.list`); `bare` is bound to none.
48
+ const schemaOf = (schema: z.ZodType) => z.toJSONSchema(schema, { io: "input" }) as JsonSchema;
49
+ const blocks = new Map([
50
+ ["codex", { block: "codex", schema: schemaOf(NoOptions) }],
51
+ ["mcode-work", { block: "mcode", schema: schemaOf(NoOptions) }],
52
+ ["claude-work", { block: "claude", schema: schemaOf(z.strictObject({ advisor: z.boolean().optional() })) }],
53
+ ] as const);
54
+ const file = join(process.cwd(), "agent-typing-probe.ts");
55
+
56
+ async function errorsOf(lines: readonly string[], actions = catalogue, callable: readonly ActionName[] = names) {
57
+ const text = ["export default workflow({ output: z.json() }, async () => {", ...lines, " return null;", "});"].join("\n");
58
+ return (await scriptChecker()({ file, text }, { actions, callable, blocks })).errors;
59
+ }
60
+
61
+ test("a harness the host serves is accepted, with the model and the effort it lists", async () => {
62
+ expect(
63
+ await errorsOf([
64
+ ' await ask({ harness: "codex", model: "gpt-5", effort: "high" }, "a");',
65
+ ' await ask({ harness: "mcode-work", model: "any-model", effort: "any-effort", mode: "ask", cwd: "/tmp" }, "b");',
66
+ ' await ask({ label: "no harness" }, "c");',
67
+ ' await ask({}, "d");',
68
+ ]),
69
+ ).toEqual([]);
70
+ });
71
+
72
+ test("an unknown harness is an error of the check", async () => {
73
+ const errors = await errorsOf([' await ask({ harness: "nope" }, "a");']);
74
+ expect(errors).toHaveLength(1);
75
+ expect(errors[0]).toMatchObject({ line: 2, code: "TS2769" });
76
+ });
77
+
78
+ test("a model or an effort outside the list of its adapter is an error, and another harness is not held to it", async () => {
79
+ const model = await errorsOf([' await ask({ harness: "codex", model: "gpt-9" }, "a");']);
80
+ expect(model).toHaveLength(1);
81
+ expect(model[0]).toMatchObject({ line: 2 });
82
+ const effort = await errorsOf([' await ask({ harness: "codex", effort: "max" }, "a");']);
83
+ expect(effort).toHaveLength(1);
84
+ expect(effort[0]).toMatchObject({ line: 2 });
85
+ expect(await errorsOf([' await ask({ harness: "mcode-work", model: "gpt-9", effort: "max" }, "a");'])).toEqual([]);
86
+ });
87
+
88
+ test("the typed answer of a schema still comes with a harness", async () => {
89
+ expect(
90
+ await errorsOf([
91
+ ' const review = await ask({ harness: "codex", model: "gpt-5", schema: z.object({ ok: z.boolean() }) }, "a");',
92
+ " const ok: boolean = review.ok;",
93
+ " const text: string = (await ask({ harness: \"mcode-work\" }, \"b\")).answer;",
94
+ " void ok; void text;",
95
+ ]),
96
+ ).toEqual([]);
97
+ const wrong = await errorsOf([' const review = await ask({ harness: "codex", schema: z.object({ ok: z.boolean() }) }, "a");', " const n: number = review.ok;"]);
98
+ expect(wrong).toHaveLength(1);
99
+ expect(wrong[0]).toMatchObject({ line: 3, code: "TS2322" });
100
+ });
101
+
102
+ test("the harnesses are the ones the caller may call, and a host that serves none has none to check", async () => {
103
+ const typing = scriptTyping(catalogue, names.filter((name) => name === "session.start.mcode-work")).declarations;
104
+ expect(typing).toContain('"mcode-work"');
105
+ expect(typing).not.toContain('harness: "codex"');
106
+ expect(await errorsOf([' await ask({ harness: "whatever", model: "m" }, "a");'], [], [])).toEqual([]);
107
+ });
108
+
109
+ test("the options block follows the harness: its own kind's block is typed, another kind's block is an error", async () => {
110
+ expect(
111
+ await errorsOf([
112
+ ' await ask({ harness: "claude-work", claude: { advisor: false } }, "a");',
113
+ ' await ask({ harness: "codex", model: "gpt-5", codex: {} }, "b");',
114
+ ' await ask({ harness: "mcode-work", mcode: {} }, "c");',
115
+ ]),
116
+ ).toEqual([]);
117
+ // The block of another kind, on a harness of each kind.
118
+ for (const call of [
119
+ '{ harness: "codex", claude: { advisor: false } }',
120
+ '{ harness: "claude-work", codex: {} }',
121
+ '{ harness: "mcode-work", claude: {} }',
122
+ ]) {
123
+ const errors = await errorsOf([` await ask(${call}, "a");`]);
124
+ expect(errors).toHaveLength(1);
125
+ expect(errors[0]).toMatchObject({ line: 2, code: "TS2769" });
126
+ }
127
+ // With a schema the call has more overloads to fail, and each says where: the call is refused, at that line.
128
+ const schemed = await errorsOf([' await ask({ harness: "codex", model: "gpt-5", schema: z.object({ ok: z.boolean() }), claude: { advisor: false } }, "a");']);
129
+ expect(schemed.length).toBeGreaterThan(0);
130
+ for (const error of schemed) expect(error).toMatchObject({ line: 2, code: "TS2769" });
131
+ // A field the own block does not have, or a value of the wrong type.
132
+ expect(await errorsOf([' await ask({ harness: "claude-work", claude: { advisor: "no" } }, "a");'])).toHaveLength(1);
133
+ expect(await errorsOf([' await ask({ harness: "claude-work", claude: { speed: 1 } }, "a");'])).toHaveLength(1);
134
+ // A harness given without its kind's options, and a call that names no harness, take no block.
135
+ expect(await errorsOf([' await ask({ harness: "bare", claude: { advisor: false } }, "a");'])).toHaveLength(1);
136
+ expect(await errorsOf([' await ask({ codex: {} }, "a");'])).toHaveLength(1);
137
+ // An unknown harness is an error, with a block or without.
138
+ expect(await errorsOf([' await ask({ harness: "nope", claude: { advisor: false } }, "a");'])).toHaveLength(1);
139
+ });
140
+
141
+ test("a registered workflow is called as niwa.flow[id], typed by its literal id", async () => {
142
+ expect(await errorsOf([' const out = await niwa.flow["wf-a3f9c2"]({ n: 1 });', " void out;"])).toEqual([]);
143
+ const unknown = await errorsOf([' await niwa.flow["wf-000000"]({ n: 1 });']);
144
+ expect(unknown).toHaveLength(1);
145
+ expect(unknown[0]).toMatchObject({ line: 2 });
146
+ const input = await errorsOf([' await niwa.flow["wf-a3f9c2"]({ n: "one" });']);
147
+ expect(input).toHaveLength(1);
148
+ expect(input[0]).toMatchObject({ line: 2, code: "TS2322" });
149
+ });
150
+
151
+ test("a pipeline hands each stage the typed value of the one before", async () => {
152
+ expect(
153
+ await errorsOf([
154
+ ' const [first, second, third] = await pipeline([',
155
+ ' () => ask({}, "one"),',
156
+ ' (previous) => ask({}, "two " + previous.answer),',
157
+ " async (previous) => ({ words: previous.answer.split(\" \").length }),",
158
+ " ]);",
159
+ " const a: string = first.answer;",
160
+ " const b: string = second.answer;",
161
+ " const c: number = third.words;",
162
+ " void a; void b; void c;",
163
+ " const [x, y, z4, w] = await pipeline([() => 1, (n) => n + 1, (n) => String(n), (s) => s.length]);",
164
+ " const sum: number = x + y + w;",
165
+ " const s: string = z4;",
166
+ " void sum; void s;",
167
+ ]),
168
+ ).toEqual([]);
169
+ });
170
+
171
+ test("a stage that misuses the value before it is an error, and so is a pipeline of one or five stages", async () => {
172
+ const misuse = await errorsOf([' await pipeline([() => ask({}, "one"), (previous) => previous.nothing]);']);
173
+ expect(misuse).toHaveLength(1);
174
+ expect(misuse[0]).toMatchObject({ line: 2, code: "TS2339" });
175
+ const wrongType = await errorsOf([" await pipeline([() => 1, (n) => n.toUpperCase()]);"]);
176
+ expect(wrongType).toHaveLength(1);
177
+ expect(wrongType[0]).toMatchObject({ line: 2, code: "TS2339" });
178
+ expect((await errorsOf([" await pipeline([() => 1]);"])).length).toBeGreaterThan(0);
179
+ expect((await errorsOf([" await pipeline([() => 1, (n) => n, (n) => n, (n) => n, (n) => n]);"])).length).toBeGreaterThan(0);
180
+ });
181
+
182
+ test("workflow.check on a live host holds a script to the harnesses and the lists of the plugin", async () => {
183
+ const home = await tempHome();
184
+ homes.push(home);
185
+ const host = createNiwa({ home: home.path });
186
+ host.use(workflow({ harnesses: [{ id: "codex", models: ["gpt-5"], efforts: ["low", "high"] }, "mcode-work"] }));
187
+ await host.serve();
188
+ hosts.push(host);
189
+ await mkdir(home.path, { recursive: true });
190
+ const check = async (name: string, call: string) => {
191
+ const path = join(home.path, name);
192
+ await writeFile(path, ["export default workflow({ output: z.json() }, async () => {", ` await ask(${call}, "a");`, " return null;", "});"].join("\n"));
193
+ return host.call(workflowCheck, { file: path });
194
+ };
195
+ expect((await check("ok.ts", '{ harness: "codex", model: "gpt-5", effort: "low" }')).ok).toBe(true);
196
+ expect((await check("ok2.ts", '{ harness: "mcode-work", model: "anything" }')).ok).toBe(true);
197
+ const unknown = await check("unknown.ts", '{ harness: "claude-haiku" }');
198
+ expect(unknown.ok).toBe(false);
199
+ expect(unknown.errors[0]).toMatchObject({ line: 2, code: "TS2769" });
200
+ const effort = await check("effort.ts", '{ harness: "codex", effort: "max" }');
201
+ expect(effort.ok).toBe(false);
202
+ expect(effort.errors[0]).toMatchObject({ line: 2 });
203
+ }, 60_000);
204
+
205
+ test("the agent action of a harness with listed models refuses another model, and one with none takes any", () => {
206
+ const listed = sessionAgent("codex", { models: ["gpt-5"], efforts: ["low"] });
207
+ expect(listed.input.safeParse({ prompt: "x", model: "gpt-5", effort: "low" }).success).toBe(true);
208
+ expect(listed.input.safeParse({ prompt: "x", model: "gpt-9" }).success).toBe(false);
209
+ expect(listed.input.safeParse({ prompt: "x", effort: "max" }).success).toBe(false);
210
+ const open = sessionAgent("mcode-work");
211
+ expect(open.input.safeParse({ prompt: "x", prompts: "typo" }).success).toBe(false);
212
+ expect(open.input.safeParse({ prompt: "x", model: "gpt-9", effort: "max" }).success).toBe(true);
213
+ expect(open.input.safeParse({ prompt: "x", model: "" }).success).toBe(false);
214
+ });
215
+
216
+ test("the agent action takes a block as an object, left to its kind to check, and names a field it does not have", () => {
217
+ const claude = sessionAgent("claude-work");
218
+ expect(claude.input.safeParse({ prompt: "x", claude: { advisor: false } }).success).toBe(true);
219
+ // What is in a block, and which block the harness takes, are the sessions module's to check when the call runs.
220
+ expect(claude.input.safeParse({ prompt: "x", acme: { speed: 1 } }).success).toBe(true);
221
+ expect(claude.input.safeParse({ prompt: "x", codex: 5 }).success).toBe(false);
222
+ const typo = claude.input.safeParse({ prompt: "x", modle: "m" });
223
+ expect(typo.error?.issues[0]?.message).toBe('the agent call of the harness "claude-work" has no field "modle"');
224
+ });
225
+
226
+ test("ask({ worktree }) is typed: the answer carries the worktree it left, with or without a schema", async () => {
227
+ expect(
228
+ await errorsOf([
229
+ ' const plain = await ask({ harness: "codex", worktree: true }, "a");',
230
+ " const branch: string | undefined = plain.worktree?.branch;",
231
+ " const changed: boolean | undefined = plain.worktree?.changed;",
232
+ ' const typed = await ask({ harness: "claude-work", worktree: { repo: "/tmp/repo", base: "main", description: "a try" }, schema: z.object({ ok: z.boolean() }) }, "b");',
233
+ " const ok: boolean = typed.ok;",
234
+ " const path: string | undefined = typed.worktree?.path;",
235
+ ]),
236
+ ).toEqual([]);
237
+ const wrong = await errorsOf([' await ask({ harness: "codex", worktree: { branch: "x" } }, "a");']);
238
+ expect(wrong).toHaveLength(1);
239
+ const absent = await errorsOf([' const plain = await ask({ harness: "codex" }, "a");', " plain.worktree;"]);
240
+ expect(absent).toHaveLength(1);
241
+ });
@@ -0,0 +1,145 @@
1
+ // A cancelled or expired `ask` is answered from the journal on a resume.
2
+ //
3
+ // The first start threw `AskCancelled` or `AskExpired` at the script; a replay throws the same
4
+ // error again and puts no new question to the owner.
5
+
6
+ import { afterEach, expect, test } from "bun:test";
7
+ import { writeFile } from "node:fs/promises";
8
+ import { join } from "node:path";
9
+
10
+ import { seq } from "@niwa-labs/core";
11
+ import type { StoredRecord } from "@niwa-labs/core";
12
+ import { RequestCreated, requestCancel } from "@niwa-labs/requests/records";
13
+ import { connect, createNiwa, requests, eventually, tempHome, testClock, ownerTokenOf, timers } from "@niwa-labs/testing";
14
+ import type { Host, TestClock } from "@niwa-labs/testing";
15
+ import { workflow, workflowCancel, workflowInspect, workflowResume, workflowStart } from "../src/index.ts";
16
+ import { z } from "zod";
17
+
18
+
19
+ const START = 1_700_000_000_000;
20
+ const MINUTE = 60_000;
21
+
22
+ const homes: Array<{ cleanup(): Promise<void> }> = [];
23
+ const hosts: Host[] = [];
24
+
25
+ afterEach(async () => {
26
+ for (const host of hosts.splice(0)) await host.close().catch(() => {});
27
+ for (const home of homes.splice(0)) await home.cleanup();
28
+ });
29
+
30
+ async function hostOn(path: string, clock: TestClock): Promise<Host> {
31
+ const niwa = createNiwa({ home: path, clock });
32
+ niwa.use(requests());
33
+ niwa.use(timers([]));
34
+ niwa.use(workflow());
35
+ await niwa.serve();
36
+ hosts.push(niwa);
37
+ return niwa;
38
+ }
39
+
40
+ const recordsOf = async (niwa: Host): Promise<StoredRecord[]> => niwa.records.read();
41
+ const count = async (niwa: Host, type: string): Promise<number> => (await recordsOf(niwa)).filter((row) => row.type === type).length;
42
+ const Finished = z.object({ outcome: z.object({ result: z.unknown() }) });
43
+ const results = async (niwa: Host): Promise<unknown[]> =>
44
+ (await recordsOf(niwa)).filter((row) => row.type === "workflow.run.finished").map((row) => Finished.parse(row.data).outcome.result);
45
+
46
+ /** The script asks once, with a timeout when it is given one, and returns the name of the error it caught. */
47
+ async function script(home: string, options: string): Promise<string> {
48
+ const file = join(home, "script.js");
49
+ await writeFile(
50
+ file,
51
+ `export default workflow({ output: z.string() }, async () => {
52
+ try { return await ask.confirm("Go on?"${options}); } catch (error) { return error.name; }
53
+ });`,
54
+ );
55
+ return file;
56
+ }
57
+
58
+ /** Run the script until the owner is asked, end the request, and let the run finish. */
59
+ async function firstStart(niwa: Host, file: string, end: () => Promise<void>): Promise<string> {
60
+ const started = await niwa.call(workflowStart, { file });
61
+ await eventually(async () => (await count(niwa, "request.created")) === 1, 10_000, "the owner should be asked");
62
+ await end();
63
+ await eventually(async () => (await results(niwa)).length === 1, 10_000, "the first start should finish");
64
+ return started.run;
65
+ }
66
+
67
+ test("a resume after a cancelled ask throws the same error at the script and asks nothing", async () => {
68
+ const home = await tempHome();
69
+ homes.push(home);
70
+ const niwa = await hostOn(home.path, testClock(START));
71
+ const owner = await connect({ home: home.path, id: "owner:ask-cancel", token: ownerTokenOf(home.path) });
72
+ try {
73
+ const run = await firstStart(niwa, await script(home.path, ""), async () => {
74
+ const created = (await recordsOf(niwa)).find((row) => row.type === "request.created");
75
+ await owner.call(requestCancel, { id: RequestCreated.schema.parse(created?.data).id });
76
+ });
77
+ await niwa.call(workflowResume, { run });
78
+ await eventually(async () => (await results(niwa)).length === 2, 10_000, "the replay should finish by itself");
79
+ expect(await results(niwa)).toEqual(["AskCancelled", "AskCancelled"]);
80
+ expect(await count(niwa, "request.created")).toBe(1);
81
+ expect((await niwa.call(workflowInspect, { run })).steps).toMatchObject([
82
+ { action: "request.ask", prompt: "Go on?", endedAt: expect.any(String), status: "cancelled" },
83
+ ]);
84
+ } finally {
85
+ await owner.close().catch(() => {});
86
+ }
87
+ }, 30_000);
88
+
89
+ test("a resume after an expired ask throws the same error at the script and asks nothing", async () => {
90
+ const home = await tempHome();
91
+ homes.push(home);
92
+ const clock = testClock(START);
93
+ const niwa = await hostOn(home.path, clock);
94
+ const run = await firstStart(niwa, await script(home.path, `, { timeout: "1m" }`), async () => {
95
+ await clock.advance(2 * MINUTE);
96
+ });
97
+ await niwa.call(workflowResume, { run });
98
+ await eventually(async () => (await results(niwa)).length === 2, 10_000, "the replay should finish by itself");
99
+ expect(await results(niwa)).toEqual(["AskExpired", "AskExpired"]);
100
+ expect(await count(niwa, "request.created")).toBe(1);
101
+ expect((await niwa.call(workflowInspect, { run })).steps).toMatchObject([
102
+ { action: "request.ask", prompt: "Go on?", endedAt: expect.any(String), status: "failed" },
103
+ ]);
104
+ }, 30_000);
105
+
106
+ test("an ask cancelled and not caught waits for a revision or a cancel: a retry would get the same cancel", async () => {
107
+ const home = await tempHome();
108
+ homes.push(home);
109
+ const niwa = await hostOn(home.path, testClock(START));
110
+ const owner = await connect({ home: home.path, id: "owner:ask-uncaught", token: ownerTokenOf(home.path) });
111
+ try {
112
+ const file = join(home.path, "uncaught.js");
113
+ await writeFile(file, `export default workflow({ output: z.boolean() }, async () => ask.confirm("Go on?", { label: "go" }));`);
114
+ const { run } = await niwa.call(workflowStart, { file });
115
+ await eventually(async () => (await count(niwa, "request.created")) === 1, 10_000, "the owner should be asked");
116
+ const created = (await recordsOf(niwa)).find((row) => row.type === "request.created");
117
+ await owner.call(requestCancel, { id: RequestCreated.schema.parse(created?.data).id });
118
+ await eventually(async () => (await niwa.call(workflowInspect, { run })).status.state === "paused", 10_000, "the run should pause");
119
+ const inspected = await niwa.call(workflowInspect, { run });
120
+ // Only cancel: the replay throws AskCancelled again, so there is nothing to retry or skip.
121
+ expect(inspected.status).toMatchObject({ state: "paused", choices: ["cancel"] });
122
+ expect(inspected.status.reason).toContain("AskCancelled");
123
+ expect(inspected.status.reason).not.toContain("handler error");
124
+ expect(inspected.steps).toMatchObject([{ action: "request.ask", status: "cancelled" }]);
125
+ await expect(niwa.call(workflowResume, { run, choice: "retry" })).rejects.toThrow();
126
+ // The cancel ends it, and nothing is left waiting.
127
+ await niwa.call(workflowCancel, { run });
128
+ await eventually(async () => (await niwa.call(workflowInspect, { run })).status.state === "finished", 10_000, "the run should end");
129
+ expect((await niwa.call(workflowInspect, { run })).status).toMatchObject({ state: "finished", outcome: { status: "cancelled" }, requests: [] });
130
+ } finally {
131
+ await owner.close().catch(() => {});
132
+ }
133
+ }, 30_000);
134
+
135
+ test("a script error outside any step offers retry and cancel, not skip, and refuses a skip", async () => {
136
+ const home = await tempHome();
137
+ homes.push(home);
138
+ const niwa = await hostOn(home.path, testClock(START));
139
+ const file = join(home.path, "boom.js");
140
+ await writeFile(file, `export default workflow({}, async () => { throw new Error("boom"); });`);
141
+ const { run } = await niwa.call(workflowStart, { file });
142
+ await eventually(async () => (await niwa.call(workflowInspect, { run })).status.state === "paused", 10_000, "the run should pause");
143
+ expect((await niwa.call(workflowInspect, { run })).status).toMatchObject({ state: "paused", reason: "boom", choices: ["retry", "cancel"] });
144
+ await expect(niwa.call(workflowResume, { run, choice: "skip" })).rejects.toThrow(/does not offer skip/);
145
+ }, 30_000);
@@ -0,0 +1,133 @@
1
+ // The key of an unlabeled call says which branch it is in.
2
+ //
3
+ // A workflow cache is never keyed by call position alone: the calls of a script
4
+ // that carry no label are keyed by the branch they are in, so the branch that answers first
5
+ // does not take the place of the branch that answers later.
6
+ //
7
+ // The scenario runs against a real host process (test/fixtures/branches-host.ts):
8
+ //
9
+ // 1. the script runs two branches in parallel, each making two unlabeled calls
10
+ // 2. the second branch answers before the first: the host is killed with the first branch
11
+ // still in flight
12
+ // 3. the host comes back and the run goes on: the calls that finished are answered from the
13
+ // journal, and the branch that was waiting runs again
14
+ // 4. every branch keeps its own answer, and no call is made twice
15
+ //
16
+ // Only the public API is used: the entries of the packages, and of testing.
17
+
18
+ import { expect, test } from "bun:test";
19
+ import { fileURLToPath } from "node:url";
20
+
21
+ import type { ActionName, StoredRecord } from "@niwa-labs/core";
22
+ import { counter, eventually, gate, spawnHost, tempHome, watch, connectAsOwner } from "@niwa-labs/testing";
23
+ import { z } from "zod";
24
+
25
+
26
+ const HOST_SCRIPT = fileURLToPath(new URL("./fixtures/branches-host.ts", import.meta.url));
27
+ const SCRIPT = fileURLToPath(new URL("./fixtures/branches-script.js", import.meta.url));
28
+
29
+ /** What the workflow actions answer. */
30
+ const RunOutput = z.object({ run: z.string(), finished: z.boolean() });
31
+
32
+ /** The result the script returns: the reports of the two branches. */
33
+ const ScriptResult = z.array(z.array(z.object({ answer: z.string() })));
34
+
35
+ /** The records of one type, as the observer saw them. */
36
+ function ofType(seen: StoredRecord[], type: string): StoredRecord[] {
37
+ return seen.filter((record) => record.type === type);
38
+ }
39
+
40
+ /** The key of a step, as the journal holds it. */
41
+ function stepKeyOf(record: StoredRecord): string {
42
+ return (record.data as { key?: string }).key ?? "";
43
+ }
44
+
45
+ test("the key of an unlabeled call says its branch, and a run goes on cleanly", async () => {
46
+ const home = await tempHome();
47
+ const homePath = home.path;
48
+ let first: ReturnType<typeof spawnHost> | undefined;
49
+ let second: ReturnType<typeof spawnHost> | undefined;
50
+ let observer: Awaited<ReturnType<typeof watch>> | undefined;
51
+
52
+ try {
53
+ // 1. The host, and the script that runs two branches in parallel.
54
+ first = spawnHost(HOST_SCRIPT, homePath);
55
+ await first.ready();
56
+ const client = await connectAsOwner(homePath);
57
+ observer = await watch(homePath);
58
+ const records = observer.seen;
59
+
60
+ const started = RunOutput.parse(
61
+ await client.call("workflow.start" as ActionName, { file: SCRIPT } as never),
62
+ );
63
+
64
+ await eventually(
65
+ () => counter(homePath, "branches.agent").count() === 2,
66
+ 20_000,
67
+ "the first call of each branch should have been made",
68
+ );
69
+
70
+ // 2. The second branch answers before the first: c1 and c2 are done, b1 is not.
71
+ gate(homePath, "branches.gate.c1").open();
72
+ gate(homePath, "branches.gate.c2").open();
73
+ await eventually(
74
+ () => counter(homePath, "branches.agent").count() === 3,
75
+ 20_000,
76
+ "the second branch should have made its second call",
77
+ );
78
+
79
+ // The keys of the calls say which branch they are in: the two branches have their own keys.
80
+ // The observer feed can lag behind the side-effect counter: wait for the records themselves.
81
+ // The hold of the grant on each call is a step of its own, under `<key>~auth`: it is not a call.
82
+ const callKeys = (): string[] =>
83
+ ofType(records, "niwa.step.intent").map(stepKeyOf).filter((key) => !key.endsWith("~auth"));
84
+ await eventually(() => callKeys().length >= 3, 20_000, "the observer should have seen the three step intents");
85
+ const keys = callKeys();
86
+ expect(keys).toHaveLength(3);
87
+ // The two branches have keys of their own: no key belongs to both.
88
+ expect(new Set(keys).size).toBe(3);
89
+ expect(keys.filter((key) => key.startsWith("p1.0."))).toHaveLength(1);
90
+ expect(keys.filter((key) => key.startsWith("p1.1."))).toHaveLength(2);
91
+
92
+ // The host is killed in the middle: the first branch is still in flight.
93
+ await first.kill();
94
+ first = undefined;
95
+ await client.close().catch(() => {});
96
+
97
+ // 3. The host comes back and the first branch goes on: the calls that finished are answered
98
+ // from the journal, and the branch that was waiting runs again.
99
+ second = spawnHost(HOST_SCRIPT, homePath);
100
+ await second.ready();
101
+ gate(homePath, "branches.gate.b1").open();
102
+ gate(homePath, "branches.gate.b2").open();
103
+
104
+ await eventually(
105
+ () => ofType(records, "workflow.run.finished").length > 0,
106
+ 30_000,
107
+ "the run should have finished",
108
+ );
109
+
110
+ // 4. Every branch kept its own answer: the second branch did not take the place of the first.
111
+ const finished = ofType(records, "workflow.run.finished")[0];
112
+ const result = ScriptResult.parse((finished?.data as { outcome?: { result?: unknown } }).outcome?.result);
113
+ expect(result[0]).toEqual([
114
+ { answer: "answered: b1" },
115
+ { answer: "answered: b2" },
116
+ ]);
117
+ expect(result[1]).toEqual([
118
+ { answer: "answered: c1" },
119
+ { answer: "answered: c2" },
120
+ ]);
121
+
122
+ // The calls that finished were not repeated: c1, c2 and b2 were each made once. b1 was in
123
+ // flight when the host was killed, so it was made again: five calls for four of them.
124
+ expect(counter(homePath, "branches.agent").count()).toBe(5);
125
+
126
+ await client.close().catch(() => {});
127
+ } finally {
128
+ await observer?.stop();
129
+ await first?.kill().catch(() => {});
130
+ await second?.kill().catch(() => {});
131
+ await home.cleanup();
132
+ }
133
+ }, 90_000);