@namzu/sdk 39.0.0 → 40.0.0

package/src/runtime/jobs/registry.ts

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process'
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 
 /**
  * Work that outlives a tool call, owned by whoever started it.
@@ -310,6 +311,32 @@ export class BackgroundJobRegistry {
 		return entry.record
 	}
 
+	/**
+	 * Await one job's exit — the public counterpart to `onExit`, for a
+	 * caller that wants a single result rather than a standing
+	 * subscription. Resolves at once for a job that has already stopped, so
+	 * a caller that lost the race against a fast-finishing job never blocks
+	 * on a promise that would otherwise never settle.
+	 *
+	 * `signal` is honoured: an aborted wait rejects and detaches rather than
+	 * holding the internal exit promise's continuation open for a job that
+	 * may run for another hour. That only ends the WAIT — the job itself is
+	 * untouched either way, exactly as a timed-out `kill`-less wait leaves
+	 * it. See `wait-for-job-bounds.ts`, the first caller.
+	 */
+	waitForExit(id: string, opts: { signal?: AbortSignal } = {}): Promise<BackgroundJob> {
+		const entry = this.jobs.get(id)
+		if (!entry) throw new UnknownBackgroundJobError({ id })
+		if (entry.record.status !== 'running') return Promise.resolve(entry.record)
+		// `entry` is the same object the `finalize` closure in `start()`
+		// mutates in place, so reading `entry.record` after `exit` settles
+		// sees the final status — the same trick `kill()` already relies on.
+		return awaitWithAbort(
+			entry.exit.then(() => entry.record),
+			opts.signal,
+		)
+	}
+
 	/**
 	 * Output since `fromOffset`, with what the cap dropped stated.
 	 *
@@ -410,6 +437,17 @@ export function bindOwner(
 			readonly workingDirectory: string
 			readonly env?: Record<string, string>
 		}) => JobProcess
+		/**
+		 * Be told that the model said it is waiting on a job's exit.
+		 *
+		 * The registry does not keep this: wait-intent belongs to the RUN that
+		 * expressed it, not to a registry a host may share across runs and
+		 * sessions. The run passes its own recorder here — `AwaitedJobs`, which
+		 * is what the iteration loop holds open for. Absent means nobody is
+		 * listening, and `markAwaited` is then absent from the bound ref rather
+		 * than present and silently doing nothing.
+		 */
+		readonly onAwaited?: (id: string) => void
 	} = {},
 ) {
 	const mine = (id: string): BackgroundJob => {
@@ -443,6 +481,18 @@ export function bindOwner(
 			mine(id)
 			return registry.read(id, opts ?? {})
 		},
+		waitForExit: (id: string, opts?: { signal?: AbortSignal }) => {
+			mine(id)
+			return registry.waitForExit(id, opts ?? {})
+		},
+		...(defaults.onAwaited
+			? {
+					markAwaited: (id: string) => {
+						mine(id)
+						defaults.onAwaited?.(id)
+					},
+				}
+			: {}),
 		kill: async (id: string) => {
 			mine(id)
 			return await registry.kill(id)

package/src/runtime/query/executor.ts

@@ -51,6 +51,8 @@ import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import { describeVisibleFileEvidence } from './file-evidence-context.js'
+import { seedObservationLedger } from './file-evidence-seed.js'
+import { skippedToolResultText } from './plugin-hooks.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
@@ -334,6 +336,16 @@ export interface ToolExecutorConfig {
 	 * session and stops them itself when the session ends.
 	 */
 	backgroundJobOwner?: string
+	/**
+	 * Where `wait_for_job` records that the model is waiting on a job.
+	 *
+	 * A callback rather than the recorder itself: the executor's part is to
+	 * hand the tools a bound ref, and what the run does with the intent —
+	 * hold itself open for the job — is the iteration loop's business. Absent
+	 * means the bound ref has no `markAwaited` at all, so a host that wires no
+	 * recorder gets no hold rather than a marking call that goes nowhere.
+	 */
+	onJobAwaited?: (id: string) => void
 
 	/**
 	 * Where the `skill` tool reads from.
@@ -514,6 +526,8 @@ export class ToolExecutor {
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
 	private readonly fileReadTracker: FileReadTracker
+	/** A ledger is rebuilt from history at most once; a second pass would re-append its chains. */
+	private fileObservationsSeeded = false
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -547,6 +561,39 @@ export class ToolExecutor {
 		this.config = { ...this.config, sandbox }
 	}
 
+	/**
+	 * Rebuild this run's observation ledger from history a resume restored.
+	 *
+	 * Once, and only from a history that has already been repaired — the ledger
+	 * has to describe what the model is about to be shown, not what was
+	 * checkpointed before the repair removed an abandoned call. `sandboxed` is
+	 * passed rather than read off this executor's config because a resumed run
+	 * restores its history before it acquires a sandbox, so the config does not
+	 * know yet what the run's tool paths will be keyed on.
+	 *
+	 * Awaited, and the only filesystem work anywhere in this feature: the seed
+	 * has to write its entries under the keys the mutation tools will look them
+	 * up under, which on a host means resolving each path through its symlinks
+	 * the way `write` and `edit` do. No file's content is read.
+	 */
+	async seedFileObservations(messages: readonly Message[], sandboxed: boolean): Promise<void> {
+		if (this.fileObservationsSeeded) return
+		this.fileObservationsSeeded = true
+		const report = await seedObservationLedger(messages, this.fileReadTracker, {
+			workingDirectory: this.config.workingDirectory,
+			...(this.config.additionalDirectories
+				? { additionalDirectories: this.config.additionalDirectories }
+				: {}),
+			sandboxed,
+		})
+		this.log.info('Rebuilt the file observation ledger from restored history', {
+			[NAMZU.RUN_ID]: this.config.runId,
+			'namzu.files.witnessed': report.pathsWitnessed,
+			'namzu.files.seen': report.pathsSeen,
+			'namzu.files.replayed_units': report.unitsReplayed,
+		})
+	}
+
 	/** Request-only evidence from the same ledger used by mutation admission. No filesystem I/O. */
 	describeFileEvidence(messages: readonly Message[]): string | undefined {
 		return describeVisibleFileEvidence(
@@ -1342,6 +1389,7 @@ export class ToolExecutor {
 												) as JobProcess,
 										}
 									: {}),
+								...(this.config.onJobAwaited ? { onAwaited: this.config.onJobAwaited } : {}),
 							},
 						),
 					}
@@ -2265,7 +2313,7 @@ export class ToolExecutor {
 					return {
 						kind: 'skip',
 						input: currentInput,
-						output: `Tool ${toolName} skipped by plugin: ${result.reason}`,
+						output: skippedToolResultText(toolName, result.reason),
 					}
 				case 'error':
 					return {

package/src/runtime/query/file-evidence-context.ts

@@ -1,9 +1,42 @@
-import { resolve } from 'node:path'
-import { isClearedToolResult } from '../../compaction/tool-result-editing.js'
 import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
-import { WriteFileTool } from '../../tools/builtins/write-file.js'
-import type { Message, ToolCall } from '../../types/message/index.js'
+import { ReadFileTool } from '../../tools/builtins/read-file.js'
+import type { Message } from '../../types/message/index.js'
 import type { FileReadTracker } from '../../types/tool/index.js'
+import {
+	MAX_EDIT_CALLS,
+	MAX_PATH_UNITS,
+	MAX_WITNESSED_PATHS,
+	type ReplayBudget,
+	type VisibleHistory,
+	createReplayBudget,
+	indexVisibleHistory,
+	knownStale,
+	lexicalFileKeys,
+	replayHop,
+	spend,
+	visibleCall,
+	visibleEdit,
+	visibleWrite,
+} from './file-evidence-replay.js'
+
+/**
+ * Receipt text a read entry may point at.
+ *
+ * The same class of bound as the one on a write call's arguments, and set to
+ * the same number for the same reason: past it the text is not read at all. A
+ * bigger file is simply not admitted this way — the model re-reads it, which is
+ * what it does today.
+ */
+const MAX_RECEIPT_UNITS = 32_000
+
+interface FileEvidence {
+	readonly path: string
+	/** Absent on the write-rooted entries; `'read'` on a body that is a receipt. */
+	readonly kind?: 'read'
+	readonly bodyInCall: string
+	readonly editsInCalls?: readonly string[]
+	readonly observedFingerprint: string
+}
 
 /** Join visible call bodies, successful receipts and this executor's observation ledger. */
 export function describeVisibleFileEvidence(
@@ -14,52 +47,163 @@ export function describeVisibleFileEvidence(
 ): string | undefined {
 	// Execution-owned witnesses survive transparent wrappers; a name alone proves nothing.
 	if (!tracker.writeCallId || !tracker.fingerprint) return
-	const calls = new Map<string, ToolCall | null>()
-	const results = new Map<string, Message | null>()
-	for (const message of messages) {
-		if (message.role === 'assistant') {
-			for (const call of message.toolCalls ?? []) {
-				calls.set(call.id, calls.has(call.id) ? null : call)
-			}
-		} else if (message.role === 'tool') {
-			results.set(message.toolCallId, results.has(message.toolCallId) ? null : message)
-		}
-	}
-	const files = new Map<string, { path: string; bodyInCall: string; observedFingerprint: string }>()
-	for (const [id, call] of calls) {
-		const receipt = results.get(id)
-		if (
-			!call ||
-			call.function.name !== 'write' ||
-			call.metadata?.inputTruncated ||
-			call.function.arguments.length > 32_000 ||
-			id.length > 256 ||
-			!receipt ||
-			receipt.role !== 'tool' ||
-			receipt.isError ||
-			typeof receipt.content !== 'string' ||
-			isClearedToolResult(receipt.content)
-		)
-			continue
+	// Lexical, as this projection has always looked entries up: a spelling that
+	// does not resolve to the tool's canonical key finds nothing and the path is
+	// simply not admitted. Writing the ledger is the side that has to key the
+	// way the tools do — see `file-evidence-seed.ts`.
+	const history = indexVisibleHistory(messages, lexicalFileKeys(workingDirectory, sandboxed))
+	const budget = createReplayBudget()
+	const files = new Map<string, FileEvidence>()
+	for (const [id, call] of history.calls) {
+		const name = call?.function.name
+		if (name !== 'write' && name !== 'edit' && name !== 'read') continue
 		try {
-			const input = WriteFileTool.inputSchema.safeParse(JSON.parse(call.function.arguments))
-			if (!input.success || input.data.path.length > 512) continue
-			const body = input.data.content ?? input.data.newStr
-			if (typeof body !== 'string') continue
-			const key = sandboxed ? input.data.path : resolve(workingDirectory, input.data.path)
-			const fingerprint = fingerprintContent(body)
-			if (tracker.writeCallId(key) !== id || tracker.fingerprint(key) !== fingerprint) continue
-			files.delete(key)
-			files.set(key, {
-				path: input.data.path,
-				bodyInCall: id,
-				observedFingerprint: fingerprint,
-			})
-			if (files.size > 6) files.delete(files.keys().next().value as string)
+			const admitted =
+				name === 'write'
+					? writeEvidence(id, tracker, history)
+					: name === 'edit'
+						? chainEvidence(id, tracker, history, budget)
+						: readEvidence(id, tracker, history)
+			if (!admitted) continue
+			// A write-rooted entry outranks a read of the same file: it names a
+			// body the model composed itself, and edits can be replayed onto it.
+			// The ledger already withholds a read witness where one survives; this
+			// keeps a read that ran BEFORE the write from taking the path back.
+			const held = files.get(admitted.key)
+			if (admitted.evidence.kind === 'read' && held && held.kind !== 'read') continue
+			files.delete(admitted.key)
+			files.set(admitted.key, admitted.evidence)
+			if (files.size > MAX_WITNESSED_PATHS) files.delete(files.keys().next().value as string)
 		} catch {
 			// Malformed retained inputs or a custom tracker cannot establish evidence.
 		}
 	}
 	if (files.size === 0) return
-	return `Visible file evidence (this request only): each complete body remains in the named successful write call and matches the latest conversation observation. Reuse that body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`
+	return `Visible file evidence (this request only): each entry's current body is the complete body in the named successful write call, with the edit calls in editsInCalls — when present — applied in that order. An entry marked kind:"read" instead names a successful read call whose own receipt shows the file WHOLE, rendered with every line behind its own N<tab> prefix; that receipt is the body, and such an entry never carries editsInCalls. This runtime performed that reconstruction and checked it against its own file observation; it is not a derivation left to you. Reuse the body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check, and after a resume the observation behind an entry may itself have been rebuilt from this conversation's own earlier calls rather than made while this process ran. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`
+}
+
+/** A full body that arrived whole in one call and is still the file's body. */
+function writeEvidence(
+	id: string,
+	tracker: FileReadTracker,
+	history: VisibleHistory,
+): { key: string; evidence: FileEvidence } | undefined {
+	const written = visibleWrite(history, id)
+	if (!written || knownStale(tracker, written.key)) return
+	const fingerprint = fingerprintContent(written.body)
+	if (
+		tracker.writeCallId?.(written.key) !== id ||
+		tracker.fingerprint?.(written.key) !== fingerprint
+	)
+		return
+	return {
+		key: written.key,
+		evidence: {
+			path: written.path,
+			bodyInCall: id,
+			observedFingerprint: fingerprint,
+		},
+	}
+}
+
+/**
+ * A full body plus the visible edits since, replayed and then checked.
+ *
+ * Only the chain's TIP establishes the path: a middle hop is validated as part
+ * of the walk below, and admitting one on its own would claim the file stops
+ * at an edit later calls have already moved past. The replay runs the same
+ * apply core the tool ran at mutation time, over call arguments that are
+ * already in the conversation — no filesystem read, and the result is compared
+ * to the ledger's disk-derived fingerprint, never written into it.
+ */
+function chainEvidence(
+	id: string,
+	tracker: FileReadTracker,
+	history: VisibleHistory,
+	budget: ReplayBudget,
+): { key: string; evidence: FileEvidence } | undefined {
+	const tip = visibleEdit(history, id)
+	if (!tip || knownStale(tracker, tip.key)) return
+	const key = tip.key
+	const chain = tracker.editChain?.(key)
+	const observed = tracker.fingerprint?.(key)
+	if (!chain || observed === undefined || chain.editCallIds.at(-1) !== id) return
+	// The call bound before the walk, the unit bound before each operation it
+	// pays for. Neither is measured by doing the work it exists to refuse.
+	if (chain.editCallIds.length > MAX_EDIT_CALLS) return
+	const rootId = chain.rootWriteCallId
+	const root = visibleWrite(history, rootId)
+	// A root naming a different file is an ambiguity, not a base: the ledger
+	// and the visible call disagree about what was written where.
+	if (!root || root.key !== key) return
+	let content = root.body
+	if (!spend(budget, content.length)) return
+	for (const editId of chain.editCallIds) {
+		const hop = editId === id ? tip : visibleEdit(history, editId)
+		if (!hop || hop.key !== key) return
+		// Each of this hop's operations is measured against the body it is about
+		// to be applied to, charged, and only then applied — so a hop over the
+		// ceiling is refused before it is built rather than after, and one that
+		// fits is never turned away for a ceiling that guessed high. A hop the
+		// budget refuses, or one whose anchors no longer match, reconstructs
+		// nothing and withholds the whole path.
+		const replayed = replayHop(content, hop.input, budget)
+		if (replayed === undefined) return
+		content = replayed
+	}
+	if (fingerprintContent(content) !== observed) return
+	return {
+		key,
+		evidence: {
+			path: root.path,
+			bodyInCall: rootId,
+			editsInCalls: [...chain.editCallIds],
+			observedFingerprint: observed,
+		},
+	}
+}
+
+/**
+ * A body the model can still see because a read of the whole file put it there.
+ *
+ * Structurally unlike the two above, and deliberately so. They name a body the
+ * model itself composed, in arguments this projection can parse and replay; this
+ * names a RESULT, and the only thing anyone is allowed to do with it is compare
+ * it. The tool fingerprinted the exact string it emitted, and the entry is
+ * admitted only while the receipt still fingerprints to that — so a receipt the
+ * output budget elided or spilled, one compaction cleared, or one changed in any
+ * other way withholds the path rather than pointing the model at a body that is
+ * no longer in front of it. Nothing here undoes the line numbering to recover
+ * text: the numbering is what makes the comparison conclusive, not an encoding
+ * to be reversed.
+ *
+ * No chain, ever. A read roots nothing, so an entry here is the file as that one
+ * call showed it, and the ledger drops the witness the moment an edit lands.
+ */
+function readEvidence(
+	id: string,
+	tracker: FileReadTracker,
+	history: VisibleHistory,
+): { key: string; evidence: FileEvidence } | undefined {
+	if (!tracker.readWitness) return
+	const call = visibleCall(history, id, 'read')
+	const shown = history.results.get(id)?.content
+	if (!call || typeof shown !== 'string' || shown.length > MAX_RECEIPT_UNITS) return
+	const input = ReadFileTool.inputSchema.safeParse(JSON.parse(call.function.arguments))
+	if (!input.success || input.data.path.length > MAX_PATH_UNITS) return
+	const key = history.keyOf(input.data.path)
+	if (key === undefined || knownStale(tracker, key)) return
+	const witness = tracker.readWitness(key)
+	const observed = tracker.fingerprint?.(key)
+	if (!witness || witness.callId !== id || observed === undefined) return
+	if (fingerprintContent(shown) !== witness.renderedFingerprint) return
+	return {
+		key,
+		evidence: {
+			path: input.data.path,
+			kind: 'read',
+			bodyInCall: id,
+			observedFingerprint: observed,
+		},
+	}
 }