@namzu/sdk 20.0.0 → 20.2.0

package/src/public-runtime.ts

@@ -198,12 +198,25 @@ export {
 	DiskCheckpointStore,
 	DiskMemoryStore,
 	DiskTaskStore,
+	InMemoryCheckpointStore,
 	InMemoryMemoryIndex,
 	InMemoryMemoryStore,
 	InMemoryStore,
 	InMemoryTaskStore,
 	RunDiskStore,
 } from './store/index.js'
+export type { DiskCheckpointStoreAttribution } from './store/index.js'
+// Enumerating runs above a run id — the read an approval inbox and a park
+// sweep are built from, and the one the contract had no way to express.
+// `listDurableRuns` REFUSES on a store that cannot list rather than
+// reporting an empty page, because "nothing is waiting on a human" is not
+// what "I cannot tell" means.
+export {
+	assertContiguousListingScope,
+	listDurableRuns,
+	paginateDurableRuns,
+	toDurableRunEntry,
+} from './store/index.js'
 
 export {
 	AgentRegistry,

package/src/runtime/query/checkpoint.ts

@@ -51,6 +51,12 @@ export function projectEmergencyToCheckpoint(dump: EmergencySaveData): Iteration
 	return {
 		id: `cp_emergency_${emergencySuffix}` as CheckpointId,
 		runId: dump.runId,
+		// The dump records the run's start, so this projection carries the
+		// same stamp an ordinary checkpoint of that run would — a run whose
+		// only surviving record is an emergency dump still has a real
+		// attribution instant, and dropping it here would put that run in the
+		// "never recorded" bucket for no reason.
+		runCreatedAt: dump.startedAt,
 		iteration: dump.currentIteration,
 		messages: dump.messages,
 		tokenUsage: dump.tokenUsage,
@@ -148,6 +154,27 @@ export class CheckpointManager {
 	/** See {@link setParkTtl}. */
 	private parkTtlMs?: number
 
+	/**
+	 * The run's attribution instant, stamped onto every checkpoint this
+	 * manager writes.
+	 *
+	 * Settled exactly once, by whichever of two things happens first, and
+	 * never reassigned — every write to it below is `??=`, and there are only
+	 * two:
+	 *
+	 *  - `restore` ADOPTS it from the checkpoint a resume came back through.
+	 *    A resumed run is the same run, and its creation is already on the
+	 *    record; a fresh process minting a new one would move the key that
+	 *    exists specifically because it does not move.
+	 *  - `create` MINTS it from the run's own start instant when nothing was
+	 *    adopted, which is the fresh-run case.
+	 *
+	 * Restore runs during run setup, before the first iteration and therefore
+	 * before the first `create`, so the adopt always wins on the resume path
+	 * without either site needing to know which path it is on.
+	 */
+	private runCreatedAt?: number
+
 	/**
 	 * @param store scope-keyed checkpoint persistence. The default query
 	 *   pipeline passes the run's disk-backed store
@@ -182,9 +209,17 @@ export class CheckpointManager {
 			workingState?: WorkingStateSnapshot
 		},
 	): Promise<IterationCheckpoint> {
+		// The run's own start, not `Date.now()`. This is meant to say when the
+		// run was attributed; taking the clock at the first checkpoint would
+		// say when it first became durable, which is a different and later
+		// fact, and naming it after the earlier one would make it wrong in
+		// exactly the way that is hard to notice.
+		this.runCreatedAt ??= runMgr.getSession().startedAt ?? Date.now()
+
 		const checkpoint: IterationCheckpoint = {
 			id: generateCheckpointId(),
 			runId: runMgr.id,
+			runCreatedAt: this.runCreatedAt,
 			iteration,
 			messages: [...runMgr.messages],
 			tokenUsage: { ...runMgr.tokenUsage },
@@ -342,6 +377,22 @@ export class CheckpointManager {
 				details: { checkpointId, runId: this.scope.runId },
 			})
 		}
+
+		// Adopt the run's recorded attribution. A resumed run is the SAME run
+		// under the same id, and its creation is already on the record; a
+		// fresh process minting a new one would step the stamp forward on
+		// every resume, which is the motion it exists to avoid.
+		//
+		// This needs no "is it really my run" guard, and one was written and
+		// removed: `readCheckpoint` is keyed by THIS manager's scope, so the
+		// only checkpoints reachable here are the ones belonging to
+		// `scope.runId`. A replay fork never arrives here at all — it reads
+		// its origin through the SOURCE scope in `prepareReplayState` and
+		// starts a fresh run, so it mints its own stamp rather than claiming
+		// its origin's age. A guard that no input can trip would have read as
+		// protection and been none.
+		this.runCreatedAt ??= checkpoint.runCreatedAt
+
 		return checkpoint
 	}
 

package/src/store/index.ts

@@ -3,6 +3,24 @@ export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
 export { RunDiskStore } from './run/disk.js'
 export { DiskCheckpointStore } from './run/checkpoint-disk.js'
+export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'
+export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
+// The refusing entry point to the optional listing capability, plus the two
+// projections a host implementing its own backend actually calls: one turns
+// a run's checkpoints into a row, the other applies the contract's filter,
+// ordering and cursor. Re-deriving either is how two stores start
+// disagreeing about what "outstanding" means or where a page ends.
+//
+// `summarizePark` and `DEFAULT_DURABLE_RUN_LIMIT` are deliberately NOT here.
+// The first is an internal of `toDurableRunEntry` and no caller wants half a
+// row; the second is a number a host reads by omitting `limit`. A name a
+// host has no use for is surface to keep correct forever for nobody.
+export {
+	assertContiguousListingScope,
+	listDurableRuns,
+	paginateDurableRuns,
+	toDurableRunEntry,
+} from './run/listing.js'
 
 export { ActivityStore } from './activity/memory.js'
 export type { ActivityEvent, ActivityEventListener } from './activity/memory.js'

package/src/store/run/checkpoint-disk.ts

@@ -1,8 +1,40 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { NamzuError } from '../../types/errors/index.js'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { RunId } from '../../types/ids/index.js'
-import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+} from '../../types/run/checkpoint-store.js'
 import type { RunStoreConfig } from '../../types/run/index.js'
-import { RunDiskStore } from './disk.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import { RunDiskStore, readCheckpointsIn } from './disk.js'
+import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+
+/**
+ * The attribution a disk store's own layout does not record.
+ *
+ * The canonical layout is
+ * `{root}/projects/{projectId}/sessions/{sessionId}/runs/{runId}` — there is
+ * no tenant segment anywhere in it, and `baseDir` is already one session's
+ * `runs/` directory, so the project and session are implicit in a string the
+ * store cannot parse back out without knowing the layout that built it.
+ *
+ * A per-run read never needed any of it: the caller supplies a full
+ * `CheckpointRunScope` and the store only uses `runId`. A LISTING does — its
+ * rows have to be addressable, and a row with no tenant is a row nothing can
+ * be resumed from. So the store is told, once, what tree it is holding.
+ */
+export interface DiskCheckpointStoreAttribution {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly sessionId: SessionId
+}
 
 /**
  * Disk conformance layer for {@link CheckpointStore}: adapts the existing
@@ -20,10 +52,20 @@ import { RunDiskStore } from './disk.js'
  */
 export class DiskCheckpointStore implements CheckpointStore {
 	private readonly config: RunStoreConfig
+	private readonly attribution?: DiskCheckpointStoreAttribution
 	private readonly bound = new Map<RunId, Promise<RunDiskStore>>()
 
-	constructor(config: RunStoreConfig) {
+	/**
+	 * @param config the run-store config; `baseDir` is one session's `runs/`
+	 *   directory.
+	 * @param attribution what tree this is, for
+	 *   {@link DiskCheckpointStore.listDurableRuns}. Optional so that adding
+	 *   the listing did not change an existing construction; a store built
+	 *   without it refuses to list rather than inventing a tenant.
+	 */
+	constructor(config: RunStoreConfig, attribution?: DiskCheckpointStoreAttribution) {
 		this.config = config
+		this.attribution = attribution
 	}
 
 	private bind(scope: CheckpointRunScope): Promise<RunDiskStore> {
@@ -64,4 +106,86 @@ export class DiskCheckpointStore implements CheckpointStore {
 		const store = await this.bind(scope)
 		await store.deleteCheckpoint(checkpointId)
 	}
+
+	/**
+	 * Every run with checkpoints under this store's tree.
+	 *
+	 * Reads the directories rather than binding a {@link RunDiskStore} per
+	 * run, because binding CREATES the run directory — a listing that
+	 * materialized a directory for every run it looked at would grow the tree
+	 * it is reporting on.
+	 *
+	 * ### Why a two-level walk reaches every depth
+	 *
+	 * `initRun` nests exactly one level: a run with a parent goes to
+	 * `{baseDir}/{parentRunId}/children/{runId}`, and a grandchild goes to
+	 * `{baseDir}/{itsOwnParentRunId}/children/{runId}` — beside the top-level
+	 * runs, not beneath its grandparent. So the tree is flat-with-one-nesting
+	 * at every depth, `{baseDir}/*` plus `{baseDir}/* /children/*` enumerates
+	 * all of it, and each run's `parentRunId` is the directory it sits under.
+	 * A deep run leaves a bare shell directory under its own id at the top
+	 * level (`{baseDir}/{parentRunId}` created by `mkdir -p` for a child of a
+	 * run whose own data lives elsewhere); those hold no `checkpoints/` and
+	 * drop out as entries with no durable state.
+	 */
+	async listDurableRuns(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage> {
+		assertContiguousListingScope(scope, 'DiskCheckpointStore.listDurableRuns')
+
+		const attribution = this.attribution
+		if (!attribution) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message:
+					'DiskCheckpointStore.listDurableRuns: this store was constructed without attribution, so it cannot say which tenant, project or session its runs belong to — and a listing row that carries no scope is a row nothing can be resumed or swept from. Pass the second constructor argument. Refusing rather than returning rows stamped with a guessed tenant.',
+				details: { baseDir: this.config.baseDir },
+			})
+		}
+
+		// A listing is scoped, not addressed: a query for another tenant is a
+		// question this tree has no rows for, not an isolation violation. Same
+		// reasoning `SessionStore.listSessions` already states for sessions
+		// that happen to share a thread id across tenants.
+		if (
+			scope.tenantId !== attribution.tenantId ||
+			(scope.projectId !== undefined && scope.projectId !== attribution.projectId) ||
+			(scope.sessionId !== undefined && scope.sessionId !== attribution.sessionId)
+		) {
+			return { entries: [] }
+		}
+
+		const now = options?.now ?? Date.now()
+		const entries: DurableRunEntry[] = []
+
+		for (const runId of await this.readRunDirs(this.config.baseDir)) {
+			const runDir = join(this.config.baseDir, runId)
+
+			const own = toDurableRunEntry({ ...attribution, runId }, await readCheckpointsIn(runDir), now)
+			if (own) entries.push(own)
+
+			for (const childId of await this.readRunDirs(join(runDir, 'children'))) {
+				const child = toDurableRunEntry(
+					{ ...attribution, runId: childId, parentRunId: runId },
+					await readCheckpointsIn(join(runDir, 'children', childId)),
+					now,
+				)
+				if (child) entries.push(child)
+			}
+		}
+
+		return paginateDurableRuns(entries, options)
+	}
+
+	/** Directory names under `dir`, or none when `dir` does not exist. */
+	private async readRunDirs(dir: string): Promise<RunId[]> {
+		try {
+			const found = await readdir(dir, { withFileTypes: true })
+			return found.filter((e) => e.isDirectory()).map((e) => e.name as RunId)
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+			throw err
+		}
+	}
 }

package/src/store/run/checkpoint-memory.ts

@@ -0,0 +1,101 @@
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+} from '../../types/run/checkpoint-store.js'
+import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+
+/**
+ * Process-local {@link CheckpointStore}, keyed by the full five-layer scope.
+ *
+ * Shipped rather than left as a test fixture for two reasons. It is the
+ * reference a host reads when writing a backend of its own — the disk store
+ * is path-addressed and answers "what does an attribution-keyed store look
+ * like" with a directory layout, which is the wrong lesson. And it is the
+ * only implementation that can hold more than one tenant at once, because
+ * the disk layout has no tenant in it: a test that two tenants' listings
+ * stay separate is not expressible against disk, and a rule that cannot be
+ * tested on the store a host will actually inject is a rule on paper.
+ *
+ * Not durable, deliberately: it is for tests, for a single-process host that
+ * genuinely wants checkpoints to die with the process, and as the parity
+ * partner that proves the listing contract is not a filesystem in disguise.
+ */
+export class InMemoryCheckpointStore implements CheckpointStore {
+	/** `tenant/project/session/run` → checkpoint id → checkpoint. */
+	private readonly runs = new Map<string, Map<CheckpointId, IterationCheckpoint>>()
+	/** Same key → the run's scope, so a listing can rebuild an addressable entry. */
+	private readonly scopes = new Map<string, CheckpointRunScope>()
+
+	private key(scope: CheckpointRunScope): string {
+		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')
+	}
+
+	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+		const key = this.key(scope)
+		let run = this.runs.get(key)
+		if (!run) {
+			run = new Map()
+			this.runs.set(key, run)
+		}
+		// The run's scope is kept beside its checkpoints because the key is a
+		// joined string and a listing has to hand back the parts — above all
+		// `parentRunId`, which is what makes a sub-run's row addressable.
+		//
+		// Written on every call rather than only the first, and that is
+		// simplicity, not defence: a run's scope is fixed when the run is
+		// constructed, so the two cannot differ, and a `has` guard here would
+		// be a branch no input can take.
+		this.scopes.set(key, {
+			tenantId: scope.tenantId,
+			projectId: scope.projectId,
+			sessionId: scope.sessionId,
+			runId: scope.runId,
+			...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		})
+		run.set(checkpoint.id, checkpoint)
+	}
+
+	async readCheckpoint(
+		scope: CheckpointRunScope,
+		checkpointId: CheckpointId,
+	): Promise<IterationCheckpoint | null> {
+		return this.runs.get(this.key(scope))?.get(checkpointId) ?? null
+	}
+
+	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
+		const run = this.runs.get(this.key(scope))
+		if (!run) return []
+		return [...run.values()].sort((a, b) => a.createdAt - b.createdAt)
+	}
+
+	async deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void> {
+		this.runs.get(this.key(scope))?.delete(checkpointId)
+	}
+
+	async listDurableRuns(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage> {
+		assertContiguousListingScope(scope, 'InMemoryCheckpointStore.listDurableRuns')
+		const now = options?.now ?? Date.now()
+
+		const entries: DurableRunEntry[] = []
+		for (const [key, checkpoints] of this.runs) {
+			const runScope = this.scopes.get(key)
+			if (!runScope) continue
+			if (runScope.tenantId !== scope.tenantId) continue
+			if (scope.projectId !== undefined && runScope.projectId !== scope.projectId) continue
+			if (scope.sessionId !== undefined && runScope.sessionId !== scope.sessionId) continue
+
+			const entry = toDurableRunEntry(runScope, [...checkpoints.values()], now)
+			if (entry) entries.push(entry)
+		}
+
+		return paginateDurableRuns(entries, options)
+	}
+}

package/src/store/run/disk.ts

@@ -192,33 +192,7 @@ export class RunDiskStore {
 	}
 
 	async listCheckpoints(): Promise<IterationCheckpoint[]> {
-		const dir = this.requireInit()
-		const cpDir = join(dir, 'checkpoints')
-		try {
-			const files = await readdir(cpDir)
-			const checkpoints: IterationCheckpoint[] = []
-			for (const file of files) {
-				if (!file.endsWith('.json')) continue
-				// An unreadable checkpoint used to be logged and skipped, so
-				// this returned a silently short list that four callers treat
-				// as complete. A missing NEWEST checkpoint quietly resumes
-				// from an older point and re-runs a whole iteration of tool
-				// calls; a missing PARKED one reports "not parked" and drops
-				// an approval a human already granted, because the file is
-				// the only durable record of a park. Pruning under-deletes
-				// too: a file the keep-count cannot see is immortal.
-				//
-				// The by-id read next door was already strict. Two read paths
-				// disagreeing about whether damage matters is how the lenient
-				// one gets trusted.
-				const content = await readFile(join(cpDir, file), 'utf-8')
-				checkpoints.push(parseCheckpoint(content, file))
-			}
-			return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
-		} catch (err) {
-			if (isFileNotFound(err)) return []
-			throw err
-		}
+		return readCheckpointsIn(this.requireInit())
 	}
 
 	async deleteCheckpoint(checkpointId: CheckpointId): Promise<void> {
@@ -230,6 +204,29 @@ export class RunDiskStore {
 		}
 	}
 
+	/**
+	 * @deprecated Superseded by
+	 *   {@link import('../../types/run/checkpoint-store.js').CheckpointStore.listDurableRuns},
+	 *   reached through {@link import('./listing.js').listDurableRuns}.
+	 *   Removed in the next major.
+	 *
+	 *   Three things are wrong with `index.json` as the answer to "which runs
+	 *   are there":
+	 *
+	 *   1. Its entries carry no tenant, project or session, so a row cannot be
+	 *      turned back into an addressable scope — nothing can be resumed or
+	 *      swept from it.
+	 *   2. `addToIndex` skips every sub-run, so an inbox built on it drops
+	 *      every approval raised by delegated work, and the symptom looks like
+	 *      a hung specialist rather than a blind listing.
+	 *   3. It is a catalogue of runs that STARTED, not of runs with durable
+	 *      state, so it cannot tell a run something could resume from one that
+	 *      left nothing behind.
+	 *
+	 *   Deprecated for one minor rather than deleted outright: this is public
+	 *   surface and a consumer calling it today gets real data back, so the
+	 *   deprecate-before-you-remove rule applies.
+	 */
 	static async listRuns(baseDir: string): Promise<
 		Array<{
 			id: string
@@ -297,6 +294,54 @@ export class RunDiskStore {
 	}
 }
 
+/**
+ * Every checkpoint stored under one run directory, ascending by `createdAt`.
+ *
+ * A free function rather than a method because the scope-level listing walks
+ * run directories it has never bound a {@link RunDiskStore} to — and binding
+ * one would CREATE the directory, which is not something a read should do.
+ * Sharing the function is what keeps the two read paths from disagreeing
+ * about what a damaged file means.
+ *
+ * An unreadable checkpoint used to be logged and skipped, so this returned a
+ * silently short list that four callers treat as complete. A missing NEWEST
+ * checkpoint quietly resumes from an older point and re-runs a whole
+ * iteration of tool calls; a missing PARKED one reports "not parked" and
+ * drops an approval a human already granted, because the file is the only
+ * durable record of a park. Pruning under-deletes too: a file the keep-count
+ * cannot see is immortal. The by-id read next door was already strict, and
+ * two read paths disagreeing about whether damage matters is how the lenient
+ * one gets trusted.
+ *
+ * The same reasoning carries up to the listing, which is why the throw
+ * propagates there rather than dropping the run: a damaged checkpoint that
+ * removed a run from an approval inbox is the missing-park failure again,
+ * one level up.
+ *
+ * A missing `checkpoints/` directory is the only absence that reads as
+ * empty — the run genuinely has none. A file that disappears BETWEEN the
+ * directory listing and its read throws, where the old shape returned the
+ * empty array and discarded every checkpoint it had already parsed.
+ */
+export async function readCheckpointsIn(runDir: string): Promise<IterationCheckpoint[]> {
+	const cpDir = join(runDir, 'checkpoints')
+	let files: string[]
+	try {
+		files = await readdir(cpDir)
+	} catch (err) {
+		if (isFileNotFound(err)) return []
+		throw err
+	}
+
+	const checkpoints: IterationCheckpoint[] = []
+	for (const file of files) {
+		if (!file.endsWith('.json')) continue
+		const content = await readFile(join(cpDir, file), 'utf-8')
+		checkpoints.push(parseCheckpoint(content, file))
+	}
+	return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
+}
+
 async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
 	await atomicWriteFile(filePath, JSON.stringify(stamp(SCHEMA, value), null, 2))
 }