@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,513 @@
1
+ // The Codex reading side against small synthetic rollouts in a temp dir: the two layers of the
2
+ // format, the forked session, the compressed copy, resume by locator, and a rewritten file.
3
+
4
+ import { afterEach, beforeEach, expect, test } from "bun:test";
5
+ import { appendFileSync, mkdirSync, readdirSync, rmSync, utimesSync, statSync, writeFileSync } from "node:fs";
6
+ import { join } from "node:path";
7
+
8
+ import { harnessId, sessionId } from "@niwa-labs/harness";
9
+ import type { Locator, SessionFilter, SessionRecord } from "@niwa-labs/harness";
10
+
11
+ import { CodexReading } from "../src/reading.ts";
12
+ import { tempDirSync } from "@niwa-labs/testing";
13
+
14
+ let home: string;
15
+ const reading = () => new CodexReading({ harness: harnessId("codex-test"), home });
16
+
17
+ const NATIVE = "00000000-0000-4000-8000-000000000001";
18
+ const ID = sessionId(harnessId("codex-test"), NATIVE);
19
+
20
+ beforeEach(() => {
21
+ home = tempDirSync("codex-reading");
22
+ });
23
+ afterEach(() => rmSync(home, { recursive: true, force: true }));
24
+
25
+ /** The path of a rollout file, and the text to put in it. */
26
+ function rollout(native: string, text: string): string {
27
+ const dir = join(home, "sessions", "2026", "01", "01");
28
+ mkdirSync(dir, { recursive: true });
29
+ const path = join(dir, `rollout-2026-01-01T00-00-00-${native}.jsonl`);
30
+ writeFileSync(path, text);
31
+ return path;
32
+ }
33
+
34
+ const record = (ordinal: number, type: string, payload: unknown): string =>
35
+ `${JSON.stringify({ timestamp: `2026-01-01T00:00:0${ordinal}.000Z`, ordinal, type, payload })}\n`;
36
+
37
+ const meta = (native: string, ordinal = 0): string =>
38
+ record(ordinal, "session_meta", {
39
+ id: native,
40
+ session_id: native,
41
+ timestamp: "2026-01-01T00:00:00.000Z",
42
+ cwd: "/work/x",
43
+ });
44
+
45
+ const message = (ordinal: number, role: string, text: string): string =>
46
+ record(ordinal, "response_item", {
47
+ type: "message",
48
+ role,
49
+ content: [{ type: role === "assistant" ? "output_text" : "input_text", text }],
50
+ });
51
+
52
+ async function all(iter: AsyncIterable<SessionRecord>): Promise<SessionRecord[]> {
53
+ const out: SessionRecord[] = [];
54
+ for await (const r of iter) out.push(r);
55
+ return out;
56
+ }
57
+
58
+ test("lists a session from the files, with its cwd and its times", async () => {
59
+ rollout(NATIVE, meta(NATIVE) + message(1, "user", "hello"));
60
+ const infos = [];
61
+ for await (const info of reading().list()) infos.push(info);
62
+ expect(infos).toHaveLength(1);
63
+ expect(String(infos[0]?.id.native)).toBe(NATIVE);
64
+ expect(infos[0]?.cwd).toBe("/work/x");
65
+ expect(infos[0]?.startedAt).toBeGreaterThan(0 as never);
66
+ const records = await all(reading().read(ID));
67
+ expect(records[0]).toMatchObject({ kind: "user", text: "hello" });
68
+ });
69
+
70
+ test("the title is the name Codex gave the thread, else the first message of the person", async () => {
71
+ const OTHER = "00000000-0000-4000-8000-000000000002";
72
+ const preamble = "# AGENTS.md instructions for /work/x\n\n<INSTRUCTIONS>\nbe kind\n</INSTRUCTIONS>";
73
+ const context = "<environment_context>\n <cwd>/work/x</cwd>\n</environment_context>";
74
+ rollout(NATIVE, meta(NATIVE) + message(1, "user", preamble) + message(2, "user", context) + message(3, "user", "fix the build"));
75
+ rollout(OTHER, meta(OTHER) + message(1, "user", "hello"));
76
+ writeFileSync(
77
+ join(home, "session_index.jsonl"),
78
+ `${JSON.stringify({ id: OTHER, thread_name: "Old name", updated_at: "2026-01-01T00:00:00Z" })}\n` +
79
+ "not json\n" +
80
+ `${JSON.stringify({ id: OTHER, thread_name: "Fix the reading side", updated_at: "2026-01-02T00:00:00Z" })}\n`,
81
+ );
82
+ const titles = new Map<string, string | undefined>();
83
+ for await (const info of reading().list()) titles.set(String(info.id.native), info.title);
84
+ expect(titles.get(OTHER)).toBe("Fix the reading side");
85
+ expect(titles.get(NATIVE)).toBe("fix the build");
86
+ });
87
+
88
+ /** The titles a reading side lists, by native id. */
89
+ async function titlesOf(side: CodexReading, filter?: SessionFilter): Promise<Map<string, string | undefined>> {
90
+ const titles = new Map<string, string | undefined>();
91
+ for await (const info of side.list(filter)) titles.set(String(info.id.native), info.title);
92
+ return titles;
93
+ }
94
+
95
+ test("a title is made once per file: a file that is the same is not read for it again, one that changed is", async () => {
96
+ const path = rollout(NATIVE, meta(NATIVE) + message(1, "user", "first words"));
97
+ const before = statSync(path);
98
+ const side = reading();
99
+ expect((await titlesOf(side)).get(NATIVE)).toBe("first words");
100
+
101
+ // The same size and the same time: the file is taken as it was, and its kept title is used.
102
+ writeFileSync(path, meta(NATIVE) + message(1, "user", "other words"));
103
+ utimesSync(path, before.atimeMs / 1000, before.mtimeMs / 1000);
104
+ expect(statSync(path).size).toBe(before.size);
105
+ expect((await titlesOf(side)).get(NATIVE)).toBe("first words");
106
+ // A reading side of its own keeps nothing and reads the file.
107
+ expect((await titlesOf(reading())).get(NATIVE)).toBe("other words");
108
+
109
+ // A file that grew is looked into again.
110
+ appendFileSync(path, message(2, "user", "and more"));
111
+ expect((await titlesOf(side)).get(NATIVE)).toBe("other words");
112
+
113
+ // A file of another size is looked into again, even when it is stamped with the old time.
114
+ const kept = statSync(path);
115
+ writeFileSync(path, meta(NATIVE) + message(1, "user", "a longer first message than before"));
116
+ utimesSync(path, kept.atimeMs / 1000, kept.mtimeMs / 1000);
117
+ expect((await titlesOf(side)).get(NATIVE)).toBe("a longer first message than before");
118
+
119
+ // A file of the same size and another time is looked into again too.
120
+ const now = statSync(path);
121
+ writeFileSync(path, meta(NATIVE) + message(1, "user", "A LONGER FIRST MESSAGE THAN BEFORE"));
122
+ utimesSync(path, now.atimeMs / 1000, now.mtimeMs / 1000 + 100);
123
+ expect(statSync(path).size).toBe(now.size);
124
+ expect((await titlesOf(side)).get(NATIVE)).toBe("A LONGER FIRST MESSAGE THAN BEFORE");
125
+ });
126
+
127
+ test("a session without a title is kept as such, until its file changes", async () => {
128
+ const spoke = meta(NATIVE) + message(1, "user", "somebody spoke");
129
+ // The text of the file as it is now is as long as the one it will be replaced with.
130
+ const silent = meta(NATIVE) + message(1, "assistant", "x");
131
+ const path = rollout(NATIVE, silent.replace('"x"', `"${"x".repeat(1 + spoke.length - silent.length)}"`));
132
+ const before = statSync(path);
133
+ const side = reading();
134
+ expect((await titlesOf(side)).get(NATIVE)).toBeUndefined();
135
+ writeFileSync(path, spoke);
136
+ utimesSync(path, before.atimeMs / 1000, before.mtimeMs / 1000);
137
+ expect(statSync(path).size).toBe(before.size);
138
+ expect((await titlesOf(side)).get(NATIVE)).toBeUndefined();
139
+ appendFileSync(path, message(2, "assistant", "x"));
140
+ expect((await titlesOf(side)).get(NATIVE)).toBe("somebody spoke");
141
+ });
142
+
143
+ test("a listing can be limited to some sessions, and the others are not read", async () => {
144
+ const OTHER = "00000000-0000-4000-8000-000000000002";
145
+ rollout(NATIVE, meta(NATIVE) + message(1, "user", "one"));
146
+ rollout(OTHER, meta(OTHER) + message(1, "user", "two"));
147
+ expect([...(await titlesOf(reading(), { natives: [OTHER] })).keys()]).toEqual([OTHER]);
148
+ expect((await titlesOf(reading(), { natives: [] })).size).toBe(0);
149
+ expect((await titlesOf(reading())).size).toBe(2);
150
+ });
151
+
152
+ test("the conversation layer is read; the event layer repeats are not read twice", async () => {
153
+ rollout(
154
+ NATIVE,
155
+ meta(NATIVE) +
156
+ message(1, "user", "hello") +
157
+ message(2, "assistant", "hi") +
158
+ record(3, "event_msg", {
159
+ type: "item_completed",
160
+ item: { type: "UserMessage", id: "item-1", content: [{ type: "text", text: "hello" }] },
161
+ }) +
162
+ record(4, "event_msg", {
163
+ type: "item_completed",
164
+ item: { type: "AgentMessage", id: "item-2", content: [{ type: "text", text: "hi" }] },
165
+ }),
166
+ );
167
+ const kinds = (await all(reading().read(ID))).map((r) => r.kind);
168
+ expect(kinds).toEqual(["user", "assistant"]);
169
+ });
170
+
171
+ test("a tool call and its result are paired; the result names the tool", async () => {
172
+ rollout(
173
+ NATIVE,
174
+ meta(NATIVE) +
175
+ record(1, "response_item", {
176
+ type: "function_call",
177
+ call_id: "call_1",
178
+ name: "shell",
179
+ arguments: JSON.stringify({ cmd: "ls" }),
180
+ }) +
181
+ record(2, "response_item", { type: "function_call_output", call_id: "call_1", output: "a.txt" }),
182
+ );
183
+ const records = await all(reading().read(ID));
184
+ expect(records.map((r) => r.kind)).toEqual(["tool-call", "tool-result"]);
185
+ expect(records[0]).toMatchObject({ callId: "call_1", name: "shell", input: { cmd: "ls" } });
186
+ expect(records[1]).toMatchObject({ callId: "call_1", name: "shell", output: "a.txt" });
187
+ });
188
+
189
+ test("a call is named by its category and its target; a patch is about the first file it names", async () => {
190
+ const patch = "*** Begin Patch\n*** Update File: src/a.ts\n@@\n-x\n+y\n*** Add File: src/b.ts\n+z\n*** End Patch";
191
+ rollout(
192
+ NATIVE,
193
+ meta(NATIVE) +
194
+ record(1, "response_item", { type: "function_call", call_id: "c1", name: "exec_command", arguments: JSON.stringify({ cmd: "bun test" }) }) +
195
+ record(2, "response_item", { type: "custom_tool_call", call_id: "c2", name: "apply_patch", input: patch }) +
196
+ record(3, "response_item", { type: "function_call", call_id: "c3", name: "update_plan", arguments: JSON.stringify({ plan: [] }) }) +
197
+ record(4, "response_item", { type: "function_call", call_id: "c4", name: "mcp__niwa__session_send", arguments: "{}" }) +
198
+ record(5, "response_item", { type: "function_call", call_id: "c5", name: "frobnicate", arguments: "{}" }),
199
+ );
200
+ const calls = (await all(reading().read(ID))).flatMap((r) => (r.kind === "tool-call" ? [r] : []));
201
+ expect(calls.map((c) => [c.category, c.target])).toEqual([
202
+ ["shell", "bun test"],
203
+ ["edit", "src/a.ts"],
204
+ ["plan", undefined],
205
+ ["mcp", undefined],
206
+ ["other", undefined],
207
+ ]);
208
+ });
209
+
210
+ test("an update_plan call leaves the checklist it wrote; arguments Codex would refuse leave none", async () => {
211
+ const plan = [
212
+ { step: "read", status: "completed" },
213
+ { step: "write", status: "in_progress" },
214
+ ];
215
+ rollout(
216
+ NATIVE,
217
+ meta(NATIVE) +
218
+ record(1, "response_item", { type: "function_call", call_id: "p1", name: "update_plan", arguments: JSON.stringify({ plan }) }) +
219
+ record(2, "response_item", { type: "function_call", call_id: "p2", name: "update_plan", arguments: JSON.stringify({ plan: "x" }) }),
220
+ );
221
+ const records = await all(reading().read(ID));
222
+ expect(records.map((r) => r.kind)).toEqual(["tool-call", "checklist", "tool-call"]);
223
+ expect(records[1]).toMatchObject({ callId: "p1", items: [{ text: "read", state: "done" }, { text: "write", state: "active" }] });
224
+ });
225
+
226
+ test("a subagent that was spawned is a nested record; a compaction is its own kind", async () => {
227
+ rollout(
228
+ NATIVE,
229
+ meta(NATIVE) +
230
+ record(1, "event_msg", {
231
+ type: "item_completed",
232
+ item: {
233
+ type: "SubAgentActivity",
234
+ kind: "started",
235
+ id: "call_1",
236
+ agent_thread_id: "00000000-0000-4000-8000-0000000000ff",
237
+ },
238
+ }) +
239
+ record(2, "compacted", { message: "what happened so far" }),
240
+ );
241
+ const records = await all(reading().read(ID));
242
+ expect(records.map((r) => r.kind)).toEqual(["nested", "compaction"]);
243
+ expect(records[0]).toMatchObject({
244
+ child: { native: "00000000-0000-4000-8000-0000000000ff" },
245
+ });
246
+ expect(records[1]).toMatchObject({ summary: "what happened so far" });
247
+ });
248
+
249
+ test("the replayed history of a parent is not this session's own history", async () => {
250
+ rollout(
251
+ NATIVE,
252
+ meta(NATIVE, 0) +
253
+ record(1, "session_meta", { id: "parent", timestamp: "2026-01-01T00:00:00.000Z" }) +
254
+ message(2, "user", "from the parent") +
255
+ record(3, "turn_context", { turn_id: "t1", model: "gpt-x", cwd: "/work/x" }) +
256
+ message(4, "user", "mine"),
257
+ );
258
+ const records = await all(reading().read(ID));
259
+ expect(records.map((r) => r.kind)).toEqual(["user"]);
260
+ expect(records[0]).toMatchObject({ text: "mine" });
261
+ });
262
+
263
+ test("an unfamiliar record is unknown with its raw kept, and reading does not stop at it", async () => {
264
+ rollout(NATIVE, meta(NATIVE) + '{"unfamiliar":"shape"}\n' + message(1, "user", "after"));
265
+ const records = await all(reading().read(ID));
266
+ expect(records.map((r) => r.kind)).toEqual(["unknown", "user"]);
267
+ expect(records[0]).toMatchObject({ raw: { unfamiliar: "shape" } });
268
+ });
269
+
270
+ test("H3 a half-written tail is marked incomplete and is delivered again once whole", async () => {
271
+ const whole = message(2, "assistant", "second");
272
+ const path = rollout(NATIVE, meta(NATIVE) + message(1, "user", "first") + whole.slice(0, 20));
273
+ const first = await all(reading().read(ID));
274
+ expect(first.map((r) => r.incomplete)).toEqual([false, true]);
275
+ expect(await reading().coverage(ID, first[0]?.locator)).toEqual({ status: "not-scanned" });
276
+
277
+ appendFileSync(path, whole.slice(20));
278
+ const rest = await all(reading().read(ID, first[0]?.locator));
279
+ expect(rest).toHaveLength(1);
280
+ expect(rest[0]).toMatchObject({ kind: "assistant", text: "second", incomplete: false });
281
+
282
+ // Resuming from the marked tail reads it again, never past it.
283
+ expect(await all(reading().read(ID, first[1]?.locator))).toHaveLength(1);
284
+ });
285
+
286
+ test("a locator resumes exactly", async () => {
287
+ rollout(NATIVE, meta(NATIVE) + message(1, "user", "u1") + message(2, "assistant", "u2"));
288
+ const full = await all(reading().read(ID));
289
+ expect(full).toHaveLength(2);
290
+ for (let i = 0; i < full.length; i += 1) {
291
+ const rest = await all(reading().read(ID, full[i]?.locator));
292
+ expect(rest.map((r) => r.locator)).toEqual(full.slice(i + 1).map((r) => r.locator));
293
+ }
294
+ expect(await reading().coverage(ID, full[1]?.locator)).toEqual({ status: "empty" });
295
+ });
296
+
297
+ test("a rewritten file is detected: the read restarts and raw refuses the old locator", async () => {
298
+ const path = rollout(NATIVE, meta(NATIVE) + message(1, "user", "one") + message(2, "user", "two"));
299
+ const [, second] = await all(reading().read(ID));
300
+ const old = second?.locator as Locator;
301
+
302
+ writeFileSync(path, meta(NATIVE) + message(1, "user", "ONE") + message(2, "user", "TWO"));
303
+ const again = await all(reading().read(ID, old));
304
+ expect(again).toHaveLength(2);
305
+ // The read began again, and the first record says so; the ones after it do not.
306
+ expect(again.map((r) => r.reanchored)).toEqual([true, undefined]);
307
+ expect((await all(reading().read(ID, again[0]?.locator))).some((r) => r.reanchored === true)).toBe(false);
308
+ await expect(reading().raw(ID, old)).rejects.toThrow("does not belong");
309
+ });
310
+
311
+ test("a record rewritten in place far into the file is detected, though the file is as long as before", async () => {
312
+ // The first message is longer than any prefix a revision could be limited to.
313
+ const text = (late: string): string =>
314
+ meta(NATIVE) + message(1, "user", "x".repeat(6000)) + message(2, "user", "two") + message(3, "user", late);
315
+ const path = rollout(NATIVE, text("late one"));
316
+ const [, second, third] = await all(reading().read(ID));
317
+ const [secondAt, thirdAt] = [second?.locator as Locator, third?.locator as Locator];
318
+ expect(await reading().raw(ID, thirdAt)).toMatchObject({ payload: { content: [{ text: "late one" }] } });
319
+
320
+ // The same length, at the same place: only the content differs.
321
+ writeFileSync(path, text("LATE ONE"));
322
+ await expect(reading().raw(ID, thirdAt)).rejects.toThrow("does not belong");
323
+ // The locator before the rewritten record is still good, and a read from it delivers the new text.
324
+ const rest = await all(reading().read(ID, secondAt));
325
+ expect(rest).toHaveLength(1);
326
+ expect(rest[0]).toMatchObject({ kind: "user", text: "LATE ONE" });
327
+
328
+ // A rewrite of the record the locator names is no longer the position it was.
329
+ writeFileSync(path, text("late one").replace("two", "TWO"));
330
+ await expect(reading().raw(ID, secondAt)).rejects.toThrow("does not belong");
331
+ expect(await all(reading().read(ID, secondAt))).toHaveLength(3);
332
+ });
333
+
334
+ test("a compressed rollout rewritten in place far into the file is detected too", async () => {
335
+ const dir = join(home, "sessions", "2026", "01", "01");
336
+ mkdirSync(dir, { recursive: true });
337
+ const path = join(dir, `rollout-2026-01-01T00-00-00-${NATIVE}.jsonl.zst`);
338
+ const text = (late: string): string => meta(NATIVE) + message(1, "user", "x".repeat(6000)) + message(2, "user", late);
339
+ writeFileSync(path, Bun.zstdCompressSync(Buffer.from(text("late one"))));
340
+ const [, second] = await all(reading().read(ID));
341
+ const old = second?.locator as Locator;
342
+
343
+ writeFileSync(path, Bun.zstdCompressSync(Buffer.from(text("LATE ONE"))));
344
+ await expect(reading().raw(ID, old)).rejects.toThrow("does not belong");
345
+ });
346
+
347
+ test("the compressed copy of a rollout is the same session and is read", async () => {
348
+ const dir = join(home, "sessions", "2026", "01", "01");
349
+ mkdirSync(dir, { recursive: true });
350
+ const text = meta(NATIVE) + message(1, "user", "hello") + message(2, "assistant", "hi");
351
+ const plain = join(dir, `rollout-2026-01-01T00-00-00-${NATIVE}.jsonl`);
352
+ writeFileSync(plain, text);
353
+ // Codex compresses a cold rollout itself: the same JSONL in a zstd container.
354
+ writeFileSync(`${plain}.zst`, Bun.zstdCompressSync(Buffer.from(text)));
355
+
356
+ const infos = [];
357
+ for await (const info of reading().list()) infos.push(info);
358
+ // One session, not two: the compressed copy is the same rollout.
359
+ expect(infos).toHaveLength(1);
360
+
361
+ const records = await all(reading().read(ID));
362
+ expect(records.map((r) => r.kind)).toEqual(["user", "assistant"]);
363
+ expect(records[0]).toMatchObject({ text: "hello" });
364
+ });
365
+
366
+ test("listing reads the head of each rollout and leaves no file open, compressed or not", async () => {
367
+ const FILES = 200;
368
+ const dir = join(home, "sessions", "2026", "01", "01");
369
+ mkdirSync(dir, { recursive: true });
370
+ // Long rollouts, so the listing stops reading each one long before its end.
371
+ const tail = Array.from({ length: 4_000 }, (_, i) => message(i + 2, "assistant", `line ${i} ${"x".repeat(80)}`)).join("");
372
+ for (let i = 0; i < FILES; i += 1) {
373
+ const native = `00000000-0000-4000-8000-${String(100_000 + i).padStart(12, "0")}`;
374
+ const text = meta(native) + message(1, "user", "hello") + tail;
375
+ const path = join(dir, `rollout-2026-01-01T00-00-00-${native}.jsonl`);
376
+ if (i % 2 === 0) writeFileSync(`${path}.zst`, Bun.zstdCompressSync(Buffer.from(text)));
377
+ else writeFileSync(path, text);
378
+ }
379
+ const open = () => readdirSync("/dev/fd").length;
380
+ const before = open();
381
+ const infos = [];
382
+ for await (const info of reading().list()) infos.push(info);
383
+ expect(infos).toHaveLength(FILES);
384
+ // Let closed streams settle before counting. Without the fix every compressed rollout keeps a
385
+ // descriptor (FILES / 2 of them), far above the few the runtime itself keeps.
386
+ await Bun.sleep(100);
387
+ expect(open() - before).toBeLessThan(10);
388
+ });
389
+
390
+ test("raw gives the harness's own record whole; coverage states what it does not know", async () => {
391
+ rollout(NATIVE, meta(NATIVE) + message(1, "user", "hi"));
392
+ const [rec] = await all(reading().read(ID));
393
+ expect(await reading().raw(ID, rec?.locator as Locator)).toMatchObject({
394
+ type: "response_item",
395
+ payload: { type: "message", role: "user" },
396
+ });
397
+ const missing = sessionId(harnessId("codex-test"), "00000000-0000-4000-8000-0000000000ee");
398
+ expect((await reading().coverage(missing)).status).toBe("unavailable");
399
+ await expect(reading().raw(ID, "bogus" as Locator)).rejects.toThrow("not of this side");
400
+ });
401
+
402
+ test("a reasoning item is a thinking record: its words, else its summaries, else a sealed thought; the item stays behind raw", async () => {
403
+ const reasoning = (ordinal: number, payload: Record<string, unknown>): string =>
404
+ record(ordinal, "response_item", { type: "reasoning", id: `rs_${ordinal}`, ...payload });
405
+ rollout(
406
+ NATIVE,
407
+ meta(NATIVE) +
408
+ reasoning(1, { summary: [], content: [{ type: "reasoning_text", text: "first the parser" }], encrypted_content: "sealed" }) +
409
+ reasoning(2, { summary: [{ type: "summary_text", text: "Read the parser" }, { type: "summary_text", text: "Fix it" }], encrypted_content: "sealed" }) +
410
+ reasoning(3, { summary: [], content: null, encrypted_content: "sealed" }) +
411
+ reasoning(4, { summary: [] }),
412
+ );
413
+ const records = await all(reading().read(ID));
414
+ expect(records.map((r) => r.kind)).toEqual(["thinking", "thinking", "thinking", "unknown"]);
415
+ expect(records[0]).toMatchObject({ text: "first the parser", redacted: false });
416
+ expect(records[1]).toMatchObject({ text: "Read the parser\nFix it", redacted: false });
417
+ expect(records[2]).toMatchObject({ text: "", redacted: true });
418
+ expect(await reading().raw(ID, records[2]?.locator as Locator)).toMatchObject({
419
+ payload: { type: "reasoning", id: "rs_3", encrypted_content: "sealed" },
420
+ });
421
+ });
422
+
423
+ test("a resumed read keeps what the earlier lines said: the tool's name and the model", async () => {
424
+ rollout(
425
+ NATIVE,
426
+ meta(NATIVE) +
427
+ record(1, "turn_context", { turn_id: "t1", model: "gpt-x" }) +
428
+ record(2, "response_item", { type: "function_call", call_id: "c1", name: "shell", arguments: "{}" }) +
429
+ record(3, "response_item", { type: "function_call_output", call_id: "c1", output: "ok" }) +
430
+ message(4, "assistant", "done"),
431
+ );
432
+ const full = await all(reading().read(ID));
433
+ const resumed = await all(reading().read(ID, full[0]?.locator));
434
+ expect(resumed).toEqual(full.slice(1));
435
+ expect(resumed[0]).toMatchObject({ kind: "tool-result", name: "shell" });
436
+ expect(resumed[1]).toMatchObject({ kind: "assistant", model: "gpt-x" });
437
+ });
438
+
439
+ test("a legacy rollout's subagent event is nested; a compaction is one record, not two", async () => {
440
+ rollout(
441
+ NATIVE,
442
+ meta(NATIVE) +
443
+ record(1, "event_msg", {
444
+ type: "sub_agent_activity",
445
+ event_id: "e1",
446
+ agent_thread_id: "00000000-0000-4000-8000-0000000000ff",
447
+ kind: "started",
448
+ }) +
449
+ record(2, "compacted", { message: "", retained_context: { user_messages: [{ text: "keep me" }] } }) +
450
+ record(3, "event_msg", { type: "context_compacted" }) +
451
+ record(4, "event_msg", { type: "item_completed", item: { type: "ContextCompaction", id: "i1" } }),
452
+ );
453
+ const records = await all(reading().read(ID));
454
+ expect(records.map((r) => r.kind)).toEqual(["nested", "compaction"]);
455
+ expect(records[1]).toMatchObject({ summary: "owner: keep me" });
456
+ });
457
+
458
+ test("a session is updated when its file was, and is listed under the id control uses", async () => {
459
+ rollout(NATIVE, meta(NATIVE) + message(1, "user", "hello"));
460
+ const [info] = await (async () => {
461
+ const out = [];
462
+ for await (const i of reading().list()) out.push(i);
463
+ return out;
464
+ })();
465
+ expect(info?.updatedAt).toBeGreaterThan(Date.parse("2026-06-01") as never);
466
+ expect(info?.id).toEqual(ID);
467
+ });
468
+
469
+ test("a line that is not valid UTF-8 does not move the locators of the lines after it", async () => {
470
+ const path = rollout(NATIVE, "");
471
+ const bad = Buffer.concat([Buffer.from('{"type":"x","payload":"'), Buffer.from([0xff, 0xfe]), Buffer.from('"}\n')]);
472
+ writeFileSync(path, Buffer.concat([bad, Buffer.from(meta(NATIVE) + message(1, "user", "one") + message(2, "user", "two"))]));
473
+ const full = await all(reading().read(ID));
474
+ const resumed = await all(reading().read(ID, full[1]?.locator));
475
+ expect(resumed).toEqual(full.slice(2));
476
+ expect(await reading().raw(ID, full[2]?.locator as Locator)).toMatchObject({ type: "response_item" });
477
+ });
478
+
479
+ test("a patch that names several files lists every one of them, a move by where the file goes", async () => {
480
+ const patch = "*** Begin Patch\n*** Update File: src/a.ts\n*** Move to: src/c.ts\n@@\n-x\n+y\n*** Add File: src/b.ts\n+z\n*** Delete File: src/d.ts\n*** End Patch";
481
+ const single = "*** Begin Patch\n*** Update File: src/only.ts\n@@\n-x\n+y\n*** End Patch";
482
+ rollout(
483
+ NATIVE,
484
+ meta(NATIVE) +
485
+ record(1, "response_item", { type: "custom_tool_call", call_id: "c1", name: "apply_patch", input: patch }) +
486
+ record(2, "response_item", { type: "custom_tool_call", call_id: "c2", name: "apply_patch", input: single }),
487
+ );
488
+ const [many, one] = (await all(reading().read(ID))).flatMap((r) => (r.kind === "tool-call" ? [r] : []));
489
+ expect(many).toMatchObject({ target: "src/a.ts", paths: ["src/a.ts", "src/c.ts", "src/b.ts", "src/d.ts"] });
490
+ expect(one?.target).toBe("src/only.ts");
491
+ expect(one?.paths).toBeUndefined();
492
+ });
493
+
494
+ test("a message marks what Codex inserted, and a result and a message keep their pictures as marks", async () => {
495
+ const environment = "<environment_context>\n <cwd>/work/x</cwd>\n</environment_context>";
496
+ const png = "data:image/png;base64,AAAA";
497
+ rollout(
498
+ NATIVE,
499
+ meta(NATIVE) +
500
+ record(1, "response_item", { type: "message", role: "user", content: [{ type: "input_text", text: environment }, { type: "input_text", text: "Fix <user-card>x</user-card>" }, { type: "input_image", image_url: png }] }) +
501
+ record(2, "response_item", { type: "function_call", call_id: "c1", name: "view_image", arguments: JSON.stringify({ path: "/a.png" }) }) +
502
+ record(3, "response_item", { type: "function_call_output", call_id: "c1", output: [{ type: "input_text", text: "shown" }, { type: "input_image", image_url: png }] }),
503
+ );
504
+ const [user, , result] = await all(reading().read(ID));
505
+ expect(user).toMatchObject({
506
+ kind: "user",
507
+ text: `${environment}\nFix <user-card>x</user-card>`,
508
+ inserted: [{ from: 0, to: environment.length + 1, origin: "harness" }],
509
+ images: [{ at: environment.length + 1 + "Fix <user-card>x</user-card>".length, mime: "image/png" }],
510
+ });
511
+ expect(result).toMatchObject({ kind: "tool-result", output: "shown", images: [{ at: 5, mime: "image/png" }] });
512
+ expect(JSON.stringify([user, result])).not.toContain("AAAA");
513
+ });
@@ -0,0 +1,21 @@
1
+ {"method": "remoteControl/status/changed", "params": {"status": "disabled", "serverName": "example", "installationId": "example", "environmentId": null}, "emittedAtMs": 1795130651698}
2
+ {"method": "account/updated", "params": {"authMode": "chatgpt", "planType": "plus"}, "emittedAtMs": 1795130652065}
3
+ {"method": "thread/started", "params": {"thread": {"id": "00000000-0000-4000-8000-000000000001", "environments": [{"environmentId": "local", "cwd": "/work/work", "runtimeWorkspaceRoots": ["/work/work"]}], "extra": null, "sessionId": "00000000-0000-4000-8000-000000000001", "forkedFromId": null, "attachedToThreadId": null, "parentThreadId": null, "preview": "", "ephemeral": false, "section": null, "sectionEnteredAt": null, "projectId": null, "historyMode": "paginated", "modelProvider": "openai", "model": "gpt-6.2-astra", "reasoningEffort": "high", "createdAt": 1795130652, "updatedAt": 1795130652, "recencyAt": 1795130652, "status": {"type": "idle"}, "path": "/home/user/.codex/sessions/2026/11/20/rollout-2026-11-20T02-24-12-00000000-0000-4000-8000-000000000001.jsonl", "cwd": "/work/work", "cliVersion": "0.169.0-alpha.11.1", "originator": "niwa", "source": "vscode", "canAcceptDirectInput": true, "threadSource": null, "agentNickname": null, "agentRole": null, "gitInfo": null, "name": null, "daybreakEnabled": null, "turns": []}}, "emittedAtMs": 1795130675298}
4
+ {"method": "warning", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "message": "Codex is ignoring 2 unrecognized configuration settings."}, "emittedAtMs": 1795130675299}
5
+ {"method": "mcpServer/startupStatus/updated", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "name": "example", "status": "starting", "error": null, "failureReason": null}, "emittedAtMs": 1795130675299}
6
+ {"method": "thread/status/changed", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "status": {"type": "active", "activeFlags": []}}, "emittedAtMs": 1795130675851}
7
+ {"method": "turn/started", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "turn": {"id": "00000000-0000-4000-8000-000000000002", "rootTurnId": "00000000-0000-4000-8000-000000000002", "items": [], "itemsView": "notLoaded", "status": "inProgress", "error": null, "startedAt": 1795130675, "completedAt": null, "durationMs": null}}, "emittedAtMs": 1795130675851}
8
+ {"method": "hook/started", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "run": {"id": "session-start:0", "eventName": "sessionStart", "handlerType": "command", "executionMode": "sync", "scope": "thread", "sourcePath": "/home/user/.codex/config.toml", "source": "user", "displayOrder": 0, "status": "running", "statusMessage": null, "startedAt": 1795130676, "completedAt": null, "durationMs": null, "entries": []}}, "emittedAtMs": 1795130676669}
9
+ {"method": "hook/completed", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "run": {"id": "session-start:0", "eventName": "sessionStart", "handlerType": "command", "executionMode": "sync", "scope": "thread", "sourcePath": "/home/user/.codex/config.toml", "source": "user", "displayOrder": 0, "status": "completed", "statusMessage": null, "startedAt": 1795130676, "completedAt": 1795130678, "durationMs": 2049, "entries": []}}, "emittedAtMs": 1795130678717}
10
+ {"method": "item/started", "params": {"item": {"type": "userMessage", "id": "00000000-0000-4000-8000-000000000003", "clientId": null, "content": [{"type": "text", "text": "Reply with exactly: ok", "text_elements": []}], "startedAtMs": 1795130678725, "completedAtMs": null}, "threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "startedAtMs": 1795130678725}, "emittedAtMs": 1795130678725}
11
+ {"method": "item/completed", "params": {"item": {"type": "userMessage", "id": "00000000-0000-4000-8000-000000000003", "clientId": null, "content": [{"type": "text", "text": "Reply with exactly: ok", "text_elements": []}], "startedAtMs": 1795130678725, "completedAtMs": 1795130678725}, "threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "contentTokenCount": null, "completedAtMs": 1795130678725}, "emittedAtMs": 1795130678758}
12
+ {"method": "item/started", "params": {"item": {"type": "agentMessage", "moderation": null, "id": "msg_0cc6426d94458611016aff853981bc87d296fca1e617d94301", "text": "", "phase": "final_answer", "memoryCitation": null, "delivery": null, "questions": null, "startedAtMs": 1795130681552, "completedAtMs": null}, "threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "startedAtMs": 1795130681552}, "emittedAtMs": 1795130681553}
13
+ {"method": "item/agentMessage/delta", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "itemId": "msg_0cc6426d94458611016aff853981bc87d296fca1e617d94301", "delta": "ok"}, "emittedAtMs": 1795130681553}
14
+ {"method": "item/completed", "params": {"item": {"type": "agentMessage", "moderation": null, "id": "msg_0cc6426d94458611016aff853981bc87d296fca1e617d94301", "text": "ok", "phase": "final_answer", "memoryCitation": null, "delivery": null, "questions": null, "startedAtMs": 1795130681552, "completedAtMs": 1795130681727}, "threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "contentTokenCount": 2, "completedAtMs": 1795130681727}, "emittedAtMs": 1795130681730}
15
+ {"method": "thread/tokenUsage/updated", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "turnId": "00000000-0000-4000-8000-000000000002", "tokenUsage": {"total": {"totalTokens": 26621, "inputTokens": 26616, "cachedInputTokens": 7296, "cacheWriteInputTokens": 0, "outputTokens": 5, "reasoningOutputTokens": 0}, "last": {"totalTokens": 26621, "inputTokens": 26616, "cachedInputTokens": 7296, "cacheWriteInputTokens": 0, "outputTokens": 5, "reasoningOutputTokens": 0}, "modelContextWindow": 258400}}, "emittedAtMs": 1795130681743}
16
+ {"method": "account/rateLimits/updated", "params": {"rateLimits": {"limitId": "codex", "limitName": null, "normalModelSlug": null, "primary": {"usedPercent": 15, "windowDurationMins": 10080, "resetsAt": 1795347625}, "secondary": null, "credits": {"hasCredits": true, "unlimited": false, "balance": "60531.6507835000"}, "individualLimit": null, "spendControlReached": null, "planType": "plus", "rateLimitReachedType": null}}, "emittedAtMs": 1795130681743}
17
+ {"method": "turn/completed", "params": {"threadId": "00000000-0000-4000-8000-000000000001", "turn": {"id": "00000000-0000-4000-8000-000000000002", "rootTurnId": "00000000-0000-4000-8000-000000000002", "items": [{"type": "agentMessage", "moderation": null, "id": "msg_0cc6426d94458611016aff853981bc87d296fca1e617d94301", "text": "ok", "phase": "final_answer", "memoryCitation": null, "delivery": null, "questions": null, "startedAtMs": 1795130681552, "completedAtMs": 1795130681727}], "itemsView": "summary", "status": "completed", "error": null, "startedAt": 1795130675, "completedAt": 1795130681, "durationMs": 6428}}, "emittedAtMs": 1795130681849}
18
+ {"method": "item/started", "params": {"item": {"type": "commandExecution", "id": "exec-00000000-0000-4000-8000-000000000004", "pluginId": null, "scriptPath": null, "command": "/bin/zsh -lc 'touch /work/outside.txt'", "cwd": "/work/work", "processId": null, "source": "agent", "status": "inProgress", "commandActions": [{"type": "unknown", "command": "touch /work/outside.txt"}], "aggregatedOutput": null, "exitCode": null, "durationMs": null, "startedAtMs": 1795130762873, "completedAtMs": null}, "threadId": "00000000-0000-4000-8000-000000000005", "turnId": "00000000-0000-4000-8000-000000000006", "startedAtMs": 1795130762873}, "emittedAtMs": 1795130762882}
19
+ {"method": "item/commandExecution/requestApproval", "id": 0, "params": {"kind": "command", "threadId": "00000000-0000-4000-8000-000000000005", "turnId": "00000000-0000-4000-8000-000000000006", "itemId": "exec-00000000-0000-4000-8000-000000000004", "startedAtMs": 1795130762873, "environmentId": "local", "reason": "Allow the requested touch command to write outside the read-only workspace?", "command": "/bin/zsh -lc 'touch /work/outside.txt'", "cwd": "/work/work", "commandActions": [{"type": "unknown", "command": "touch /work/outside.txt"}], "proposedExecpolicyAmendment": ["touch", "/work/outside.txt"], "availableDecisions": ["accept", {"acceptWithExecpolicyAmendment": {"execpolicy_amendment": ["touch", "/work/outside.txt"]}}, "cancel"]}}
20
+ {"method": "serverRequest/resolved", "params": {"threadId": "00000000-0000-4000-8000-000000000005", "requestId": 0}, "emittedAtMs": 1795130762904}
21
+ {"method": "item/completed", "params": {"item": {"type": "commandExecution", "id": "exec-00000000-0000-4000-8000-000000000004", "pluginId": null, "scriptPath": null, "command": "/bin/zsh -lc 'touch /work/outside.txt'", "cwd": "/work/work", "processId": null, "source": "agent", "status": "declined", "commandActions": [{"type": "unknown", "command": "touch /work/outside.txt"}], "aggregatedOutput": null, "exitCode": null, "durationMs": null, "startedAtMs": 1795130762873, "completedAtMs": 1795130762914}, "threadId": "00000000-0000-4000-8000-000000000005", "turnId": "00000000-0000-4000-8000-000000000006", "contentTokenCount": null, "completedAtMs": 1795130762914}, "emittedAtMs": 1795130762917}
@@ -0,0 +1,88 @@
1
+ /**
2
+ * The frames of a fake `codex app-server`, written as the real one writes them: the field
3
+ * names and the shape of each are those of the frames captured from codex-cli 0.169
4
+ * (`codex-app-server/captured.jsonl`). A fake that sends a frame the real server never would
5
+ * proves nothing about how a frame is read, so a test of the control side builds its frames here.
6
+ *
7
+ * This module imports nothing: the fakes run as scripts of their own and import it by path.
8
+ */
9
+
10
+ export type TurnStatus = "inProgress" | "completed" | "failed" | "interrupted";
11
+
12
+ /** A turn as `turn/started` and `turn/completed` carry it. */
13
+ export function turnOf(id: string, status: TurnStatus, error?: string) {
14
+ return {
15
+ id,
16
+ rootTurnId: id,
17
+ items: [],
18
+ itemsView: "notLoaded",
19
+ status,
20
+ error: error === undefined ? null : { message: error },
21
+ startedAt: 1,
22
+ completedAt: status === "inProgress" ? null : 2,
23
+ durationMs: status === "inProgress" ? null : 1000,
24
+ };
25
+ }
26
+
27
+ export function turnStarted(threadId: string, turnId: string) {
28
+ return { method: "turn/started", params: { threadId, turn: turnOf(turnId, "inProgress") } };
29
+ }
30
+
31
+ export function turnCompleted(threadId: string, turnId: string, status: TurnStatus, error?: string) {
32
+ return { method: "turn/completed", params: { threadId, turn: turnOf(turnId, status, error) } };
33
+ }
34
+
35
+ /** The agent's message, finished: `phase` is what says whether it is the answer of the turn. */
36
+ export function agentMessageCompleted(threadId: string, turnId: string, text: string, phase: string | null = "final_answer") {
37
+ return {
38
+ method: "item/completed",
39
+ params: {
40
+ threadId,
41
+ turnId,
42
+ contentTokenCount: null,
43
+ completedAtMs: 2,
44
+ item: {
45
+ type: "agentMessage",
46
+ id: `message-${turnId}`,
47
+ text,
48
+ phase,
49
+ moderation: null,
50
+ memoryCitation: null,
51
+ delivery: null,
52
+ questions: null,
53
+ startedAtMs: 1,
54
+ completedAtMs: 2,
55
+ },
56
+ },
57
+ };
58
+ }
59
+
60
+ /** A file change Codex announces: the approval of it names no path, so the paths are told here. */
61
+ export function fileChangeStarted(threadId: string, turnId: string, itemId: string, paths: readonly string[]) {
62
+ return {
63
+ method: "item/started",
64
+ params: {
65
+ threadId,
66
+ turnId,
67
+ startedAtMs: 1,
68
+ item: {
69
+ type: "fileChange",
70
+ id: itemId,
71
+ status: "inProgress",
72
+ changes: paths.map((path) => ({ path, kind: { type: "add" }, diff: "x" })),
73
+ startedAtMs: 1,
74
+ completedAtMs: null,
75
+ },
76
+ },
77
+ };
78
+ }
79
+
80
+ /** A request of Codex that waits for the client; `params` are the fields the request adds to its thread and turn. */
81
+ export function serverRequest(id: string | number, method: string, threadId: string, turnId: string, params: Record<string, unknown>) {
82
+ return { id, method, params: { threadId, turnId, ...params } };
83
+ }
84
+
85
+ /** What a command approval carries, as the captured request does. */
86
+ export function commandApprovalParams(params: Record<string, unknown>) {
87
+ return { kind: "command", itemId: "call-1", startedAtMs: 1, environmentId: null, ...params };
88
+ }