@niwa-labs/harness-mcode 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,1153 @@
1
+ /**
2
+ * The reading side of a MiniMax Code installation. It works
3
+ * from the files and copies nothing. The format is in `format.ts`, the layout in `paths.ts`.
4
+ *
5
+ * A locator is `mcode:v1:<prefixBytes>:<prefixHash>:<offset>:<after>`: the head of the journal it
6
+ * was taken from (a rewritten or truncated file is detected), the start of the line, and how many
7
+ * of that line's records were already delivered. A half-written tail line has `after = 0`, so a
8
+ * resume reads it again once it is whole.
9
+ */
10
+
11
+ import { createHash } from "node:crypto";
12
+ import { existsSync } from "node:fs";
13
+ import { open, readFile, stat } from "node:fs/promises";
14
+ import type { FileHandle } from "node:fs/promises";
15
+ import { join } from "node:path";
16
+
17
+ import { z } from "zod";
18
+
19
+ import { jsonOf, timestamp } from "@niwa-labs/core";
20
+ import type { Timestamp } from "@niwa-labs/core";
21
+ import type {
22
+ HarnessId,
23
+ Coverage,
24
+ Locator,
25
+ SessionFilter,
26
+ SessionId,
27
+ SessionInfo,
28
+ SessionReading,
29
+ SessionRecord,
30
+ } from "@niwa-labs/harness";
31
+ import {
32
+ EMPTY,
33
+ LocatorSchema,
34
+ NOT_SCANNED,
35
+ NativeSessionIdSchema,
36
+ failedCoverage,
37
+ firstMessageTitle,
38
+ titleFromText,
39
+ unavailableCoverage,
40
+ } from "@niwa-labs/harness";
41
+
42
+ import {
43
+ ManifestSchema,
44
+ RawRecordSchema,
45
+ isWrappedNoise,
46
+ millisOf,
47
+ parseNativeRecord,
48
+ readAgentContext,
49
+ stripHarnessNoise,
50
+ textOf,
51
+ } from "./format.ts";
52
+ import type { AgentContext, Manifest, McodeMessage, McodeRecord } from "./format.ts";
53
+ import {
54
+ durableFirst,
55
+ durableHasSession,
56
+ durablePathOf,
57
+ durableSessions,
58
+ messageIdOf,
59
+ readDurableSession,
60
+ readView,
61
+ sessionDurablePath,
62
+ sessionStoreIds,
63
+ STOP,
64
+ } from "./durable.ts";
65
+ import type { DurableTurn } from "./durable.ts";
66
+ import { parseLedger } from "./ledger.ts";
67
+ import type { LedgerContent, LedgerLine, LedgerTurn } from "./ledger.ts";
68
+ import {
69
+ dirNameHoldsId,
70
+ encodeNativeId,
71
+ isSessionDir,
72
+ ledgerPathOf,
73
+ logPathOf,
74
+ manifestPathOf,
75
+ nativeIdFromDirName,
76
+ subdirsOf,
77
+ } from "./paths.ts";
78
+ import { runtimeStatePathOf, sessionTitles } from "./titles.ts";
79
+ import { mcodeChecklist, mcodeToolShape } from "./tools.ts";
80
+
81
+ export interface McodeReadingOptions {
82
+ /** The id of the installation this side serves. */
83
+ readonly harness: HarnessId;
84
+ /** The directory that holds `v2/sessions`. */
85
+ readonly home: string;
86
+ /** Read the fork's canonical per-session databases before its older history sources. */
87
+ readonly perSessionHistory?: boolean;
88
+ }
89
+
90
+ const CHUNK_SIZE = 65_536;
91
+ /** Bytes of the head of the journal the revision hashes. */
92
+ const PREFIX_BYTES = 4096;
93
+ /** Listing looks for the preamble only in lines that start inside this much of the head. */
94
+ const HEAD_BYTES = 65_536;
95
+
96
+ /** A record before the reading side has put its locator in. */
97
+ type Unlocated = SessionRecord extends infer R ? (R extends unknown ? Omit<R, "locator"> : never) : never;
98
+
99
+ interface RecordBase {
100
+ readonly at?: number;
101
+ readonly incomplete: boolean;
102
+ }
103
+
104
+ interface RawLine {
105
+ /** Offset of the start of the line. */
106
+ readonly byte: number;
107
+ /** The bytes without the LF. */
108
+ readonly bytes: Uint8Array;
109
+ /** `false` — no LF yet: the half-written tail of the journal. */
110
+ readonly complete: boolean;
111
+ }
112
+
113
+ interface FoundSession {
114
+ readonly dirName: string;
115
+ readonly logPath: string;
116
+ readonly manifestPath: string;
117
+ readonly ledgerPath: string;
118
+ }
119
+
120
+ /** A locator read back. */
121
+ interface Position {
122
+ readonly prefixBytes: number;
123
+ readonly prefixHash: string;
124
+ readonly offset: number;
125
+ readonly after: number;
126
+ }
127
+
128
+ /** Lines of a file from `fromByte` (a line start), streamed; memory holds one chunk and one line. */
129
+ async function* scanLines(handle: FileHandle, fromByte: number): AsyncGenerator<RawLine> {
130
+ const chunk = Buffer.allocUnsafe(CHUNK_SIZE);
131
+ let filePos = fromByte;
132
+ let lineStart = fromByte;
133
+ let carry: Buffer[] = [];
134
+ let carryLen = 0;
135
+ for (;;) {
136
+ const { bytesRead } = await handle.read(chunk, 0, CHUNK_SIZE, filePos);
137
+ if (bytesRead === 0) break;
138
+ filePos += bytesRead;
139
+ let from = 0;
140
+ for (;;) {
141
+ const lf = chunk.indexOf(0x0a, from);
142
+ if (lf < 0 || lf >= bytesRead) break;
143
+ const part = chunk.subarray(from, lf);
144
+ const bytes = carry.length === 0 ? part : Buffer.concat([...carry, part]);
145
+ yield { byte: lineStart, bytes, complete: true };
146
+ lineStart += carryLen + (lf - from) + 1;
147
+ carry = [];
148
+ carryLen = 0;
149
+ from = lf + 1;
150
+ }
151
+ if (from < bytesRead) {
152
+ carry.push(Buffer.from(chunk.subarray(from, bytesRead)));
153
+ carryLen += bytesRead - from;
154
+ }
155
+ }
156
+ if (carryLen > 0) {
157
+ yield { byte: lineStart, bytes: Buffer.concat(carry), complete: false };
158
+ }
159
+ }
160
+
161
+ /** A line as JSON; text that does not parse is kept as text, never an error. */
162
+ function parseLine(bytes: Uint8Array): unknown {
163
+ const text = new TextDecoder().decode(bytes);
164
+ try {
165
+ return JSON.parse(text);
166
+ } catch {
167
+ return text;
168
+ }
169
+ }
170
+
171
+ function isBlank(bytes: Uint8Array): boolean {
172
+ return bytes.every((b) => b === 0x20 || b === 0x09 || b === 0x0d);
173
+ }
174
+
175
+ async function prefixOf(handle: FileHandle, count: number): Promise<Buffer> {
176
+ const buffer = Buffer.alloc(count);
177
+ const { bytesRead } = await handle.read(buffer, 0, count, 0);
178
+ return buffer.subarray(0, bytesRead);
179
+ }
180
+
181
+ function hashOf(bytes: Uint8Array): string {
182
+ return createHash("sha256").update(bytes).digest("hex");
183
+ }
184
+
185
+ /**
186
+ * Does the position still mean what it meant? The journal is only appended to, so its head stays;
187
+ * a rewritten or truncated file fails the head hash, the size, or the line boundary.
188
+ */
189
+ async function positionHolds(handle: FileHandle, position: Position): Promise<boolean> {
190
+ const { size } = await handle.stat();
191
+ if (position.offset >= size) return false;
192
+ const head = await prefixOf(handle, position.prefixBytes);
193
+ if (head.length !== position.prefixBytes || hashOf(head) !== position.prefixHash) return false;
194
+ if (position.offset === 0) return true;
195
+ const before = Buffer.alloc(1);
196
+ const { bytesRead } = await handle.read(before, 0, 1, position.offset - 1);
197
+ return bytesRead === 1 && before[0] === 0x0a;
198
+ }
199
+
200
+ /** The tag of a locator of the journal. */
201
+ const JOURNAL_TAG = "mcode";
202
+
203
+ /**
204
+ * The locator of a record of `line`. The revision hashes the head of the journal, but only the
205
+ * bytes that are final by the end of this line: a journal that grows must not invalidate the
206
+ * locators it already gave out, so the half-written tail never takes part in the hash.
207
+ */
208
+ function makeLocator(head: Buffer, line: RawLine, after: number): Locator {
209
+ const final = line.complete ? line.byte + line.bytes.length + 1 : line.byte;
210
+ const prefix = head.subarray(0, Math.min(final, head.length));
211
+ return LocatorSchema.parse(
212
+ `${JOURNAL_TAG}:v1:${prefix.length}:${hashOf(prefix)}:${line.byte}:${line.complete ? after : 0}`,
213
+ );
214
+ }
215
+
216
+ /** A locator that is not this side's own is refused by name. */
217
+ function decodeLocator(locator: Locator): Position {
218
+ const parts = locator.split(":");
219
+ const [tag, version, bytes, hash, offset, after] = parts;
220
+ const numbers = [bytes, offset, after].map(Number);
221
+ if (
222
+ parts.length !== 6 ||
223
+ tag !== JOURNAL_TAG ||
224
+ version !== "v1" ||
225
+ hash === undefined ||
226
+ numbers.some((n) => !Number.isSafeInteger(n) || n < 0)
227
+ ) {
228
+ throw new Error(`mcode: locator ${locator} is not of this side's form`);
229
+ }
230
+ return { prefixBytes: numbers[0]!, prefixHash: hash, offset: numbers[1]!, after: numbers[2]! };
231
+ }
232
+
233
+ /**
234
+ * A locator of a record that came from the ledger of a session.
235
+ *
236
+ * The ledger is a file of its own, so its records are named by their own tag: a locator of the
237
+ * journal of a session says nothing about the ledger of that session, and the other way about.
238
+ */
239
+ const LEDGER_TAG = "mcode-ledger";
240
+
241
+ /** The locator of a record of the ledger of a session. */
242
+ function makeLedgerLocator(head: Buffer, line: LedgerLine, after: number): Locator {
243
+ const final = line.complete ? line.byte + line.bytes.length + 1 : line.byte;
244
+ const prefix = head.subarray(0, Math.min(final, head.length));
245
+ return LocatorSchema.parse(
246
+ `${LEDGER_TAG}:v1:${prefix.length}:${hashOf(prefix)}:${line.byte}:${line.complete ? after : 0}`,
247
+ );
248
+ }
249
+
250
+ /** A locator of the ledger read back. */
251
+ function decodeLedgerLocator(locator: Locator): Position {
252
+ const parts = locator.split(":");
253
+ const [tag, version, bytes, hash, offset, after] = parts;
254
+ const numbers = [bytes, offset, after].map(Number);
255
+ if (
256
+ parts.length !== 6 ||
257
+ tag !== LEDGER_TAG ||
258
+ version !== "v1" ||
259
+ hash === undefined ||
260
+ numbers.some((n) => !Number.isSafeInteger(n) || n < 0)
261
+ ) {
262
+ throw new Error(`mcode: locator ${locator} is not of this side's form`);
263
+ }
264
+ return { prefixBytes: numbers[0]!, prefixHash: hash, offset: numbers[1]!, after: numbers[2]! };
265
+ }
266
+
267
+ /**
268
+ * A locator of a record that came from the durable history. The database is only appended to, so
269
+ * a record is named by what it is: `mcode-db:v1:<seq>:<ordinal>:<index>:<after>:<message id>` — the
270
+ * entry that carried it (seq, ordinal), the place of the envelope in that entry, how many of the
271
+ * envelope's records were delivered, and the `message_id` (percent-encoded, `-` for none). A read
272
+ * resumes after the envelope with that message id; when the active view no longer holds it (a
273
+ * history that was replaced), the read starts from the beginning.
274
+ */
275
+ const DURABLE_TAG = "mcode-db";
276
+
277
+ function isDurableLocator(locator: Locator): boolean {
278
+ return locator.startsWith(`${DURABLE_TAG}:`);
279
+ }
280
+
281
+ /** The place a locator was taken from. */
282
+ type LocatorForm = "journal" | "ledger" | "durable";
283
+
284
+ /** The place a locator was taken from; `undefined` when the locator is none of this side's. */
285
+ function formOf(locator: Locator): LocatorForm | undefined {
286
+ switch (locator.slice(0, locator.indexOf(":"))) {
287
+ case JOURNAL_TAG:
288
+ return "journal";
289
+ case LEDGER_TAG:
290
+ return "ledger";
291
+ case DURABLE_TAG:
292
+ return "durable";
293
+ default:
294
+ return undefined;
295
+ }
296
+ }
297
+
298
+ /**
299
+ * The locator of a read, refused when it is none of this side's. One taken from another place than
300
+ * the one the session is read from now (the history moved between the database, the journal and
301
+ * the ledger) names no record here: such a read starts over, as it does for a rewritten file.
302
+ */
303
+ function checkedLocator(from: Locator | undefined): void {
304
+ if (from === undefined) return;
305
+ switch (formOf(from)) {
306
+ case "journal":
307
+ decodeLocator(from);
308
+ return;
309
+ case "ledger":
310
+ decodeLedgerLocator(from);
311
+ return;
312
+ case "durable":
313
+ decodeDurableLocator(from);
314
+ return;
315
+ default:
316
+ throw new Error(`mcode: locator ${from} is not of this side's form`);
317
+ }
318
+ }
319
+
320
+ /** The position of a locator of the database, when that is what it is. */
321
+ function durableFrom(from: Locator | undefined): DurablePosition | undefined {
322
+ return from !== undefined && formOf(from) === "durable" ? decodeDurableLocator(from) : undefined;
323
+ }
324
+
325
+ /** The position of a locator of the ledger, when that is what it is. */
326
+ function ledgerFrom(from: Locator | undefined): Position | undefined {
327
+ return from !== undefined && formOf(from) === "ledger" ? decodeLedgerLocator(from) : undefined;
328
+ }
329
+
330
+ /** The position of a locator of the journal, when that is what it is. */
331
+ function journalFrom(from: Locator | undefined): Position | undefined {
332
+ return from !== undefined && formOf(from) === "journal" ? decodeLocator(from) : undefined;
333
+ }
334
+
335
+ function makeDurableLocator(turn: DurableTurn, after: number): Locator {
336
+ const id = turn.messageId === undefined ? "-" : encodeURIComponent(turn.messageId);
337
+ return LocatorSchema.parse(`${DURABLE_TAG}:v1:${turn.seq}:${turn.ordinal}:${turn.index}:${after}:${id}`);
338
+ }
339
+
340
+ interface DurablePosition {
341
+ readonly seq: number;
342
+ readonly ordinal: number;
343
+ readonly index: number;
344
+ readonly after: number;
345
+ readonly messageId: string | undefined;
346
+ }
347
+
348
+ function decodeDurableLocator(locator: Locator): DurablePosition {
349
+ const parts = locator.split(":");
350
+ const [tag, version, seq, ordinal, index, after, id] = parts;
351
+ const numbers = [seq, ordinal, index, after].map(Number);
352
+ if (
353
+ parts.length !== 7 ||
354
+ tag !== DURABLE_TAG ||
355
+ version !== "v1" ||
356
+ id === undefined ||
357
+ numbers.some((n) => !Number.isSafeInteger(n) || n < 0)
358
+ ) {
359
+ throw new Error(`mcode: locator ${locator} is not of this side's form`);
360
+ }
361
+ return {
362
+ seq: numbers[0]!,
363
+ ordinal: numbers[1]!,
364
+ index: numbers[2]!,
365
+ after: numbers[3]!,
366
+ messageId: id === "-" ? undefined : decodeURIComponent(id),
367
+ };
368
+ }
369
+
370
+ /**
371
+ * Where a read resumes: the turn of the position (the first one whose records are not all
372
+ * delivered) and how many of its records were. A position the view no longer holds starts over.
373
+ * With `exact`, the index is that of the turn the position names, or past the end when none is.
374
+ */
375
+ function durableStart(
376
+ turns: readonly DurableTurn[],
377
+ position: DurablePosition | undefined,
378
+ exact = false,
379
+ ): { turn: number; after: number; stale: boolean } {
380
+ if (position === undefined) return { turn: 0, after: 0, stale: false };
381
+ const at = turns.findIndex((turn) =>
382
+ position.messageId === undefined
383
+ ? turn.messageId === undefined &&
384
+ turn.seq === position.seq &&
385
+ turn.ordinal === position.ordinal &&
386
+ turn.index === position.index
387
+ : turn.messageId === position.messageId,
388
+ );
389
+ if (at < 0) return exact ? { turn: turns.length, after: 0, stale: true } : { turn: 0, after: 0, stale: true };
390
+ return { turn: at, after: position.after, stale: false };
391
+ }
392
+
393
+ /**
394
+ * A session that was in the durable history only has its journal now (it was adopted): the locator
395
+ * it was given names a message, and the journal holds the same envelope on a line of its own. The
396
+ * read resumes after that line, so what was delivered is not delivered twice. A journal that does
397
+ * not (yet) hold the message starts over, as a rewritten file does.
398
+ */
399
+ async function resumeAfterMessage(
400
+ handle: FileHandle,
401
+ position: DurablePosition,
402
+ ): Promise<{ readonly offset: number; readonly after: number } | undefined> {
403
+ if (position.messageId === undefined) return undefined;
404
+ for await (const line of scanLines(handle, 0)) {
405
+ if (!line.complete) break;
406
+ if (isBlank(line.bytes)) continue;
407
+ if (messageIdOf(parseLine(line.bytes)) === position.messageId) {
408
+ return { offset: line.byte, after: position.after };
409
+ }
410
+ }
411
+ return undefined;
412
+ }
413
+
414
+ export class McodeReading implements SessionReading {
415
+ readonly #harness: HarnessId;
416
+ readonly #sessionsRoot: string;
417
+ readonly #perSessionHome: string | undefined;
418
+ readonly #durablePath: string;
419
+ readonly #runtimeStatePath: string;
420
+
421
+ constructor(options: McodeReadingOptions) {
422
+ this.#harness = options.harness;
423
+ this.#perSessionHome = options.perSessionHistory ? options.home : undefined;
424
+ this.#sessionsRoot = join(options.home, "v2", "sessions");
425
+ this.#durablePath = durablePathOf(options.home);
426
+ this.#runtimeStatePath = runtimeStatePathOf(options.home);
427
+ }
428
+
429
+ /** A line that does not parse is returned as text, an unfamiliar shape as it is. */
430
+ readonly rawSchema = z.union([RawRecordSchema, z.json()]);
431
+
432
+ /** The sessions on disk, newest first. */
433
+ async *list(filter?: SessionFilter): AsyncIterable<SessionInfo> {
434
+ const listed = new Set<string>();
435
+ const titles = sessionTitles(this.#runtimeStatePath, filter?.natives);
436
+ const wanted = filter?.natives === undefined ? undefined : new Set(filter.natives);
437
+ for await (const found of this.#discover()) {
438
+ const info = await this.#infoOf(found, titles, wanted);
439
+ if (info === null) continue;
440
+ listed.add(info.id.native);
441
+ if (filter?.cwd !== undefined && info.cwd !== filter.cwd) continue;
442
+ if (filter?.since !== undefined && (info.updatedAt === undefined || info.updatedAt < filter.since)) {
443
+ continue;
444
+ }
445
+ yield info;
446
+ }
447
+ // Sessions the durable history holds and no session directory names: all that is known of
448
+ // them is the id and what they say, so a filter on the directory or the time leaves them out.
449
+ if (filter?.cwd !== undefined || filter?.since !== undefined) return;
450
+ for (const native of durableSessions(this.#durablePath)) {
451
+ if (listed.has(native) || !NativeSessionIdSchema.safeParse(native).success) continue;
452
+ if (wanted !== undefined && !wanted.has(native)) continue;
453
+ const id: SessionId = { harness: this.#harness, native: NativeSessionIdSchema.parse(native) };
454
+ const title = titles.get(native) ?? this.#durableTitle(native) ?? undefined;
455
+ listed.add(native);
456
+ yield { id, ...(title !== undefined ? { title } : {}) };
457
+ }
458
+ if (this.#perSessionHome === undefined) return;
459
+ for (const native of sessionStoreIds(this.#perSessionHome, wanted, listed)) {
460
+ const parsed = NativeSessionIdSchema.safeParse(native);
461
+ if (!parsed.success) continue;
462
+ const title = titles.get(native);
463
+ yield { id: { harness: this.#harness, native: parsed.data }, ...(title !== undefined ? { title } : {}) };
464
+ }
465
+ }
466
+
467
+ /**
468
+ * Records of a session, after `from` when given. A locator whose file was rewritten no longer
469
+ * names a record, so the read then starts from the beginning and delivers everything.
470
+ *
471
+ * A session that kept no journal of its own is read from its ledger instead: one source per
472
+ * session, never both.
473
+ */
474
+ async *read(id: SessionId, from?: Locator): AsyncIterable<SessionRecord> {
475
+ checkedLocator(from);
476
+ const turns = this.#sessionFileTurns(id);
477
+ if (turns !== undefined) yield* this.#readDurable(turns, from);
478
+ else yield* this.#readOf(id, await this.#find(id), from);
479
+ }
480
+
481
+ #sessionFileTurns(id: SessionId): DurableTurn[] | undefined {
482
+ if (this.#perSessionHome === undefined) return undefined;
483
+ if (id.harness !== this.#harness) throw new Error("ncode: session belongs to another harness installation");
484
+ const path = sessionDurablePath(this.#perSessionHome, id.native);
485
+ return path === undefined ? undefined : readView(path, id.native, true);
486
+ }
487
+
488
+ /** The records of a session whose directory is already found, or that has none. */
489
+ async *#readOf(id: SessionId, found: FoundSession | null, from?: Locator): AsyncIterable<SessionRecord> {
490
+ if (found === null) {
491
+ const turns = this.#inDurable(id.native) ? this.#durableTurns(id.native) : null;
492
+ if (turns !== null) yield* this.#readDurable(turns, from);
493
+ return;
494
+ }
495
+ let source = await this.#sourceOf(found);
496
+ if (source === "durable") {
497
+ const turns = this.#durableTurns(id.native);
498
+ if (turns !== null) {
499
+ yield* this.#readDurable(turns, from);
500
+ return;
501
+ }
502
+ // The database could not be read: the session is read as it was before the database.
503
+ source = "ledger";
504
+ }
505
+ if (source === "ledger") {
506
+ yield* this.#readLedger(found, from);
507
+ return;
508
+ }
509
+ const position = journalFrom(from);
510
+ const durable = durableFrom(from);
511
+ const handle = await open(found.logPath, "r");
512
+ try {
513
+ const head = await prefixOf(handle, PREFIX_BYTES);
514
+ const resume =
515
+ durable !== undefined
516
+ ? await resumeAfterMessage(handle, durable)
517
+ : position !== undefined && (await positionHolds(handle, position))
518
+ ? position
519
+ : undefined;
520
+ // A locator of another source, or one the file no longer holds, starts the read over.
521
+ let restarted = from !== undefined && resume === undefined;
522
+ for await (const line of scanLines(handle, resume?.offset ?? 0)) {
523
+ if (isBlank(line.bytes)) continue;
524
+ const skip = resume !== undefined && line.byte === resume.offset ? resume.after : 0;
525
+ for (const [index, record] of this.#recordsOf(line).entries()) {
526
+ if (index < skip) continue;
527
+ yield { ...record, ...(restarted ? { reanchored: true } : {}), locator: makeLocator(head, line, index + 1) } as SessionRecord;
528
+ restarted = false;
529
+ }
530
+ }
531
+ } finally {
532
+ await handle.close();
533
+ }
534
+ }
535
+
536
+ /**
537
+ * Where the records of a session come from: its journal, or its ledger.
538
+ *
539
+ * A session keeps its history in its journal. Some sessions kept none: they have no journal at
540
+ * all, or the one they have holds nothing. Their history is in the ledger of the session
541
+ * directory. One source per session: a journal with records in it is never read together with
542
+ * the ledger.
543
+ *
544
+ * A journal that cannot be read at all is not a journal that is missing: it stays the source,
545
+ * and the scan fails rather than the ledger taking its place.
546
+ */
547
+ async #sourceOf(found: FoundSession): Promise<"journal" | "durable" | "ledger"> {
548
+ let info;
549
+ try {
550
+ info = await stat(found.logPath);
551
+ } catch (error) {
552
+ if (isMissing(error)) return await this.#emptyJournalSource(found);
553
+ throw error;
554
+ }
555
+ if (!info.isFile()) return "journal";
556
+ return info.size > 0 ? "journal" : await this.#emptyJournalSource(found);
557
+ }
558
+
559
+ /**
560
+ * A session with no journal content: its history is in the durable history when the database
561
+ * holds entries of it (a session not yet adopted keeps its journal empty), else in its ledger.
562
+ */
563
+ async #emptyJournalSource(found: FoundSession): Promise<"durable" | "ledger"> {
564
+ // The regular harness has no database: nothing but the ledger is asked, not even the manifest.
565
+ if (!existsSync(this.#durablePath)) return "ledger";
566
+ const native = await this.#nativeOf(found);
567
+ return native !== null && this.#inDurable(native) ? "durable" : "ledger";
568
+ }
569
+
570
+ /** The id a session directory stands for: the manifest's, else the directory name's. */
571
+ async #nativeOf(found: FoundSession): Promise<string | null> {
572
+ const manifest = await this.#manifestOf(found);
573
+ const native = manifest?.sessionId ?? nativeIdFromDirName(found.dirName);
574
+ return native === undefined || native === null || native.length === 0 ? null : native;
575
+ }
576
+
577
+ #inDurable(native: string): boolean {
578
+ return durableHasSession(this.#durablePath, native) === true;
579
+ }
580
+
581
+ /** The active view of a session in the durable history. */
582
+ #durableTurns(native: string): DurableTurn[] | null {
583
+ return readDurableSession(this.#durablePath, native);
584
+ }
585
+
586
+ /** The records of a session that kept its history in the durable database. */
587
+ async *#readDurable(turns: readonly DurableTurn[], from?: Locator): AsyncIterable<SessionRecord> {
588
+ const position = durableFrom(from);
589
+ const start = durableStart(turns, position);
590
+ // A locator of another source, or one the view no longer holds, starts the read over.
591
+ let restarted = from !== undefined && (position === undefined || start.stale);
592
+ for (const [at, turn] of turns.entries()) {
593
+ if (at < start.turn) continue;
594
+ for (const [index, record] of this.#durableRecordsOf(turn).entries()) {
595
+ if (at === start.turn && index < start.after) continue;
596
+ yield { ...record, ...(restarted ? { reanchored: true } : {}), locator: makeDurableLocator(turn, index + 1) } as SessionRecord;
597
+ restarted = false;
598
+ }
599
+ }
600
+ }
601
+
602
+ #durableRecordsOf(turn: DurableTurn): Unlocated[] {
603
+ return recordsOfEnvelope(turn.record, turn.raw, { incomplete: false }, this.#harness);
604
+ }
605
+
606
+ /** The envelope at a locator of the durable history. */
607
+ #rawDurable(turns: readonly DurableTurn[], native: string, locator: Locator): unknown {
608
+ const position = decodeDurableLocator(locator);
609
+ const at = durableStart(turns, position, true).turn;
610
+ const turn = turns[at];
611
+ if (turn === undefined || at >= turns.length) {
612
+ throw new Error(`mcode: no record at ${locator} in session ${native}`);
613
+ }
614
+ return turn.raw;
615
+ }
616
+
617
+ /** The coverage of a session that kept its history in the durable database. */
618
+ #durableCoverage(turns: readonly DurableTurn[], from?: Locator): Coverage {
619
+ const start = durableStart(turns, durableFrom(from));
620
+ for (const [at, turn] of turns.entries()) {
621
+ if (at < start.turn) continue;
622
+ const count = this.#durableRecordsOf(turn).length;
623
+ if (count > (at === start.turn ? start.after : 0)) return NOT_SCANNED;
624
+ }
625
+ return EMPTY;
626
+ }
627
+
628
+ /** The records of a session that kept its history in its ledger. */
629
+ async *#readLedger(found: FoundSession, from?: Locator): AsyncIterable<SessionRecord> {
630
+ const content = await this.#ledgerOf(found);
631
+ if (content === null) return;
632
+ const position = ledgerFrom(from);
633
+ // A locator of another source, or one the ledger no longer holds, starts the read over.
634
+ let restarted = from !== undefined && (position === undefined || !ledgerPositionHolds(content, position));
635
+ for (const { record, line, at } of ledgerPending(content, this.#harness, position)) {
636
+ yield { ...record, ...(restarted ? { reanchored: true } : {}), locator: makeLedgerLocator(content.head, line, at + 1) } as SessionRecord;
637
+ restarted = false;
638
+ }
639
+ }
640
+
641
+ /** The ledger of a session: `null` when there is no ledger to read. */
642
+ async #ledgerOf(found: FoundSession): Promise<LedgerContent | null> {
643
+ let bytes: Buffer;
644
+ try {
645
+ bytes = await readFile(found.ledgerPath);
646
+ } catch (error) {
647
+ // Only a ledger that is not there is "no ledger"; one that exists and cannot be read fails.
648
+ if (isMissing(error)) return null;
649
+ throw error;
650
+ }
651
+ return parseLedger(bytes);
652
+ }
653
+
654
+ /** The harness's own record, whole, at a locator of the current file. */
655
+ async raw(id: SessionId, locator: Locator): Promise<unknown> {
656
+ const active = this.#sessionFileTurns(id);
657
+ if (active !== undefined) return this.#rawDurable(active, id.native, locator);
658
+ const found = await this.#find(id);
659
+ if (found === null) {
660
+ const turns = this.#inDurable(id.native) ? this.#durableTurns(id.native) : null;
661
+ if (turns !== null) return this.#rawDurable(turns, id.native, locator);
662
+ throw new Error(`mcode: session ${id.native} is not on disk`);
663
+ }
664
+ let source = await this.#sourceOf(found);
665
+ if (source === "durable") {
666
+ const turns = this.#durableTurns(id.native);
667
+ if (turns !== null) return this.#rawDurable(turns, id.native, locator);
668
+ source = "ledger";
669
+ }
670
+ if (source === "ledger") {
671
+ return this.#rawLedger(found, locator);
672
+ }
673
+ if (isDurableLocator(locator)) return this.#rawByMessage(found, id, locator);
674
+ const position = decodeLocator(locator);
675
+ const handle = await open(found.logPath, "r");
676
+ try {
677
+ if (!(await positionHolds(handle, position))) {
678
+ throw new Error(`mcode: locator ${locator} does not belong to the current file of ${id.native}`);
679
+ }
680
+ for await (const line of scanLines(handle, position.offset)) return parseLine(line.bytes);
681
+ } finally {
682
+ await handle.close();
683
+ }
684
+ throw new Error(`mcode: no record at ${locator} in session ${id.native}`);
685
+ }
686
+
687
+ /** The envelope a locator of the durable history names, in the journal the session has now. */
688
+ async #rawByMessage(found: FoundSession, id: SessionId, locator: Locator): Promise<unknown> {
689
+ const messageId = decodeDurableLocator(locator).messageId;
690
+ const handle = await open(found.logPath, "r");
691
+ try {
692
+ for await (const line of scanLines(handle, 0)) {
693
+ if (!line.complete) break;
694
+ const parsed = isBlank(line.bytes) ? undefined : parseLine(line.bytes);
695
+ if (messageId !== undefined && messageIdOf(parsed) === messageId) return parsed;
696
+ }
697
+ } finally {
698
+ await handle.close();
699
+ }
700
+ throw new Error(`mcode: no record at ${locator} in session ${id.native}`);
701
+ }
702
+
703
+ /** The record of the ledger of a session, whole, at a locator of the ledger. */
704
+ async #rawLedger(found: FoundSession, locator: Locator): Promise<unknown> {
705
+ const position = decodeLedgerLocator(locator);
706
+ const content = await this.#ledgerOf(found);
707
+ if (content === null) throw new Error(`mcode: session ${found.dirName} has no ledger`);
708
+ if (position.offset >= content.size) {
709
+ throw new Error(`mcode: locator ${locator} does not belong to the current ledger of ${found.dirName}`);
710
+ }
711
+ const prefix = content.head.subarray(0, Math.min(position.prefixBytes, content.head.length));
712
+ if (prefix.length !== position.prefixBytes || hashOf(prefix) !== position.prefixHash) {
713
+ throw new Error(`mcode: locator ${locator} does not belong to the current ledger of ${found.dirName}`);
714
+ }
715
+ for (const turn of content.turns) {
716
+ if (turn.line.byte !== position.offset) continue;
717
+ return turn.raw;
718
+ }
719
+ throw new Error(`mcode: no record at ${locator} in the ledger of ${found.dirName}`);
720
+ }
721
+
722
+ /**
723
+ * `unavailable` — not on disk; `failed` — the scan broke; `empty` — nothing in the range;
724
+ * `not-scanned` — there are records niwa has not read: it copies nothing, so a range is only
725
+ * read when a caller asks `read`.
726
+ */
727
+ async coverage(id: SessionId, from?: Locator): Promise<Coverage> {
728
+ checkedLocator(from);
729
+ try {
730
+ return await this.#coverageOf(id, from);
731
+ } catch (error) {
732
+ return failedCoverage(`mcode: session ${id.native} could not be scanned: ${reasonOf(error)}`);
733
+ }
734
+ }
735
+
736
+ async #coverageOf(id: SessionId, from?: Locator): Promise<Coverage> {
737
+ const active = this.#sessionFileTurns(id);
738
+ if (active !== undefined) return this.#durableCoverage(active, from);
739
+ const found = await this.#find(id);
740
+ if (found === null) {
741
+ const held = this.#durableHolds(id.native);
742
+ if (held === null) return failedCoverage(`mcode: the durable history of session ${id.native} could not be read`);
743
+ const turns = held ? this.#durableTurns(id.native) : null;
744
+ if (turns !== null) return this.#durableCoverage(turns, from);
745
+ if (held) return failedCoverage(`mcode: the durable history of session ${id.native} could not be read`);
746
+ return unavailableCoverage(`mcode: session ${id.native} is not on disk`);
747
+ }
748
+ let source = await this.#sourceOf(found);
749
+ let durableFailed = false;
750
+ if (source === "durable") {
751
+ const turns = this.#durableTurns(id.native);
752
+ if (turns !== null) return this.#durableCoverage(turns, from);
753
+ durableFailed = true;
754
+ source = "ledger";
755
+ }
756
+ if (source === "ledger") return this.#ledgerCoverage(found, from, durableFailed);
757
+ const position = journalFrom(from);
758
+ const durable = durableFrom(from);
759
+ const handle = await open(found.logPath, "r");
760
+ try {
761
+ const resume =
762
+ durable !== undefined
763
+ ? await resumeAfterMessage(handle, durable)
764
+ : position !== undefined && (await positionHolds(handle, position))
765
+ ? position
766
+ : undefined;
767
+ for await (const line of scanLines(handle, resume?.offset ?? 0)) {
768
+ if (isBlank(line.bytes)) continue;
769
+ const skip = resume !== undefined && line.byte === resume.offset ? resume.after : 0;
770
+ if (this.#recordsOf(line).length > skip) return NOT_SCANNED;
771
+ }
772
+ return EMPTY;
773
+ } finally {
774
+ await handle.close();
775
+ }
776
+ }
777
+
778
+ /**
779
+ * The coverage of a session that kept its history in its ledger. A session with no ledger holds
780
+ * nothing, unless its history was in a database that could not be read: that is not empty, it is
781
+ * unknown.
782
+ */
783
+ async #ledgerCoverage(found: FoundSession, from: Locator | undefined, durableFailed: boolean): Promise<Coverage> {
784
+ const content = await this.#ledgerOf(found);
785
+ if (content === null) {
786
+ if (durableFailed || (await this.#durableUnreadable(found))) {
787
+ return failedCoverage(`mcode: the durable history of ${found.dirName} could not be read and it has no ledger`);
788
+ }
789
+ return EMPTY;
790
+ }
791
+ for (const _ of ledgerPending(content, this.#harness, ledgerFrom(from))) return NOT_SCANNED;
792
+ return EMPTY;
793
+ }
794
+
795
+ /** Whether the database exists and cannot be asked about the session of a directory. */
796
+ async #durableUnreadable(found: FoundSession): Promise<boolean> {
797
+ if (!existsSync(this.#durablePath)) return false;
798
+ const native = await this.#nativeOf(found);
799
+ return native !== null && durableHasSession(this.#durablePath, native) === null;
800
+ }
801
+
802
+ /** Whether the database holds the session; `null` when it cannot be asked. */
803
+ #durableHolds(native: string): boolean | null {
804
+ return durableHasSession(this.#durablePath, native);
805
+ }
806
+
807
+ async *#discover(): AsyncGenerator<FoundSession> {
808
+ const root = this.#sessionsRoot;
809
+ for (const year of await subdirsOf(root, /^\d{4}$/)) {
810
+ for (const month of await subdirsOf(join(root, year), /^\d{2}$/)) {
811
+ for (const day of await subdirsOf(join(root, year, month), /^\d{2}$/)) {
812
+ const dayPath = join(root, year, month, day);
813
+ for (const dirName of await subdirsOf(dayPath)) {
814
+ if (!isSessionDir(dirName)) continue;
815
+ const dir = join(dayPath, dirName);
816
+ yield {
817
+ dirName,
818
+ logPath: logPathOf(dir),
819
+ manifestPath: manifestPathOf(dir),
820
+ ledgerPath: ledgerPathOf(dir),
821
+ };
822
+ }
823
+ }
824
+ }
825
+ }
826
+ }
827
+
828
+ /** The id is the manifest's, the directory name is the fallback; `null` when neither names one. */
829
+ async #infoOf(
830
+ found: FoundSession,
831
+ titles: ReadonlyMap<string, string>,
832
+ wanted?: ReadonlySet<string>,
833
+ ): Promise<SessionInfo | null> {
834
+ const manifest = await this.#manifestOf(found);
835
+ const native = manifest?.sessionId ?? nativeIdFromDirName(found.dirName);
836
+ if (native === null || native === undefined || native.length === 0) return null;
837
+ // A session that is not wanted is left out before its context or its title is read.
838
+ if (wanted !== undefined && !wanted.has(native)) return null;
839
+ const startedAt = toTimestamp(manifest?.createdAtMs);
840
+ const updatedAt = toTimestamp(manifest?.updatedAtMs) ?? startedAt;
841
+ const cwd = (await this.#contextOf(found))?.workspaceDir ?? undefined;
842
+ const id: SessionId = { harness: this.#harness, native: NativeSessionIdSchema.parse(native) };
843
+ const title = titles.get(native) ?? (await this.#titleOf(id, found));
844
+ return {
845
+ id,
846
+ ...(title !== undefined ? { title } : {}),
847
+ ...(cwd !== undefined ? { cwd } : {}),
848
+ ...(startedAt !== undefined ? { startedAt } : {}),
849
+ ...(updatedAt !== undefined ? { updatedAt } : {}),
850
+ };
851
+ }
852
+
853
+ /**
854
+ * The title of a session the harness gave no title in its runtime state: the first message of
855
+ * the person, with the agent-context preamble cut out. From the durable history only its head
856
+ * is looked at, as for the working directory: the listing does not decode a history.
857
+ */
858
+ async #titleOf(id: SessionId, found: FoundSession): Promise<string | undefined> {
859
+ try {
860
+ if ((await this.#sourceOf(found)) === "durable") {
861
+ const native = await this.#nativeOf(found);
862
+ const title = native === null ? null : this.#durableTitle(native);
863
+ // `null` is a database that cannot be read: the read falls back to the ledger then.
864
+ if (title !== null) return title;
865
+ }
866
+ return await firstMessageTitle(this.#readOf(id, found));
867
+ } catch {
868
+ return undefined;
869
+ }
870
+ }
871
+
872
+ /** The title from the head of the durable history; `null` when the database cannot be read. */
873
+ #durableTitle(native: string): string | undefined | null {
874
+ let seen = 0;
875
+ return durableFirst(this.#durablePath, native, (turn) => {
876
+ seen += 1;
877
+ if (seen > 50) return STOP;
878
+ if (turn.record?.message.role !== "user") return undefined;
879
+ return titleFromText(stripHarnessNoise(textOf(turn.record.message.content)));
880
+ });
881
+ }
882
+
883
+ async #manifestOf(found: FoundSession): Promise<Manifest | null> {
884
+ try {
885
+ const parsed = ManifestSchema.safeParse(JSON.parse(await readFile(found.manifestPath, "utf8")));
886
+ return parsed.success ? parsed.data : null;
887
+ } catch {
888
+ return null;
889
+ }
890
+ }
891
+
892
+ /** The preamble of the first human message, looked for in the head of the journal only. */
893
+ async #contextOf(found: FoundSession): Promise<AgentContext | null> {
894
+ const source = await this.#sourceOf(found);
895
+ let ledger = source === "ledger";
896
+ if (source === "durable") {
897
+ const native = await this.#nativeOf(found);
898
+ // The head of the history, as for a journal: not the whole of it, for the listing asks this
899
+ // of every session. `null` is a database that cannot be read: the ledger answers then.
900
+ const context =
901
+ native === null
902
+ ? undefined
903
+ : durableFirst(this.#durablePath, native, (turn) => {
904
+ if (turn.record?.message.role !== "user") return undefined;
905
+ // The preamble is on the first human message: the look ends there.
906
+ const stated = readAgentContext(textOf(turn.record.message.content));
907
+ return stated.workspaceDir !== null || stated.parentSessionId !== null ? stated : STOP;
908
+ });
909
+ if (context !== null) return context ?? null;
910
+ ledger = true;
911
+ }
912
+ if (ledger) {
913
+ const content = await this.#ledgerOf(found);
914
+ if (content === null) return null;
915
+ const stated = content.workspaceDir;
916
+ if (stated === undefined) return null;
917
+ return {
918
+ sessionRole: null,
919
+ sessionId: null,
920
+ parentSessionId: null,
921
+ workspaceDir: stated,
922
+ };
923
+ }
924
+ let handle: FileHandle;
925
+ try {
926
+ handle = await open(found.logPath, "r");
927
+ } catch {
928
+ return null;
929
+ }
930
+ try {
931
+ for await (const line of scanLines(handle, 0)) {
932
+ if (line.byte >= HEAD_BYTES) break;
933
+ if (!line.complete) break;
934
+ const record = parseNativeRecord(parseLine(line.bytes));
935
+ if (record?.message.role !== "user") continue;
936
+ const context = readAgentContext(textOf(record.message.content));
937
+ if (context.workspaceDir !== null || context.parentSessionId !== null) return context;
938
+ }
939
+ } catch {
940
+ return null;
941
+ } finally {
942
+ await handle.close();
943
+ }
944
+ return null;
945
+ }
946
+
947
+ /** The directory name carries the encoded id; when it was cut, the manifests are asked. */
948
+ async #find(id: SessionId): Promise<FoundSession | null> {
949
+ const encoded = encodeNativeId(id.native);
950
+ for await (const found of this.#discover()) {
951
+ if (dirNameHoldsId(found.dirName, encoded)) return found;
952
+ }
953
+ for await (const found of this.#discover()) {
954
+ if ((await this.#manifestOf(found))?.sessionId === id.native) return found;
955
+ }
956
+ return null;
957
+ }
958
+
959
+ /**
960
+ * The records of one native line. One line may give several: an answer with a call in it gives
961
+ * an assistant record and a tool-call record.
962
+ */
963
+ #recordsOf(line: RawLine): Unlocated[] {
964
+ const parsed = parseLine(line.bytes);
965
+ return recordsOfEnvelope(parseNativeRecord(parsed), parsed, { incomplete: !line.complete }, this.#harness);
966
+ }
967
+ }
968
+
969
+ /** The records of one envelope of the journal, or of the durable history: the same mapping. */
970
+ function recordsOfEnvelope(
971
+ record: McodeRecord | null,
972
+ parsed: unknown,
973
+ state: { readonly incomplete: boolean },
974
+ harness: HarnessId,
975
+ ): Unlocated[] {
976
+ const incomplete = state.incomplete;
977
+ if (record === null) return [unknownRecord(parsed, { incomplete })];
978
+ const message = record.message;
979
+ const at = millisOf(message.timestamp);
980
+ const base: RecordBase = { ...(at !== undefined ? { at } : {}), incomplete };
981
+ switch (message.role) {
982
+ case "user":
983
+ return userRecords(record, parsed, base);
984
+ case "assistant":
985
+ return assistantRecords(message, base, parsed);
986
+ case "toolResult":
987
+ return toolResultRecords(message, base, parsed, harness);
988
+ case "compactionSummary":
989
+ return [{ kind: "compaction", summary: message.summary ?? "", ...base }];
990
+ default:
991
+ return [unknownRecord(parsed, base)];
992
+ }
993
+ }
994
+
995
+ /** Whether a position taken from a ledger still names a place in it: the head it hashed is the head it has. */
996
+ function ledgerPositionHolds(content: LedgerContent, position: Position): boolean {
997
+ if (position.offset >= content.size) return false;
998
+ const prefix = content.head.subarray(0, Math.min(position.prefixBytes, content.head.length));
999
+ return prefix.length === position.prefixBytes && hashOf(prefix) === position.prefixHash;
1000
+ }
1001
+
1002
+ /**
1003
+ * The records of a ledger that come after a position: everything on lines before the line of the
1004
+ * position, and the records of that line it did not deliver, are left out. A position of a ledger
1005
+ * that was rewritten names nothing, and the read starts over.
1006
+ */
1007
+ function* ledgerPending(
1008
+ content: LedgerContent,
1009
+ harness: HarnessId,
1010
+ position: Position | undefined,
1011
+ ): Generator<{ readonly record: Unlocated; readonly line: LedgerLine; readonly at: number }> {
1012
+ const held = position !== undefined && ledgerPositionHolds(content, position) ? position : undefined;
1013
+ let currentByte = -1;
1014
+ let delivered = 0;
1015
+ for (const turn of content.turns) {
1016
+ if (turn.line.byte !== currentByte) {
1017
+ currentByte = turn.line.byte;
1018
+ delivered = 0;
1019
+ }
1020
+ const records = ledgerRecordsOf(turn, harness);
1021
+ const skip =
1022
+ held === undefined || turn.line.byte > held.offset
1023
+ ? 0
1024
+ : turn.line.byte < held.offset
1025
+ ? Number.POSITIVE_INFINITY
1026
+ : held.after;
1027
+ for (const [index, record] of records.entries()) {
1028
+ const at = delivered + index;
1029
+ if (at >= skip) yield { record, line: turn.line, at };
1030
+ }
1031
+ delivered += records.length;
1032
+ }
1033
+ }
1034
+
1035
+ /**
1036
+ * The records of one turn of the ledger. A turn is mapped the way a line of the journal is
1037
+ * mapped: the same kinds, the same meanings.
1038
+ */
1039
+ function ledgerRecordsOf(turn: LedgerTurn, harness: HarnessId): Unlocated[] {
1040
+ const incomplete = !turn.line.complete;
1041
+ const base: RecordBase = { incomplete };
1042
+ const message = turn.message;
1043
+ if (message === null) return [unknownRecord(turn.raw, base)];
1044
+ const at = millisOf(message.timestamp);
1045
+ const withTime: RecordBase = { ...(at !== undefined ? { at } : {}), incomplete };
1046
+ switch (message.role) {
1047
+ case "user":
1048
+ return userRecords({ message }, turn.raw, withTime);
1049
+ case "assistant":
1050
+ return assistantRecords(message, withTime, turn.raw);
1051
+ case "toolResult":
1052
+ return toolResultRecords(message, withTime, turn.raw, harness);
1053
+ case "compactionSummary":
1054
+ return [{ kind: "compaction", summary: message.summary ?? "", ...withTime }];
1055
+ default:
1056
+ return [unknownRecord(turn.raw, withTime)];
1057
+ }
1058
+ }
1059
+
1060
+ /** What the human said, with the machine preamble cut out; nothing left means the line is kept whole. */
1061
+ function userRecords(record: McodeRecord, raw: unknown, base: RecordBase): Unlocated[] {
1062
+ const text = stripHarnessNoise(textOf(record.message.content));
1063
+ if (text.length === 0 || isWrappedNoise(text)) return [unknownRecord(raw, base)];
1064
+ // The reader cut what the harness inserted out of the text itself, so what is left was typed.
1065
+ return [{ kind: "user", text, inserted: [], ...base }];
1066
+ }
1067
+
1068
+ function assistantRecords(message: McodeMessage, base: RecordBase, raw: unknown): Unlocated[] {
1069
+ const records: Unlocated[] = [];
1070
+ const model = message.model === undefined ? {} : { model: message.model };
1071
+ const blocks =
1072
+ typeof message.content === "string"
1073
+ ? [{ type: "text", text: message.content }]
1074
+ : (message.content ?? []);
1075
+ for (const block of blocks) {
1076
+ if (block.type === "text") {
1077
+ if (block.text !== undefined && block.text.length > 0) {
1078
+ records.push({ kind: "assistant", text: block.text, ...model, ...base });
1079
+ }
1080
+ } else if (block.type === "toolCall" && block.id !== undefined && block.name !== undefined) {
1081
+ records.push({
1082
+ kind: "tool-call",
1083
+ callId: block.id,
1084
+ name: block.name,
1085
+ ...mcodeToolShape(block.name, block.arguments),
1086
+ ...(block.arguments === undefined ? {} : { input: jsonOf(block.arguments) }),
1087
+ ...base,
1088
+ });
1089
+ const checklist = mcodeChecklist(block.name, block.arguments);
1090
+ if (checklist !== undefined) records.push({ kind: "checklist", callId: block.id, items: checklist.items, ...base });
1091
+ } else if (block.type === "thinking") {
1092
+ records.push({ kind: "thinking", text: block.thinking ?? "", redacted: block.redacted === true, ...base });
1093
+ } else {
1094
+ // A call without an id that cannot be paired, or a block of no known kind: kept whole.
1095
+ records.push(unknownRecord(block, base));
1096
+ }
1097
+ }
1098
+ return records.length === 0 ? [unknownRecord(raw, base)] : records;
1099
+ }
1100
+
1101
+ /** The answer of a tool; the answer of `task` also names the session it spawned. */
1102
+ function toolResultRecords(
1103
+ message: McodeMessage,
1104
+ base: RecordBase,
1105
+ raw: unknown,
1106
+ harness: HarnessId,
1107
+ ): Unlocated[] {
1108
+ const callId = message.toolCallId;
1109
+ if (callId === undefined || callId.length === 0) return [unknownRecord(raw, base)];
1110
+ const text = textOf(message.content);
1111
+ const records: Unlocated[] = [
1112
+ {
1113
+ kind: "tool-result",
1114
+ callId,
1115
+ ...(message.toolName === undefined ? {} : { name: message.toolName }),
1116
+ output: text,
1117
+ ok: message.isError !== true,
1118
+ ...base,
1119
+ },
1120
+ ];
1121
+ const child = message.toolName === "task" ? /session_id="(mvs_[A-Za-z0-9_-]+)"/.exec(text)?.[1] : undefined;
1122
+ if (child !== undefined) {
1123
+ records.push({
1124
+ kind: "nested",
1125
+ child: { harness, native: NativeSessionIdSchema.parse(child) },
1126
+ ...base,
1127
+ });
1128
+ }
1129
+ return records;
1130
+ }
1131
+
1132
+ function unknownRecord(raw: unknown, base: RecordBase): Unlocated {
1133
+ return { kind: "unknown", raw, ...base };
1134
+ }
1135
+
1136
+ function toTimestamp(value: number | undefined): Timestamp | undefined {
1137
+ const ms = millisOf(value);
1138
+ return ms === undefined ? undefined : timestamp(ms);
1139
+ }
1140
+
1141
+ function reasonOf(error: unknown): string {
1142
+ return error instanceof Error ? error.message : String(error);
1143
+ }
1144
+
1145
+ /** Is this the error of a file that is not there? */
1146
+ function isMissing(error: unknown): boolean {
1147
+ return (
1148
+ typeof error === "object" &&
1149
+ error !== null &&
1150
+ "code" in error &&
1151
+ (error as { readonly code?: unknown }).code === "ENOENT"
1152
+ );
1153
+ }