@niwa-labs/sessions 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,168 @@
1
+ // The signs of life of a session across a restart of the host: after a restart a last "turn
2
+ // started" does not prove a turn is running now; the state is then "unknown".
3
+ //
4
+ // The host runs out of process, so it can really be killed:
5
+ //
6
+ // 1. a session starts, the fake reports a turn that starts and ends, and the journal holds both
7
+ // signs of life;
8
+ // 2. the fake reports a turn that starts, the host is killed with SIGKILL while the turn is
9
+ // open, and the host is started again on the same home: the state read through the public
10
+ // API is "unknown", not "running";
11
+ // 3. the fake then reports that the turn ended, and the state becomes "idle".
12
+ //
13
+ // Only the public API is used: "@niwa-labs/core", the sessions entry and "@niwa-labs/testing".
14
+
15
+ import { expect, test } from "bun:test";
16
+
17
+ import { appendFileSync } from "node:fs";
18
+ import { join } from "node:path";
19
+
20
+ import { z } from "zod";
21
+
22
+ import { actionName, seq } from "@niwa-labs/core";
23
+ import { connectAsOwner, eventually, spawnHost, tempHome } from "@niwa-labs/testing";
24
+ import type { NiwaApi } from "@niwa-labs/testing";
25
+
26
+ import { SessionStarted, SessionTurnEnded, SessionTurnStarted } from "../src/index.ts";
27
+ import { HARNESS, INSTRUCTIONS, SESSION } from "./fixtures/restart-host.ts";
28
+
29
+ /** The host program of the test. */
30
+ const HOST_SCRIPT = join(import.meta.dir, "fixtures/restart-host.ts");
31
+
32
+ /** What the public API says about one session. */
33
+ const SessionEntry = z.object({
34
+ ref: z.string(),
35
+ state: z.enum(["running", "idle", "ended", "unknown"]),
36
+ });
37
+
38
+ /** The answer of "session.list". */
39
+ const SessionList = z.object({
40
+ sessions: z.array(SessionEntry),
41
+ unreadable: z.array(z.unknown()),
42
+ });
43
+
44
+ /** The answer of "session.running". */
45
+ const SessionRunning = z.object({
46
+ running: z.array(z.string()),
47
+ unknown: z.array(z.string()),
48
+ });
49
+
50
+ /** The answer of "session.start". */
51
+ const Started = z.object({ session: z.string(), ref: z.string() });
52
+
53
+ /** Call an action by its name, through the public API. */
54
+ function call(client: NiwaApi, name: string, input: unknown): Promise<unknown> {
55
+ return client.call(actionName(name), input);
56
+ }
57
+
58
+ /** The types of the signs of life the journal holds, in the order they were written. */
59
+ async function lifeTypes(client: NiwaApi): Promise<string[]> {
60
+ const records = await client.records.read({ types: [SessionStarted, SessionTurnStarted, SessionTurnEnded] });
61
+ return records.map((record) => String(record.type));
62
+ }
63
+
64
+ /** How many of the signs of life of one type the journal holds. */
65
+ async function countOf(client: NiwaApi, type: string): Promise<number> {
66
+ return (await lifeTypes(client)).filter((entry) => entry === type).length;
67
+ }
68
+
69
+ /** The state of the one session, read through "session.list". */
70
+ async function stateOf(client: NiwaApi): Promise<string> {
71
+ const listed = SessionList.parse(await call(client, "session.list", { harness: HARNESS }));
72
+ expect(listed.sessions).toHaveLength(1);
73
+ return listed.sessions[0]?.state ?? "missing";
74
+ }
75
+
76
+ /** Wait until the journal holds as many signs of life of one type as it should. */
77
+ async function untilCounted(client: NiwaApi, type: string, count: number, what: string): Promise<void> {
78
+ await eventually(
79
+ async () => (await countOf(client, type)) === count,
80
+ 10_000,
81
+ `${what} (${String(count)} of "${type}")`,
82
+ );
83
+ }
84
+
85
+ test("a turn left open by a dead host reads as unknown, and the turn that ends it reads as idle", async () => {
86
+ const home = await tempHome();
87
+ const instructions = join(home.path, INSTRUCTIONS);
88
+ let host = spawnHost(HOST_SCRIPT, home.path);
89
+ let client: NiwaApi | undefined;
90
+
91
+ try {
92
+ await host.ready();
93
+ client = await connectAsOwner(home.path);
94
+ const first = client;
95
+
96
+ // 1. The session starts, the fake reports a turn that starts and ends, and the journal
97
+ // holds both signs of life.
98
+ const started = Started.parse(await call(first, "session.start", { harness: HARNESS, prompt: "go" }));
99
+ expect(started.ref).toBe(SESSION);
100
+
101
+ appendFileSync(instructions, "turn-started 1\n");
102
+ await untilCounted(first, "session.turn-started", 1, "the turn did not start");
103
+ // The turn is open in this very process: it is running now.
104
+ expect(await stateOf(first)).toBe("running");
105
+
106
+ appendFileSync(instructions, "turn-ended 1\n");
107
+ await untilCounted(first, "session.turn-ended", 1, "the turn did not end");
108
+ expect(await lifeTypes(first)).toEqual([
109
+ "session.started",
110
+ "session.turn-started",
111
+ "session.turn-ended",
112
+ ]);
113
+ // The turn is closed: the session is idle.
114
+ expect(await stateOf(first)).toBe("idle");
115
+
116
+ // 2. The fake reports a turn that starts, and the host is killed while the turn is open.
117
+ appendFileSync(instructions, "turn-started 2\n");
118
+ await untilCounted(first, "session.turn-started", 2, "the second turn did not start");
119
+ await host.kill();
120
+
121
+ // The host comes back on the same home, and the fake reports nothing yet.
122
+ host = spawnHost(HOST_SCRIPT, home.path);
123
+ await host.ready();
124
+ await client.close();
125
+ client = await connectAsOwner(home.path);
126
+ const second = client;
127
+
128
+ // The open turn proves nothing about now: the state is "unknown", never "running".
129
+ expect(await stateOf(second)).toBe("unknown");
130
+ const running = SessionRunning.parse(await call(second, "session.running", { harness: HARNESS }));
131
+ expect(running.running).toEqual([]);
132
+ expect(running.unknown.map((line) => line.split(" ")[0])).toEqual([started.session]);
133
+
134
+ // 3. The fake reports that the turn ended: the session is idle again.
135
+ await call(second, "session.resume", { session: SESSION });
136
+ appendFileSync(instructions, "turn-ended 2\n");
137
+ await untilCounted(second, "session.turn-ended", 2, "the second turn did not end");
138
+ expect(await stateOf(second)).toBe("idle");
139
+ } finally {
140
+ await client?.close().catch(() => undefined);
141
+ await host.stop();
142
+ await home.cleanup();
143
+ }
144
+ });
145
+
146
+ test("a turn that ends is journaled with how it ended: what the harness said, completed when it said nothing", async () => {
147
+ const home = await tempHome();
148
+ const instructions = join(home.path, INSTRUCTIONS);
149
+ const host = spawnHost(HOST_SCRIPT, home.path);
150
+ let client: NiwaApi | undefined;
151
+ try {
152
+ await host.ready();
153
+ client = await connectAsOwner(home.path);
154
+ const open = client;
155
+ await call(open, "session.start", { harness: HARNESS, prompt: "go" });
156
+ const endings = ["failed", "unknown", "completed", ""];
157
+ for (const [index, ending] of endings.entries()) {
158
+ appendFileSync(instructions, `turn-started ${String(index + 1)}\nturn-ended ${String(index + 1)} ${ending}\n`);
159
+ }
160
+ await untilCounted(open, "session.turn-ended", endings.length, "the turns did not end");
161
+ const ended = await open.records.read({ types: [SessionTurnEnded] });
162
+ expect(ended.map((record) => (record.data as { how?: string }).how)).toEqual(["failed", "unknown", "completed", "completed"]);
163
+ } finally {
164
+ await client?.close().catch(() => undefined);
165
+ await host.stop();
166
+ await home.cleanup();
167
+ }
168
+ });
@@ -0,0 +1,341 @@
1
+ // Reverse requests through the sessions module.
2
+ //
3
+ // A fake control side keeps the handler it was given at the start and calls it the way an adapter
4
+ // does: a question and the raw request of its harness. The tests look at what the starter is asked,
5
+ // what is answered without asking, and what the journal says.
6
+
7
+ import { afterEach, expect, test } from "bun:test";
8
+
9
+ import { OptionIdSchema, owner, seq } from "@niwa-labs/core";
10
+ import type { ActionName, Answer, Question, StoredRecord } from "@niwa-labs/core";
11
+ import { harnessId, harnessKind, machineId, sessionId } from "@niwa-labs/harness";
12
+ import type {
13
+ AskAnswer,
14
+ AskOptions,
15
+ DeliveryReceipt,
16
+ Harness,
17
+ LifeEvent,
18
+ ReverseHandler,
19
+ SessionControl,
20
+ SessionId,
21
+ SessionState,
22
+ StartedSession,
23
+ StartOptions,
24
+ } from "@niwa-labs/harness";
25
+ import { createNiwa, eventually, requests, tempHome } from "@niwa-labs/testing";
26
+ import type { Host } from "@niwa-labs/testing";
27
+
28
+ import { sessions } from "../src/index.ts";
29
+
30
+ const HARNESS = "fake-harness";
31
+
32
+ const id = (text: string) => OptionIdSchema.parse(text);
33
+ /** An answer that picks options. */
34
+ const picks = (...texts: string[]): Answer => ({ ids: texts.map(id) });
35
+
36
+ /** A control side that names a session and keeps the handler of its reverse requests. */
37
+ class ReverseControl implements SessionControl {
38
+ handler: ReverseHandler | undefined;
39
+ id: SessionId | undefined;
40
+ /** The servers the session was started with. */
41
+ servers: StartOptions["servers"];
42
+
43
+ async start(options: StartOptions): Promise<StartedSession> {
44
+ this.handler = options.reverse;
45
+ this.servers = options.servers;
46
+ this.id = sessionId(harnessId(HARNESS), "session-1");
47
+ return { session: this.id };
48
+ }
49
+
50
+ async resume(): Promise<void> {}
51
+
52
+ async send(): Promise<DeliveryReceipt> {
53
+ return { status: "started", turn: 1 };
54
+ }
55
+
56
+ async interrupt(): Promise<void> {}
57
+
58
+ async ask<T>(id: SessionId, _options: AskOptions<T>): Promise<AskAnswer<T>> {
59
+ throw new Error(`not asked: ${id.native}`);
60
+ }
61
+
62
+ async *life(): AsyncIterable<LifeEvent> {
63
+ await new Promise<void>(() => {});
64
+ }
65
+
66
+ async state(): Promise<SessionState> {
67
+ return "idle";
68
+ }
69
+
70
+ /** What an adapter does: hand the handler a question and the raw request, and wait for the answer. */
71
+ async reverse(question: Question, signal: AbortSignal = new AbortController().signal): Promise<Answer> {
72
+ if (this.handler === undefined || this.id === undefined) throw new Error("no session was started");
73
+ return await this.handler(this.id, { question, raw: { method: "fake/request", params: { question } }, signal });
74
+ }
75
+ }
76
+
77
+ const installation: Harness = {
78
+ id: harnessId(HARNESS),
79
+ kind: harnessKind("fake-kind"),
80
+ machine: machineId("machine-1"),
81
+ home: "/tmp/fake-home",
82
+ sides: { control: { start: true, resume: true, send: true, interrupt: true, ask: true, structuredOutput: false, launch: { model: false, effort: [], modes: [] }, tools: { niwaOnly: true, allow: true } } },
83
+ };
84
+
85
+ const open: Array<() => Promise<void>> = [];
86
+ afterEach(async () => {
87
+ for (const close of open.splice(0)) await close();
88
+ });
89
+
90
+ async function serve(
91
+ control: ReverseControl,
92
+ existing?: string,
93
+ niwaMcp?: { command: string; args: readonly string[] },
94
+ ): Promise<{ niwa: Host; records: StoredRecord[]; home: string }> {
95
+ const fresh = existing === undefined ? await tempHome() : undefined;
96
+ const homePath = existing ?? fresh?.path ?? "";
97
+ const niwa = createNiwa({ home: homePath });
98
+ niwa.use(requests({ bind: () => owner }));
99
+ niwa.use(sessions({ harnesses: [{ instance: installation, control }], ...(niwaMcp === undefined ? {} : { niwaMcp }) }));
100
+ await niwa.serve();
101
+ const records: StoredRecord[] = [];
102
+ void (async () => {
103
+ for await (const record of niwa.records.since()) records.push(record);
104
+ })();
105
+ open.push(async () => {
106
+ await niwa.close();
107
+ await fresh?.cleanup();
108
+ });
109
+ return { niwa, records, home: homePath };
110
+ }
111
+
112
+ const call = <O>(niwa: Host, name: string, input: unknown): Promise<O> => niwa.call(name as ActionName, input) as Promise<O>;
113
+
114
+ interface OpenRequest {
115
+ id: string;
116
+ question: string;
117
+ to: { kind: string };
118
+ input: Question;
119
+ answer?: Record<string, unknown>;
120
+ }
121
+
122
+ async function openRequests(niwa: Host): Promise<OpenRequest[]> {
123
+ const { requests: all } = await call<{ requests: OpenRequest[] }>(niwa, "request.open", {});
124
+ return all.filter((entry) => entry.question === "session.reverse");
125
+ }
126
+
127
+ async function nextRequest(niwa: Host): Promise<OpenRequest> {
128
+ let found: OpenRequest | undefined;
129
+ await eventually(async () => {
130
+ found = (await openRequests(niwa))[0];
131
+ return found !== undefined;
132
+ });
133
+ if (found === undefined) throw new Error("no request");
134
+ return found;
135
+ }
136
+
137
+ const permission = (target: string, tool?: string): Question => ({
138
+ kind: "permission",
139
+ title: `run ${target}`,
140
+ options: [
141
+ { id: id("allow"), label: "Allow", flavor: "allow_once" },
142
+ { id: id("reject"), label: "Reject", flavor: "reject_once" },
143
+ ],
144
+ subject: { ...(tool === undefined ? {} : { tool }), kind: "execute", target },
145
+ });
146
+
147
+ const typesOf = (records: StoredRecord[]): string[] => records.map((record) => record.type).filter((type) => type.startsWith("session.reverse"));
148
+
149
+ async function started(niwa: Host, visible?: { actions: string[] }): Promise<void> {
150
+ await call(niwa, "session.start", { harness: HARNESS, prompt: "go", ...(visible === undefined ? {} : { visible }) });
151
+ }
152
+
153
+ test("a permission the grant does not cover is a request to the starter, and the answer goes back as it was picked", async () => {
154
+ const control = new ReverseControl();
155
+ const { niwa, records } = await serve(control);
156
+ await started(niwa);
157
+
158
+ const answered = control.reverse(permission("ls", "Bash"));
159
+ const request = await nextRequest(niwa);
160
+
161
+ expect(request.to).toEqual({ kind: "owner" });
162
+ expect(request.input.kind).toBe("permission");
163
+ // The starter may allow it for the rest of the session, though the harness offered no such thing.
164
+ expect(request.input.kind === "permission" && request.input.options.map((option) => option.flavor)).toEqual([
165
+ "allow_once",
166
+ "reject_once",
167
+ "allow_always",
168
+ ]);
169
+
170
+ await call(niwa, "request.answer", { id: request.id, answer: { ids: ["allow"] } });
171
+ expect(await answered).toEqual(picks("allow"));
172
+
173
+ await eventually(() => typesOf(records).includes("session.reverse.answered"));
174
+ const asked = records.find((record) => record.type === "session.reverse.asked");
175
+ expect(asked?.data).toMatchObject({ route: "starter", raw: { method: "fake/request" } });
176
+ expect(records.find((record) => record.type === "session.reverse.answered")?.data).toMatchObject({ by: "starter", answer: { ids: ["allow"] } });
177
+ });
178
+
179
+ test("rejecting answers the harness's once-only reject", async () => {
180
+ const control = new ReverseControl();
181
+ const { niwa } = await serve(control);
182
+ await started(niwa);
183
+
184
+ const answered = control.reverse(permission("rm x"));
185
+ const request = await nextRequest(niwa);
186
+ await call(niwa, "request.answer", { id: request.id, answer: { ids: ["reject"] } });
187
+ expect(await answered).toEqual(picks("reject"));
188
+ });
189
+
190
+ test("an answer outside the options of the question is refused and the question stays open", async () => {
191
+ const control = new ReverseControl();
192
+ const { niwa } = await serve(control);
193
+ await started(niwa);
194
+
195
+ const answered = control.reverse(permission("ls"));
196
+ const request = await nextRequest(niwa);
197
+ await expect(call(niwa, "request.answer", { id: request.id, answer: { ids: ["nonsense"] } })).rejects.toThrow();
198
+ expect((await openRequests(niwa)).length).toBe(1);
199
+ await call(niwa, "request.answer", { id: request.id, answer: { ids: ["allow"] } });
200
+ await answered;
201
+ });
202
+
203
+ test("a tool the session's grant covers is allowed without a request", async () => {
204
+ const control = new ReverseControl();
205
+ const { niwa, records } = await serve(control);
206
+ await started(niwa, { actions: ["tool:Bash"] });
207
+
208
+ expect(await control.reverse(permission("ls", "Bash"))).toEqual(picks("allow"));
209
+ expect(await openRequests(niwa)).toEqual([]);
210
+ await eventually(() => typesOf(records).includes("session.reverse.answered"));
211
+ expect(records.find((record) => record.type === "session.reverse.answered")?.data).toMatchObject({ by: "grant" });
212
+ expect(records.find((record) => record.type === "session.reverse.asked")?.data).toMatchObject({ route: "grant" });
213
+ });
214
+
215
+ test("a tool of niwa's own server is allowed by the grant of a session that was given the server; a tool of another server is asked", async () => {
216
+ const control = new ReverseControl();
217
+ const { niwa, records } = await serve(control, undefined, { command: "niwa", args: ["mcp"] });
218
+ await started(niwa, { actions: ["task.create"] });
219
+ const server = control.servers?.[0]?.name ?? "";
220
+ expect(server).not.toBe("");
221
+
222
+ expect(await control.reverse(permission("{}", `mcp__${server}__task_create`))).toEqual(picks("allow"));
223
+ expect(await openRequests(niwa)).toEqual([]);
224
+ await eventually(() => typesOf(records).includes("session.reverse.answered"));
225
+ expect(records.find((record) => record.type === "session.reverse.answered")?.data).toMatchObject({ by: "grant" });
226
+
227
+ const other = control.reverse(permission("{}", "mcp__github__create_issue"));
228
+ const request = await nextRequest(niwa);
229
+ await call(niwa, "request.answer", { id: request.id, answer: { ids: ["reject"] } });
230
+ expect(await other).toEqual(picks("reject"));
231
+ });
232
+
233
+ test("a session that was given no niwa server is asked about a tool that carries the name of one", async () => {
234
+ const control = new ReverseControl();
235
+ const { niwa } = await serve(control, undefined, { command: "niwa", args: ["mcp"] });
236
+ await started(niwa);
237
+ expect(control.servers).toBeUndefined();
238
+
239
+ const answered = control.reverse(permission("{}", "mcp__niwa__task_create"));
240
+ const request = await nextRequest(niwa);
241
+ await call(niwa, "request.answer", { id: request.id, answer: { ids: ["allow"] } });
242
+ expect(await answered).toEqual(picks("allow"));
243
+ });
244
+
245
+ test("allow always is remembered by niwa: the next matching request is allowed once, with no new request", async () => {
246
+ const control = new ReverseControl();
247
+ const { niwa, records } = await serve(control);
248
+ await started(niwa);
249
+
250
+ const first = control.reverse(permission("ls -la"));
251
+ const request = await nextRequest(niwa);
252
+ await call(niwa, "request.answer", { id: request.id, answer: { ids: ["niwa.allow_always"] } });
253
+ // The harness is never given its own "always": it is told to allow this once.
254
+ expect(await first).toEqual(picks("allow"));
255
+
256
+ expect(await control.reverse(permission("ls -la"))).toEqual(picks("allow"));
257
+ expect(await openRequests(niwa)).toEqual([]);
258
+ expect(records.filter((record) => record.type === "request.created").length).toBe(1);
259
+ await eventually(() => records.some((record) => record.type === "session.reverse.answered" && (record.data as { by: string }).by === "remembered"));
260
+
261
+ // Another target is another request.
262
+ const other = control.reverse(permission("rm -rf /"));
263
+ const second = await nextRequest(niwa);
264
+ await call(niwa, "request.answer", { id: second.id, answer: { ids: ["reject"] } });
265
+ expect(await other).toEqual(picks("reject"));
266
+ });
267
+
268
+ test("when the harness stops waiting the niwa request is cancelled and the record says so", async () => {
269
+ const control = new ReverseControl();
270
+ const { niwa, records } = await serve(control);
271
+ await started(niwa);
272
+
273
+ const gone = new AbortController();
274
+ const answered = control.reverse(permission("sleep 100"), gone.signal);
275
+ await nextRequest(niwa);
276
+ gone.abort();
277
+
278
+ expect(await answered).toEqual({ cancelled: true });
279
+ await eventually(async () => (await openRequests(niwa)).length === 0);
280
+ await eventually(() => records.some((record) => record.type === "request.cancelled"));
281
+ await eventually(() => records.some((record) => record.type === "session.reverse.answered"));
282
+ expect(records.find((record) => record.type === "session.reverse.answered")?.data).toMatchObject({ by: "cancelled", answer: { cancelled: true } });
283
+ });
284
+
285
+ test("a question is a request to the starter and a text may be given instead of an option when the question allows it", async () => {
286
+ const control = new ReverseControl();
287
+ const { niwa } = await serve(control);
288
+ await started(niwa);
289
+
290
+ const question: Question = {
291
+ kind: "choice",
292
+ title: "Which library?",
293
+ options: [
294
+ { id: id("option-1"), label: "date-fns", flavor: "plain" },
295
+ { id: id("option-2"), label: "dayjs", flavor: "plain" },
296
+ ],
297
+ allowOther: true,
298
+ };
299
+ const answered = control.reverse(question);
300
+ const request = await nextRequest(niwa);
301
+ await expect(call(niwa, "request.answer", { id: request.id, answer: { ids: ["option-1", "option-2"] } })).rejects.toThrow();
302
+ await call(niwa, "request.answer", { id: request.id, answer: { text: "luxon" } });
303
+ expect(await answered).toEqual({ text: "luxon" });
304
+ });
305
+
306
+ test("a question that does not allow other refuses a free text, and a form takes a value of its own schema", async () => {
307
+ const control = new ReverseControl();
308
+ const { niwa } = await serve(control);
309
+ await started(niwa);
310
+
311
+ const closed = control.reverse({ kind: "confirm", title: "Go?", options: [{ id: id("yes"), label: "Yes", flavor: "plain" }, { id: id("no"), label: "No", flavor: "plain" }], allowOther: false });
312
+ const first = await nextRequest(niwa);
313
+ await expect(call(niwa, "request.answer", { id: first.id, answer: { text: "maybe" } })).rejects.toThrow();
314
+ await call(niwa, "request.answer", { id: first.id, answer: { ids: ["no"] } });
315
+ expect(await closed).toEqual(picks("no"));
316
+
317
+ const form = control.reverse({
318
+ kind: "form",
319
+ title: "Deploy",
320
+ schema: { type: "object", properties: { env: { type: "string" } }, required: ["env"] },
321
+ });
322
+ const second = await nextRequest(niwa);
323
+ await expect(call(niwa, "request.answer", { id: second.id, answer: { form: {} } })).rejects.toThrow();
324
+ await call(niwa, "request.answer", { id: second.id, answer: { form: { env: "staging" } } });
325
+ expect(await form).toEqual({ form: { env: "staging" } });
326
+ });
327
+
328
+ test("a question left open when the host stopped is closed when the host serves again: nobody waits for it", async () => {
329
+ const control = new ReverseControl();
330
+ const first = await serve(control);
331
+ await started(first.niwa);
332
+ void control.reverse(permission("sleep 99")).catch(() => {});
333
+ await nextRequest(first.niwa);
334
+ await first.niwa.close();
335
+
336
+ const second = await serve(new ReverseControl(), first.home);
337
+ await eventually(async () => (await openRequests(second.niwa)).length === 0);
338
+ await eventually(() => second.records.some((record) => record.type === "request.cancelled"));
339
+ await eventually(() => second.records.some((record) => record.type === "session.reverse.answered"));
340
+ expect(second.records.find((record) => record.type === "session.reverse.answered")?.data).toMatchObject({ by: "cancelled" });
341
+ });