@niwa-labs/flow 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.
@@ -0,0 +1,146 @@
1
+ // What the flow tests share: a host with the workflow module and stub agents, and a way to run a
2
+ // script that imports the helpers as a package, the way an owner's script does.
3
+
4
+ import { realpathSync } from "node:fs";
5
+ import { mkdir, symlink, writeFile } from "node:fs/promises";
6
+ import { join } from "node:path";
7
+
8
+ import { z } from "zod";
9
+
10
+ import { createNiwa, connect, eventually, ownerTokenOf, plugin, requests, stubAction, tempHome, timers, workflow } from "@niwa-labs/testing";
11
+ import type { Host, TestClock } from "@niwa-labs/testing";
12
+
13
+ /** What an agent call reaches a stub with. */
14
+ export interface AgentCall {
15
+ prompt: string;
16
+ harness?: string;
17
+ }
18
+
19
+ /** A stub agent: its answer to a call. Throwing fails the call. */
20
+ export type Reply = (call: AgentCall) => unknown;
21
+
22
+ /** What a run ended as. */
23
+ export interface Ended {
24
+ run: string;
25
+ state: string;
26
+ outcome?: { status: string; result?: unknown; error?: string; name?: string };
27
+ requests: unknown[];
28
+ }
29
+
30
+ export interface FlowHost {
31
+ host: Host;
32
+ home: string;
33
+ /** The calls each stub agent got, by harness. */
34
+ calls: Record<string, AgentCall[]>;
35
+ /** Run a script once and wait for it to end; `packages` are linked beside it by name. */
36
+ run(source: string, args?: unknown): Promise<Ended>;
37
+ /** Start a script once and answer with its run, without waiting. */
38
+ start(source: string, args?: unknown): Promise<string>;
39
+ wait(run: string): Promise<Ended>;
40
+ /** Answer the owner's open question (the first one) with an option id. */
41
+ answer(id: string): Promise<void>;
42
+ /** Cancel the owner's open question. */
43
+ cancelAsk(): Promise<void>;
44
+ close(): Promise<void>;
45
+ }
46
+
47
+ const PACKAGES = join(import.meta.dir, "..", "..");
48
+
49
+ /** A plugin a test adds to the host. */
50
+ export type Extra = Parameters<Host["use"]>[number];
51
+
52
+ /** What a test host has besides the stub agents: the packages a script finds by name, and more plugins. */
53
+ export interface FlowHostOptions {
54
+ /** The clock of the host, when the test moves it by hand. */
55
+ clock?: TestClock;
56
+ packages?: readonly string[];
57
+ plugins?: (home: string) => Extra[];
58
+ }
59
+
60
+ /** A host with the workflow module and an agent per harness of `agents`. */
61
+ export async function flowHost(agents: Record<string, Reply>, opts: FlowHostOptions = {}): Promise<FlowHost> {
62
+ const packages = opts.packages ?? ["flow"];
63
+ const temp = await tempHome();
64
+ const home = realpathSync(temp.path);
65
+ const calls: Record<string, AgentCall[]> = {};
66
+ const actions = Object.entries(agents).map(([harness, reply]) => {
67
+ calls[harness] = [];
68
+ const seen = calls[harness] as AgentCall[];
69
+ return [
70
+ harness,
71
+ stubAction(`session.start.${harness}`, {
72
+ home,
73
+ input: z.looseObject({ prompt: z.string(), harness: z.string().optional() }),
74
+ output: z.any(),
75
+ recovery: "repeat",
76
+ result: (input) => {
77
+ const call = { prompt: input.prompt, ...(input.harness === undefined ? {} : { harness: input.harness }) };
78
+ seen.push(call);
79
+ return reply(call);
80
+ },
81
+ }),
82
+ ] as const;
83
+ });
84
+ const host = createNiwa({ home, ...(opts.clock === undefined ? {} : { clock: opts.clock }) });
85
+ host.use(
86
+ requests(),
87
+ timers([]),
88
+ plugin("stub-agents", (api) => {
89
+ for (const [, one] of actions) api.action(one);
90
+ }),
91
+ workflow({ agents: Object.fromEntries(actions) }),
92
+ ...(opts.plugins?.(home) ?? []),
93
+ );
94
+ await host.serve();
95
+
96
+ const src = join(home, "src");
97
+ await mkdir(join(src, "node_modules", "@niwa-labs"), { recursive: true });
98
+ for (const name of packages) await symlink(realpathSync(join(PACKAGES, name)), join(src, "node_modules", "@niwa-labs", name), "dir");
99
+ let scripts = 0;
100
+ const owner = await connect({ home, id: "owner:flow", token: ownerTokenOf(home) });
101
+
102
+ const start = async (source: string, args?: unknown): Promise<string> => {
103
+ scripts += 1;
104
+ const file = join(src, `script-${String(scripts)}.ts`);
105
+ await writeFile(file, source);
106
+ const started = (await host.call("workflow.start" as never, { file, ...(args === undefined ? {} : { args }) } as never)) as { run: string };
107
+ return started.run;
108
+ };
109
+ const wait = async (run: string): Promise<Ended> => (await host.call("workflow.wait" as never, { run, timeoutMs: 30_000 } as never)) as Ended;
110
+ const openId = async (): Promise<string> => {
111
+ let id: string | undefined;
112
+ await eventually(async () => {
113
+ const open = (await owner.call("request.open" as never, {} as never)) as { requests?: Array<{ id: string }>; items?: Array<{ id: string }> };
114
+ id = (open.requests ?? open.items ?? [])[0]?.id;
115
+ return id !== undefined;
116
+ }, 15_000, "the owner should be asked");
117
+ return id as string;
118
+ };
119
+ return {
120
+ host,
121
+ home,
122
+ calls,
123
+ start,
124
+ wait,
125
+ run: async (source, args) => wait(await start(source, args)),
126
+ answer: async (choice) => {
127
+ const id = await openId();
128
+ await owner.call("request.answer" as never, { id, answer: { ids: [choice] } } as never);
129
+ },
130
+ cancelAsk: async () => {
131
+ const id = await openId();
132
+ await owner.call("request.cancel" as never, { id } as never);
133
+ },
134
+ close: async () => {
135
+ await owner.close?.();
136
+ await host.close().catch(() => {});
137
+ await temp.cleanup();
138
+ },
139
+ };
140
+ }
141
+
142
+ /** The result of a run that finished, or a failure that says how it ended. */
143
+ export function resultOf(ended: Ended): unknown {
144
+ if (ended.state !== "finished" || ended.outcome?.status !== "done") throw new Error(`the run did not finish: ${JSON.stringify(ended).slice(0, 2000)}`);
145
+ return ended.outcome.result;
146
+ }
@@ -0,0 +1,151 @@
1
+ // Waiting in a real script: a gate of the owner never throws for a decline or a cancel and opens
2
+ // only on a choice; settle reads first, so what is settled already is not waited for, and wakes on
3
+ // a record after the position it read.
4
+
5
+ import { afterEach, expect, test } from "bun:test";
6
+
7
+ import { z } from "zod";
8
+
9
+ import { counter, eventually, gate, plugin, stub, stubAction, testClock } from "@niwa-labs/testing";
10
+ import type { TestClock } from "@niwa-labs/testing";
11
+
12
+ import { flowHost, resultOf } from "./support.ts";
13
+ import type { FlowHost } from "./support.ts";
14
+
15
+ const hosts: FlowHost[] = [];
16
+ afterEach(async () => {
17
+ for (const one of hosts.splice(0)) await one.close();
18
+ }, 30_000);
19
+
20
+ const GATE = `
21
+ import { humanGate } from "@niwa-labs/flow";
22
+ export default workflow({ output: z.json() }, async (): Promise<any> =>
23
+ humanGate("ship", { summary: "Ship the release?", options: ["ship", "hold"], recommend: "hold", risk: "a user sees it" }));`;
24
+
25
+ test("a gate of the owner gives the choice, a decline, or a cancel as an outcome", async () => {
26
+ const flow = await flowHost({});
27
+ hosts.push(flow);
28
+
29
+ const chosen = await flow.start(GATE);
30
+ await flow.answer("ship");
31
+ expect(resultOf(await flow.wait(chosen))).toEqual({ outcome: "chosen", choice: "ship" });
32
+
33
+ const declined = await flow.start(GATE);
34
+ await flow.answer("decline");
35
+ expect(resultOf(await flow.wait(declined))).toEqual({ outcome: "declined" });
36
+
37
+ const cancelled = await flow.start(GATE);
38
+ await flow.cancelAsk();
39
+ expect(resultOf(await flow.wait(cancelled))).toEqual({ outcome: "cancelled" });
40
+ }, 60_000);
41
+
42
+ /** A host whose `probe.read` counts its calls, beside the stub plugin whose `stub.finish` writes `stub.finished`. */
43
+ async function settleHost(packages?: readonly string[], clock?: TestClock): Promise<FlowHost> {
44
+ const flow = await flowHost({}, {
45
+ ...(clock === undefined ? {} : { clock }),
46
+ ...(packages === undefined ? {} : { packages }),
47
+ plugins: (home) => [
48
+ stub(home),
49
+ plugin("probe", (api) =>
50
+ api.action(
51
+ stubAction("probe.read", { home, input: z.object({}), output: z.object({ n: z.number() }), recovery: "repeat", effect: "read", result: () => ({ n: counter(home, "probe.read").count() }) }),
52
+ ),
53
+ ),
54
+ plugin("slow", (api) => {
55
+ for (const gated of ["slow.read", "block.read"]) {
56
+ api.action(stubAction(gated, { home, input: z.object({}), output: z.object({ n: z.number() }), recovery: "repeat", effect: "read", gate: gated, result: () => ({ n: 0 }) }));
57
+ }
58
+ }
59
+ ),
60
+ ],
61
+ });
62
+ hosts.push(flow);
63
+ return flow;
64
+ }
65
+
66
+ const SETTLE = (until: number) => `
67
+ import { settle } from "@niwa-labs/flow";
68
+ export default workflow({ output: z.json() }, async (): Promise<any> =>
69
+ settle("finished", {
70
+ on: { types: ["stub.finished"] },
71
+ every: "1h",
72
+ read: async () => (await call("probe.read", {})).n,
73
+ done: (n) => n >= ${String(until)},
74
+ }));`;
75
+
76
+ test("settle does not wait when the facts are settled already", async () => {
77
+ const flow = await settleHost();
78
+ expect(resultOf(await flow.run(SETTLE(1)))).toEqual({ facts: 1, outcome: "done" });
79
+ }, 30_000);
80
+
81
+ test("settle wakes on a record written after the position it read, and reads again", async () => {
82
+ const flow = await settleHost();
83
+ const run = await flow.start(SETTLE(2));
84
+ await eventually(() => counter(flow.home, "probe.read").count() === 1, 15_000, "the facts should be read once");
85
+ await flow.host.call("stub.finish" as never, { id: "t-1" } as never);
86
+ expect(resultOf(await flow.wait(run))).toEqual({ facts: 2, outcome: "done" });
87
+ }, 30_000);
88
+
89
+ const SETTLE_BY_REFERENCE = `
90
+ import { record } from "@niwa-labs/core";
91
+ import { settle } from "@niwa-labs/flow";
92
+ const StubFinished = record("stub.finished", z.object({ id: z.string() }));
93
+ export default workflow({ output: z.json() }, async (): Promise<any> =>
94
+ settle("finished", {
95
+ on: { types: [StubFinished], filter: { id: "t-1" } },
96
+ every: "1h",
97
+ read: async () => (await call("probe.read", {})).n,
98
+ done: (n) => n >= 2,
99
+ }));`;
100
+
101
+ test("settle waits for a type named by reference as it waits for one named as text", async () => {
102
+ const flow = await settleHost(["flow", "core"]);
103
+ const run = await flow.start(SETTLE_BY_REFERENCE);
104
+ await eventually(() => counter(flow.home, "probe.read").count() === 1, 15_000, "the facts should be read once");
105
+ await flow.host.call("stub.finish" as never, { id: "t-2" } as never);
106
+ await flow.host.call("stub.finish" as never, { id: "t-1" } as never);
107
+ expect(resultOf(await flow.wait(run))).toEqual({ facts: 2, outcome: "done" });
108
+ }, 30_000);
109
+
110
+ const SETTLE_NAMED_READ = `
111
+ import { settle } from "@niwa-labs/flow";
112
+ export default workflow({ output: z.json() }, async (): Promise<any> =>
113
+ settle("finished", {
114
+ on: { types: ["stub.finished"] },
115
+ every: "1h",
116
+ read: async () => scope("read", undefined, async () => (await call("probe.read", {})).n),
117
+ done: (n) => n >= 2,
118
+ }));`;
119
+
120
+ test("settle reads again with a helper that opens a named scope in its read", async () => {
121
+ const flow = await settleHost();
122
+ const run = await flow.start(SETTLE_NAMED_READ);
123
+ await eventually(() => counter(flow.home, "probe.read").count() === 1, 15_000, "the facts should be read once");
124
+ await flow.host.call("stub.finish" as never, { id: "t-1" } as never);
125
+ expect(resultOf(await flow.wait(run))).toEqual({ facts: 2, outcome: "done" });
126
+ }, 30_000);
127
+
128
+ test("settle past its deadline gives the facts it read, and the first read is not cut short by it", async () => {
129
+ const clock = testClock();
130
+ const flow = await settleHost(undefined, clock);
131
+ const run = await flow.start(`
132
+ import { settle } from "@niwa-labs/flow";
133
+ export default workflow({ output: z.json() }, async (): Promise<any> => {
134
+ let reads = 0;
135
+ return settle("finished", {
136
+ on: { types: ["stub.finished"] },
137
+ every: "1h",
138
+ deadline: "1m",
139
+ read: async () => { reads += 1; return (await call(reads === 1 ? "slow.read" : "block.read", {})).n; },
140
+ done: (n) => n >= 1,
141
+ });
142
+ });`);
143
+ await eventually(() => counter(flow.home, "slow.read").count() === 1, 15_000, "the first read should begin");
144
+ await clock.advance(5 * 60_000);
145
+ gate(flow.home, "slow.read").open();
146
+ await eventually(async () => ((await flow.host.call("workflow.wait" as never, { run, timeoutMs: 200 } as never)) as { waiting?: string }).waiting === "wait stub.finished", 15_000, "the settle should wait for the record");
147
+ await flow.host.call("stub.finish" as never, { id: "t-1" } as never);
148
+ await eventually(() => counter(flow.home, "block.read").count() === 1, 15_000, "the second read should begin");
149
+ await clock.advance(2 * 60_000);
150
+ expect(resultOf(await flow.wait(run))).toEqual({ facts: 0, outcome: "timed-out" });
151
+ }, 60_000);
package/tsconfig.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "extends": "../../tsconfig.base.json",
3
+ "include": [
4
+ "src"
5
+ ]
6
+ }