@namzu/sdk 20.2.0 → 20.3.0

package/src/store/run/memory.ts

@@ -0,0 +1,121 @@
+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'
+
+/**
+ * Process-local {@link RunStore}: a run's evidence with no filesystem.
+ *
+ * The reason it ships rather than living in a test file is that it is the
+ * only way to demonstrate the seam actually is one. A contract with a single
+ * implementation is a refactor; the second implementation is what proves a
+ * host could supply a third. It is also the parity partner for the disk
+ * store — a memory store that answers differently from disk is worse than
+ * none, because a host tests against one and ships the other.
+ *
+ * Deliberately not durable. It is for tests, for a single-process host that
+ * genuinely wants a run's evidence to die with the process, and for
+ * environments with no writable filesystem at all.
+ */
+export class InMemoryRunStore implements RunStore {
+	private runId: string | null = null
+	private parentRunId: string | undefined
+	private meta: Run | null = null
+	private messages: Run['messages'] = []
+	private report: string | null = null
+	private readonly events: RunEvent[] = []
+
+	async initRun(runId: string, parentRunId?: string): Promise<string | null> {
+		this.runId = runId
+		this.parentRunId = parentRunId
+		// No location, and that is the honest answer rather than a defect.
+		// Callers render `null` as "this run is not on a filesystem"; a
+		// synthesized path would put a directory that does not exist in front
+		// of an operator.
+		return null
+	}
+
+	private requireInit(): string {
+		if (this.runId === null) {
+			throw new Error('InMemoryRunStore not initialized — call initRun() first')
+		}
+		return this.runId
+	}
+
+	/** The run this store is bound to, and its parent when it has one. */
+	get boundTo(): { runId: string; parentRunId?: string } | null {
+		return this.runId === null
+			? null
+			: { runId: this.runId, ...(this.parentRunId ? { parentRunId: this.parentRunId } : {}) }
+	}
+
+	async writeRunMeta(run: Run): Promise<void> {
+		this.requireInit()
+		// Copied, not referenced. The caller keeps mutating this object for
+		// the rest of the run, so storing it by reference would make every
+		// historical read return the run's present state — a transcript that
+		// silently rewrites itself is worse than no transcript.
+		this.meta = structuredClone(run)
+	}
+
+	async writeMessages(run: Run): Promise<void> {
+		this.requireInit()
+		this.messages = structuredClone(run.messages)
+	}
+
+	async appendEvent(event: RunEvent): Promise<void> {
+		this.requireInit()
+		// Stamped on write, exactly as the disk store stamps its transcript
+		// 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)
+	}
+
+	async writeReport(content: string): Promise<string | null> {
+		this.requireInit()
+		this.report = content
+		return null
+	}
+
+	async readCompletedTools(): Promise<Map<string, CompletedToolRecord>> {
+		this.requireInit()
+		const completed = new Map<string, CompletedToolRecord>()
+		for (const event of this.events) {
+			const e = event as unknown as Record<string, unknown>
+			if (e.type !== 'tool_completed') continue
+			const toolUseId = e.toolUseId
+			const toolName = e.toolName
+			if (typeof toolUseId !== 'string' || typeof toolName !== 'string') continue
+			// Last write wins: a retried tool emits one event per attempt and
+			// the final one is what actually answered the call. Same rule the
+			// disk store applies, and it has to be the same rule — a resumed
+			// run must not depend on which backend it was recorded with.
+			completed.set(toolUseId, {
+				toolUseId,
+				toolName,
+				result: typeof e.result === 'string' ? e.result : '',
+				isError: e.isError === true,
+			})
+		}
+		return completed
+	}
+
+	getRunDir(): string | null {
+		return null
+	}
+
+	// `addToIndex` is deliberately not implemented. It maintains a browsable
+	// catalogue for a human reading a directory, and there is no directory
+	// here. The optional method exists on the contract precisely so a backend
+	// can decline it rather than implement a no-op that looks like a listing.
+
+	/** Everything recorded for the bound run, for tests and parity checks. */
+	snapshot(): {
+		meta: Run | null
+		messages: Run['messages']
+		report: string | null
+		events: readonly RunEvent[]
+	} {
+		return { meta: this.meta, messages: this.messages, report: this.report, events: this.events }
+	}
+}

package/src/types/run/config.ts

@@ -136,6 +136,19 @@ export interface RunPersistenceConfig {
 	 * hosts inject a scope-keyed backend (e.g. Postgres) here.
 	 */
 	checkpointStore?: CheckpointStore
+
+	/**
+	 * Optional run-evidence persistence override. Defaults to the disk layout
+	 * under `outputDir` (a
+	 * {@link import('../../store/run/disk.js').RunDiskStore}); hosts inject
+	 * their own backend here.
+	 *
+	 * The sibling of `checkpointStore`, and it should have been one from the
+	 * start: checkpoints got an injectable seam while the run record, its
+	 * messages, its transcript and its report did not, so the evidence was
+	 * the one part of a run that could not leave the local filesystem.
+	 */
+	runStore?: import('./store.js').RunStore
 }
 
 export interface RunStoreConfig {

package/src/types/run/index.ts

@@ -3,6 +3,7 @@ export * from './prepare-step.js'
 export * from './stop-reason.js'
 export * from './config.js'
 export * from './checkpoint-store.js'
+export * from './store.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

@@ -0,0 +1,112 @@
+/**
+ * RunStore — persistence contract for a run's own evidence.
+ *
+ * The checkpoint store got an injectable seam and this did not, which left
+ * the run record, its messages, its transcript and its report reachable only
+ * through a concrete filesystem class. For a kernel whose stated purpose is
+ * auditable evidence, the evidence was the one thing that could not be
+ * pointed at durable storage: on ephemeral infrastructure the transcript dies
+ * with the container, and behind a load balancer two replicas write two
+ * disjoint run trees for one tenant.
+ *
+ * The location was already injectable through a path builder — but that
+ * returns filesystem path strings, so it relocates the directory without
+ * changing the medium.
+ *
+ * ## Bound to one run, unlike {@link CheckpointStore}
+ *
+ * Every accessor here addresses the run the store was bound to by
+ * {@link RunStore.initRun}, where a `CheckpointStore` takes an explicit scope
+ * per call. That asymmetry is inherited rather than chosen: this contract is
+ * extracted from a class the runtime already constructs per run and holds for
+ * the run's lifetime, and re-keying it would change every call site in the
+ * same change that introduces the seam — two risks where one will do.
+ *
+ * A host implementing a shared backend therefore keys its rows by the
+ * attribution it was constructed with plus the bound run id. If this is later
+ * re-keyed per call, it happens once, deliberately, as its own change.
+ */
+
+import type { Run } from './entity.js'
+import type { RunEvent } from './events.js'
+
+/**
+ * One finished tool call, recovered from the run's own transcript.
+ *
+ * Re-declared here rather than imported from the disk store so the contract
+ * does not depend on an implementation of itself.
+ */
+export interface CompletedToolRecord {
+	readonly toolUseId: string
+	readonly toolName: string
+	readonly result: string
+	readonly isError: boolean
+}
+
+export interface RunStore {
+	/**
+	 * Bind this store to a run, before any other call.
+	 *
+	 * Returns a location when the backend has one — the built-in disk store
+	 * returns the run's directory — and `null` when it does not. A caller
+	 * that renders the value must treat `null` as "this run is not on a
+	 * filesystem" rather than as an error: an in-memory or object-storage
+	 * backend has nothing to print, and inventing a path for it would put a
+	 * directory that does not exist in front of an operator.
+	 */
+	initRun(runId: string, parentRunId?: string): Promise<string | null>
+
+	/** Persist the run record: status, metadata, usage, timings. */
+	writeRunMeta(run: Run): Promise<void>
+
+	/** Persist the run's full message history. */
+	writeMessages(run: Run): Promise<void>
+
+	/**
+	 * Append one event to the run's durable event log.
+	 *
+	 * High-frequency streaming deltas are excluded before they reach here —
+	 * that exclusion is a deliberate trade and belongs to the emitter, not to
+	 * the backend, so a store must not re-filter.
+	 */
+	appendEvent(event: RunEvent): Promise<void>
+
+	/**
+	 * Persist the run's final report. Returns a location, or `null` when the
+	 * backend has none. See {@link RunStore.initRun}.
+	 */
+	writeReport(content: string): Promise<string | null>
+
+	/**
+	 * Every tool call this run has already finished, keyed by `toolUseId`.
+	 *
+	 * A batch's results reach the message history only once the WHOLE batch
+	 * settles, so a hard kill part-way through loses every result that had
+	 * already come back, and the resumed run re-executes those calls. For a
+	 * file write that is waste; for a payment or an email it is a second one.
+	 *
+	 * A backend that does not retain individual events answers with an empty
+	 * map, which costs re-execution and is honest. It must not answer with a
+	 * PARTIAL map: a caller reads a present entry as "this call is already
+	 * answered", so a half-remembered batch is worse than a forgotten one.
+	 */
+	readCompletedTools(): Promise<Map<string, CompletedToolRecord>>
+
+	/**
+	 * Where this run's evidence lives, or `null` when it is not on a
+	 * filesystem. Valid only after {@link RunStore.initRun}.
+	 */
+	getRunDir(): string | null
+
+	/**
+	 * Record the run in a browsable catalogue of runs. OPTIONAL.
+	 *
+	 * Optional because it is the one method here that is not evidence: it
+	 * maintains a convenience listing for a human reading the directory, and
+	 * a backend whose runs are already queryable has nothing to add. The
+	 * programmatic answer to "which runs are there" is
+	 * `CheckpointStore.listDurableRuns`, which carries attribution and
+	 * includes sub-runs; this does neither.
+	 */
+	addToIndex?(run: Run): Promise<void>
+}