@namzu/sdk 20.4.0 → 21.0.0

package/src/store/run/disk.ts

@@ -1,8 +1,8 @@
 import { appendFile, mkdir, readFile, readdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { Run, RunEvent, RunStoreConfig } from '../../types/run/index.js'
-import type { CompletedToolRecord, RunStore } from '../../types/run/store.js'
+import type { PersistedRunEvent, Run, RunEvent, RunStoreConfig } from '../../types/run/index.js'
+import type { CompletedToolRecord, ReadRunEventsOptions, RunStore } from '../../types/run/store.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 import { defineSchema, migrate, stamp } from '../schema.js'
@@ -51,6 +51,7 @@ export class RunDiskStore implements RunStore {
 			this.runDir = join(this.baseDir, runId)
 		}
 		await mkdir(this.runDir, { recursive: true })
+		await healTornTranscript(this.runDir)
 		this.log.info(`Run directory created: ${this.runDir}`)
 		return this.runDir
 	}
@@ -66,6 +67,10 @@ export class RunDiskStore implements RunStore {
 		await appendFile(join(dir, 'transcript.jsonl'), line, 'utf-8')
 	}
 
+	async readEvents(options?: ReadRunEventsOptions): Promise<readonly PersistedRunEvent[]> {
+		return readRunEventsIn(this.requireInit(), options)
+	}
+
 	/**
 	 * Every tool call this run has already finished, keyed by `toolUseId`.
 	 *
@@ -296,6 +301,105 @@ export class RunDiskStore implements RunStore {
 	}
 }
 
+/**
+ * Every durable event under one run directory, oldest first.
+ *
+ * A free function for the same reason {@link readCheckpointsIn} is one: a
+ * caller catching up on a run this process never started would otherwise have
+ * to bind a {@link RunDiskStore} to read it, and binding one CREATES the
+ * directory. A read that mints an empty run directory then answers "no events"
+ * is indistinguishable from a run that genuinely has none.
+ *
+ * ## Unsequenced lines take their position
+ *
+ * A transcript written before events were numbered carries no `seq` at all.
+ * Numbering those lines by their 1-based position is what keeps their evidence
+ * reachable: a legacy run of five lines reads back as 1..5, seeds the emitter
+ * at 5, and its next event is 6 — continuous, and stable on every later read.
+ * Skipping them instead would erase a run's whole history from a catch-up, and
+ * synthesising nothing at all would put the emitter back at 1 on top of a log
+ * that already has five entries.
+ *
+ * A damaged line is skipped rather than refused, which is the one place this
+ * differs from the checkpoint reader next door, and deliberately: a checkpoint
+ * is read to RESUME from, so a damaged one must stop the resume, while the
+ * transcript is read to REPORT from, and dropping every event after a torn line
+ * would be a larger loss than the torn line itself. The position count still
+ * advances over it, so the numbering of the events after it is unchanged.
+ */
+export async function readRunEventsIn(
+	runDir: string,
+	options?: ReadRunEventsOptions,
+): Promise<readonly PersistedRunEvent[]> {
+	let raw: string
+	try {
+		raw = await readFile(join(runDir, 'transcript.jsonl'), 'utf-8')
+	} catch (err) {
+		if (isFileNotFound(err)) return []
+		throw err
+	}
+
+	const sinceSeq = options?.sinceSeq ?? 0
+	const events: PersistedRunEvent[] = []
+	let position = 0
+
+	for (const line of raw.split('\n')) {
+		if (line.length === 0) continue
+		position += 1
+
+		let parsed: Record<string, unknown>
+		try {
+			parsed = JSON.parse(line) as Record<string, unknown>
+		} catch {
+			continue
+		}
+		if (parsed === null || typeof parsed !== 'object' || typeof parsed.type !== 'string') continue
+
+		const seq = typeof parsed.seq === 'number' ? parsed.seq : position
+		if (seq <= sinceSeq) continue
+
+		events.push({
+			...parsed,
+			seq,
+			// Stamped by `appendEvent` since long before it was declared. A line
+			// that predates even that gets the only honest answer available:
+			// zero, which sorts before every real moment and cannot be mistaken
+			// for one.
+			timestamp: typeof parsed.timestamp === 'number' ? parsed.timestamp : 0,
+		} as unknown as PersistedRunEvent)
+	}
+
+	return events
+}
+
+/**
+ * Terminate a transcript whose last line was cut off mid-write.
+ *
+ * A process killed during `appendFile` leaves a fragment with no newline. The
+ * next append lands on the same line, so the fragment and a WHOLE, correct
+ * event merge into one unparsable line — and the reader skips it. The event was
+ * written, the emitter counted it as durable, and it is gone.
+ *
+ * Ending the fragment is enough. It stays unreadable and is skipped as it
+ * always was; everything appended after it survives, which is the difference
+ * between losing one event and losing one event plus the next.
+ *
+ * Called from `initRun`, which is the only moment the store knows nothing is
+ * mid-write.
+ */
+async function healTornTranscript(runDir: string): Promise<void> {
+	const path = join(runDir, 'transcript.jsonl')
+	let raw: string
+	try {
+		raw = await readFile(path, 'utf-8')
+	} catch (err) {
+		if (isFileNotFound(err)) return
+		throw err
+	}
+	if (raw.length === 0 || raw.endsWith('\n')) return
+	await appendFile(path, '\n', 'utf-8')
+}
+
 /**
  * Every checkpoint stored under one run directory, ascending by `createdAt`.
  *

package/src/store/run/memory.ts

@@ -1,6 +1,6 @@
 import type { Run } from '../../types/run/entity.js'
-import type { RunEvent } from '../../types/run/events.js'
-import type { CompletedToolRecord, RunStore } from '../../types/run/store.js'
+import type { PersistedRunEvent, RunEvent } from '../../types/run/events.js'
+import type { CompletedToolRecord, ReadRunEventsOptions, RunStore } from '../../types/run/store.js'
 
 /**
  * Process-local {@link RunStore}: a run's evidence with no filesystem.
@@ -22,9 +22,21 @@ export class InMemoryRunStore implements RunStore {
 	private meta: Run | null = null
 	private messages: Run['messages'] = []
 	private report: string | null = null
-	private readonly events: RunEvent[] = []
+	private events: PersistedRunEvent[] = []
 
 	async initRun(runId: string, parentRunId?: string): Promise<string | null> {
+		// Rebinding to a DIFFERENT run starts that run's evidence empty. The disk
+		// store gets this for free — a different id is a different directory —
+		// and this one has to say it, because one instance reused for a replay
+		// fork otherwise reports the origin run's events, its messages and its
+		// report as the new run's own. Evidence attributed to the wrong run is
+		// worse than none: it is wrong and it looks right.
+		if (this.runId !== null && this.runId !== runId) {
+			this.meta = null
+			this.messages = []
+			this.report = null
+			this.events = []
+		}
 		this.runId = runId
 		this.parentRunId = parentRunId
 		// No location, and that is the honest answer rather than a defect.
@@ -68,7 +80,25 @@ export class InMemoryRunStore implements RunStore {
 		// line — a parity test compares the two read-backs, and a timestamp
 		// present in one medium and absent in the other would make identical
 		// runs look different depending on where they were recorded.
-		this.events.push({ ...event, timestamp: Date.now() } as unknown as RunEvent)
+		//
+		// An unsequenced event takes its position in the log, which is the same
+		// rule the disk reader applies to a line written before events were
+		// numbered. Nothing in the kernel appends unsequenced today; the rule is
+		// here so the two backends cannot answer differently if something does.
+		this.events.push({
+			...event,
+			seq: event.seq ?? this.events.length + 1,
+			timestamp: Date.now(),
+		} as unknown as PersistedRunEvent)
+	}
+
+	async readEvents(options?: ReadRunEventsOptions): Promise<readonly PersistedRunEvent[]> {
+		this.requireInit()
+		const sinceSeq = options?.sinceSeq ?? 0
+		// Copied, not sliced by reference, for the same reason `writeRunMeta`
+		// clones: a caller holding the array must not be able to reach into the
+		// log through it.
+		return this.events.filter((event) => event.seq > sinceSeq).map((event) => ({ ...event }))
 	}
 
 	async writeReport(content: string): Promise<string | null> {
@@ -114,7 +144,7 @@ export class InMemoryRunStore implements RunStore {
 		meta: Run | null
 		messages: Run['messages']
 		report: string | null
-		events: readonly RunEvent[]
+		events: readonly PersistedRunEvent[]
 	} {
 		return { meta: this.meta, messages: this.messages, report: this.report, events: this.events }
 	}

package/src/types/doctor/check.ts

@@ -1,4 +1,21 @@
-export type DoctorStatus = 'pass' | 'fail' | 'inconclusive' | 'warn'
+/**
+ * What a check concluded.
+ *
+ * `skipped` and `inconclusive` are the two ways a check produces no verdict,
+ * and they are separate because a caller acts on them differently.
+ *
+ * - `skipped` — the check LOOKED and there was nothing here to check: an
+ *   optional package is not installed, a registry the check reads has no
+ *   auto-discovery to read, nothing is configured yet. A permanent or
+ *   by-design absence, and an ordinary state of a healthy machine.
+ * - `inconclusive` — the check DID NOT ANSWER: it timed out, it was aborted,
+ *   the thing it reads threw. Nothing is known either way, and that is itself
+ *   a gap in the report worth acting on.
+ *
+ * The word used to cover both, so `namzu doctor` could not tell "healthy" from
+ * "did not manage to look", and neither could anything reading its exit code.
+ */
+export type DoctorStatus = 'pass' | 'fail' | 'inconclusive' | 'warn' | 'skipped'
 
 export type DoctorCategory =
 	| 'sandbox'
@@ -47,7 +64,16 @@ export interface DoctorReport {
 		readonly fail: number
 		readonly inconclusive: number
 		readonly warn: number
+		readonly skipped: number
+		/** Every other count sums to this. A reader may rely on that. */
 		readonly total: number
 	}
-	readonly exit: 0 | 1 | 2 | 70
+	/**
+	 * `69` is sysexits `EX_UNAVAILABLE`, whose own definition ends "a catchall
+	 * when something you wanted to do doesn't work, but you don't know why".
+	 * That is `inconclusive`. It is not `2`, which this report already spends on
+	 * "nothing was registered", and not `70`, which says the CLI is broken and
+	 * is worth a bug report.
+	 */
+	readonly exit: 0 | 1 | 2 | 69 | 70
 }

package/src/types/run/event-cursor.ts

@@ -0,0 +1,118 @@
+/**
+ * Where a reconnecting consumer left off, and whether the kernel can honour it.
+ *
+ * The shortfall is a VALUE here, not a sentence in a document. A consumer that
+ * asks for everything after sequence 400 and silently receives a splice from a
+ * different generation of the run is wrong and has no way to find out; a
+ * consumer handed `{ status: 'unavailable', reason: 'cursor_ahead' }` re-derives
+ * from the transcript and is right. That is refuse-do-not-degrade applied to a
+ * subscription rather than to a capability.
+ */
+
+import type { ClaimFence } from './checkpoint-store.js'
+import type { PersistedRunEvent } from './events.js'
+
+/** What a consumer holds when it comes back. */
+export interface RunEventCursor {
+	/**
+	 * The last `seq` the consumer actually received, from the envelope. Zero —
+	 * or the field absent — means "from the beginning".
+	 */
+	readonly sinceSeq: number
+	/**
+	 * The `generation` carried on the events the consumer received, when they
+	 * carried one.
+	 *
+	 * Compared for equality only. Absent on both sides is not a match and not a
+	 * mismatch: it is an unfenced run, where the sequence is the only evidence
+	 * available and the log persisting is the assumption.
+	 */
+	readonly generation?: ClaimFence
+}
+
+/** Why a cursor could not be honoured. */
+export type RunEventReplayRefusal =
+	/**
+	 * The consumer claims to have seen more than the log holds.
+	 *
+	 * The ordinary cause is not a lying client: it is a log that did not
+	 * survive. An in-memory run store on a restarted process seeds at zero
+	 * while the consumer still holds 400, and this is the verdict that says so
+	 * instead of reporting a serene "you are up to date".
+	 */
+	| 'cursor_ahead'
+	/**
+	 * The run has been taken over since. The consumer's sequence numbers were
+	 * minted under an older claim and address a different sequence space, so
+	 * they are not comparable — not merely stale.
+	 */
+	| 'generation_changed'
+	/**
+	 * The store answered, and its oldest available event is above the one after
+	 * the cursor. A pruning or windowed backend, caught at the boundary rather
+	 * than delivered as a continuous stream with a hole in it.
+	 */
+	| 'gap'
+
+/** What came of a cursor. */
+export type RunEventReplay =
+	/** The cursor is already at the log's head. Nothing was missed. */
+	| { readonly status: 'complete' }
+	/** Contiguous from `sinceSeq + 1`, oldest first. */
+	| { readonly status: 'replayed'; readonly events: readonly PersistedRunEvent[] }
+	/** Nothing is delivered. The consumer re-derives from the transcript. */
+	| { readonly status: 'unavailable'; readonly reason: RunEventReplayRefusal }
+
+/** The log's present state, as the store reports it. */
+export interface RunEventLogHead {
+	/** Highest sequence in the log; zero when it is empty. */
+	readonly lastSeq: number
+	/** The fence the run is being written under, when it holds a claim. */
+	readonly generation?: ClaimFence
+}
+
+/**
+ * Decide what a cursor is owed, given what the log holds.
+ *
+ * Pure, and ordered deliberately: a takeover invalidates the sequence space, so
+ * comparing sequences across generations would be arithmetic on two different
+ * scales. The generation check therefore runs FIRST, before the numbers are
+ * allowed to mean anything.
+ *
+ * `events` is what the store returned for `{ sinceSeq: cursor.sinceSeq }`. It is
+ * passed in rather than fetched here so this stays a function of its arguments
+ * — the property "no gap, no duplicate" is decidable from the three inputs, and
+ * a test can drive every branch without a store.
+ */
+export function resolveRunEventReplay(
+	cursor: RunEventCursor,
+	head: RunEventLogHead,
+	events: readonly PersistedRunEvent[],
+): RunEventReplay {
+	// Both sides must carry one for a mismatch to mean anything. An unfenced run
+	// has no generation to disagree with, and treating "absent" as a distinct
+	// value would refuse every run that never took a claim — which is most of
+	// them.
+	if (
+		cursor.generation !== undefined &&
+		head.generation !== undefined &&
+		cursor.generation !== head.generation
+	) {
+		return { status: 'unavailable', reason: 'generation_changed' }
+	}
+
+	if (cursor.sinceSeq > head.lastSeq) {
+		return { status: 'unavailable', reason: 'cursor_ahead' }
+	}
+
+	if (cursor.sinceSeq === head.lastSeq) return { status: 'complete' }
+
+	// The log says there is something above the cursor, so an empty answer is
+	// the store contradicting its own head rather than "nothing to send".
+	const first = events[0]
+	if (!first || first.seq !== cursor.sinceSeq + 1) {
+		return { status: 'unavailable', reason: 'gap' }
+	}
+
+	return { status: 'replayed', events }
+}

package/src/types/run/events.ts

@@ -15,6 +15,7 @@ import type {
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
+import type { ClaimFence } from './checkpoint-store.js'
 import type { Lineage } from './lineage.js'
 import type { MessageStopReason, StopReason } from './stop-reason.js'
 import type {
@@ -43,6 +44,57 @@ interface RunEventEnvelope {
 	 */
 	schemaVersion?: 3
 	lineage?: Lineage
+	/**
+	 * This event's position in its OWN run's durable event log, from 1.
+	 *
+	 * **Present means recorded.** The emitter takes a candidate number, appends
+	 * the event stamped with it, and only then advances the counter and hands
+	 * the event to the live stream — so a `seq` a consumer can see is a `seq`
+	 * the log contains. That is what makes it usable as a cursor: reconnect,
+	 * ask for everything above it, and nothing is missed and nothing arrives
+	 * twice.
+	 *
+	 * **Absent means not recoverable**, and three different things arrive that
+	 * way:
+	 *
+	 *  - the high-frequency events {@link isEphemeralEvent} names, which are
+	 *    deliberately never persisted;
+	 *  - an event whose durable write FAILED — it still reaches the live
+	 *    stream, unstamped, because losing the news of a failure is worse than
+	 *    delivering it without a cursor;
+	 *  - the delegation lifecycle events (`agent_pending`, `agent_completed`,
+	 *    `agent_failed`, `agent_canceled` and the three sub-session variants),
+	 *    which the agent manager hands straight to a host's listener without
+	 *    passing through the run's event translator at all. They are not in any
+	 *    run's log, and the missing `seq` is how a consumer learns that rather
+	 *    than discovering it after a reconnect.
+	 *
+	 * **Per run, not per stream.** A parent's listener also receives its
+	 * children's events, each numbered in its own run's log, so a consumer
+	 * keeps one cursor per `runId`. The SSE mapper carries the pair as
+	 * `<runId>:<seq>` for exactly this reason.
+	 *
+	 * Monotonic under a single writer. The run store takes no claim fence
+	 * today (see `QueryParams.claimFence`), so two workers that both took one
+	 * run can both append — `generation` is what makes that detectable.
+	 */
+	seq?: number
+	/**
+	 * The claim fence the run was being written under, when it holds a claim.
+	 *
+	 * A sequence alone lies across a takeover: a client at seq 400 reconnects
+	 * to a run whose store lost its log, the new writer starts at 1, and the
+	 * client's cursor silently addresses a different sequence space. The fence
+	 * is already the arbiter of who may write and it only increases, so
+	 * carrying it here makes a takeover ORDERED rather than merely
+	 * distinguishable.
+	 *
+	 * Absent when the run was written unfenced, which is every run that took no
+	 * claim. A cursor then relies on the log persisting — the disk store's
+	 * does, an in-memory store's does not, and `cursor_ahead` is the verdict
+	 * that catches the difference.
+	 */
+	generation?: ClaimFence
 }
 
 type CoreRunEvent =
@@ -679,12 +731,37 @@ type CoreRunEvent =
  */
 export type RunEvent =
 	| (CoreRunEvent & RunEventEnvelope)
-	| SubsessionSpawnedEvent
-	| SubsessionMessagedEvent
-	| SubsessionIdledEvent
+	// Intersected so `seq` is READABLE on every member of the union — TypeScript
+	// refuses a property access on a union where one member lacks the field, and
+	// a consumer holding a cursor has to be able to ask any event for its
+	// number. These three never carry one, and that is the answer rather than an
+	// omission: they are emitted straight to a host's listener and reach no run's
+	// durable log.
+	| (SubsessionSpawnedEvent & RunEventEnvelope)
+	| (SubsessionMessagedEvent & RunEventEnvelope)
+	| (SubsessionIdledEvent & RunEventEnvelope)
 
 export type RunEventListener = (event: RunEvent) => void | Promise<void>
 
+/**
+ * A run event as the durable log gives it back.
+ *
+ * `seq` and `timestamp` are REQUIRED here and optional on the live envelope,
+ * which is the whole difference between the two types: a recorded event has a
+ * position and a moment, and a live one may be neither recorded nor
+ * recoverable.
+ *
+ * `timestamp` is not new — both store implementations have always stamped it
+ * on write. It was simply never declared anywhere, so the field was persisted
+ * by two writers, typed by neither, and read by nobody. Declaring it is what
+ * lets the read-back stop casting.
+ */
+export type PersistedRunEvent = RunEvent & {
+	readonly seq: number
+	/** Epoch ms at which the store recorded the event. */
+	readonly timestamp: number
+}
+
 /**
  * Event types whose volume makes durable persistence wasteful.
  *

package/src/types/run/index.ts

@@ -4,6 +4,7 @@ export * from './stop-reason.js'
 export * from './config.js'
 export * from './checkpoint-store.js'
 export * from './store.js'
+export * from './event-cursor.js'
 export * from './entity.js'
 export * from './replay.js'
 // Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to

package/src/types/run/store.ts

@@ -28,7 +28,19 @@
  */
 
 import type { Run } from './entity.js'
-import type { RunEvent } from './events.js'
+import type { PersistedRunEvent, RunEvent } from './events.js'
+
+/** What a caller asks the log for. See {@link RunStore.readEvents}. */
+export interface ReadRunEventsOptions {
+	/**
+	 * Return only events ABOVE this sequence — strictly greater, never equal.
+	 *
+	 * The exclusive boundary is what makes a cursor round-trip: a consumer that
+	 * last saw `seq: 12` passes 12 and receives 13 onward, so nothing is
+	 * delivered twice. Absent means the whole log.
+	 */
+	readonly sinceSeq?: number
+}
 
 /**
  * One finished tool call, recovered from the run's own transcript.
@@ -71,6 +83,36 @@ export interface RunStore {
 	 */
 	appendEvent(event: RunEvent): Promise<void>
 
+	/**
+	 * Read the run's durable event log back, oldest first.
+	 *
+	 * Required, unlike {@link RunStore.addToIndex}, and the asymmetry is the
+	 * point: a store that records a transcript it cannot read back is
+	 * write-only evidence, which is the defect the whole contract exists to
+	 * fix one level up. It is also what a reconnecting consumer catches up
+	 * through — "refresh the page and keep watching the answer arrive" is this
+	 * method plus a cursor and nothing else.
+	 *
+	 * Three obligations, each of which a consumer relies on:
+	 *
+	 *  1. **Ascending by `seq`, in the order the events were appended.** Do not
+	 *     sort a log back into order — a log that needs sorting was written by
+	 *     two processes, and hiding that produces a plausible transcript of a
+	 *     run that never happened.
+	 *  2. **`sinceSeq` is exclusive.** See {@link ReadRunEventsOptions}.
+	 *  3. **Contiguous, or honestly short.** A backend that prunes may return a
+	 *     first event above `sinceSeq + 1`; that is a gap, the caller detects
+	 *     it, and the reconnect is refused rather than spliced. Do NOT
+	 *     manufacture placeholders to close it.
+	 *
+	 * High-frequency events never enter the log (see
+	 * {@link RunStore.appendEvent}), so what a late subscriber recovers is
+	 * message-granular, not keystroke-granular. Aggregated assistant text,
+	 * every tool result and the full message list are all intact; the deltas
+	 * that composed them are not, and are not meant to be.
+	 */
+	readEvents(options?: ReadRunEventsOptions): Promise<readonly PersistedRunEvent[]>
+
 	/**
 	 * Persist the run's final report. Returns a location, or `null` when the
 	 * backend has none. See {@link RunStore.initRun}.