@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,262 @@
1
+ // The workflow plugin registers the agent action of every harness it was given.
2
+ //
3
+ // The workflow module needs no hand glue for a script that names a harness.
4
+ //
5
+ // The option `harnesses` says which harnesses a script may name. For each of them the plugin
6
+ // registers the agent action `session.start.<harness>`, so `session({harness})` works with no hand
7
+ // glue.
8
+ //
9
+ // The scenario runs against a fake control side: the script names a harness, and the session that
10
+ // the harness starts answers.
11
+
12
+ import { expect, test } from "bun:test";
13
+
14
+ import { rmSync } from "node:fs";
15
+ import { join } from "node:path";
16
+
17
+ import type { ActionName } from "@niwa-labs/core";
18
+ import { harnessId, machineId } from "@niwa-labs/harness";
19
+ import type { Harness, SessionControl, SessionId } from "@niwa-labs/harness";
20
+ import { createNiwa, sessions, eventually, tempDirSync, watch } from "@niwa-labs/testing";
21
+ import { workflow } from "../src/index.ts";
22
+
23
+
24
+ /** The harness the script names. */
25
+ const HARNESS = harnessId("fake-harness");
26
+
27
+ /** The sessions the fake control side started, in order. */
28
+ interface FakeSession {
29
+ readonly id: SessionId;
30
+ readonly prompts: string[];
31
+ readonly cwd: string | undefined;
32
+ readonly model: string | undefined;
33
+ readonly effort: string | undefined;
34
+ readonly mode: string | undefined;
35
+ }
36
+
37
+ /**
38
+ * The fake control side: it starts sessions and answers them.
39
+ */
40
+ class FakeControl implements SessionControl {
41
+ readonly started: FakeSession[] = [];
42
+ private counter = 0;
43
+
44
+ async start(options: { prompt: { sections: Array<{ text: string }> }; cwd?: string; model?: string; effort?: string; mode?: string }): Promise<{ session: SessionId }> {
45
+ this.counter += 1;
46
+ const id = { harness: HARNESS, native: `session-${this.counter}` as never };
47
+ this.started.push({
48
+ id,
49
+ prompts: options.prompt.sections.map((section) => section.text),
50
+ cwd: options.cwd,
51
+ model: options.model,
52
+ effort: options.effort,
53
+ mode: options.mode,
54
+ });
55
+ return { session: id };
56
+ }
57
+
58
+ async resume(): Promise<void> {
59
+ throw new Error("this session cannot be resumed");
60
+ }
61
+
62
+ async send() {
63
+ return { status: "started" as const, turn: 1 };
64
+ }
65
+
66
+ async interrupt(): Promise<void> {
67
+ // The fake interrupts nothing.
68
+ }
69
+
70
+ async ask<T>(id: SessionId, options: { prompt: { sections: Array<{ text: string }> } }): Promise<{
71
+ session: SessionId;
72
+ value: T;
73
+ at: never;
74
+ }> {
75
+ const question = options.prompt.sections.map((section) => section.text).join("\n\n");
76
+ return { session: id, value: { answer: `answered: ${question}` } as T, at: 0 as never };
77
+ }
78
+
79
+ async *life(): AsyncIterable<never> {
80
+ // The fake reports no signs of life: the sessions module does not need them here.
81
+ }
82
+
83
+ async state(): Promise<"running" | "idle" | "unknown"> {
84
+ return "unknown";
85
+ }
86
+ }
87
+
88
+ /** The installation the fake side serves. */
89
+ const fakeInstance: Harness = {
90
+ id: HARNESS,
91
+ kind: "fake-kind" as never,
92
+ machine: machineId("machine-1"),
93
+ home: "/tmp/fake-home",
94
+ sides: {
95
+ reading: { list: true, read: true, watch: false },
96
+ control: {
97
+ start: true,
98
+ resume: false,
99
+ send: true,
100
+ interrupt: true,
101
+ ask: true,
102
+ structuredOutput: true, launch: { model: true, effort: ["low", "high"], modes: ["ask", "auto"] },
103
+ },
104
+ },
105
+ };
106
+
107
+ test("the workflow registers the agent action of every harness it was given", async () => {
108
+ const control = new FakeControl();
109
+ const home = tempDirSync("harnesses");
110
+ const niwa = createNiwa({ home });
111
+ niwa.use(sessions({ harnesses: [{ instance: fakeInstance, control }] }));
112
+ // The host says which harnesses a script may name: nothing else is asked of it.
113
+ niwa.use(workflow({ harnesses: [HARNESS] }));
114
+ await niwa.serve();
115
+
116
+ try {
117
+ // 1. The agent action of the harness is registered: it is there with no hand glue.
118
+ const description = await niwa.describe();
119
+ const agentAction = description.actions.find(
120
+ (entry) => entry.name === `session.start.${HARNESS}`,
121
+ );
122
+ expect(agentAction).toBeDefined();
123
+
124
+ // 2. A script that names the harness reaches the agents of that harness.
125
+ const script = join(home, "script.js");
126
+ await Bun.write(
127
+ script,
128
+ [
129
+ "export default workflow({ output: z.json() }, async () => {",
130
+ ' const answer = await ask({ harness: "fake-harness" }, "Study the core.");',
131
+ " return answer;",
132
+ "});",
133
+ "",
134
+ ].join("\n"),
135
+ );
136
+
137
+ const started = (await niwa.call("workflow.start" as ActionName, { file: script } as never)) as {
138
+ run: string;
139
+ };
140
+ expect(started.run).toBeDefined();
141
+
142
+ // 3. The session was started on that harness, and the script got its answer.
143
+ const observer = await watch(home);
144
+ await eventually(() => observer.seen.some((record) => record.type === "workflow.run.finished"));
145
+ expect(control.started.length).toBe(1);
146
+ expect(control.started[0]?.id.harness).toBe(HARNESS);
147
+
148
+ // 4. The run finished with what the session answered.
149
+ const finished = observer.seen.find((record) => record.type === "workflow.run.finished");
150
+ expect(finished).toBeDefined();
151
+ expect((finished?.data as { outcome?: { result?: unknown } }).outcome?.result).toEqual({
152
+ answer: "answered: Study the core.",
153
+ });
154
+
155
+ await observer.stop();
156
+ } finally {
157
+ await niwa.close();
158
+ rmSync(home, { recursive: true, force: true });
159
+ }
160
+ }, 30_000);
161
+
162
+ test("an agent call may name the directory its session starts in, and without one the session is given none", async () => {
163
+ const control = new FakeControl();
164
+ const home = tempDirSync("agent-cwd");
165
+ const niwa = createNiwa({ home });
166
+ niwa.use(sessions({ harnesses: [{ instance: fakeInstance, control }] }));
167
+ niwa.use(workflow({ harnesses: [HARNESS] }));
168
+ await niwa.serve();
169
+
170
+ try {
171
+ const script = join(home, "script.js");
172
+ await Bun.write(
173
+ script,
174
+ [
175
+ "export default workflow({ output: z.json() }, async () => {",
176
+ ' await ask({ harness: "fake-harness", cwd: "/tmp/the-worktree" }, "in the worktree");',
177
+ ' await ask({ harness: "fake-harness" }, "where the host is");',
178
+ " return null;",
179
+ "});",
180
+ "",
181
+ ].join("\n"),
182
+ );
183
+ await niwa.call("workflow.start" as ActionName, { file: script } as never);
184
+ const observer = await watch(home);
185
+ for (let waited = 0; waited < 10_000 && control.started.length < 2; waited += 100) await Bun.sleep(100);
186
+ await observer.stop();
187
+
188
+ expect(control.started.map((session) => session.cwd)).toEqual(["/tmp/the-worktree", undefined]);
189
+ expect(control.started.map((session) => [session.model, session.effort])).toEqual([[undefined, undefined], [undefined, undefined]]);
190
+ } finally {
191
+ await niwa.close();
192
+ rmSync(home, { recursive: true, force: true });
193
+ }
194
+ }, 30_000);
195
+
196
+ test("an agent call may name the model and the effort of its session, and a level the kind does not take fails the call before a session starts", async () => {
197
+ const control = new FakeControl();
198
+ const home = tempDirSync("agent-effort");
199
+ const niwa = createNiwa({ home });
200
+ niwa.use(sessions({ harnesses: [{ instance: fakeInstance, control }] }));
201
+ niwa.use(workflow({ harnesses: [HARNESS] }));
202
+ await niwa.serve();
203
+
204
+ try {
205
+ const script = join(home, "script.js");
206
+ await Bun.write(
207
+ script,
208
+ [
209
+ "export default workflow({ output: z.json() }, async () => {",
210
+ ' await ask({ harness: "fake-harness", model: "m-1", effort: "high" }, "tuned");',
211
+ ' await ask({ harness: "fake-harness", effort: "max" }, "too much");',
212
+ " return null;",
213
+ "});",
214
+ "",
215
+ ].join("\n"),
216
+ );
217
+ await niwa.call("workflow.start" as ActionName, { file: script } as never);
218
+ const observer = await watch(home);
219
+ for (let waited = 0; waited < 10_000 && !JSON.stringify(observer.seen).includes("is not one of"); waited += 100) await Bun.sleep(100);
220
+ await observer.stop();
221
+
222
+ expect(control.started.map((session) => [session.model, session.effort])).toEqual([["m-1", "high"]]);
223
+ expect(JSON.stringify(observer.seen)).toContain("is not one of low, high");
224
+ } finally {
225
+ await niwa.close();
226
+ rmSync(home, { recursive: true, force: true });
227
+ }
228
+ }, 30_000);
229
+
230
+ test("an agent call may name the mode of its session, and a mode the kind does not have fails the call before a session starts", async () => {
231
+ const control = new FakeControl();
232
+ const home = tempDirSync("agent-mode");
233
+ const niwa = createNiwa({ home });
234
+ niwa.use(sessions({ harnesses: [{ instance: fakeInstance, control }] }));
235
+ niwa.use(workflow({ harnesses: [HARNESS] }));
236
+ await niwa.serve();
237
+
238
+ try {
239
+ const script = join(home, "script.js");
240
+ await Bun.write(
241
+ script,
242
+ [
243
+ "export default workflow({ output: z.json() }, async () => {",
244
+ ' await ask({ harness: "fake-harness", mode: "ask" }, "careful");',
245
+ ' await ask({ harness: "fake-harness", mode: "full" }, "unrestricted");',
246
+ " return null;",
247
+ "});",
248
+ "",
249
+ ].join("\n"),
250
+ );
251
+ await niwa.call("workflow.start" as ActionName, { file: script } as never);
252
+ const observer = await watch(home);
253
+ for (let waited = 0; waited < 10_000 && !JSON.stringify(observer.seen).includes("is not one of"); waited += 100) await Bun.sleep(100);
254
+ await observer.stop();
255
+
256
+ expect(control.started.map((session) => session.mode)).toEqual(["ask"]);
257
+ expect(JSON.stringify(observer.seen)).toContain('the mode \\"full\\" is not one of ask, auto');
258
+ } finally {
259
+ await niwa.close();
260
+ rmSync(home, { recursive: true, force: true });
261
+ }
262
+ }, 30_000);
@@ -0,0 +1,152 @@
1
+ import { expect, test } from "bun:test";
2
+ import { writeFile } from "node:fs/promises";
3
+ import { join } from "node:path";
4
+
5
+ import { action, grant, principalOf, seq, shortRun } from "@niwa-labs/core";
6
+ import { harnessId, harnessKind, machineId, sessionId } from "@niwa-labs/harness";
7
+ import type { Harness, SessionControl } from "@niwa-labs/harness";
8
+ import { plugin } from "@niwa-labs/plugin";
9
+ import { SessionStarted, sessionRef } from "@niwa-labs/sessions/records";
10
+ import { connect, createNiwa, sessions, eventually, tempHome } from "@niwa-labs/testing";
11
+ import { workflow, workflowInspect, workflowResume, workflowStart, workflowWait } from "../src/index.ts";
12
+ import { z } from "zod";
13
+
14
+ test("inspect shows the declared phases with their states and steps, and links parallel steps to their own nested sessions", async () => {
15
+ const home = await tempHome();
16
+ const host = createNiwa({ home: home.path });
17
+ const harness = harnessId("inspect-test");
18
+ const held = Promise.withResolvers<void>();
19
+ const asked = new Map<string, ReturnType<typeof sessionId>>();
20
+ let launches = 0;
21
+ const control: SessionControl = {
22
+ start: async () => ({ session: sessionId(harness, `launch-${++launches}`) }),
23
+ resume: async () => {},
24
+ send: async () => ({ status: "started", turn: 1 }),
25
+ interrupt: async () => {},
26
+ ask: async <T>(session: Parameters<SessionControl["ask"]>[0], options: Parameters<SessionControl["ask"]>[1]) => {
27
+ const prompt = options.prompt.sections.map((section) => section.text).join("");
28
+ asked.set(prompt, session);
29
+ if (prompt === "left") await held.promise;
30
+ return { session, value: options.schema.parse({ answer: prompt }) as T, at: 0 as never };
31
+ },
32
+ life: async function* () {},
33
+ state: async () => "unknown",
34
+ };
35
+ const instance: Harness = {
36
+ id: harness,
37
+ kind: harnessKind("inspect-fake"),
38
+ machine: machineId("inspect-machine"),
39
+ home: home.path,
40
+ sides: {
41
+ reading: { list: true, read: true, watch: false },
42
+ control: { start: true, resume: false, send: true, interrupt: true, ask: true, structuredOutput: true, launch: { model: false, effort: [], modes: [] } },
43
+ },
44
+ };
45
+ host.use(sessions({ harnesses: [{ instance, control }] }), workflow({ harnesses: [harness] }));
46
+ try {
47
+ await host.serve();
48
+ const file = join(home.path, "inspect.js");
49
+ await writeFile(file, `export default workflow({ phases: [{ title: "sample" }, { title: "agents", detail: "two at once" }, { title: "review" }] }, async () => {
50
+ await now({ label: "before" });
51
+ for (let n = 0; n < 2; n++) {
52
+ phase("sample");
53
+ await now({ label: "sample-" + n });
54
+ }
55
+ phase("agents");
56
+ await parallel([
57
+ () => ask({ harness: "inspect-test" }, "left"),
58
+ () => ask({ harness: "inspect-test" }, "right"),
59
+ ]);
60
+ });`);
61
+ const { run } = await host.call(workflowStart, { file, label: "inspection" });
62
+ const inspect = () => host.call(workflowInspect, { run: shortRun(run) });
63
+ await eventually(async () => (await inspect()).phases[1]?.steps.some((step) => step.prompt === "right" && step.status === "completed") === true, 15_000);
64
+ const found = await inspect();
65
+ expect(found.run).toBe(run);
66
+ expect(found.origin).toMatchObject({ file, label: "inspection", requestedAt: expect.any(String), startedAt: expect.any(String) });
67
+ expect(found.origin.finishedAt).toBeUndefined();
68
+ expect(found.status.state).toBe("running");
69
+ expect(found.steps.map((step) => step.label)).toEqual(["before"]);
70
+ expect(found.phases.map(({ title, detail, state }) => ({ title, detail, state }))).toEqual([
71
+ { title: "sample", detail: undefined, state: "done" },
72
+ { title: "agents", detail: "two at once", state: "current" },
73
+ { title: "review", detail: undefined, state: "ahead" },
74
+ ]);
75
+ expect(found.status.phases?.map((phase) => phase.state)).toEqual(["done", "current", "ahead"]);
76
+ expect(found.status.currentPhases).toEqual(["agents"]);
77
+ expect(found.phases[0]?.steps.map((step) => [step.label, step.phase])).toEqual([["sample-0", "sample"], ["sample-1", "sample"]]);
78
+ expect(found.phases[2]?.steps).toEqual([]);
79
+
80
+ const started = (await host.records.read()).filter((row) => row.type === SessionStarted.name).map((row) => SessionStarted.schema.parse(row.data));
81
+ const sessionFor = (prompt: string) => {
82
+ const session = asked.get(prompt);
83
+ return session === undefined ? undefined : started.find((record) => record.session === sessionRef(session))?.id;
84
+ };
85
+ expect(sessionFor("left")).toBeDefined();
86
+ expect(sessionFor("right")).toBeDefined();
87
+ expect(sessionFor("left")).not.toBe(sessionFor("right"));
88
+ const steps = found.phases[1]?.steps ?? [];
89
+ expect(steps).toHaveLength(2);
90
+ expect(steps.find((step) => step.prompt === "left")).toMatchObject({ branch: "p1.0", action: "session.start.inspect-test", status: "running", session: sessionFor("left") });
91
+ expect(steps.find((step) => step.prompt === "right")).toMatchObject({ branch: "p1.1", action: "session.start.inspect-test", status: "completed", endedAt: expect.any(String), session: sessionFor("right") });
92
+
93
+ held.resolve();
94
+ await host.call(workflowWait, { run, timeoutMs: 15_000 });
95
+ const completed = await inspect();
96
+ expect(completed.status).toMatchObject({ state: "finished", outcome: { status: "done" } });
97
+ expect(completed.origin.finishedAt).toBeDefined();
98
+ // A run that finished with its result has done every phase it reached; the one it never reached is still ahead.
99
+ expect(completed.phases.map((phase) => phase.state)).toEqual(["done", "done", "ahead"]);
100
+ } finally {
101
+ held.resolve();
102
+ await host.close();
103
+ await home.cleanup();
104
+ }
105
+ }, 30_000);
106
+
107
+ test("inspect uses run ownership and reports a skipped step without a session", async () => {
108
+ const home = await tempHome();
109
+ const host = createNiwa({ home: home.path });
110
+ const fail = action("inspect.fail", {
111
+ description: "Fail an inspected step.",
112
+ input: z.object({}),
113
+ output: z.object({}),
114
+ recovery: "repeat",
115
+ effect: "write",
116
+ run: () => { throw new Error("expected failure"); },
117
+ });
118
+ host.use(plugin("inspect", (api) => api.action(fail)), workflow());
119
+ const clients: Array<Awaited<ReturnType<typeof connect>>> = [];
120
+ try {
121
+ await host.serve();
122
+ for (const name of ["starter", "other"]) {
123
+ const token = host.issueToken(principalOf("session", name), { grant: grant(["workflow.inspect", "workflow.start", "inspect.fail"]) });
124
+ clients.push(await connect({ home: home.path, id: `session:${name}`, token }));
125
+ }
126
+ const [starter, other] = clients;
127
+ if (starter === undefined || other === undefined) throw new Error("clients did not connect");
128
+ const file = join(home.path, "pause.js");
129
+ await writeFile(file, `export default workflow({ uses: ["inspect.fail"], phases: [{ title: "check" }] }, async () => {
130
+ phase("check");
131
+ await call("inspect.fail", {}, { label: "fails" });
132
+ });`);
133
+ const { run } = await starter.call(workflowStart, { file });
134
+ await host.call(workflowWait, { run, timeoutMs: 15_000 });
135
+ await expect(other.call(workflowInspect, { run })).rejects.toThrow("whoever made it");
136
+ const paused = await starter.call(workflowInspect, { run });
137
+ expect(paused.status.state).toBe("paused");
138
+ expect(paused.phases[0]).toMatchObject({ title: "check", state: "current" });
139
+ expect(paused.phases[0]?.steps).toMatchObject([{ key: "label:fails", label: "fails", action: "inspect.fail", status: "failed", endedAt: expect.any(String) }]);
140
+ expect(paused.phases[0]?.steps[0]?.session).toBeUndefined();
141
+
142
+ await host.call(workflowResume, { run, choice: "skip" });
143
+ await eventually(async () => (await host.call(workflowInspect, { run })).status.state === "finished", 15_000);
144
+ const finished = await host.call(workflowInspect, { run });
145
+ expect(finished.phases[0]?.steps).toMatchObject([{ key: "label:fails", status: "skipped", endedAt: expect.any(String) }]);
146
+ expect(finished.phases[0]?.state).toBe("done");
147
+ } finally {
148
+ for (const client of clients) await client.close();
149
+ await host.close();
150
+ await home.cleanup();
151
+ }
152
+ }, 30_000);
@@ -0,0 +1,148 @@
1
+ // The language of a script as the check types it: the globals the checker declares answer what the host answers, and
2
+ // they agree with the types of the script package where both name the same function.
3
+
4
+ import { afterEach, expect, test } from "bun:test";
5
+ import { mkdir, writeFile } from "node:fs/promises";
6
+ import { join } from "node:path";
7
+
8
+ import { plugin } from "@niwa-labs/plugin";
9
+ import { createNiwa, requests, tempHome, timers } from "@niwa-labs/testing";
10
+ import type { Host } from "@niwa-labs/testing";
11
+
12
+ import { workflow, workflowCheck } from "../src/index.ts";
13
+ import { Ping, Pong } from "./fixtures/ping-records.ts";
14
+
15
+ const homes: Array<{ cleanup(): Promise<void> }> = [];
16
+ const hosts: Host[] = [];
17
+
18
+ afterEach(async () => {
19
+ for (const host of hosts.splice(0)) await host.close().catch(() => {});
20
+ for (const home of homes.splice(0)) await home.cleanup();
21
+ }, 60_000);
22
+
23
+ const RECORDS = join(import.meta.dir, "fixtures", "ping-records.ts");
24
+
25
+ async function served(): Promise<{ host: Host; home: string }> {
26
+ const home = await tempHome();
27
+ homes.push(home);
28
+ const host = createNiwa({ home: home.path });
29
+ host.use(requests(), timers([]), plugin("ping", (api) => api.declare(Ping, Pong)), workflow());
30
+ await host.serve();
31
+ hosts.push(host);
32
+ return { host, home: home.path };
33
+ }
34
+
35
+ /** A line of a probe: the code, and whether the type checker must refuse it. */
36
+ type Probe = readonly [code: string, refused: boolean];
37
+
38
+ /** Check a script made of probes, and say which of them the checker refused beside which it should. */
39
+ async function refusedLines(probes: readonly Probe[], extra: readonly string[] = []): Promise<{ refused: number[]; expected: number[]; other: string[] }> {
40
+ const { host, home } = await served();
41
+ const head = [
42
+ `import { Ping, Pong, pingsTo } from ${JSON.stringify(RECORDS)};`,
43
+ 'import type { ScriptApi } from "@niwa-labs/script";',
44
+ 'declare const api: ScriptApi;',
45
+ ...extra,
46
+ 'export default workflow({ uses: ["niwa.records.read"], output: z.json() }, async () => {',
47
+ ];
48
+ // A `declare const` of a probe is a name given to the script: it stands outside the function.
49
+ const given = probes.flatMap(([code]) => (code.includes(" => ") && code.startsWith("declare") ? [code.slice(0, code.indexOf(" => "))] : []));
50
+ const body = probes.map(([code]) => ` { ${code.startsWith("declare") ? code.slice(code.indexOf(" => ") + 4) : code} }`);
51
+ const lines = [...head.slice(0, -1), ...given, head.at(-1) as string, ...body, " return null;", "});"];
52
+ const before = lines.indexOf(head.at(-1) as string) + 1;
53
+ await mkdir(home, { recursive: true });
54
+ const file = join(home, "language.ts");
55
+ await writeFile(file, lines.join("\n"));
56
+ if (process.env.KEEP !== undefined) await writeFile("/tmp/language-probe.ts", lines.join("\n"));
57
+ const errors = (await host.call(workflowCheck, { file })).errors;
58
+ return {
59
+ refused: [...new Set(errors.filter((error) => /^TS/.test(error.code)).map((error) => error.line - before))].sort((a, b) => a - b),
60
+ expected: probes.flatMap(([, refused], index) => (refused ? [index + 1] : [])),
61
+ other: errors.filter((error) => !/^TS/.test(error.code)).map((error) => `${error.code}: ${error.message}`),
62
+ };
63
+ }
64
+
65
+ test("the check types a wait whose options may hold a timeout as one that may time out", async () => {
66
+ const found = await refusedLines(
67
+ [
68
+ ["const a = { from: 1, timeout: 10 }; const got = await wait(Ping, a); const n: number = got.data.size;", true],
69
+ ["declare const b: { timeout?: string }; => const got = await wait(Ping, b); const n: number = got.at;", true],
70
+ ["declare const c: { timeout: number }; => const got = await wait(pingsTo('a'), c); const n: number = got.at;", true],
71
+ ['declare const d: { timeout: number }; => const got = await wait("ping.sent", d); const n: number = got.at;', true],
72
+ ['declare const e: { from: number; timeout: number }; => const got = await wait(Ping, e); if ("timedOut" in got) return null; const n: number = got.data.size;', false],
73
+ ["declare const f: { from: number }; => const got = await wait(Ping, f); const n: number = got.data.size;", false],
74
+ ['const got = await wait("ping.sent", { filter: { id: "x" } }); const n: number = got.data.size;', false],
75
+ ['const got = await wait(Ping, { timeout: "1m" }); if ("timedOut" in got) return null; const n: number = got.data.size;', false],
76
+ ],
77
+ );
78
+ expect(found).toEqual({ refused: found.expected, expected: found.expected, other: [] });
79
+ }, 60_000);
80
+
81
+ test("the check types a wait of a query of one type that names no stream, as a read of it is", async () => {
82
+ const found = await refusedLines([
83
+ ["const q = { types: [Ping] as const, stream: 's' }; await wait(q);", true],
84
+ ["const q = { types: [Ping] as const, from: 3 }; await wait(q);", false],
85
+ ["const q = { types: [Ping] as const, stream: 's' }; await read.records(q);", false],
86
+ ]);
87
+ expect(found).toEqual({ refused: found.expected, expected: found.expected, other: [] });
88
+ }, 60_000);
89
+
90
+ test("the check types a scope with a deadline as one that gives undefined past it, unless it throws", async () => {
91
+ const found = await refusedLines([
92
+ ['const n: number = await scope("a", { deadline: 1 }, async () => 1);', true],
93
+ ['const n: number = await scope("a", { deadline: 1, onDeadline: "skip" }, async () => 1);', true],
94
+ ['declare const o: { deadline?: number; onDeadline?: "skip" | "fail" }; => const n: number = await scope("a", o, async () => 1);', true],
95
+ ['const n: number = await moveOnAfter("a", 1, async () => 1);', true],
96
+ ['const n: number = await scope("a", { deadline: 1, onDeadline: "fail" }, async () => 1);', false],
97
+ ['const n: number = await scope("a", { concurrency: 2 }, async () => 1);', false],
98
+ ['const n: number = await scope("a", async () => 1);', false],
99
+ ['const n: number = await failAfter("a", 1, async () => 1);', false],
100
+ ['const n: number | undefined = await scope("a", { deadline: 1 }, async () => 1);', false],
101
+ ]);
102
+ expect(found).toEqual({ refused: found.expected, expected: found.expected, other: [] });
103
+ }, 60_000);
104
+
105
+ test("the check types a read of a list that may be empty with data of unknown shape, and holds a filter of references to their data", async () => {
106
+ const found = await refusedLines([
107
+ ["declare const refs1: (typeof Ping)[]; => const { records } = await read.records({ types: refs1 }); const n: number = records[0]!.data.size;", true],
108
+ ["const { records } = await read.records({ types: [] }); const n: number = records[0]!.data.size;", true],
109
+ ['declare const names1: Array<"ping.sent">; => const { records } = await read.records({ types: names1 }); const n: number = records[0]!.data.size;', true],
110
+ ['const { records } = await read.records({ types: [Ping, "other.*"] }); const n: number = records[0]!.data.size;', true],
111
+ ['await read.records({ types: [Ping], filter: { size: "no" } });', true],
112
+ ['await read.records({ types: ["ping.sent"], filter: { size: "no" } });', true],
113
+ ['await read.records({ types: [Ping], filter: { nothing: 1 } });', true],
114
+ ["const { records } = await read.records({ types: [Ping] }); const n: number = records[0]!.data.size;", false],
115
+ ['const { records } = await read.records({ types: ["ping.sent"] }); const n: number = records[0]!.data.size;', false],
116
+ ['const { records } = await read.records({ types: [Ping, Pong] }); for (const row of records) if ("size" in row.data) { const n: number = row.data.size; }', false],
117
+ ["declare const refs2: (typeof Ping)[]; => await read.records({ types: refs2, filter: { anything: 1 } }); await read.records({ types: ['a.*'], filter: { anything: 1 } }); await read.records();", false],
118
+ ]);
119
+ expect(found).toEqual({ refused: found.expected, expected: found.expected, other: [] });
120
+ }, 60_000);
121
+
122
+ test("the check types an agent call with a worktree as one that answers an object", async () => {
123
+ const found = await refusedLines([
124
+ ["await ask({ worktree: true, schema: z.string() }, 'go');", true],
125
+ ["declare const opts: { worktree: true; schema: ReturnType<typeof z.string> }; => await ask(opts, 'go');", true],
126
+ ["const done = await ask({ worktree: true, schema: z.object({ ok: z.boolean() }) }, 'go'); const ok: boolean = done.ok; const path: string | undefined = done.worktree?.path;", false],
127
+ ["const text = await ask({ schema: z.string() }, 'go'); const s: string = text;", false],
128
+ ["const answer = await ask({ worktree: { base: 'main' } }, 'go'); const a: string = answer.answer;", false],
129
+ ]);
130
+ expect(found).toEqual({ refused: found.expected, expected: found.expected, other: [] });
131
+ }, 60_000);
132
+
133
+ test("the globals of the check and the types of the script package are one language where they name the same function", async () => {
134
+ const same = ["scope", "moveOnAfter", "failAfter", "parallel", "stream", "race", "pipeline", "sleep", "now", "random", "record", "emit", "log"];
135
+ const found = await refusedLines(
136
+ [
137
+ // Each pair is one type, not types that take each other: a parameter that is looser on one side is a drift.
138
+ ...same.map((name): Probe => [`const ${name}Same: Same<typeof ${name}, ScriptApi["${name}"]> = true;`, false]),
139
+ // The kinds of `ask` hold conditional types of their own names: each is one function of the other side's.
140
+ ['const askOf: ScriptApi["ask"] = ask; const askBack: typeof ask = api.ask; const choice: Same<Parameters<typeof ask.choice>[0], Parameters<ScriptApi["ask"]["choice"]>[0]> = true;', false],
141
+ ["const phaseBack: typeof phase = api.phase;", false],
142
+ // The check itself: a pair that differs is refused.
143
+ ['const differs: Same<typeof sleep, (duration: number) => Promise<void>> = true;', true],
144
+ ],
145
+ ["type Same<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;"],
146
+ );
147
+ expect(found).toEqual({ refused: found.expected, expected: found.expected, other: [] });
148
+ }, 60_000);
@@ -0,0 +1,93 @@
1
+ // The manifest of a registered version says what the version is: its entry, the hash of every file of its
2
+ // source closure, the data files it reads, the packages it imports by name with their versions, and the
3
+ // version of the script ABI it was registered for. A start and a run read the copy through it: a copy that
4
+ // is not what its manifest says, or one made for another ABI, does not run.
5
+
6
+ import { afterEach, expect, test } from "bun:test";
7
+ import { createHash } from "node:crypto";
8
+ import { readFileSync, realpathSync } from "node:fs";
9
+ import { mkdir, symlink, writeFile } from "node:fs/promises";
10
+ import { join } from "node:path";
11
+
12
+ import { SCRIPT_ABI } from "@niwa-labs/script";
13
+ import { createNiwa, requests, tempHome, timers } from "@niwa-labs/testing";
14
+ import type { Host } from "@niwa-labs/testing";
15
+ import { workflow, workflowRegister, workflowStart, workflowWait } from "../src/index.ts";
16
+
17
+ const homes: Array<{ cleanup(): Promise<void> }> = [];
18
+ const hosts: Host[] = [];
19
+
20
+ afterEach(async () => {
21
+ for (const host of hosts.splice(0)) await host.close().catch(() => {});
22
+ for (const home of homes.splice(0)) await home.cleanup();
23
+ }, 60_000);
24
+
25
+ const sha = (path: string): string => createHash("sha256").update(readFileSync(path)).digest("hex");
26
+
27
+ async function registered(): Promise<{ host: Host; home: string; id: string; version: string; dir: string }> {
28
+ const temp = await tempHome();
29
+ homes.push(temp);
30
+ const host = createNiwa({ home: temp.path });
31
+ host.use(requests(), timers([]), workflow());
32
+ await host.serve();
33
+ hosts.push(host);
34
+ const home = realpathSync(temp.path);
35
+ const src = join(home, "src");
36
+ await mkdir(join(src, "lib"), { recursive: true });
37
+ await symlink(realpathSync(join(import.meta.dir, "..", "node_modules")), join(src, "node_modules"), "dir");
38
+ await writeFile(join(src, "lib", "label.ts"), 'export const label = "one";\n');
39
+ await writeFile(join(src, "lib", "table.json"), '{ "n": 2 }\n');
40
+ await writeFile(
41
+ join(src, "flow.ts"),
42
+ [
43
+ 'import { z as zod } from "zod";',
44
+ 'import { label } from "./lib/label.ts";',
45
+ 'import table from "./lib/table.json";',
46
+ 'export default workflow({ description: "Answer the label", output: z.string() }, async () => zod.string().parse(`${label}:${String(table.n)}`));',
47
+ ].join("\n"),
48
+ );
49
+ const { id, version } = await host.call(workflowRegister, { file: join(src, "flow.ts") });
50
+ return { host, home, id, version, dir: join(home, "workflows", id, version) };
51
+ }
52
+
53
+ const run = async (host: Host, id: string): Promise<unknown> => {
54
+ const { run: started } = await host.call(workflowStart, { id });
55
+ return (await host.call(workflowWait, { run: started, timeoutMs: 20_000 })).outcome;
56
+ };
57
+
58
+ test("the manifest names the files with their hashes, the data files, the packages and the script ABI", async () => {
59
+ const { host, home, id, version, dir } = await registered();
60
+ const manifest = JSON.parse(readFileSync(join(home, "workflows", id, `${version}.json`), "utf8"));
61
+ const zod = JSON.parse(readFileSync(join(import.meta.dir, "..", "node_modules", "zod", "package.json"), "utf8")) as { version: string };
62
+ expect(manifest).toEqual({
63
+ entry: "flow.ts",
64
+ from: join(home, "src", "flow.ts"),
65
+ abi: SCRIPT_ABI,
66
+ files: { "flow.ts": sha(join(dir, "flow.ts")), "lib/label.ts": sha(join(dir, "lib", "label.ts")) },
67
+ data: { "lib/table.json": sha(join(dir, "lib", "table.json")) },
68
+ imports: { zod: zod.version },
69
+ });
70
+ expect(await run(host, id)).toEqual({ status: "done", result: "one:2" });
71
+ }, 60_000);
72
+
73
+ test("a copy that is not what its manifest says does not start", async () => {
74
+ const { host, id, dir } = await registered();
75
+ await writeFile(join(dir, "lib", "table.json"), '{ "n": 3 }\n');
76
+ await expect(host.call(workflowStart, { id })).rejects.toThrow('"lib/table.json" is not the file');
77
+ }, 60_000);
78
+
79
+ test("a version registered for another script ABI does not start", async () => {
80
+ const { host, home, id, version } = await registered();
81
+ const path = join(home, "workflows", id, `${version}.json`);
82
+ await writeFile(path, JSON.stringify({ ...JSON.parse(readFileSync(path, "utf8")), abi: SCRIPT_ABI + 1 }));
83
+ await expect(host.call(workflowStart, { id })).rejects.toThrow(`script ABI ${String(SCRIPT_ABI + 1)}`);
84
+ }, 60_000);
85
+
86
+ test("a manifest that names only the entry is completed from the copy, which is its version", async () => {
87
+ const { host, home, id, version } = await registered();
88
+ const path = join(home, "workflows", id, `${version}.json`);
89
+ const full = JSON.parse(readFileSync(path, "utf8"));
90
+ await writeFile(path, JSON.stringify({ entry: full.entry, from: full.from }));
91
+ expect(await run(host, id)).toEqual({ status: "done", result: "one:2" });
92
+ expect(JSON.parse(readFileSync(path, "utf8"))).toEqual(full);
93
+ }, 60_000);