@namzu/sdk 43.0.0 → 44.1.0

package/src/scheduler/local.ts

@@ -11,8 +11,8 @@ import type {
 import type { AgentTaskContext } from '../types/agent/task.js'
 import type { TaskId } from '../types/ids/index.js'
 import { createUserMessage } from '../types/message/index.js'
-import type { CancelCause } from '../types/run/cancel-cause.js'
-import type { RunEventListener } from '../types/run/events.js'
+import type { CancelCause } from '../types/session/cancel-cause.js'
+import type { ChildSessionLifecycleEvent, SessionEventListener } from '../types/session/events.js'
 import { toErrorMessage } from '../utils/error.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
@@ -20,10 +20,10 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
 /**
  * How many launched tasks a gateway remembers.
  *
- * High enough that no realistic single run reaches it — a fan-out is eight,
- * a long supervisory run is dozens — so the listing a supervisor reads at the
- * end of its run is always complete. It exists for the host that reuses one
- * gateway across runs, where the alternative is a set and a map that grow for
+ * High enough that no realistic single turn reaches it — a fan-out is eight,
+ * a long supervisory turn is dozens — so the listing a supervisor reads at the
+ * end of its turn is always complete. It exists for the host that reuses one
+ * gateway across turns, where the alternative is a set and a map that grow for
  * the life of the process.
  */
 const GATEWAY_TASK_LEDGER_CAP = 1_000
@@ -31,7 +31,7 @@ const GATEWAY_TASK_LEDGER_CAP = 1_000
 interface ObserverDelivery {
 	busy: boolean
 	readonly queue: Array<{
-		readonly event: Parameters<RunEventListener>[0]
+		readonly event: Parameters<SessionEventListener>[0]
 		readonly observer: 'scheduler' | 'task'
 	}>
 }
@@ -39,7 +39,7 @@ interface ObserverDelivery {
 export class LocalTaskScheduler implements TaskScheduler {
 	private agentManager: AgentManagerContract
 	private taskContext: AgentTaskContext
-	private listener: RunEventListener | undefined
+	private listener: SessionEventListener | undefined
 	private trackedTaskIds: Set<TaskId> = new Set()
 
 	private parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>
@@ -52,7 +52,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 	 * Terminal tasks leave the manager 30 seconds after they finish, and
 	 * `listTasks` rebuilt itself by looking every tracked id back up — so a
 	 * task that finished a minute ago simply vanished from the tool whose
-	 * whole job is the end-of-run check. A supervisor could not tell an
+	 * whole job is the end-of-turn check. A supervisor could not tell an
 	 * evicted task from one that never launched; both read as absence.
 	 *
 	 * Eviction is there to release the heavy state — messages, controllers,
@@ -64,6 +64,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 	private siblingFailurePolicy: SiblingFailurePolicy = 'continue'
 	/** See {@link onTaskProgress}. */
 	private readonly progressListeners = new Set<(taskId: TaskId) => void>()
+	private readonly childSessionListeners = new Set<(event: ChildSessionLifecycleEvent) => void>()
 	/**
 	 * One non-blocking delivery chain per observer.
 	 *
@@ -72,7 +73,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 	 * slow exporter cannot hold up a task-specific screen (or another task's
 	 * screen) that uses a different callback.
 	 */
-	private readonly observerDeliveries = new WeakMap<RunEventListener, ObserverDelivery>()
+	private readonly observerDeliveries = new WeakMap<SessionEventListener, ObserverDelivery>()
 	/** Raw, unresolved — kept as the caller handed it so each of the two log
 	 * sites below resolves it independently via `resolveLogger`, rather than
 	 * this constructor baking in ONE `.child()` binding both would then share
@@ -83,7 +84,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 	constructor(
 		agentManager: AgentManagerContract,
 		taskContext: AgentTaskContext,
-		listener?: RunEventListener,
+		listener?: SessionEventListener,
 		parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>,
 		options?: { siblingFailurePolicy?: SiblingFailurePolicy; log?: Logger },
 	) {
@@ -136,7 +137,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 				projectId: this.taskContext.projectId,
 				parentActor: this.taskContext.parentActor,
 				// The caller's overrides, plus the span the caller supplied so a
-				// delegated run joins the trace it belongs to instead of
+				// delegated session joins the trace it belongs to instead of
 				// starting its own root.
 				//
 				// `options.configOverrides` used to be dropped here: this built
@@ -178,13 +179,33 @@ export class LocalTaskScheduler implements TaskScheduler {
 			(event) => {
 				// A scheduler-wide observer and this task's observer are independent.
 				// Either may throw or reject: observation is not authority over the
-				// child, and one broken screen/export must neither stop the run nor
+				// child, and one broken screen/export must neither stop the turn nor
 				// suppress the other observer. Async listeners are deliberately not
 				// awaited, so a slow renderer cannot backpressure model streaming.
 				this.deliverEvent(this.listener, event, 'scheduler')
 				if (options.onEvent !== this.listener) {
 					this.deliverEvent(options.onEvent, event, 'task')
 				}
+				// The parent turn's own record of its children. Synchronous and
+				// before anything else can settle, so `child_session_ended` is
+				// queued ahead of the parent's next record.
+				if (
+					event.type === 'child_session_spawned' ||
+					event.type === 'child_session_messaged' ||
+					event.type === 'child_session_idled'
+				) {
+					for (const notify of this.childSessionListeners) {
+						try {
+							notify(event)
+						} catch (err) {
+							resolveLogger(this.log)
+								.child({ [SCOPE_ATTRIBUTE]: 'scheduler/local' })
+								.warn('Child session observer failed', {
+									'exception.message': toErrorMessage(err),
+								})
+						}
+					}
+				}
 				// No id yet means nothing is waiting on this task: the caller
 				// does not hold the handle, so an idle bound cannot be running
 				// against it. There is no progress to report to anyone.
@@ -225,13 +246,13 @@ export class LocalTaskScheduler implements TaskScheduler {
 	}
 
 	private deliverEvent(
-		listener: RunEventListener | undefined,
-		event: Parameters<RunEventListener>[0],
+		listener: SessionEventListener | undefined,
+		event: Parameters<SessionEventListener>[0],
 		observer: 'scheduler' | 'task',
 	): void {
 		if (!listener) return
 
-		// Each observer receives its own value graph. RunEvent is readonly at the
+		// Each observer receives its own value graph. SessionEvent is readonly at the
 		// type boundary, but a JavaScript consumer can still mutate an object it
 		// was handed; that must not forge what the next independent observer sees.
 		const snapshot = structuredClone(event)
@@ -244,7 +265,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 		this.drainObserver(listener, delivery)
 	}
 
-	private drainObserver(listener: RunEventListener, delivery: ObserverDelivery): void {
+	private drainObserver(listener: SessionEventListener, delivery: ObserverDelivery): void {
 		if (delivery.busy) return
 		while (delivery.queue.length > 0) {
 			const next = delivery.queue.shift()
@@ -272,7 +293,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 	}
 
 	private reportObserverFailure(
-		eventType: Parameters<RunEventListener>[0]['type'],
+		eventType: Parameters<SessionEventListener>[0]['type'],
 		observer: 'scheduler' | 'task',
 		error: unknown,
 	): void {
@@ -362,12 +383,12 @@ export class LocalTaskScheduler implements TaskScheduler {
 	/**
 	 * Drop the oldest tasks once the ledger passes {@link GATEWAY_TASK_LEDGER_CAP}.
 	 *
-	 * A gateway constructed per run is bounded by that run and this never
+	 * A gateway constructed per turn is bounded by that turn and this never
 	 * fires. But `SupervisorAgentConfig.gateway` lets a host supply its own,
 	 * and a long-lived host reusing one accumulates an id and a settled handle
 	 * per task it ever launched, for the life of the process — the doc above
 	 * says "bounded by the number the gateway itself launched", which is true
-	 * and is not a bound when the gateway outlives the run.
+	 * and is not a bound when the gateway outlives the turn.
 	 *
 	 * Both collections are evicted **together and in insertion order**. Losing
 	 * a tracked id while keeping its handle, or the reverse, would make a task
@@ -403,7 +424,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 	 * Every event a child emits, reduced to "this one is still alive".
 	 *
 	 * Deliberately just the id. A caller that wanted the event itself has
-	 * the run listener; what an idle clock needs is the fact, and passing
+	 * the turn listener; what an idle clock needs is the fact, and passing
 	 * the payload here would make this a second way to read a worker's
 	 * output — one nobody documented and nothing frames as untrusted.
 	 */
@@ -420,6 +441,13 @@ export class LocalTaskScheduler implements TaskScheduler {
 			this.completionListeners.delete(callback)
 		}
 	}
+
+	onChildSessionEvent(callback: (event: ChildSessionLifecycleEvent) => void): () => void {
+		this.childSessionListeners.add(callback)
+		return () => {
+			this.childSessionListeners.delete(callback)
+		}
+	}
 }
 
 /**

package/src/session/events/index.ts

@@ -1,17 +1,13 @@
-// Sub-barrel for session-hierarchy run-event surface.
-// Shape types live under `types/run/` (subsession-events.ts + schema-version.ts);
-// this barrel only re-exports them. No runtime emitter lives here today.
-//
-// Phase 2 scope is limited to the sub-session lifecycle variants that are
-// spliced into `RunEvent`. A dedicated `SessionHierarchyEvent` top-level
-// union lands in a later phase (see session-hierarchy.md §10.2).
+// Sub-barrel for the session-hierarchy event surface. Shape types live under
+// `types/session/` (events.ts, records.ts); this barrel only re-exports them.
+// No runtime emitter lives here.
 
-export { RUN_EVENT_SCHEMA_VERSION } from '../../types/run/schema-version.js'
-export type { RunEventSchemaVersion } from '../../types/run/schema-version.js'
+export { SESSION_RECORD_SCHEMA_VERSION } from '../../types/session/records.js'
+export type { SessionRecordSchemaVersion } from '../../types/session/records.js'
 
 export type {
-	SubsessionSpawnedEvent,
-	SubsessionMessagedEvent,
-	SubsessionIdledEvent,
-	SubsessionLifecycleEvent,
-} from '../../types/run/subsession-events.js'
+	ChildSessionSpawnedEvent,
+	ChildSessionMessagedEvent,
+	ChildSessionIdledEvent,
+	ChildSessionLifecycleEvent,
+} from '../../types/session/events.js'

package/src/session/handoff/broadcast.ts

@@ -34,7 +34,7 @@ import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
 import type { HandoffAssignment, HandoffOutcome } from './assignment.js'
 import type { CapacityValidator } from './capacity.js'
 import type { HandoffEventSink } from './events.js'
-import type { RunStatusResolver } from './single.js'
+import type { TurnStatusResolver } from './single.js'
 import { HandoffLockRejected, HandoffVersionConflict } from './version.js'
 
 interface BroadcastHandoffBaseDeps {
@@ -43,10 +43,10 @@ interface BroadcastHandoffBaseDeps {
 	capacity: CapacityValidator
 	events: HandoffEventSink
 	/**
-	 * Required, for the reason `SingleHandoffDeps.runStatus` is: the default
+	 * Required, for the reason `SingleHandoffDeps.turnStatus` is: the default
 	 * that used to stand in here reported every session unblocked.
 	 */
-	runStatus: RunStatusResolver
+	turnStatus: TurnStatusResolver
 }
 
 /** Dependencies for a multi-recipient handoff. */
@@ -176,16 +176,16 @@ export async function executeBroadcastHandoff(
 			sessionId: source.id,
 			reason:
 				source.status === 'active'
-					? 'active_run'
+					? 'active_turn'
 					: source.status === 'awaiting_hitl'
 						? 'pending_hitl'
 						: 'pending_subsession',
 		})
 	}
 
-	// 5. Non-terminal Run fan-in (§5.1).
-	const runResolver = deps.runStatus
-	const blocking = await runResolver.blockingRun(source.id, tenantId)
+	// 5. Non-terminal turn fan-in (§5.1).
+	const turnResolver = deps.turnStatus
+	const blocking = await turnResolver.blockingTurn(source.id, tenantId)
 	if (blocking) {
 		throw new HandoffLockRejected({
 			sessionId: source.id,

package/src/session/handoff/events.ts

@@ -1,7 +1,7 @@
 /**
  * HandoffEventSink — pluggable event sink for Phase 4.
  *
- * Phase 4 does NOT extend `RunEvent` with handoff variants (they land in a
+ * Phase 4 does NOT extend `SessionEvent` with handoff variants (they land in a
  * later phase that wires the full `SessionHierarchyEvent` union referenced
  * by roadmap §1). In the meantime the flow functions invoke this sink so
  * consumers + tests can observe state transitions without a concrete event

package/src/session/handoff/index.ts

@@ -23,7 +23,7 @@ export type {
 } from './events.js'
 
 export { executeSingleHandoff } from './single.js'
-export type { RunStatusResolver, SingleHandoffDeps } from './single.js'
+export type { TurnStatusResolver, SingleHandoffDeps } from './single.js'
 
 export { executeBroadcastHandoff } from './broadcast.js'
 export type { BroadcastHandoffDeps } from './broadcast.js'

package/src/session/handoff/single.ts

@@ -8,7 +8,7 @@
  *
  * Flow (pattern doc §5.1 + §6.1):
  *   1. Load source session; verify tenant.
- *   2. Check status (must be `idle`); no non-terminal Runs.
+ *   2. Check status (must be `idle`); no non-terminal turns.
  *   3. Validate capacity (depth + width).
  *   4. Transition source `idle → locked` with CAS on `ownerVersion`.
  *   5. Emit `onLocked`.
@@ -35,23 +35,23 @@ import type { HandoffEventSink } from './events.js'
 import { HandoffLockRejected, HandoffVersionConflict } from './version.js'
 
 /**
- * Minimal surface the handoff flow queries for Run fan-in status. A Run is
- * considered "blocking" if it is in any non-terminal status that prevents the
- * source session from transitioning to `locked` (session-hierarchy.md §5.1).
+ * Minimal surface the handoff flow queries for turn fan-in status. A turn is
+ * "blocking" when it is in any non-terminal status that prevents the source
+ * session from transitioning to `locked` (session-hierarchy.md §5.1).
  *
- * The flow injects the resolver so Phase 4 stays decoupled from Phase 6's
- * Run persistence refactor. Production wires the real Run store; tests stub.
+ * The flow injects the resolver so it stays decoupled from how turns are
+ * stored. Production reads the session index; tests stub.
  */
-export interface RunStatusResolver {
+export interface TurnStatusResolver {
 	/**
-	 * Returns the reason the session has a non-terminal Run, or `null` when
-	 * all Runs are terminal and the lock is allowed.
+	 * Returns the reason the session has a non-terminal turn, or `null` when
+	 * all its turns are terminal and the lock is allowed.
 	 */
-	blockingRun(
+	blockingTurn(
 		sessionId: SessionId,
 		tenantId: TenantId,
 	): Promise<{
-		reason: 'active_run' | 'pending_hitl' | 'pending_subsession'
+		reason: 'active_turn' | 'pending_hitl' | 'pending_subsession'
 	} | null>
 }
 
@@ -66,7 +66,7 @@ interface SingleHandoffBaseDeps {
 	 * here answered `null` for every session, which is a check that cannot
 	 * fail dressed as a check that ran.
 	 */
-	runStatus: RunStatusResolver
+	turnStatus: TurnStatusResolver
 }
 
 /** Dependencies for a single-recipient handoff. */
@@ -128,9 +128,9 @@ export async function executeSingleHandoff(
 		})
 	}
 
-	// 3. Non-terminal Run fan-in (§5.1).
-	const runResolver = deps.runStatus
-	const blocking = await runResolver.blockingRun(source.id, tenantId)
+	// 3. Non-terminal turn fan-in (§5.1).
+	const turnResolver = deps.turnStatus
+	const blocking = await turnResolver.blockingTurn(source.id, tenantId)
 	if (blocking) {
 		throw new HandoffLockRejected({
 			sessionId: source.id,
@@ -308,24 +308,24 @@ async function revertLock(
 
 function statusToLockReason(
 	status: Session['status'],
-): 'active_run' | 'pending_hitl' | 'pending_subsession' {
+): 'active_turn' | 'pending_hitl' | 'pending_subsession' {
 	switch (status) {
 		case 'active':
-			return 'active_run'
+			return 'active_turn'
 		case 'awaiting_hitl':
 			return 'pending_hitl'
 		case 'awaiting_merge':
 			return 'pending_subsession'
 		case 'locked':
-			return 'active_run'
+			return 'active_turn'
 		case 'failed':
-			return 'active_run'
+			return 'active_turn'
 		case 'archived':
-			return 'active_run'
+			return 'active_turn'
 		case 'idle':
 			// Unreachable — caller guards. Keep a sentinel value so exhaustiveness
 			// does not force an `assert never` export from this module.
-			return 'active_run'
+			return 'active_turn'
 	}
 }
 

package/src/session/handoff/version.ts

@@ -7,7 +7,7 @@
  * fast).
  */
 
-import type { RunId, SessionId } from '../../types/ids/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
 
 /**
  * Raised when a handoff's CAS write finds {@link Session.ownerVersion} has
@@ -34,24 +34,28 @@ export class HandoffVersionConflict extends Error {
 /**
  * Reasons a session cannot transition `* → locked` for handoff. See
  * session-hierarchy.md §5.1 — lock entry requires an `idle` session with all
- * runs terminal. The three reasons are the non-terminal Run statuses that
+ * turns terminal. The three reasons are the non-terminal turn statuses that
  * fan in to a non-idle Session.
  */
-export type HandoffLockRejectedReason = 'active_run' | 'pending_hitl' | 'pending_subsession'
+export type HandoffLockRejectedReason = 'active_turn' | 'pending_hitl' | 'pending_subsession'
 
 /**
- * Raised when a handoff targets a session whose current Run is non-terminal.
- * Callers must wait for the active Run to terminalize (or cancel it) before
+ * Raised when a handoff targets a session whose current turn is non-terminal.
+ * Callers must wait for the active turn to terminalize (or cancel it) before
  * re-attempting the handoff (session-hierarchy.md §5.1).
  */
 export class HandoffLockRejected extends Error {
 	readonly details: {
 		sessionId: SessionId
 		reason: HandoffLockRejectedReason
-		runId?: RunId
+		turnId?: TurnId
 	}
 
-	constructor(details: { sessionId: SessionId; reason: HandoffLockRejectedReason; runId?: RunId }) {
+	constructor(details: {
+		sessionId: SessionId
+		reason: HandoffLockRejectedReason
+		turnId?: TurnId
+	}) {
 		super(`Handoff lock rejected on ${details.sessionId}: ${details.reason}`)
 		this.name = 'HandoffLockRejected'
 		this.details = details

package/src/session/home.ts

@@ -0,0 +1,66 @@
+import { lstatSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { parse, resolve } from 'node:path'
+
+/**
+ * `NAMZU_HOME`: the one user-level home the SDK and the CLI share
+ * (default `~/.namzu`). Session logs live under `projects/<slug>/` inside it;
+ * see `./paths.ts`.
+ */
+export interface ResolveNamzuHomeOptions {
+	/** OS home override for embedding and tests. */
+	readonly home?: string
+	/** Environment override for embedding and tests. */
+	readonly env?: NodeJS.ProcessEnv
+}
+
+export class NamzuHomeError extends Error {
+	override readonly name = 'NamzuHomeError'
+}
+
+/**
+ * Resolve the user-level Namzu application home without creating it.
+ *
+ * `NAMZU_HOME` is an explicit operator assertion, so it is validated more
+ * strictly than the default: it must already be a real directory and its
+ * canonical identity is returned. The default remains creatable on first use.
+ */
+export function resolveNamzuHome(options: ResolveNamzuHomeOptions = {}): string {
+	const env = options.env ?? process.env
+	const configured = env.NAMZU_HOME
+	if (configured === undefined || configured.length === 0) {
+		return resolve(options.home ?? homedir(), '.namzu')
+	}
+	if (configured.includes('\0')) {
+		throw new NamzuHomeError('NAMZU_HOME contains a NUL byte and cannot name a directory.')
+	}
+
+	let entry: ReturnType<typeof lstatSync>
+	try {
+		entry = lstatSync(configured)
+	} catch (error) {
+		throw new NamzuHomeError(
+			`NAMZU_HOME points to ${JSON.stringify(configured)}, but that path cannot be read: ${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+	if (entry.isSymbolicLink() || !entry.isDirectory()) {
+		throw new NamzuHomeError(
+			`NAMZU_HOME points to ${JSON.stringify(configured)}, but it is not a real directory.`,
+		)
+	}
+
+	let canonical: string
+	try {
+		canonical = realpathSync(configured)
+	} catch (error) {
+		throw new NamzuHomeError(
+			`NAMZU_HOME ${JSON.stringify(configured)} could not be canonicalized: ${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+	if (canonical === parse(canonical).root) {
+		throw new NamzuHomeError(
+			`NAMZU_HOME must not be a filesystem root: ${JSON.stringify(canonical)}. Choose a dedicated directory.`,
+		)
+	}
+	return canonical
+}

package/src/session/index.ts

@@ -13,3 +13,4 @@ export * from './summary/index.js'
 export * from './intervention/index.js'
 export * from './retention/index.js'
 export { TenantIsolationError, WorkspaceBackendError, AncestryCycleError } from './errors.js'
+export { readSessionMessages } from './messages.js'

package/src/session/log-hash.ts

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto'
+import {
+	SESSION_RECORD_MAX_BYTES,
+	type SessionRecord,
+	SessionRecordSchema,
+} from '../types/session/records.js'
+
+/**
+ * The byte-level rules of one session-log line, shared by the writer, the
+ * reader and the index.
+ *
+ * A line is one record serialised as JSON and terminated by `\n`. Its hash is
+ * the SHA-256 of exactly those bytes, the newline included, and a record's
+ * `prev` pointer names the previous line by seq, byte offset, byte length and
+ * that hash. Nothing is canonicalised: the bytes on disk are the bytes hashed.
+ */
+
+const NEWLINE = 0x0a
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8', { fatal: true })
+
+function bytesOf(line: string | Uint8Array): Uint8Array {
+	return typeof line === 'string' ? encoder.encode(line) : line
+}
+
+/** SHA-256 (lowercase hex) of one complete line, its terminating newline included. */
+export function recordSha256(line: string | Uint8Array): string {
+	return createHash('sha256').update(bytesOf(line)).digest('hex')
+}
+
+/** Serialise a record as the one line a log stores for it. */
+export function formatSessionLogLine(record: SessionRecord): string {
+	const line = `${JSON.stringify(record)}\n`
+	const length = encoder.encode(line).byteLength
+	if (length > SESSION_RECORD_MAX_BYTES) {
+		throw new SessionLogLineError(
+			'too-large',
+			`A ${record.type} record is ${length} bytes; the limit is ${SESSION_RECORD_MAX_BYTES}. Spill the body to tool-results/ first.`,
+		)
+	}
+	return line
+}
+
+export type SessionLogLineFault = 'torn' | 'too-large' | 'not-utf8' | 'not-json' | 'not-a-record'
+
+/** One line that is not a complete, valid record. `fault` says which rule it broke. */
+export class SessionLogLineError extends Error {
+	override readonly name = 'SessionLogLineError'
+	constructor(
+		readonly fault: SessionLogLineFault,
+		message: string,
+	) {
+		super(message)
+	}
+}
+
+export interface ParsedSessionLogLine {
+	readonly record: SessionRecord
+	/** Bytes of the line, newline included: the `length` of a pointer to it. */
+	readonly length: number
+	readonly sha256: string
+}
+
+/**
+ * Parse one complete line of a session log: exactly one record followed by
+ * one `\n`. A line with no terminating newline is `torn` (a crash mid-append);
+ * the reader, not this function, decides to truncate it.
+ */
+export function parseSessionLogLine(line: string | Uint8Array): ParsedSessionLogLine {
+	const bytes = bytesOf(line)
+	if (bytes.byteLength > SESSION_RECORD_MAX_BYTES) {
+		throw new SessionLogLineError(
+			'too-large',
+			`A session-log line is ${bytes.byteLength} bytes; the limit is ${SESSION_RECORD_MAX_BYTES}.`,
+		)
+	}
+	const end = bytes.indexOf(NEWLINE)
+	if (end !== bytes.byteLength - 1) {
+		throw new SessionLogLineError(
+			'torn',
+			end === -1
+				? 'The line has no terminating newline: the record was cut off mid-append.'
+				: 'The line holds more than one record.',
+		)
+	}
+	let text: string
+	try {
+		text = decoder.decode(bytes.subarray(0, end))
+	} catch {
+		throw new SessionLogLineError('not-utf8', 'The line is not valid UTF-8.')
+	}
+	let value: unknown
+	try {
+		value = JSON.parse(text)
+	} catch (error) {
+		throw new SessionLogLineError(
+			'not-json',
+			`The line is not JSON: ${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+	const parsed = SessionRecordSchema.safeParse(value)
+	if (!parsed.success) {
+		throw new SessionLogLineError(
+			'not-a-record',
+			`The line is not a session record: ${parsed.error.issues
+				.map((issue) => `${issue.path.join('.') || '(record)'}: ${issue.message}`)
+				.join('; ')}`,
+		)
+	}
+	return {
+		record: parsed.data as SessionRecord,
+		length: bytes.byteLength,
+		sha256: recordSha256(bytes),
+	}
+}

package/src/session/messages.ts

@@ -0,0 +1,39 @@
+import { type SessionLog, SessionMessageFold } from '../store/session-log/index.js'
+import type { SpillRef } from '../store/session-log/spill.js'
+import type { TenantId } from '../types/ids/index.js'
+import type { Message } from '../types/message/index.js'
+import type { SessionMessage } from '../types/session/messages.js'
+import type { SessionRecord } from '../types/session/records.js'
+
+/**
+ * A session's conversation as {@link SessionMessage}s: the fold of its log
+ * (with every `message_replaced` applied), each message carrying the id and
+ * time of its record. A compaction summary message has no record of its own
+ * and carries the compaction's time and no id of its own; it is skipped.
+ */
+export async function readSessionMessages(
+	log: SessionLog,
+	tenantId: TenantId,
+): Promise<SessionMessage[]> {
+	const fold = new SessionMessageFold()
+	const times = new Map<number, string>()
+	for await (const { record } of log.read()) {
+		times.set(record.seq, record.ts)
+		fold.apply(record as SessionRecord)
+	}
+	const out: SessionMessage[] = []
+	for (const entry of fold.entries()) {
+		if (!entry.messageId) continue
+		const message = entry.spill
+			? (JSON.parse(await log.readSpill(entry.spill as SpillRef)) as Message)
+			: entry.message
+		out.push({
+			id: entry.messageId,
+			sessionId: log.sessionId,
+			tenantId,
+			message,
+			at: new Date(times.get(entry.seq) ?? 0),
+		})
+	}
+	return out
+}