@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,299 @@
1
+ // Stopping part of a run, and the tree of runs.
2
+ //
3
+ // The owner stops a branch, a scope or a step of a run by its key prefix: its steps end as
4
+ // cancelled and the rest of the run goes on. A shielded scope under it is spared unless the stop
5
+ // goes through shields. A run that a branch starts is its child: stopping the branch, cancelling
6
+ // the run or pausing it goes down to the child, and a child is not started deeper than the limits
7
+ // of the tree allow.
8
+
9
+ import { afterEach, expect, test } from "bun:test";
10
+ import { writeFile } from "node:fs/promises";
11
+ import { join } from "node:path";
12
+
13
+ import { z } from "zod";
14
+
15
+ import { action } from "@niwa-labs/core";
16
+ import type { ActionName, StoredRecord } from "@niwa-labs/core";
17
+ import { plugin } from "@niwa-labs/plugin";
18
+ import { createNiwa, eventually, requests, stub, tempHome, testClock, timers } from "@niwa-labs/testing";
19
+ import type { Host } from "@niwa-labs/testing";
20
+
21
+ import { workflow } from "../src/index.ts";
22
+
23
+ const homes: Array<{ cleanup(): Promise<void> }> = [];
24
+ const hosts: Host[] = [];
25
+
26
+ afterEach(async () => {
27
+ for (const host of hosts.splice(0)) await host.close().catch(() => {});
28
+ for (const home of homes.splice(0)) await home.cleanup();
29
+ });
30
+
31
+ const ofType = (records: readonly StoredRecord[], type: string): StoredRecord[] => records.filter((row) => row.type === type);
32
+ const ofRun = (records: readonly StoredRecord[], type: string, run: string): StoredRecord[] =>
33
+ ofType(records, type).filter((row) => (row.data as { run?: string }).run === run);
34
+
35
+ async function setup() {
36
+ const home = await tempHome();
37
+ homes.push(home);
38
+ const aborted: string[] = [];
39
+ const calls: string[] = [];
40
+ const clock = testClock(1_700_000_000_000);
41
+ const niwa = createNiwa({ home: home.path, clock });
42
+ niwa.use(requests());
43
+ niwa.use(timers([]));
44
+ niwa.use(stub(home.path));
45
+ niwa.use(
46
+ plugin("tree", (api) => {
47
+ api.action(
48
+ action("tree.hang", {
49
+ description: "Runs until it is aborted.",
50
+ input: z.object({ name: z.string() }),
51
+ output: z.object({ name: z.string() }),
52
+ recovery: "do-not-repeat",
53
+ effect: "write",
54
+ run: ({ name }, ctx) =>
55
+ new Promise((_resolve, reject) => {
56
+ calls.push(name);
57
+ ctx.signal?.addEventListener("abort", () => {
58
+ aborted.push(name);
59
+ reject(new Error("aborted"));
60
+ });
61
+ }),
62
+ }),
63
+ );
64
+ api.action(
65
+ action("tree.work", {
66
+ description: "Answers at once.",
67
+ input: z.object({ name: z.string() }),
68
+ output: z.object({ name: z.string() }),
69
+ recovery: "repeat",
70
+ effect: "write",
71
+ run: async ({ name }) => {
72
+ calls.push(name);
73
+ return { name };
74
+ },
75
+ }),
76
+ );
77
+ }),
78
+ );
79
+ niwa.use(workflow());
80
+ await niwa.serve();
81
+ hosts.push(niwa);
82
+ let files = 0;
83
+ const write = async (source: string): Promise<string> => {
84
+ const file = join(home.path, `script-${String((files += 1))}.js`);
85
+ await writeFile(file, source);
86
+ return file;
87
+ };
88
+ const call = <T>(name: string, input: unknown): Promise<T> => niwa.call(name as ActionName, input as never) as Promise<T>;
89
+ return {
90
+ niwa,
91
+ clock,
92
+ aborted,
93
+ calls,
94
+ records: (): Promise<StoredRecord[]> => niwa.records.read(),
95
+ call,
96
+ start: async (source: string, extra: Record<string, unknown> = {}): Promise<string> =>
97
+ (await call<{ run: string }>("workflow.start", { file: await write(source), ...extra })).run,
98
+ register: async (source: string): Promise<string> => (await call<{ id: string }>("workflow.register", { file: await write(source) })).id,
99
+ };
100
+ }
101
+
102
+ test("the owner stops one branch of a running scope: its steps end as cancelled, and the run goes on to its end", async () => {
103
+ const t = await setup();
104
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
105
+ return await scope("work", undefined, async (s) => {
106
+ s.start("stuck", () => niwa.tree.hang({ name: "stuck" }));
107
+ s.start("waiting", async () => { await wait("stub.finished", { filter: { id: "go" } }); return "went"; });
108
+ return await s.rest();
109
+ });
110
+ });`);
111
+ await eventually(() => t.calls.includes("stuck"), 10_000, "the branch should start");
112
+ await t.call("workflow.stop", { run, at: "@work.stuck" });
113
+ // The run is not over: the other branch still waits.
114
+ await eventually(async () => ofType(await t.records(), "workflow.scope.settled").length === 1, 10_000, "the stopped branch should end");
115
+ expect(ofRun(await t.records(), "workflow.run.finished", run)).toEqual([]);
116
+ await t.call("stub.finish", { id: "go" });
117
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", run).length > 0, 10_000, "the run should finish");
118
+ const finished = ofRun(await t.records(), "workflow.run.finished", run)[0]?.data as { outcome: { status: string; result: unknown } };
119
+ expect(finished.outcome).toEqual({
120
+ status: "done",
121
+ result: { stuck: { ok: false, error: { name: "Cancelled", message: "stopped by the owner" } }, waiting: { ok: true, value: "went" } },
122
+ });
123
+ expect(t.aborted).toEqual(["stuck"]);
124
+ }, 30_000);
125
+
126
+ test("a stop of a waiting run ends the wait of the branch it names, and the run goes on", async () => {
127
+ const t = await setup();
128
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
129
+ return await scope("w", undefined, async (s) => {
130
+ s.start("never", () => wait("stub.finished", { filter: { id: "never" } }));
131
+ return await s.rest();
132
+ });
133
+ });`);
134
+ await eventually(
135
+ async () => ofType(await t.records(), "niwa.invocation.state").some((row) => (row.data as { state: string }).state === "waiting"),
136
+ 10_000,
137
+ "the run should wait",
138
+ );
139
+ await t.call("workflow.stop", { run, at: "@w.never", reason: "not needed" });
140
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", run).length > 0, 10_000, "the run should finish");
141
+ const finished = ofRun(await t.records(), "workflow.run.finished", run)[0]?.data as { outcome: { result: unknown } };
142
+ expect(finished.outcome.result).toEqual({ never: { ok: false, error: { name: "Cancelled", message: "not needed" } } });
143
+ }, 30_000);
144
+
145
+ test("a stop of a branch whose wait is suspended while another branch works takes hold when the run comes to wait", async () => {
146
+ const t = await setup();
147
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
148
+ return await scope("both", undefined, async (s) => {
149
+ s.start("waits", () => wait("stub.finished", { filter: { id: "never" } }));
150
+ s.start("works", async () => { await niwa.tree.work({ name: "before" }); await new Promise((r) => setTimeout(r, 300)); return niwa.tree.work({ name: "after" }); });
151
+ return await s.rest();
152
+ });
153
+ });`);
154
+ await eventually(() => t.calls.includes("before"), 10_000, "the working branch should start");
155
+ await eventually(
156
+ async () => ofType(await t.records(), "niwa.step.intent").some((row) => (row.data as { key: string }).key === "@both.waits.call-1"),
157
+ 10_000,
158
+ "the wait should begin",
159
+ );
160
+ await t.call("workflow.stop", { run, at: "@both.waits" });
161
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", run).length > 0, 10_000, "the run should finish");
162
+ const finished = ofRun(await t.records(), "workflow.run.finished", run)[0]?.data as { outcome: { result: unknown } };
163
+ expect(finished.outcome.result).toEqual({
164
+ waits: { ok: false, error: { name: "Cancelled", message: "stopped by the owner" } },
165
+ works: { ok: true, value: { name: "after" } },
166
+ });
167
+ }, 30_000);
168
+
169
+ test("a stop spares a shielded scope under it, and a forced stop goes through the shield", async () => {
170
+ const t = await setup();
171
+ const source = (name: string) => `export default workflow({ output: z.json() }, async () => {
172
+ return await scope("outer", undefined, async (s) => {
173
+ s.start("guarded", () => scope("safe", { shield: true }, async () => {
174
+ try { await niwa.tree.hang({ name: "${name}" }); return "not stopped"; } catch (error) { return error.name; }
175
+ }));
176
+ return await s.rest();
177
+ });
178
+ });`;
179
+ const spared = await t.start(source("spared"));
180
+ await eventually(() => t.calls.includes("spared"), 10_000, "the shielded block should start");
181
+ await t.call("workflow.stop", { run: spared, at: "@outer.guarded" });
182
+ await Bun.sleep(100);
183
+ expect(t.aborted).toEqual([]);
184
+ expect(ofRun(await t.records(), "workflow.run.finished", spared)).toEqual([]);
185
+ await t.call("workflow.stop", { run: spared, at: "@outer.guarded", force: true });
186
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", spared).length > 0, 10_000, "the run should finish");
187
+ expect(t.aborted).toEqual(["spared"]);
188
+ const finished = ofRun(await t.records(), "workflow.run.finished", spared)[0]?.data as { outcome: { result: unknown } };
189
+ expect(finished.outcome.result).toEqual({ guarded: { ok: true, value: "StepCancelled" } });
190
+ }, 30_000);
191
+
192
+ test("a run a branch starts is its child: stopping the branch ends the child, and the child knows its parent", async () => {
193
+ const t = await setup();
194
+ const child = await t.register(`export default workflow({ description: "a child that hangs", input: z.object({}), output: z.json() }, async () => {
195
+ await niwa.tree.hang({ name: "child-work" });
196
+ return "child done";
197
+ });`);
198
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
199
+ return await scope("kids", undefined, async (s) => {
200
+ s.run("one", { id: "${child}", args: {} });
201
+ return await s.rest();
202
+ });
203
+ });`);
204
+ await eventually(() => t.calls.includes("child-work"), 10_000, "the child should start");
205
+ const requested = ofType(await t.records(), "workflow.run.requested").map((row) => row.data as { run: string; parent?: { run: string; step: string } });
206
+ const childRun = requested.find((one) => one.parent?.run === run);
207
+ expect(childRun?.parent?.step).toContain("@kids.one.call-1");
208
+ await t.call("workflow.stop", { run, at: "@kids.one" });
209
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", run).length > 0, 10_000, "the parent should finish");
210
+ const childEnd = ofRun(await t.records(), "workflow.run.finished", childRun?.run ?? "")[0]?.data as { outcome: { status: string } } | undefined;
211
+ expect(childEnd?.outcome.status).toBe("cancelled");
212
+ }, 30_000);
213
+
214
+ test("cancelling a run cancels its child runs, pausing it pauses them, and the limits of a tree refuse a child too deep", async () => {
215
+ const t = await setup();
216
+ const child = await t.register(`export default workflow({ description: "a child that hangs", input: z.object({}), output: z.json() }, async () => {
217
+ await niwa.tree.hang({ name: "deep-work" });
218
+ return "child done";
219
+ });`);
220
+ const parentSource = `export default workflow({ output: z.json() }, async () => {
221
+ return await niwa.flow["${child}"]({});
222
+ });`;
223
+ const run = await t.start(parentSource);
224
+ await eventually(() => t.calls.includes("deep-work"), 10_000, "the child should start");
225
+ const childRun = ofType(await t.records(), "workflow.run.requested")
226
+ .map((row) => row.data as { run: string; parent?: { run: string } })
227
+ .find((one) => one.parent?.run === run)?.run;
228
+ expect(childRun).toBeDefined();
229
+ await t.call("workflow.pause", { run });
230
+ expect(ofRun(await t.records(), "workflow.run.pause-requested", childRun ?? "").length).toBe(1);
231
+ await t.call("workflow.cancel", { run });
232
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", childRun ?? "").length > 0, 10_000, "the child should end");
233
+
234
+ // A tree that may be one deep: the run may not start a child.
235
+ const shallow = await t.start(parentSource, { limits: { depth: 1 } });
236
+ await eventually(async () => ofRun(await t.records(), "workflow.run.paused", shallow).length > 0, 10_000, "the parent should pause");
237
+ const refusal = ofType(await t.records(), "niwa.step.outcome")
238
+ .map((row) => row.data as { outcome: { status: string; error?: string } })
239
+ .find((row) => row.outcome.error?.includes("deep") === true);
240
+ expect(refusal?.outcome.error).toContain("would be 2 deep in its tree, and its limits allow 1");
241
+ }, 30_000);
242
+
243
+ test("a child run's deadline comes no later than its parent's", async () => {
244
+ const t = await setup();
245
+ const child = await t.register(`export default workflow({ description: "a child that hangs", input: z.object({}), output: z.json() }, async () => {
246
+ await niwa.tree.hang({ name: "child-work" });
247
+ return "child done";
248
+ });`);
249
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
250
+ await sleep("10s");
251
+ return await niwa.flow["${child}"]({});
252
+ });`, { limits: { deadline: 60_000 } });
253
+ // The child starts ten seconds into its parent: its own minute would end after the parent's.
254
+ await eventually(async () => ofType(await t.records(), "timer.sleep.requested").length === 1, 10_000, "the sleep should be armed");
255
+ await t.clock.advance(10_000);
256
+ await eventually(() => t.calls.includes("child-work"), 10_000, "the child should start");
257
+ const requested = ofType(await t.records(), "workflow.run.requested").map((row) => row.data as { run: string; deadline?: number; parent?: { run: string } });
258
+ const parent = requested.find((one) => one.run === run);
259
+ const childRun = requested.find((one) => one.parent?.run === run);
260
+ expect(parent?.deadline).toBe(1_700_000_000_000 + 60_000);
261
+ expect(childRun?.deadline).toBe(parent?.deadline);
262
+ }, 30_000);
263
+
264
+ test("extending a run extends the child held to its deadline, and both go on", async () => {
265
+ const t = await setup();
266
+ const child = await t.register(`export default workflow({ description: "a child that sleeps", input: z.object({}), output: z.json() }, async () => {
267
+ await sleep("2m");
268
+ await niwa.tree.work({ name: "after-the-sleep" });
269
+ return "child done";
270
+ });`);
271
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
272
+ return await niwa.flow["${child}"]({});
273
+ });`, { limits: { deadline: 60_000 } });
274
+ await eventually(async () => ofType(await t.records(), "timer.sleep.requested").length === 1, 10_000, "the child should sleep");
275
+ await t.clock.advance(60_000);
276
+ await t.clock.advance(120_000);
277
+ await Bun.sleep(300);
278
+ expect(t.calls).not.toContain("after-the-sleep");
279
+ await t.call("workflow.extend", { run, by: 600_000 });
280
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", run).length > 0, 10_000, "the parent should finish");
281
+ expect(t.calls).toContain("after-the-sleep");
282
+ }, 30_000);
283
+
284
+ test("a branch runs a registered workflow that takes no input as its child", async () => {
285
+ const t = await setup();
286
+ const child = await t.register(`export default workflow({ description: "a child with no input", output: z.string() }, async () => {
287
+ await niwa.tree.work({ name: "plain-child" });
288
+ return "child done";
289
+ });`);
290
+ const run = await t.start(`export default workflow({ output: z.json() }, async () => {
291
+ return await scope("kids", undefined, async (s) => {
292
+ const one = s.run("one", { id: "${child}" });
293
+ return await one.value();
294
+ });
295
+ });`);
296
+ await eventually(async () => ofRun(await t.records(), "workflow.run.finished", run).length > 0, 10_000, "the parent should finish");
297
+ const finished = ofRun(await t.records(), "workflow.run.finished", run)[0]?.data as { outcome: { status: string; result: unknown } };
298
+ expect(finished.outcome).toEqual({ status: "done", result: "child done" });
299
+ }, 30_000);
@@ -0,0 +1,220 @@
1
+ // The code of a registered workflow is kept in the home: `workflow.register` copies the source closure of the version
2
+ // under `<home>/workflows/<wf-id>/<version>/`, and the version runs, installs and resumes from that copy, so the file
3
+ // it was registered from may be edited or deleted.
4
+
5
+ import { afterEach, expect, test } from "bun:test";
6
+ import { existsSync, readFileSync, realpathSync } from "node:fs";
7
+ import { mkdir, rm, symlink, writeFile } from "node:fs/promises";
8
+ import { join } from "node:path";
9
+
10
+ import { action } from "@niwa-labs/core";
11
+ import { plugin } from "@niwa-labs/plugin";
12
+ import { createNiwa, requests, eventually, tempHome, timers } from "@niwa-labs/testing";
13
+ import type { Host } from "@niwa-labs/testing";
14
+ import { workflow, workflowGet, workflowRegister, workflowResume, workflowStart, workflowWait } from "../src/index.ts";
15
+ import { z } from "zod";
16
+
17
+ import { closureOf, versionOf } from "../src/registry.ts";
18
+
19
+ const homes: Array<{ cleanup(): Promise<void> }> = [];
20
+ const hosts: Host[] = [];
21
+
22
+ afterEach(async () => {
23
+ for (const host of hosts.splice(0)) await host.close().catch(() => {});
24
+ for (const home of homes.splice(0)) await home.cleanup();
25
+ }, 60_000);
26
+
27
+ /** Whether `gate.pass` fails: a run that calls it while it does pauses. */
28
+ let shut = false;
29
+ const gate = action("gate.pass", {
30
+ description: "Pass the gate, or fail while it is shut.",
31
+ input: z.object({}),
32
+ output: z.object({ passed: z.boolean() }),
33
+ recovery: "repeat",
34
+ effect: "write",
35
+ run: () => {
36
+ if (shut) throw new Error("the gate is shut");
37
+ return { passed: true };
38
+ },
39
+ });
40
+
41
+ async function served(): Promise<{ host: Host; home: string; src: string }> {
42
+ const home = await tempHome();
43
+ homes.push(home);
44
+ const host = createNiwa({ home: home.path });
45
+ host.use(requests(), timers([]), plugin("gate", (api) => api.action(gate)), workflow());
46
+ await host.serve();
47
+ hosts.push(host);
48
+ const src = join(home.path, "src");
49
+ // The host knows its home with the links resolved, and keeps the code there.
50
+ await mkdir(join(src, "flows"), { recursive: true });
51
+ await mkdir(join(src, "lib"), { recursive: true });
52
+ return { host, home: realpathSync(home.path), src };
53
+ }
54
+
55
+ /** A script in `flows/` that imports a helper from `../lib/`, and returns its label. */
56
+ async function labelled(src: string, label: string): Promise<string> {
57
+ await writeFile(join(src, "lib", "label.ts"), `export const label = ${JSON.stringify(label)};\n`);
58
+ const file = join(src, "flows", "label.ts");
59
+ await writeFile(
60
+ file,
61
+ [
62
+ 'import { label } from "../lib/label.ts";',
63
+ "export default workflow({",
64
+ ' description: "Answer the label",',
65
+ " output: z.string(),",
66
+ "}, async () => label);",
67
+ ].join("\n"),
68
+ );
69
+ return file;
70
+ }
71
+
72
+ const run = async (host: Host, id: string): Promise<unknown> => {
73
+ const { run: started } = await host.call(workflowStart, { id });
74
+ return (await host.call(workflowWait, { run: started, timeoutMs: 20_000 })).outcome;
75
+ };
76
+
77
+ test("register copies the source closure into the home, laid out as it was, and get shows where", async () => {
78
+ const { host, home, src } = await served();
79
+ const file = await labelled(src, "one");
80
+ const { id, version } = await host.call(workflowRegister, { file });
81
+
82
+ const dir = join(home, "workflows", id, version);
83
+ expect(readFileSync(join(dir, "flows", "label.ts"), "utf8")).toBe(readFileSync(file, "utf8"));
84
+ expect(readFileSync(join(dir, "lib", "label.ts"), "utf8")).toBe('export const label = "one";\n');
85
+ // The copy is the version: the same files at the same places relative to the entry.
86
+ expect(versionOf(join(dir, "flows", "label.ts"))).toBe(version);
87
+ expect(JSON.parse(readFileSync(join(home, "workflows", id, `${version}.json`), "utf8"))).toMatchObject({ entry: "flows/label.ts", from: file });
88
+
89
+ const got = await host.call(workflowGet, { id });
90
+ expect(got.versions).toMatchObject([{ version, file, stored: join(dir, "flows", "label.ts") }]);
91
+
92
+ // The same version again is the same copy, not written again.
93
+ await host.call(workflowRegister, { file, id });
94
+ expect((await host.call(workflowGet, { id })).versions.map((one) => one.stored)).toEqual([join(dir, "flows", "label.ts")]);
95
+ }, 60_000);
96
+
97
+ test("a registered workflow runs from its copy after the file it was registered from is edited or deleted", async () => {
98
+ const { host, src } = await served();
99
+ const file = await labelled(src, "one");
100
+ const { id } = await host.call(workflowRegister, { file });
101
+
102
+ await writeFile(join(src, "lib", "label.ts"), 'export const label = "edited";\n');
103
+ expect(await run(host, id)).toEqual({ status: "done", result: "one" });
104
+
105
+ await rm(src, { recursive: true });
106
+ expect(await run(host, id)).toEqual({ status: "done", result: "one" });
107
+ }, 60_000);
108
+
109
+ test("two versions are kept side by side, and a start runs the latest one", async () => {
110
+ const { host, home, src } = await served();
111
+ const first = await host.call(workflowRegister, { file: await labelled(src, "one") });
112
+ const second = await host.call(workflowRegister, { file: await labelled(src, "two"), id: first.id });
113
+ expect(second.version).not.toBe(first.version);
114
+
115
+ const stored = (await host.call(workflowGet, { id: first.id })).versions.map((one) => one.stored);
116
+ expect(stored).toEqual([join(home, "workflows", first.id, first.version, "flows", "label.ts"), join(home, "workflows", first.id, second.version, "flows", "label.ts")]);
117
+ for (const entry of stored) expect(existsSync(entry ?? "")).toBe(true);
118
+ expect(readFileSync(join(home, "workflows", first.id, first.version, "lib", "label.ts"), "utf8")).toContain('"one"');
119
+ expect(readFileSync(join(home, "workflows", first.id, second.version, "lib", "label.ts"), "utf8")).toContain('"two"');
120
+
121
+ await rm(src, { recursive: true });
122
+ expect(await run(host, first.id)).toEqual({ status: "done", result: "two" });
123
+ }, 60_000);
124
+
125
+ test("a paused run of an older version resumes on its own copy, after a new version and with the original deleted", async () => {
126
+ const { host, src } = await served();
127
+ const file = join(src, "flows", "gated.ts");
128
+ const gated = (label: string): string =>
129
+ [
130
+ "export default workflow({",
131
+ ' description: "Pass the gate and answer the label",',
132
+ ' uses: ["gate.pass"],',
133
+ " output: z.string(),",
134
+ "}, async () => {",
135
+ ' await call("gate.pass", {}, { label: "gate" });',
136
+ ` return ${JSON.stringify(label)};`,
137
+ "});",
138
+ ].join("\n");
139
+ await writeFile(file, gated("old"));
140
+ const { id, version } = await host.call(workflowRegister, { file });
141
+
142
+ shut = true;
143
+ try {
144
+ const { run: started } = await host.call(workflowStart, { id });
145
+ expect((await host.call(workflowWait, { run: started, timeoutMs: 20_000 })).state).toBe("paused");
146
+
147
+ await writeFile(file, gated("new"));
148
+ const newer = await host.call(workflowRegister, { file, id });
149
+ expect(newer.version).not.toBe(version);
150
+ await rm(src, { recursive: true });
151
+
152
+ shut = false;
153
+ await host.call(workflowResume, { run: started });
154
+ await eventually(async () => (await host.call(workflowWait, { run: started, timeoutMs: 1_000 })).state === "finished", 20_000);
155
+ expect((await host.call(workflowWait, { run: started, timeoutMs: 1_000 })).outcome).toEqual({ status: "done", result: "old" });
156
+ // A new start runs the new version.
157
+ expect(await run(host, id)).toEqual({ status: "done", result: "new" });
158
+ } finally {
159
+ shut = false;
160
+ }
161
+ }, 90_000);
162
+
163
+ test("a copy finds what the script takes from niwa: its globals, the types of the script package and the packages niwa runs with", async () => {
164
+ const { host, home, src } = await served();
165
+ // The original sits where zod is found, as a script in niwa's own tree does: a package it imports is found from the copy too.
166
+ await symlink(realpathSync(join(import.meta.dir, "..", "node_modules")), join(src, "node_modules"), "dir");
167
+ const file = join(src, "flows", "packages.ts");
168
+ await writeFile(
169
+ file,
170
+ [
171
+ 'import type { ScriptApi } from "@niwa-labs/script";',
172
+ 'import { z as zod } from "zod";',
173
+ "const answer: ScriptApi[\"z\"] = z;",
174
+ "export default workflow({",
175
+ ' description: "Parse with an imported zod",',
176
+ " output: z.string(),",
177
+ "}, async () => `${String(answer === z)}:${zod.string().parse(\"ok\")}`);",
178
+ ].join("\n"),
179
+ );
180
+ const { id } = await host.call(workflowRegister, { file });
181
+ expect(realpathSync(join(home, "workflows", "node_modules"))).toBe(realpathSync(join(import.meta.dir, "..", "node_modules")));
182
+
183
+ await rm(src, { recursive: true });
184
+ expect(await run(host, id)).toEqual({ status: "done", result: "true:ok" });
185
+ }, 60_000);
186
+
187
+ test("a script that imports a data file has a closure: the data file is in it and is not read as code", () => {
188
+ const dir = join(import.meta.dir, "fixtures", "with-data");
189
+ const closure = closureOf(join(dir, "flow.ts"));
190
+ expect([...(closure?.files.keys() ?? [])].sort()).toEqual([join(dir, "flow.ts"), join(dir, "table.json")]);
191
+ });
192
+
193
+ test("a paused run whose copy changed under it is read through its manifest, and stays paused when it resumes", async () => {
194
+ const { host, home, src } = await served();
195
+ await writeFile(join(src, "lib", "label.ts"), 'export const label = "kept";\n');
196
+ const file = join(src, "flows", "gated.ts");
197
+ await writeFile(
198
+ file,
199
+ [
200
+ 'import { label } from "../lib/label.ts";',
201
+ 'export default workflow({ description: "Pass the gate", uses: ["gate.pass"], output: z.string() }, async () => {',
202
+ ' await call("gate.pass", {}, { label: "gate" });',
203
+ " return label;",
204
+ "});",
205
+ ].join("\n"),
206
+ );
207
+ const { id, version } = await host.call(workflowRegister, { file });
208
+ shut = true;
209
+ try {
210
+ const { run: started } = await host.call(workflowStart, { id });
211
+ expect((await host.call(workflowWait, { run: started, timeoutMs: 20_000 })).state).toBe("paused");
212
+ await writeFile(join(home, "workflows", id, version, "lib", "label.ts"), 'export const label = "swapped";\n');
213
+ shut = false;
214
+ await host.call(workflowResume, { run: started });
215
+ await eventually(async () => JSON.stringify(await host.call(workflowWait, { run: started, timeoutMs: 1_000 })).includes("is not the file"), 20_000);
216
+ expect((await host.call(workflowWait, { run: started, timeoutMs: 1_000 })).state).toBe("paused");
217
+ } finally {
218
+ shut = false;
219
+ }
220
+ }, 90_000);
@@ -0,0 +1,136 @@
1
+ // The session of an agent call sees the action that answers a question.
2
+ //
3
+ // The agent action of a workflow starts a session and asks it. A harness that cannot answer by
4
+ // itself answers through `submit-answer`, and a session that does not see that action can never
5
+ // answer at all: the session of an agent call must see it.
6
+ //
7
+ // The scenario runs against a fake control side: the script names a harness, and the session
8
+ // that the harness starts is asked.
9
+
10
+ import { expect, test } from "bun:test";
11
+
12
+ import { rmSync } from "node:fs";
13
+ import { join } from "node:path";
14
+
15
+ import type { ActionName } from "@niwa-labs/core";
16
+ import { harnessId, machineId } from "@niwa-labs/harness";
17
+ import type { Harness, SessionControl, SessionId, StartOptions } from "@niwa-labs/harness";
18
+ import { SUBMIT_ANSWER_ACTION } from "@niwa-labs/sessions/records";
19
+ import { createNiwa, sessions, tempDirSync, watch } from "@niwa-labs/testing";
20
+ import { workflow } from "../src/index.ts";
21
+
22
+
23
+ /** The harness the script names. */
24
+ const HARNESS = harnessId("fake-harness");
25
+
26
+ /**
27
+ * The fake control side: it starts sessions and answers them.
28
+ *
29
+ * It cannot answer natively, so the session of an agent call answers through the request.
30
+ */
31
+ class FakeControl implements SessionControl {
32
+ readonly starts: StartOptions[] = [];
33
+ private counter = 0;
34
+
35
+ async start(options: StartOptions): Promise<{ session: SessionId }> {
36
+ this.starts.push(options);
37
+ this.counter += 1;
38
+ return { session: { harness: HARNESS, native: `session-${this.counter}` as never } };
39
+ }
40
+
41
+ async resume(): Promise<void> {
42
+ throw new Error("this session cannot be resumed");
43
+ }
44
+
45
+ async send() {
46
+ return { status: "started" as const, turn: 1 };
47
+ }
48
+
49
+ async interrupt(): Promise<void> {
50
+ // The fake interrupts nothing.
51
+ }
52
+
53
+ async ask<T>(): Promise<{ session: SessionId; value: T; at: never }> {
54
+ throw new Error("this harness cannot answer natively");
55
+ }
56
+
57
+ async *life(): AsyncIterable<never> {
58
+ // The fake reports no signs of life: the sessions module does not need them here.
59
+ }
60
+
61
+ async state(): Promise<"running" | "idle" | "unknown"> {
62
+ return "unknown";
63
+ }
64
+ }
65
+
66
+ /** The installation the fake side serves. */
67
+ const fakeInstance: Harness = {
68
+ id: HARNESS,
69
+ kind: "fake-kind" as never,
70
+ machine: machineId("machine-1"),
71
+ home: "/tmp/fake-home",
72
+ sides: {
73
+ reading: { list: true, read: true, watch: false },
74
+ control: {
75
+ start: true,
76
+ resume: false,
77
+ send: true,
78
+ interrupt: true,
79
+ ask: true,
80
+ structuredOutput: false, launch: { model: false, effort: [], modes: [] },
81
+ },
82
+ },
83
+ };
84
+
85
+ test("the session of an agent call sees the action that answers a question", async () => {
86
+ const control = new FakeControl();
87
+ const home = tempDirSync("session-sees-answer");
88
+ const niwa = createNiwa({ home });
89
+ niwa.use(
90
+ sessions({
91
+ harnesses: [{ instance: fakeInstance, control }],
92
+ // The harness cannot answer natively, so the session answers through the niwa server.
93
+ niwaMcp: { command: "bun", args: ["bin/niwa.ts", "mcp"] },
94
+ }),
95
+ );
96
+ niwa.use(workflow({ harnesses: [HARNESS] }));
97
+ await niwa.serve();
98
+
99
+ try {
100
+ const script = join(home, "script.js");
101
+ await Bun.write(
102
+ script,
103
+ [
104
+ "export default workflow({ output: z.json() }, async () => {",
105
+ ' const answer = await ask({ harness: "fake-harness" }, "Study the core.");',
106
+ " return answer;",
107
+ "});",
108
+ "",
109
+ ].join("\n"),
110
+ );
111
+
112
+ const started = (await niwa.call("workflow.start" as ActionName, { file: script } as never)) as {
113
+ run: string;
114
+ };
115
+ expect(started.run).toBeDefined();
116
+
117
+ const observer = await watch(home);
118
+ await Bun.sleep(1500);
119
+
120
+ // The session was started, and it sees the action that answers a question.
121
+ expect(control.starts.length).toBe(1);
122
+ expect(control.starts[0]?.visible?.actions).toContain(SUBMIT_ANSWER_ACTION);
123
+
124
+ // The steps of the agent call name the actions of the sessions module, as old journals do.
125
+ const intents = observer.seen
126
+ .filter((record) => record.type === "niwa.step.intent")
127
+ .map((record) => (record.data as { action?: string }).action);
128
+ expect(intents).toContain("session.start");
129
+ expect(intents).toContain("session.ask");
130
+
131
+ await observer.stop();
132
+ } finally {
133
+ await niwa.close();
134
+ rmSync(home, { recursive: true, force: true });
135
+ }
136
+ }, 30_000);