@niwa-labs/harness-codex 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,217 @@
1
+ /**
2
+ * The live proof of the Codex control side.
3
+ *
4
+ * This test runs the real `codex` CLI against the cheapest model it offers and proves the
5
+ * things the control contract asks for:
6
+ *
7
+ * 1. a session starts, and Codex names it — the native session id is Codex's own thread id,
8
+ * not niwa's;
9
+ * 2. the turn ends: the `turn-ended` sign of life arrives with Codex's own turn;
10
+ * 3. a message into an idle session starts a turn, and the signs of life report it;
11
+ * 4. a question asked with a schema comes back as a value that passed that schema.
12
+ *
13
+ * The test runs only with `NIWA_LIVE=1` and the `codex` binary on PATH.
14
+ */
15
+
16
+ import { expect, test } from "bun:test";
17
+ import { rm } from "node:fs/promises";
18
+ import { tmpdir } from "node:os";
19
+ import { join } from "node:path";
20
+ import { z } from "zod";
21
+
22
+ import { promptFromText } from "@niwa-labs/harness";
23
+ import type { LifeEvent, SessionId } from "@niwa-labs/harness";
24
+
25
+ import { codexControl, type CodexSessionControl } from "../src/control.ts";
26
+ import { tempDir, live } from "@niwa-labs/testing";
27
+
28
+ /**
29
+ * The cheapest model Codex offers.
30
+ *
31
+ * `codex debug models` lists it as "fast and affordable model for easier tasks".
32
+ */
33
+ const MODEL = "gpt-6-luna";
34
+
35
+ /** How long the whole proof may take. */
36
+ const PROOF_TIMEOUT_MS = 300_000;
37
+
38
+ /** How long a turn may take before the proof gives up on it. */
39
+ const TURN_TIMEOUT_MS = 180_000;
40
+
41
+ /** Collect the signs of life of a session, without blocking the test on them. */
42
+ function watchLife(
43
+ control: CodexSessionControl,
44
+ id: SessionId,
45
+ ): { events: LifeEvent[]; stop: () => void } {
46
+ const events: LifeEvent[] = [];
47
+ const iterator = control.life(id)[Symbol.asyncIterator]();
48
+ void (async () => {
49
+ for (;;) {
50
+ const next = await iterator.next();
51
+ if (next.done === true) return;
52
+ events.push(next.value);
53
+ }
54
+ })();
55
+ return { events, stop: () => void iterator.return?.() };
56
+ }
57
+
58
+ /** Whether a sign of life is the given turn sign of the given turn. */
59
+ function ofTurn(
60
+ event: LifeEvent,
61
+ kind: "turn-started" | "turn-ended",
62
+ turn: number | undefined,
63
+ ): event is Extract<LifeEvent, { kind: "turn-started" | "turn-ended" }> {
64
+ return event.kind === kind && event.turn === turn;
65
+ }
66
+
67
+ /** Wait until the session is idle again: the turn ran and ended. */
68
+ async function waitForIdle(control: CodexSessionControl, id: SessionId): Promise<void> {
69
+ const deadline = Date.now() + TURN_TIMEOUT_MS;
70
+ while ((await control.state(id)) === "running") {
71
+ if (Date.now() > deadline) throw new Error("the turn did not end in time");
72
+ await Bun.sleep(100);
73
+ }
74
+ }
75
+
76
+ test.skipIf(!(live && Bun.which("codex")))(
77
+ "the Codex control side starts, resumes and answers by schema",
78
+ async () => {
79
+ const dir = await tempDir("codex-proof");
80
+ const control = codexControl({
81
+ harness: "codex-proof",
82
+ model: MODEL,
83
+ });
84
+
85
+ try {
86
+ // 1. A session starts in a temp dir, and Codex names it.
87
+ const { session: id } = await control.start({
88
+ prompt: promptFromText("reply with the word ok"),
89
+ cwd: dir,
90
+ });
91
+
92
+ expect(typeof id.native).toBe("string");
93
+ expect(id.native.length).toBeGreaterThan(0);
94
+
95
+ // The native id is Codex's own thread id: a UUID it chose, not one niwa minted.
96
+ expect(id.native).toMatch(
97
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
98
+ );
99
+ expect(String(id.harness)).toBe("codex-proof");
100
+
101
+ // 2. The turn ends: the sign of life says so.
102
+ //
103
+ // The watcher starts after the first turn, because the session only exists once Codex
104
+ // has named it, and naming it takes the first turn.
105
+ const watched = watchLife(control, id);
106
+ await waitForIdle(control, id);
107
+ expect(await control.state(id)).toBe("idle");
108
+
109
+ // 3. A message into an idle session begins a turn of its own.
110
+ const receipt = await control.send(id, "reply with the word two");
111
+ expect(receipt.status).toBe("started");
112
+ expect(receipt.turn).toBeGreaterThan(0);
113
+
114
+ // The signs of life of that turn: it started, and it ended.
115
+ const deadline = Date.now() + TURN_TIMEOUT_MS;
116
+ // The first watcher is also given the signs of the first turn, so pick by this receipt.
117
+ while (
118
+ !watched.events.some((event) => ofTurn(event, "turn-ended", receipt.turn))
119
+ ) {
120
+ if (Date.now() > deadline) throw new Error("the turn did not end in time");
121
+ await Bun.sleep(100);
122
+ }
123
+ const started = watched.events.find((event) => ofTurn(event, "turn-started", receipt.turn));
124
+ expect(started?.kind).toBe("turn-started");
125
+ expect(started && "turn" in started ? started.turn : undefined).toBe(receipt.turn);
126
+
127
+ const ended = watched.events.find((event) => ofTurn(event, "turn-ended", receipt.turn));
128
+ expect(ended?.kind).toBe("turn-ended");
129
+ expect(ended && "turn" in ended ? ended.turn : undefined).toBe(receipt.turn);
130
+
131
+ await waitForIdle(control, id);
132
+ expect(await control.state(id)).toBe("idle");
133
+
134
+ // 4. The session resumes: the same thread, the same native id.
135
+ const resumed = await control.resume(id, {
136
+ prompt: promptFromText("reply with the word three"),
137
+ });
138
+ expect(resumed).toBeUndefined();
139
+ await waitForIdle(control, id);
140
+ expect(await control.state(id)).toBe("idle");
141
+
142
+ // The resumed session is the same session: the id did not change.
143
+ const afterResume = await control.send(id, "reply with the word four");
144
+ expect(afterResume.status).toBe("started");
145
+
146
+ await waitForIdle(control, id);
147
+ expect(await control.state(id)).toBe("idle");
148
+
149
+ // 5. A question with a schema comes back as a value that passed the schema.
150
+ const Answer = z.object({ answer: z.string() });
151
+ const answer = await control.ask(id, {
152
+ schema: Answer,
153
+ prompt: promptFromText("reply with the word ok"),
154
+ });
155
+
156
+ expect(answer.session).toEqual(id);
157
+ expect(answer.value.answer).toBe("ok");
158
+ expect(answer.at).toBeGreaterThan(0);
159
+
160
+ // The schema is the gate: a value that does not pass it is not an answer.
161
+ expect(() => z.object({ answer: z.number() }).parse(answer.value)).toThrow();
162
+
163
+ watched.stop();
164
+ } finally {
165
+ await control.dispose();
166
+ await rm(dir, { recursive: true, force: true });
167
+ }
168
+ },
169
+ PROOF_TIMEOUT_MS,
170
+ );
171
+
172
+ test.skipIf(!(live && Bun.which("codex")))(
173
+ "a schema given as JSON, with an optional property, is answered by real Codex in OpenAI's strict mode",
174
+ async () => {
175
+ const control = codexControl({ harness: "codex-proof", model: MODEL, turnTimeoutMs: 120_000 });
176
+ try {
177
+ const { session: id } = await control.start({ prompt: promptFromText(""), cwd: tmpdir() });
178
+ const schema = z.fromJSONSchema({
179
+ type: "object",
180
+ properties: {
181
+ answer: { type: "integer" },
182
+ note: { type: "string" },
183
+ inner: { type: "object", properties: { n: { type: "integer" } } },
184
+ },
185
+ required: ["answer"],
186
+ });
187
+ const answer = await control.ask(id, { schema, prompt: promptFromText("What is 21+21? Put it in answer.") });
188
+ expect((answer.value as { answer: number }).answer).toBe(42);
189
+ } finally {
190
+ await control.dispose();
191
+ }
192
+ },
193
+ PROOF_TIMEOUT_MS,
194
+ );
195
+
196
+ test.skipIf(!(live && Bun.which("codex")))(
197
+ "schemas strict mode cannot take as written are still answered by real Codex: formats, maps, tuples, roots that are not objects",
198
+ async () => {
199
+ const control = codexControl({ harness: "codex-proof", model: MODEL, turnTimeoutMs: 120_000 });
200
+ const forms: Array<[z.ZodType, string, unknown]> = [
201
+ [z.object({ site: z.url() }), "Give site https://example.com", { site: "https://example.com" }],
202
+ [z.object({ scores: z.record(z.string(), z.number()) }), "Give scores with a=1 and b=2", { scores: { a: 1, b: 2 } }],
203
+ [z.object({ pair: z.tuple([z.string(), z.number()]) }), 'Give pair ["x", 1]', { pair: ["x", 1] }],
204
+ [z.array(z.number()), "Give the list 1, 2, 3", [1, 2, 3]],
205
+ ];
206
+ try {
207
+ const { session: id } = await control.start({ prompt: promptFromText(""), cwd: tmpdir() });
208
+ for (const [schema, question, expected] of forms) {
209
+ const answer = await control.ask(id, { schema, prompt: promptFromText(question) });
210
+ expect(answer.value).toEqual(expected);
211
+ }
212
+ } finally {
213
+ await control.dispose();
214
+ }
215
+ },
216
+ PROOF_TIMEOUT_MS,
217
+ );
@@ -0,0 +1,71 @@
1
+ // What `mcpServer/elicitation/request` of Codex is as a niwa question, and the reply for each answer
2
+ // . The mapping is a pure function: no process is run.
3
+
4
+ import { expect, test } from "bun:test";
5
+
6
+ import { OptionIdSchema } from "@niwa-labs/core";
7
+ import type { Answer } from "@niwa-labs/core";
8
+ import { elicitationOf } from "../src/reverse.ts";
9
+ import type { ElicitationRequest } from "../src/reverse.ts";
10
+
11
+ const picks = (text: string): Answer => ({ ids: [OptionIdSchema.parse(text)] });
12
+
13
+ function asked(params: Record<string, unknown>): ElicitationRequest {
14
+ return { id: 1, method: "mcpServer/elicitation/request", params: { threadId: "th", turnId: "t1", ...params } } as ElicitationRequest;
15
+ }
16
+
17
+ const approval = (message: string, meta: Record<string, unknown>): ElicitationRequest =>
18
+ asked({ serverName: "niwa", mode: "form", message, _meta: { codex_approval_kind: "mcp_tool_call", ...meta }, requestedSchema: { type: "object", properties: {} } });
19
+
20
+ test("leave to call a tool names the tool as an MCP tool is named, and what it acts on is the tool with its input", () => {
21
+ const found = elicitationOf(approval('Allow the niwa MCP server to run tool "task_finish"?', { tool_name: "task_finish", tool_params: { id: 7 } }));
22
+ expect(found?.question).toEqual({
23
+ kind: "permission",
24
+ title: 'Allow the niwa MCP server to run tool "task_finish"?',
25
+ detail: '{"id":7}',
26
+ options: [
27
+ { id: OptionIdSchema.parse("accept"), label: "Allow once", flavor: "allow_once" },
28
+ { id: OptionIdSchema.parse("decline"), label: "Decline", flavor: "reject_once" },
29
+ ],
30
+ subject: { tool: "mcp__niwa__task_finish", kind: "mcp", target: 'mcp__niwa__task_finish\n{"id":7}' },
31
+ });
32
+ });
33
+
34
+ test("the tool is read from _meta.tool_name, not from the words; an approval without it is declined", () => {
35
+ const named = elicitationOf(approval("Allow this app to run tool \"other\"?", { tool_name: "finish_task", tool_title: "Finish" }));
36
+ expect(named?.question).toMatchObject({ subject: { tool: "mcp__niwa__finish_task", target: "mcp__niwa__finish_task" } });
37
+ expect(elicitationOf(approval('Allow the niwa MCP server to run tool "x"?', {}))).toBeUndefined();
38
+ });
39
+
40
+ test("the answers to leave to call a tool: allow is accept, reject is decline, anything else is cancel; no persistence is ever asked", () => {
41
+ const found = elicitationOf(approval('Allow the niwa MCP server to run tool "x"?', { tool_name: "x", persist: ["session", "always"] }));
42
+ expect(found?.reply(picks("accept"))).toEqual({ action: "accept", content: null, _meta: null });
43
+ expect(found?.reply(picks("decline"))).toEqual({ action: "decline", content: null, _meta: null });
44
+ expect(found?.reply({ cancelled: true })).toEqual({ action: "cancel", content: null, _meta: null });
45
+ });
46
+
47
+ test("a form is a form question without the nulls Codex writes for what is absent, answered by its value", () => {
48
+ const found = elicitationOf(
49
+ asked({
50
+ serverName: "x",
51
+ mode: "form",
52
+ message: "Which repo?",
53
+ requestedSchema: { $schema: null, type: "object", properties: { repo: { type: "string", title: null, default: null } }, required: null },
54
+ }),
55
+ );
56
+ expect(found?.question).toEqual({
57
+ kind: "form",
58
+ title: "Which repo?",
59
+ schema: { type: "object", properties: { repo: { type: "string" } } },
60
+ });
61
+ expect(found?.reply({ form: { repo: "niwa" } })).toEqual({ action: "accept", content: { repo: "niwa" }, _meta: null });
62
+ // A form cannot be declined: what is not a value is a cancel, whatever else was picked.
63
+ expect(found?.reply(picks("accept"))).toEqual({ action: "cancel", content: null, _meta: null });
64
+ expect(found?.reply({ cancelled: true })).toEqual({ action: "cancel", content: null, _meta: null });
65
+ });
66
+
67
+ test("an elicitation of a kind niwa cannot ask a person is not one", () => {
68
+ expect(elicitationOf(asked({ serverName: "x", mode: "url", elicitationId: "e", message: "open it", url: "https://example.test" }))).toBeUndefined();
69
+ expect(elicitationOf(asked({ serverName: "x", mode: "openaiForm", message: "fill it", requestedSchema: {} }))).toBeUndefined();
70
+ expect(elicitationOf(asked({ serverName: "x", mode: "openai/form", message: "fill it", requestedSchema: {} }))).toBeUndefined();
71
+ });
@@ -0,0 +1,245 @@
1
+ /**
2
+ * The typed protocol of `codex app-server` (src/protocol, incoming.ts, refusals.ts).
3
+ *
4
+ * The schemas are generated from the installed codex, so what they prove against the real thing is
5
+ * the frames captured from it (`fixtures/codex-app-server/captured.jsonl`): each must read as the
6
+ * message it is. A variant none was captured for is made by `minimalInstance` from its schema; it
7
+ * proves that the variant is read, given a meaning, and answered, not that the schema is right.
8
+ * What is not in the snapshot at all must become a typed unknown variant that carries the message.
9
+ */
10
+
11
+ import { expect, test } from "bun:test";
12
+ import { readFileSync } from "node:fs";
13
+
14
+ import { z } from "zod";
15
+
16
+ import type { JsonValue } from "@niwa-labs/core";
17
+ import { ProtocolNameSchema, VariantNameSchema } from "@niwa-labs/harness";
18
+ import { incomingOf, incomingOfDrifted } from "../src/incoming.ts";
19
+ import type { Incoming } from "../src/incoming.ts";
20
+ import { CODEX_PROTOCOL, readFrame } from "../src/protocol/index.ts";
21
+ import type { Frame } from "../src/protocol/index.ts";
22
+ import {
23
+ ApplyPatchApprovalResponseSchema,
24
+ CommandExecutionRequestApprovalResponseSchema,
25
+ DynamicToolCallResponseSchema,
26
+ ExecCommandApprovalResponseSchema,
27
+ FileChangeRequestApprovalResponseSchema,
28
+ McpServerElicitationRequestResponseSchema,
29
+ PermissionsRequestApprovalResponseSchema,
30
+ ServerNotificationSchema,
31
+ ServerRequestSchema,
32
+ ThreadItemSchema,
33
+ ToolRequestUserInputResponseSchema,
34
+ } from "../src/protocol/generated/app-server.ts";
35
+ import type { ServerRequest } from "../src/protocol/generated/app-server.ts";
36
+ import { refusalOf } from "../src/refusals.ts";
37
+
38
+ import { minimalInstance } from "./fixtures/zod-instance.ts";
39
+
40
+ /** The frames captured from codex-cli 0.169, server to client. */
41
+ const CAPTURED = readFileSync(new URL("./fixtures/codex-app-server/captured.jsonl", import.meta.url), "utf8")
42
+ .split("\n")
43
+ .filter((line) => line !== "")
44
+ .map((line) => JSON.parse(line) as { method: string; id?: number; params: { item?: { type: string } } });
45
+
46
+ const line = (frame: unknown): string => JSON.stringify(frame);
47
+
48
+ function notificationOf(frame: Frame) {
49
+ if (frame.kind !== "notification") throw new Error(`not a notification: ${JSON.stringify(frame)}`);
50
+ return frame.notification;
51
+ }
52
+
53
+ test("every frame captured from codex reads as the message it is, never as an unknown variant", () => {
54
+ expect(CAPTURED.length).toBeGreaterThan(15);
55
+ for (const captured of CAPTURED) {
56
+ const frame = readFrame(line(captured));
57
+ expect(frame.kind).toBe(captured.id === undefined ? "notification" : "request");
58
+ }
59
+ });
60
+
61
+ const NOTIFICATIONS = ServerNotificationSchema.options.map((option) => option.shape.method.value);
62
+
63
+ test("every notification the schemas know is read, and given a meaning", () => {
64
+ expect(NOTIFICATIONS.length).toBe(86);
65
+ for (const option of ServerNotificationSchema.options) {
66
+ const method = option.shape.method.value;
67
+ const real = CAPTURED.find((captured) => captured.id === undefined && captured.method === method && captured.params.item === undefined);
68
+ const frame = readFrame(line(real ?? minimalInstance(option)));
69
+ expect(frame.kind).toBe("notification");
70
+ expect(notificationOf(frame).method).toBe(method);
71
+ expect(() => incomingOf(notificationOf(frame))).not.toThrow();
72
+ }
73
+ });
74
+
75
+ const ITEM_TYPES = ThreadItemSchema.options.map((option) => option.shape.type.value);
76
+
77
+ test("every item an item notification carries is read, and given a meaning, started and completed", () => {
78
+ expect(ITEM_TYPES.length).toBe(19);
79
+ for (const method of ["item/started", "item/completed"] as const) {
80
+ const wrapper = ServerNotificationSchema.options.find((option) => option.shape.method.value === method);
81
+ if (wrapper === undefined) throw new Error(`no ${method}`);
82
+ for (const option of ThreadItemSchema.options) {
83
+ const type = option.shape.type.value;
84
+ const real = CAPTURED.find((captured) => captured.method === method && captured.params.item?.type === type);
85
+ const made = z.object({ method: z.string(), params: z.object({ item: z.unknown() }).loose() }).loose().parse(minimalInstance(wrapper));
86
+ const sent = real ?? { ...made, params: { ...made.params, item: minimalInstance(option) } };
87
+ const frame = readFrame(line(sent));
88
+ expect(frame.kind).toBe("notification");
89
+ const incoming = incomingOf(notificationOf(frame));
90
+ expect(incoming.kind === "ignored").toBe(false);
91
+ if (incoming.kind !== "ignored" && incoming.kind !== "turn-started" && incoming.kind !== "turn-ended") {
92
+ expect(incoming.detail).toContain(type);
93
+ }
94
+ }
95
+ }
96
+ });
97
+
98
+ /** What the answer to each request must be: the schema of the result Codex takes, or an error. */
99
+ const REPLY_SCHEMAS: { readonly [Method in ServerRequest["method"]]: z.ZodType | "error" } = {
100
+ "item/commandExecution/requestApproval": CommandExecutionRequestApprovalResponseSchema,
101
+ "item/fileChange/requestApproval": FileChangeRequestApprovalResponseSchema,
102
+ "item/permissions/requestApproval": PermissionsRequestApprovalResponseSchema,
103
+ "item/tool/requestUserInput": ToolRequestUserInputResponseSchema,
104
+ "item/tool/call": DynamicToolCallResponseSchema,
105
+ "mcpServer/elicitation/request": McpServerElicitationRequestResponseSchema,
106
+ applyPatchApproval: ApplyPatchApprovalResponseSchema,
107
+ execCommandApproval: ExecCommandApprovalResponseSchema,
108
+ "account/chatgptAuthTokens/refresh": "error",
109
+ "attestation/generate": "error",
110
+ };
111
+
112
+ test("every request the schemas know is read, and refused in the words Codex takes for a refusal", () => {
113
+ expect(ServerRequestSchema.options.length).toBe(10);
114
+ for (const option of ServerRequestSchema.options) {
115
+ const method = option.shape.method.value;
116
+ const real = CAPTURED.find((captured) => captured.id !== undefined && captured.method === method);
117
+ const frame = readFrame(line(real ?? minimalInstance(option)));
118
+ expect(frame.kind).toBe("request");
119
+ const refusal = refusalOf(method);
120
+ const expected = REPLY_SCHEMAS[method];
121
+ if (expected === "error") {
122
+ expect(refusal).toMatchObject({ error: { code: -32601 } });
123
+ } else {
124
+ expect("result" in refusal && z.safeParse(expected, refusal.result).success).toBe(true);
125
+ }
126
+ }
127
+ });
128
+
129
+ test("a method the schemas do not know is a typed unknown variant that keeps the message as it arrived", () => {
130
+ const sent = { jsonrpc: "2.0", method: "novel/thing", params: { n: 1, nested: { a: [1, 2] } } };
131
+ expect(readFrame(line(sent))).toEqual({
132
+ kind: "unknown",
133
+ method: "novel/thing",
134
+ id: undefined,
135
+ variant: VariantNameSchema.parse("novel/thing"),
136
+ params: sent.params,
137
+ raw: sent,
138
+ });
139
+ expect(CODEX_PROTOCOL).toBe(ProtocolNameSchema.parse("codex app-server"));
140
+ });
141
+
142
+ test("a request the schemas do not know keeps its id, so it can be answered", () => {
143
+ const sent = { id: "q-1", method: "novel/ask", params: {} };
144
+ expect(readFrame(line(sent))).toMatchObject({ kind: "unknown", id: "q-1", variant: "novel/ask", method: "novel/ask" });
145
+ });
146
+
147
+ test("a known method whose parameters are not what the snapshot says is an unknown variant too", () => {
148
+ const sent = { method: "thread/status/changed", params: { threadId: "t", status: { type: "from-the-future" } } };
149
+ expect(readFrame(line(sent))).toMatchObject({ kind: "unknown", variant: "thread/status/changed", raw: sent });
150
+ const request = { id: 7, method: "item/commandExecution/requestApproval", params: {} };
151
+ expect(readFrame(line(request))).toMatchObject({ kind: "unknown", id: 7, variant: "item/commandExecution/requestApproval" });
152
+ });
153
+
154
+ test("an item of a type the snapshot does not know is named by that type", () => {
155
+ const started = ServerNotificationSchema.options.find((option) => option.shape.method.value === "item/started");
156
+ if (started === undefined) throw new Error("no item/started");
157
+ const made = z.object({ params: z.object({}).loose() }).loose().parse(minimalInstance(started));
158
+ const sent = { ...made, params: { ...made.params, item: { type: "hologram", id: "i-1" } } };
159
+ expect(readFrame(line(sent))).toMatchObject({ kind: "unknown", method: "item/started", variant: "item/started:hologram" });
160
+ });
161
+
162
+ test("a line that is not JSON, or not JSON-RPC, is unreadable, and says so", () => {
163
+ expect(readFrame("not json")).toMatchObject({ kind: "unreadable" });
164
+ expect(readFrame("[1, 2]")).toMatchObject({ kind: "unreadable" });
165
+ expect(readFrame('{"jsonrpc":"2.0"}')).toMatchObject({ kind: "unreadable" });
166
+ });
167
+
168
+ test("the answer to a call, and the failure of one, are read with the id of the call", () => {
169
+ expect(readFrame(line({ id: 3, result: { thread: { id: "t" } } }))).toMatchObject({ kind: "response", id: 3 });
170
+ expect(readFrame(line({ id: 3, error: { code: -32600, message: "bad" } }))).toMatchObject({ kind: "failure", id: 3, error: { message: "bad" } });
171
+ });
172
+
173
+ function incomingOfCaptured(method: string, type?: string): Incoming {
174
+ const captured = CAPTURED.find((frame) => frame.method === method && frame.params.item?.type === type);
175
+ if (captured === undefined) throw new Error(`nothing captured for ${method} ${String(type)}`);
176
+ return incomingOf(notificationOf(readFrame(line(captured))));
177
+ }
178
+
179
+ test("a turn begins and ends with the notifications of its turn", () => {
180
+ expect(incomingOfCaptured("turn/started")).toEqual({ kind: "turn-started", turnId: "00000000-0000-4000-8000-000000000002" });
181
+ expect(incomingOfCaptured("turn/completed")).toEqual({ kind: "turn-ended", turn: { id: "00000000-0000-4000-8000-000000000002", status: "completed", message: undefined } });
182
+ });
183
+
184
+ test("the final answer of the turn is the agent's message that is done, and nothing else is", () => {
185
+ expect(incomingOfCaptured("item/completed", "agentMessage")).toMatchObject({ kind: "answer", text: "ok" });
186
+ // Started, it has no text yet; a commentary is not the answer.
187
+ expect(incomingOfCaptured("item/started", "agentMessage")).toMatchObject({ kind: "sign" });
188
+ const commentary = JSON.parse(line(CAPTURED.find((frame) => frame.method === "item/completed" && frame.params.item?.type === "agentMessage"))) as {
189
+ params: { item: { phase: string } };
190
+ };
191
+ commentary.params.item.phase = "commentary";
192
+ expect(incomingOf(notificationOf(readFrame(line(commentary))))).toMatchObject({ kind: "sign" });
193
+ });
194
+
195
+ test("what Codex answers itself is a request nobody waits for any more", () => {
196
+ expect(incomingOfCaptured("serverRequest/resolved")).toEqual({ kind: "request-resolved", detail: "serverRequest/resolved", requestId: 0 });
197
+ });
198
+
199
+ test("the work of the turn is a sign of life; the account and the installation are not", () => {
200
+ expect(incomingOfCaptured("item/agentMessage/delta")).toEqual({ kind: "sign", detail: "item/agentMessage/delta" });
201
+ expect(incomingOfCaptured("thread/tokenUsage/updated")).toMatchObject({ kind: "sign" });
202
+ expect(incomingOfCaptured("account/rateLimits/updated")).toEqual({ kind: "ignored" });
203
+ expect(incomingOfCaptured("remoteControl/status/changed")).toEqual({ kind: "ignored" });
204
+ });
205
+
206
+ test("a turn that began or ended is still known to have, when the rest of its notification is not what it was", () => {
207
+ expect(incomingOfDrifted("turn/started", { turn: { id: "t9", more: true } })).toEqual({ kind: "turn-started", turnId: "t9" });
208
+ expect(incomingOfDrifted("turn/completed", { turn: { id: "t9", status: "paused", error: { message: "why" } } })).toEqual({
209
+ kind: "turn-ended",
210
+ turn: { id: "t9", status: "paused", message: "why" },
211
+ });
212
+ // An end that cannot be read is an end that is not a success.
213
+ expect(incomingOfDrifted("turn/completed", { nothing: true })).toEqual({ kind: "turn-ended", turn: { id: undefined, status: "was not readable", message: undefined } });
214
+ expect(incomingOfDrifted("serverRequest/resolved", { requestId: "r" })).toMatchObject({ kind: "request-resolved", requestId: "r" });
215
+ expect(incomingOfDrifted("novel/thing", { n: 1 })).toBeUndefined();
216
+ });
217
+
218
+ test("the answer of a turn is kept when its message carries a field the snapshot does not know, and a commentary is still not the answer", () => {
219
+ const message = (phase: string | null | "absent", extra: Record<string, JsonValue>) => ({
220
+ item: { type: "agentMessage", id: "m-1", text: "the answer", ...(phase === "absent" ? {} : { phase }), ...extra },
221
+ });
222
+ const drifted = { moderation: { from: "the future" } };
223
+ expect(incomingOfDrifted("item/completed", message("final_answer", drifted))).toEqual({
224
+ kind: "answer",
225
+ detail: "item/completed agentMessage",
226
+ text: "the answer",
227
+ });
228
+ expect(incomingOfDrifted("item/completed", message(null, drifted))).toMatchObject({ kind: "answer", text: "the answer" });
229
+ expect(incomingOfDrifted("item/completed", message("absent", drifted))).toMatchObject({ kind: "answer" });
230
+ expect(incomingOfDrifted("item/completed", message("commentary", drifted))).toEqual({ kind: "sign", detail: "item/completed agentMessage" });
231
+ expect(incomingOfDrifted("item/started", message("final_answer", drifted))).toEqual({ kind: "sign", detail: "item/started agentMessage" });
232
+ });
233
+
234
+ test("the paths of a file change are kept when the change carries a kind the snapshot does not know", () => {
235
+ const started = { item: { type: "fileChange", id: "patch-9", changes: [{ path: "/work/a.txt", kind: { type: "teleport" } }] } };
236
+ expect(incomingOfDrifted("item/started", started)).toEqual({
237
+ kind: "file-change",
238
+ detail: "item/started fileChange",
239
+ itemId: "patch-9",
240
+ paths: ["/work/a.txt"],
241
+ });
242
+ // An item of a type that is not known at all is still the agent at work.
243
+ expect(incomingOfDrifted("item/completed", { item: { type: "hologram" } })).toEqual({ kind: "sign", detail: "item/completed hologram" });
244
+ expect(incomingOfDrifted("item/completed", { item: "not an item" })).toBeUndefined();
245
+ });