@namzu/sdk 20.4.0 → 21.1.0

package/src/run/workspace-fingerprint.ts

@@ -0,0 +1,193 @@
+/**
+ * A hash of everything a run could have changed in its working tree.
+ *
+ * It exists to answer one question, asked between two attempts at the same
+ * verification: **did anything happen since it last failed?** A verify-then-fix
+ * loop that re-runs the build after a turn which edited nothing spends a full
+ * command execution to learn what a comparison already knew, and does it once
+ * per remaining attempt — so a model that has stopped making progress burns
+ * the entire budget confirming the same failure.
+ *
+ * ## What is hashed, and why each part
+ *
+ * Three sources, because no one of them is complete:
+ *
+ *  1. **`git status --porcelain`** — which paths differ from the index at all.
+ *     Cheap, and it catches additions, deletions and mode changes. On its own
+ *     it is not enough: editing a tracked file that was ALREADY modified
+ *     leaves the status output byte-identical.
+ *  2. **`git diff --binary HEAD`** — the content of every tracked change.
+ *     `--binary` so an edit to a file git treats as binary is a real diff
+ *     rather than the constant line `Binary files … differ`, which would make
+ *     every edit to such a file invisible.
+ *  3. **Untracked file contents**, which no `git diff` covers. A new file is
+ *     named by `status` but its CONTENT is not, so successive edits to a
+ *     brand-new file would otherwise look like no change at all.
+ *
+ * ### Symlinks are recorded as their target, not read through
+ *
+ * Reading a link follows it, so a link repointed from one file to another
+ * with identical contents hashes the same — while the thing the workspace
+ * actually resolves has changed. The link's target path is the fact that
+ * moved, so that is what goes in.
+ *
+ * ## Failing open, on the cheap side
+ *
+ * Every uncertainty returns `null`, meaning *no fingerprint*, and a caller
+ * that cannot fingerprint re-runs its command. That is the correct direction:
+ * the cost of a wrong `null` is one command execution, and the cost of a
+ * wrong MATCH is a verification silently skipped — the loop would report
+ * "nothing changed" about a workspace that did change, and the model would be
+ * told to edit something it had already edited.
+ *
+ * So: a non-zero exit from any git invocation, a repository with no commits,
+ * a timeout, or output past the size cap all produce `null` rather than a
+ * partial hash. A truncated diff that hashed successfully would be the worst
+ * outcome available here, because two different workspaces truncated at the
+ * same point collide.
+ */
+
+import { createHash } from 'node:crypto'
+import { lstat, readFile, readlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { CommandOptions, CommandResult } from '../types/execution/index.js'
+
+/** How a fingerprint runs git. Injected so a test needs no repository. */
+export type FingerprintExec = (
+	command: string,
+	args: string[],
+	options?: CommandOptions,
+) => Promise<CommandResult>
+
+/**
+ * The three filesystem reads an untracked entry needs.
+ *
+ * Injectable for one specific reason, written down because a seam that
+ * exists only for tests is usually a smell: **creating a symlink requires a
+ * privilege that is not granted by default on Windows**, so the symlink rule
+ * below — the one that says a repointed link changes the fingerprint even
+ * when the bytes behind it do not — cannot be exercised on a developer
+ * machine without it. A rule that can only be checked on some machines is a
+ * rule nobody checks.
+ *
+ * The default is `node:fs/promises` and every other test uses it against a
+ * real repository, so this is not a fixture standing in for production; it is
+ * one branch of one function reached without a privilege.
+ */
+export interface FingerprintFs {
+	lstat(path: string): Promise<{ isSymbolicLink(): boolean; isFile(): boolean }>
+	readlink(path: string): Promise<string>
+	readFile(path: string): Promise<Buffer>
+}
+
+const NODE_FS: FingerprintFs = { lstat, readlink, readFile }
+
+/**
+ * Cap on the bytes any single git invocation may produce.
+ *
+ * Past it the fingerprint is abandoned rather than hashed. A diff big enough
+ * to hit this is a diff nobody is going to iterate on anyway, and hashing a
+ * clipped one would let two different trees agree.
+ */
+export const FINGERPRINT_MAX_BYTES = 4 * 1024 * 1024
+
+/** Default deadline per git invocation. */
+export const FINGERPRINT_TIMEOUT_MS = 20_000
+
+export interface WorkspaceFingerprintOptions {
+	/** Repository root, or any directory inside it. */
+	readonly cwd: string
+	/** How to run git. */
+	readonly exec: FingerprintExec
+	/** Per-invocation deadline. See {@link FINGERPRINT_TIMEOUT_MS}. */
+	readonly timeoutMs?: number
+	/** See {@link FINGERPRINT_MAX_BYTES}. */
+	readonly maxBytes?: number
+	/** Filesystem reads. See {@link FingerprintFs}. */
+	readonly fs?: FingerprintFs
+}
+
+/** One untracked path's contribution, or `null` when it could not be read. */
+async function untrackedEntry(cwd: string, rel: string, fs: FingerprintFs): Promise<string | null> {
+	const abs = join(cwd, rel)
+	try {
+		const stats = await fs.lstat(abs)
+		if (stats.isSymbolicLink()) {
+			// The TARGET, not what is behind it. Following the link would hash a
+			// repointed link to the same value whenever the new target happens
+			// to hold the same bytes, and a repoint is a change to the workspace
+			// by any reading that matters.
+			return `L ${rel}\0${await fs.readlink(abs)}`
+		}
+		if (!stats.isFile()) return `? ${rel}`
+		const body = await fs.readFile(abs)
+		return `F ${rel}\0${createHash('sha256').update(body).digest('hex')}`
+	} catch {
+		// Vanished between the listing and the read, or unreadable. Neither is
+		// a fingerprint this function may guess at.
+		return null
+	}
+}
+
+/**
+ * A hash of the working tree's uncommitted state, or `null` when it cannot be
+ * established.
+ *
+ * **`null` is never "unchanged".** It means "I cannot tell", and the caller
+ * must treat it as a reason to do the work rather than to skip it.
+ */
+export async function fingerprintWorkspace(
+	options: WorkspaceFingerprintOptions,
+): Promise<string | null> {
+	const { cwd, exec } = options
+	const timeoutMs = options.timeoutMs ?? FINGERPRINT_TIMEOUT_MS
+	const maxBytes = options.maxBytes ?? FINGERPRINT_MAX_BYTES
+	const fs = options.fs ?? NODE_FS
+
+	const git = async (args: string[]): Promise<string | null> => {
+		let result: CommandResult
+		try {
+			result = await exec('git', args, { cwd, timeoutMs })
+		} catch {
+			return null
+		}
+		// A timeout surfaces here as a non-zero exit, and so does "not a
+		// repository" and "no commits yet". All three mean the same thing to
+		// this function: it has no basis for a comparison.
+		if (result.exitCode !== 0) return null
+		if (Buffer.byteLength(result.stdout, 'utf8') > maxBytes) return null
+		return result.stdout
+	}
+
+	const status = await git(['status', '--porcelain'])
+	if (status === null) return null
+
+	const diff = await git(['diff', '--binary', 'HEAD'])
+	if (diff === null) return null
+
+	const untracked = await git(['ls-files', '--others', '--exclude-standard', '-z'])
+	if (untracked === null) return null
+
+	const parts = [`status ${status}`, `diff ${diff}`]
+	// Split on NUL, which is what `-z` is for: a path may contain a newline,
+	// and splitting on one would turn a single strange filename into two
+	// ordinary-looking ones.
+	//
+	// Sorted, because `ls-files` order is not part of any contract and a
+	// fingerprint that moved when the listing order did would report a change
+	// nobody made.
+	for (const rel of untracked.split('\0').filter(Boolean).sort()) {
+		const entry = await untrackedEntry(cwd, rel, fs)
+		if (entry === null) return null
+		parts.push(entry)
+	}
+
+	// Length-prefixed rather than delimiter-joined. A diff can contain any
+	// byte, so any separator is a separator the content can forge — and two
+	// different trees that agreed after forgery would be reported as
+	// unchanged, which is the one wrong answer this file is arranged to avoid.
+	const hash = createHash('sha256')
+	for (const part of parts) hash.update(`${Buffer.byteLength(part, 'utf8')}:${part}`)
+	return hash.digest('hex')
+}

package/src/runtime/query/events.ts

@@ -4,6 +4,7 @@ import { buildProbeContext } from '../../probe/context.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ActivityEvent, ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
+import type { ClaimFence } from '../../types/run/checkpoint-store.js'
 import { isEphemeralEvent } from '../../types/run/events.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { TaskEvent, TaskStore } from '../../types/task/index.js'
@@ -37,6 +38,22 @@ export class EventTranslator {
 		this.probes = probeRegistry
 	}
 
+	/**
+	 * The claim this run is being written under, when it holds one.
+	 *
+	 * Stamped on every durable event as its `generation`, so a consumer whose
+	 * cursor predates a takeover is told its sequence space changed instead of
+	 * being handed a splice from a different writer's log.
+	 */
+	private generation: ClaimFence | undefined
+
+	/** Serializes sequence assignment against the append. See {@link emitEvent}. */
+	private appendChain: Promise<void> = Promise.resolve()
+
+	setGeneration(fence: ClaimFence | undefined): void {
+		this.generation = fence
+	}
+
 	readonly emitEvent: EmitEvent = async (event: RunEvent): Promise<void> => {
 		this.probes.dispatch(event, buildProbeContext({ runId: event.runId }))
 
@@ -64,15 +81,62 @@ export class EventTranslator {
 			// briefly than to drop a state transition.
 		}
 
-		this.pendingEvents.push(event)
-
 		// D1 middle path: ephemeral events never enter `transcript.jsonl`.
 		// They live only on the in-memory bus for live UI rendering.
 		// Replay (`runtime/query/replay/prepare.ts`) reads checkpoints
 		// not transcripts, so this preserves replay fidelity while
 		// eliminating the durable bloat review flagged.
-		if (!isEphemeralEvent(event)) {
-			await this.runMgr.getRunStore().appendEvent(event)
+		if (isEphemeralEvent(event)) {
+			// No number, and that is the honest statement: nothing will
+			// persist this, so a consumer must never advance a cursor to it.
+			this.pendingEvents.push(event)
+			return
+		}
+
+		// One appender at a time, and this is not a precaution — it is the fix
+		// for a measured defect. Taking the number, awaiting the write and then
+		// committing is a read-modify-write, and emits genuinely interleave:
+		// the task store, the plan manager and a batch of parallel tools all
+		// emit into this one funnel. Measured on a two-tool run, three events
+		// took the number 15 and two took 12. A duplicated sequence is worse
+		// than a missing one — a consumer asking for everything above 15 is
+		// handed part of the run it already had, spliced in as if it were new.
+		const previous = this.appendChain
+		let release!: () => void
+		this.appendChain = new Promise<void>((resolve) => {
+			release = resolve
+		})
+
+		try {
+			await previous
+
+			// The number is a claim that the event is IN the log, so it is taken
+			// against the append and not before it. The candidate goes to the
+			// store first; only a write that landed advances the counter and
+			// reaches the live stream carrying it.
+			//
+			// The failure path still delivers the event — unstamped. A store
+			// that cannot record a `run_failed` must not also swallow it, and an
+			// unstamped event says exactly what is true of it: it happened, and
+			// it is not recoverable.
+			const seq = this.runMgr.nextEventSeq()
+			const stamped = {
+				...event,
+				seq,
+				...(this.generation !== undefined ? { generation: this.generation } : {}),
+			} as RunEvent
+
+			try {
+				await this.runMgr.getRunStore().appendEvent(stamped)
+			} catch (err) {
+				this.pendingEvents.push(event)
+				throw err
+			}
+
+			this.runMgr.commitEventSeq(seq)
+			this.pendingEvents.push(stamped)
+		} finally {
+			release()
 		}
 	};
 

package/src/runtime/query/index.ts

@@ -15,6 +15,7 @@ import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire
 import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
+import type { RunPersistence } from '../../manager/run/persistence.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
 import {
 	type ProviderChainMember,
@@ -59,6 +60,8 @@ import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { ReviewAnswer } from '../../types/run/answer-review.js'
 import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.js'
+import type { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js'
+import { resolveRunEventReplay } from '../../types/run/event-cursor.js'
 import type {
 	AgentRunConfig,
 	PrepareStepChain,
@@ -445,6 +448,43 @@ export interface QueryParams {
 	 */
 	runStore?: RunStore
 
+	/**
+	 * Where a reconnecting consumer left off, so this run's stream can start by
+	 * handing back what it missed.
+	 *
+	 * The case this serves is the one that exists without a network hop: the
+	 * process holding the run died, and the consumer watching it is coming back
+	 * to a run that has to be resumed. Pair it with `resumeFromCheckpoint` — or
+	 * reach it through {@link import('./resume-run.js').resumeRun}, which is the
+	 * surface that does both — and the missed durable events are yielded, in
+	 * order, before the resumed run emits anything of its own.
+	 *
+	 * On a run with no log to catch up on the cursor is answered honestly rather
+	 * than ignored: a `sinceSeq` above what exists is `cursor_ahead`, not
+	 * silence.
+	 *
+	 * What comes back is message-granular. Streaming deltas are never persisted
+	 * — see {@link import('../../types/run/store.js').RunStore.appendEvent} —
+	 * so a late subscriber recovers the assistant text, the tool results and the
+	 * lifecycle, not the keystroke cadence that produced them.
+	 */
+	eventCursor?: RunEventCursor
+
+	/**
+	 * What became of {@link QueryParams.eventCursor}.
+	 *
+	 * A callback rather than an event on the stream, because the answer is about
+	 * the SUBSCRIPTION and not about the run — and rather than a throw, because
+	 * a stale cursor is a client's problem and must not be able to stop a run
+	 * from continuing. A host that receives `unavailable` re-derives from the
+	 * transcript; one that receives nothing at all would splice a hole into its
+	 * state and never know.
+	 *
+	 * Called once, before the run's first event, and only when a cursor was
+	 * supplied.
+	 */
+	onEventReplay?: (replay: RunEventReplay) => void
+
 	runId?: RunId
 
 	parentRunId?: RunId
@@ -1038,6 +1078,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// fence exists, the refusal exists, and no checkpoint a RUN writes ever
 		// carries a number — so a stalled worker is refused nowhere.
 		checkpointMgr.setClaimFence(params.claimFence)
+		// And every EVENT it records carries the same fence as its generation,
+		// so a consumer whose cursor was minted under an older holding is told
+		// the sequence space changed rather than handed a splice from it.
+		eventTranslator.setGeneration(params.claimFence)
 
 		// A question raised from inside a tool becomes a real checkpoint
 		// here. It used to park under a synthetic id nothing ever wrote, so
@@ -1115,6 +1159,20 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		try {
 			await ctx.runMgr.init()
 
+			// A consumer coming back gets what it missed BEFORE the run says
+			// anything new, which is the only order that lets it fold one
+			// stream into one state. It has to follow `init()` — that is what
+			// binds the store and reads the log's head — and precede every
+			// emit below.
+			if (params.eventCursor) {
+				yield* catchUpFromCursor(
+					ctx.runMgr,
+					params.eventCursor,
+					params.onEventReplay,
+					params.claimFence,
+				)
+			}
+
 			// Handed over here, and the position is load-bearing in BOTH
 			// directions. It has to follow `wirePlanManager`, or a host that
 			// builds its plan in this callback — which is what the callback is
@@ -1594,6 +1652,35 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	})()
 }
 
+/**
+ * Hand a returning consumer what it missed, or tell it why it cannot have it.
+ *
+ * Yields NOTHING on a refusal. A partial catch-up is the failure this exists to
+ * prevent: a consumer that receives some of the gap folds it into its state and
+ * cannot tell the state is wrong, where one that receives an explicit
+ * `unavailable` re-derives from the transcript and is right. The run continues
+ * either way — a stale cursor belongs to the client, and must not be able to
+ * stop the work.
+ */
+async function* catchUpFromCursor(
+	runMgr: RunPersistence,
+	cursor: RunEventCursor,
+	onEventReplay: ((replay: RunEventReplay) => void) | undefined,
+	generation: ClaimFence | undefined,
+): AsyncGenerator<RunEvent, void> {
+	const missed = await runMgr.getRunStore().readEvents({ sinceSeq: cursor.sinceSeq })
+	const replay = resolveRunEventReplay(
+		cursor,
+		{ lastSeq: runMgr.lastEventSeq, ...(generation !== undefined ? { generation } : {}) },
+		missed,
+	)
+
+	onEventReplay?.(replay)
+
+	if (replay.status !== 'replayed') return
+	for (const event of replay.events) yield event
+}
+
 export async function drainQuery(
 	params: Omit<QueryParams, 'resumeHandler'> & { resumeHandler?: ResumeHandler },
 	listener?: RunEventListener,

package/src/runtime/query/resume-run.ts

@@ -1,6 +1,8 @@
 import type { PendingDecision } from '../../types/hitl/index.js'
 import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.js'
 import type { Run } from '../../types/run/entity.js'
+import type { RunEventReplay } from '../../types/run/event-cursor.js'
+import type { RunEventListener } from '../../types/run/events.js'
 import type { RunState } from '../../types/run/state.js'
 import { type QueryParams, drainQuery } from './index.js'
 import { type RunStateScope, loadRunState } from './run-state.js'
@@ -23,7 +25,21 @@ export type ResumeOutcome =
 			readonly pending: PendingDecision
 			readonly state: RunState
 	  }
-	| { readonly resumed: true; readonly run: Run; readonly state: RunState }
+	| {
+			readonly resumed: true
+			readonly run: Run
+			readonly state: RunState
+			/**
+			 * What became of {@link ResumeRunParams.eventCursor}. Absent when no
+			 * cursor was supplied.
+			 *
+			 * Reported rather than thrown: a stale cursor is the client's
+			 * problem and the run still had to be resumed. A caller that sees
+			 * `unavailable` re-derives its view from the run's transcript
+			 * instead of folding a hole into it.
+			 */
+			readonly replay?: RunEventReplay
+	  }
 
 /**
  * The half of a run that cannot be serialized, plus where to look.
@@ -52,6 +68,20 @@ export interface ResumeRunParams
 	 * Absent means the parked checkpoint if there is one, else the newest.
 	 */
 	readonly checkpointId?: RunState['checkpointId']
+
+	/**
+	 * Where to send the resumed run's events.
+	 *
+	 * This call had none, and the consequence was total: it drains the run to
+	 * completion and every event the run emits — every tool call, every park,
+	 * every token update — was discarded, because `drainQuery` forwards to a
+	 * listener and none was ever passed. So the one API for continuing a run
+	 * another process started could not show anybody what the run was doing.
+	 *
+	 * It is also what makes {@link ResumeRunParams.eventCursor} mean anything:
+	 * a catch-up delivered into a stream nobody receives is not a catch-up.
+	 */
+	readonly listener?: RunEventListener
 }
 
 /**
@@ -76,7 +106,16 @@ export interface ResumeRunParams
  * resumed past without the answer it is waiting for.
  */
 export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome> {
-	const { scope, checkpointStore, checkpointId, pendingDecision, claimFence, ...rest } = params
+	const {
+		scope,
+		checkpointStore,
+		checkpointId,
+		pendingDecision,
+		claimFence,
+		listener,
+		onEventReplay,
+		...rest
+	} = params
 
 	const state = await loadRunState(checkpointStore, scope, checkpointId)
 	if (!state?.checkpointId) return { resumed: false, reason: 'no-checkpoint' }
@@ -89,15 +128,31 @@ export async function resumeRun(params: ResumeRunParams): Promise<ResumeOutcome>
 		return { resumed: false, reason: 'awaiting-decision', pending: outstanding, state }
 	}
 
-	const run = await drainQuery({
-		...rest,
-		messages: [],
-		runId: state.runId,
-		resumeFromCheckpoint: state.checkpointId,
-		checkpointStore,
-		...(claimFence !== undefined ? { claimFence } : {}),
-		...(pendingDecision ? { pendingDecision } : {}),
-	} as QueryParams)
+	let replay: RunEventReplay | undefined
+
+	const run = await drainQuery(
+		{
+			...rest,
+			messages: [],
+			runId: state.runId,
+			// Forwarded, and it is not cosmetic: the run store nests a sub-run's
+			// evidence under `<parent>/children/<run>`, so resuming a sub-run
+			// without this binds `<base>/<run>` instead — a second, empty
+			// transcript under a run id that already has one, a sequence that
+			// restarts at 1, and a catch-up that reports a live run as having
+			// produced nothing.
+			...(state.parentRunId !== undefined ? { parentRunId: state.parentRunId } : {}),
+			resumeFromCheckpoint: state.checkpointId,
+			checkpointStore,
+			...(claimFence !== undefined ? { claimFence } : {}),
+			...(pendingDecision ? { pendingDecision } : {}),
+			onEventReplay: (verdict: RunEventReplay) => {
+				replay = verdict
+				onEventReplay?.(verdict)
+			},
+		} as QueryParams,
+		listener,
+	)
 
-	return { resumed: true, run, state }
+	return { resumed: true, run, state, ...(replay !== undefined ? { replay } : {}) }
 }

package/src/store/index.ts

@@ -1,7 +1,7 @@
 export { InMemoryStore } from './InMemoryStore.js'
 export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
-export { RunDiskStore } from './run/disk.js'
+export { RunDiskStore, readRunEventsIn } from './run/disk.js'
 export { InMemoryRunStore } from './run/memory.js'
 export { DiskCheckpointStore } from './run/checkpoint-disk.js'
 export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'