@namzu/sdk 39.0.0 → 41.0.0

package/src/types/connector/mcp.ts

@@ -40,11 +40,40 @@ export interface MCPStdioTransportConfig extends MCPTransportConfigBase {
 	cwd?: string
 }
 
+/**
+ * Anything that answers like `fetch`, restricted to the request shape the
+ * MCP HTTP transports actually send: a URL string, an optional
+ * method/headers/body, `redirect` (both transports pin this to `'manual'`
+ * so a caller cannot silently re-enable auto-following a redirect), and an
+ * abort signal.
+ *
+ * Structurally identical in spirit to `bridge/a2a/client.ts`'s `FetchLike`
+ * — the same injectable, socket-free function shape, so a test needs no
+ * socket — but the return type stays the real `Response` rather than that
+ * bridge's narrower `{ok, status, json(), text()}` duck type: both MCP
+ * transports already read `.headers` (content type, session id) and one of
+ * them reads `.body` as a stream (the SSE GET), neither of which the A2A
+ * bridge's version exposes. Re-declared here, rather than imported from the
+ * A2A bridge, so that bridge is not forced to grow fields it does not use.
+ */
+export type MCPFetchLike = (
+	input: string,
+	init?: {
+		method?: string
+		headers?: Record<string, string>
+		body?: string
+		redirect?: 'manual' | 'follow' | 'error'
+		signal?: AbortSignal
+	},
+) => Promise<Response>
+
 export interface MCPHttpSseTransportConfig extends MCPTransportConfigBase {
 	type: 'http-sse'
 	url: string
 	headers?: Record<string, string>
 	timeoutMs?: number
+	/** Injected in place of the ambient global `fetch`. Defaults to it. */
+	fetch?: MCPFetchLike
 }
 
 export interface MCPStreamableHttpTransportConfig extends MCPTransportConfigBase {
@@ -52,6 +81,8 @@ export interface MCPStreamableHttpTransportConfig extends MCPTransportConfigBase
 	url: string
 	headers?: Record<string, string>
 	timeoutMs?: number
+	/** Injected in place of the ambient global `fetch`. Defaults to it. */
+	fetch?: MCPFetchLike
 }
 
 export type MCPTransportUnion =
@@ -65,6 +96,79 @@ export interface MCPJsonRpcError {
 	data?: unknown
 }
 
+/**
+ * A protocol revision this client can still negotiate DOWN to when a server
+ * does not speak the current spec, newest first.
+ *
+ * Kept as a literal union (rather than just `string`) so a caller pattern
+ * matching on `McpEra` gets real exhaustiveness checking; the runtime array
+ * of the same values lives in `constants/mcp` and is typed against this.
+ */
+export type McpLegacyVersion = '2025-11-25' | '2025-06-18' | '2025-03-26' | '2024-11-05'
+
+/**
+ * A protocol revision this client speaks WITHOUT the `initialize`
+ * handshake.
+ *
+ * A modern connection is stateless: there is no handshake, no session id,
+ * and every request carries its own protocol version, client capabilities
+ * and client info in `_meta`. `connect()` probes for one before it offers
+ * the legacy handshake.
+ */
+export type McpModernVersion = '2026-07-28'
+
+/**
+ * Which family of the wire protocol a connection resolved to, and which
+ * exact revision within it.
+ *
+ * `kind` alone tells a caller which rules apply — whether `_meta` and the
+ * stateless per-request shape are in play, or the `initialize` handshake
+ * and (for 2025-06-18 and later) the `MCP-Protocol-Version` header — without
+ * re-deriving it from the version string on every read.
+ *
+ * `MCPClient.connect()` resolves this by probing for a modern peer first
+ * and falling back to the legacy `initialize` handshake, so which arm a
+ * given connection lands on is the server's answer, not a configuration.
+ */
+export type McpEra =
+	| { readonly kind: 'modern'; readonly version: McpModernVersion }
+	| { readonly kind: 'legacy'; readonly version: McpLegacyVersion }
+
+/**
+ * What a modern server answers `server/discover` with.
+ *
+ * The modern era's replacement for the `initialize` result: it names the
+ * revisions the server speaks, what it can do, and — under the reserved
+ * `_meta` key — who it is. Every field is optional on the wire as far as
+ * this client is concerned, because the one thing it MUST be able to do
+ * with a malformed answer is decline to treat it as proof of a modern peer.
+ */
+export interface MCPDiscoverResult {
+	/** Newest first is conventional but not required; this client sorts. */
+	supportedVersions?: readonly string[]
+	capabilities?: MCPServerCapabilities
+	_meta?: Record<string, unknown>
+}
+
+/**
+ * Where a resolved {@link McpEra} is remembered between connections.
+ *
+ * The spec's own guidance: a client SHOULD cache the era for the lifetime
+ * of the server process (stdio) or the origin (HTTP) and re-probe if the
+ * cached assumption later fails. Without it every connection to a legacy
+ * server pays a wasted probe round trip.
+ *
+ * An interface rather than a module-level `Map` because a process-global
+ * cache leaks between tests and would make a conformance suite depend on
+ * the order its cases happen to run in. `MCPClientConfig.eraCache` injects
+ * one; omitting it uses a process-wide default.
+ */
+export interface MCPEraCache {
+	get(key: string): McpEra | undefined
+	set(key: string, era: McpEra): void
+	delete(key: string): void
+}
+
 export interface MCPJsonRpcMessage {
 	jsonrpc: '2.0'
 	id?: string | number
@@ -83,12 +187,48 @@ export interface MCPRequestOptions {
 	 * waiting, not that an already-started remote side effect was rolled back.
 	 */
 	readonly signal?: AbortSignal
+	/**
+	 * Extra headers for this one request, merged over the transport's static
+	 * config headers (a collision resolves to this value) and under this same
+	 * call's `bearerToken`, if both are given.
+	 *
+	 * The protocol's own headers are the exception: `MCP-Protocol-Version`,
+	 * `Mcp-Method` and `Mcp-Name` mirror values inside the request this call
+	 * is sending, and a server rejects a header that disagrees with the body
+	 * it mirrors. A value given here under one of those names — matched
+	 * without regard to case — is refused and warn-logged rather than put on
+	 * the wire.
+	 *
+	 * A transport with no header concept (stdio) receives the field and does
+	 * nothing with it.
+	 */
+	readonly headers?: Readonly<Record<string, string>>
+	/**
+	 * Sent as `Authorization: Bearer <bearerToken>` on this one request.
+	 *
+	 * Overrides a configured `Authorization` header — static or supplied via
+	 * `headers` above — for this request only; it never touches a
+	 * differently-named header such as a static `X-API-Key`. Omit it and a
+	 * configured `Authorization` header is left exactly as configured.
+	 */
+	readonly bearerToken?: string
 }
 
 /** Authority for one transport write and any response body it consumes. */
 export interface MCPTransportSendOptions {
 	/** A pre-aborted signal starts no transport work. */
 	readonly signal?: AbortSignal
+	/**
+	 * Extra headers for this one send.
+	 *
+	 * An HTTP-speaking transport merges these over its static config
+	 * headers; a transport with no header concept (stdio) receives the
+	 * field and does nothing with it. Introduced so the client — which
+	 * alone knows the negotiated era — can ask for `MCP-Protocol-Version`
+	 * on a post-initialize request without the transport having to know
+	 * what a protocol version is.
+	 */
+	readonly headers?: Readonly<Record<string, string>>
 }
 
 export interface MCPTransport {
@@ -138,10 +278,38 @@ export interface MCPToolDefinition {
 	annotations?: MCPToolAnnotations
 }
 
+/**
+ * Audience/priority/freshness hints a server may attach to a content block,
+ * part of the schema since 2025-06-18. Advisory only: namzu does not act on
+ * any of these fields today, but drops none of them either — they survive
+ * into `ToolResult.data` for a host that wants to read them.
+ *
+ * Distinct from {@link MCPToolAnnotations}, which describes a TOOL
+ * (read-only, destructive, …); this describes one piece of CONTENT.
+ */
+export interface MCPContentAnnotations {
+	audience?: Array<'user' | 'assistant'>
+	priority?: number
+	lastModified?: string
+}
+
 export type MCPContentBlock =
 	| { type: 'text'; text: string }
 	| { type: 'image'; data: string; mimeType: string }
-	| { type: 'resource'; resource: { uri: string; mimeType?: string; text?: string } }
+	| {
+			type: 'resource'
+			resource: { uri: string; mimeType?: string; text?: string; blob?: string }
+			annotations?: MCPContentAnnotations
+	  }
+	/** Since 2025-03-26. Raw audio bytes, base64-encoded like `image`. */
+	| { type: 'audio'; data: string; mimeType: string }
+	/**
+	 * Since 2025-06-18. A pointer to a resource the server has NOT embedded
+	 * inline — unlike `resource`, which always carries `text` or `blob`.
+	 * Because this block carries no content at all, the adapter names it
+	 * for the model rather than fabricating text the server never sent.
+	 */
+	| { type: 'resource_link'; uri: string; name: string; description?: string; mimeType?: string }
 
 export interface MCPToolResult {
 	content: MCPContentBlock[]
@@ -160,6 +328,23 @@ export interface MCPToolResult {
 	_meta?: Record<string, unknown>
 }
 
+/**
+ * One thing the client would have to do that it never declared it could —
+ * elicit input, sample a message, list roots, or something a later spec
+ * revision defines. Only `method` is read by this client; every other field
+ * is carried opaquely so a shape it does not understand still names itself.
+ *
+ * namzu declares `clientCapabilities: {}` in every era, so MRTR rule 7 — a
+ * server MUST NOT send an `inputRequests` entry for a capability the client
+ * did not declare — means a CONFORMING server never produces one of these.
+ * The type exists for the defensive path: a non-conforming server's demand
+ * is named and refused rather than silently misread as an ordinary result.
+ */
+export interface MCPInputRequest {
+	readonly method: string
+	readonly [key: string]: unknown
+}
+
 export interface MCPResource {
 	uri: string
 	name: string
@@ -242,6 +427,25 @@ export interface MCPClientConfig {
 	 * forever — no error, no failure, just a run that stopped.
 	 */
 	requestTimeoutMs?: number
+	/**
+	 * How long `connect()`'s era probe waits for an answer before deciding
+	 * the peer speaks a legacy revision. Defaults to
+	 * `DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS`.
+	 *
+	 * Never longer than `requestTimeoutMs`: a probe is a request, and a
+	 * probe that outlived the deadline every other request is held to would
+	 * be a connect that hangs past its own timeout.
+	 */
+	eraProbeTimeoutMs?: number
+	/**
+	 * Where this client reads and records the resolved era.
+	 *
+	 * Defaults to a process-wide cache shared by every `MCPClient`, which is
+	 * the point — two clients reaching the same origin should not each pay a
+	 * probe. Inject a fresh one to isolate a test, or a longer-lived one to
+	 * scope the memory to a host rather than the process.
+	 */
+	eraCache?: MCPEraCache
 	/**
 	 * A pre-built logger. Threaded into the transport `MCPClient` constructs
 	 * internally (`createTransport`), so a caller that supplies this gets a

package/src/types/message/index.ts

@@ -246,7 +246,9 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'advisory',
 	'answer-review',
 	'auto-continuation',
+	'job-exit',
 	'limit-finalization',
+	'repeat-call',
 	'steering',
 	'step-context',
 	'structured-output',

package/src/types/run/entity.ts

@@ -123,6 +123,20 @@ export interface Run {
 	 */
 	abandonedTaskIds?: readonly string[]
 
+	/**
+	 * Background jobs the model was waiting on that were still running when
+	 * this run ended.
+	 *
+	 * Only jobs `wait_for_job` named: a dev server nobody awaited is not work
+	 * this run walked away from, it is work it deliberately left behind. The
+	 * run holds itself open for these, bounded, and names the ones the bound
+	 * ran out on — the same honesty `abandonedTaskIds` owes for a delegated
+	 * worker, and with the same limit: naming a job is not stopping it. A
+	 * run-owned job is still stopped by the run's own teardown; one bound to
+	 * the host's session keeps running, which is what it was started for.
+	 */
+	abandonedJobIds?: readonly string[]
+
 	parentRunId?: RunId
 
 	depth?: number

package/src/types/run/events.ts

@@ -812,6 +812,62 @@ type CoreRunEvent =
 			/** Approved plan edge carried while the blocking tool is still live. */
 			planId?: string
 			planStepId?: string
+			/**
+			 * How the host that delegated this child wants it GROUPED on screen —
+			 * a shared label over a set of related delegations, typically one
+			 * operator-visible piece of work several children are doing together.
+			 *
+			 * These fields are display annotations only; they do not create
+			 * dependencies, barriers, or serial execution. Nothing in the kernel
+			 * reads them: admission, ordering and concurrency come from the
+			 * scheduler and from {@link planId}/{@link planStepId}, which is the
+			 * field pair that DOES carry correlation a host may act on. A reader
+			 * who infers execution structure from a label here has inferred it
+			 * from a caption.
+			 *
+			 * Absent unless the delegating host supplied them, which is the
+			 * normal case — a host that groups nothing sends nothing, and a
+			 * consumer written before these existed reads the same event it
+			 * always did.
+			 *
+			 * They ride this event rather than staying in the delegating
+			 * process's memory for REACH: a consumer watching from outside
+			 * that process — another listener, or an SSE client — can rebuild
+			 * the same picture instead of seeing an undifferentiated list of
+			 * children.
+			 *
+			 * Reach is not durability, and this event buys only the first.
+			 * Like every delegation lifecycle event, it is handed straight to
+			 * a host's listener and never enters a run's log — which is what
+			 * the absent `seq` on this variant says, and what the `seq` doc
+			 * above spells out. A label here is therefore written nowhere by
+			 * the kernel and does not survive a restart of the host that chose
+			 * it; a host wanting the grouping to outlive its process records it
+			 * from the listener.
+			 */
+			workflow?: string
+			/**
+			 * Display group WITHIN {@link workflow} — a stage of that work, as
+			 * the delegating host labelled it. Display-only on the same terms as
+			 * {@link workflow}: it creates no dependencies, barriers or serial
+			 * execution, and two children naming the same phase are not thereby
+			 * sequenced or synchronised.
+			 */
+			phase?: string
+			/**
+			 * Longer text explaining {@link phase}, for a surface that has room
+			 * to show it. Display-only on the same terms as {@link workflow}.
+			 */
+			phaseDetail?: string
+			/**
+			 * Where {@link phase} sits in the host's intended DISPLAY order,
+			 * zero-based. Display-only on the same terms as {@link workflow}: it
+			 * orders a list on a screen and orders nothing that runs. Children in
+			 * one phase are expected to carry the same value; a consumer that
+			 * sees two disagree should keep the first rather than resequence,
+			 * because nothing here is authoritative enough to arbitrate.
+			 */
+			phaseOrder?: number
 	  }
 	| {
 			type: 'agent_completed'

package/src/types/run/store.ts

@@ -28,6 +28,7 @@ import type { RunEvidenceScope, RunTextEvidenceSource } from '../../store/eviden
  * re-keyed per call, it happens once, deliberately, as its own change.
  */
 
+import type { RunExecutionStatus } from '../common/index.js'
 import type { Message } from '../message/index.js'
 import type { AuditEvent } from './audit.js'
 import type { Run } from './entity.js'
@@ -103,6 +104,47 @@ export type ToolExecutionRecord =
 	| (CompletedToolRecord & { readonly status: 'completed' })
 	| { readonly toolUseId: string; readonly toolName: string; readonly status: 'started' }
 
+/**
+ * One delegated child run found on disk under its parent's `children/`
+ * directory, as {@link import('../../store/run/disk.js').RunDiskStore.listChildren}
+ * reports it.
+ *
+ * A DISCOVERY record, not the child's evidence: every field here comes from
+ * the child's `run.json`, and the transcript, message snapshot and report
+ * beside it stay on disk until something asks for them. {@link dir} is what
+ * that something reads from.
+ *
+ * Everything the file supplies is optional, because a `run.json` is written
+ * by the child's own terminal path and a process killed before it got there
+ * leaves a directory whose other evidence is still worth opening. An absent
+ * field is "this file did not say", never a zero or an empty string.
+ */
+export interface DelegatedChildRun {
+	/**
+	 * The child's run id, taken from the directory name.
+	 *
+	 * The location is the fact: `initRun` names the directory after the run
+	 * it binds, so a `run.json` whose `id` disagrees with its own directory
+	 * was moved or hand-edited, and the directory is the half that decides
+	 * where the evidence actually is.
+	 */
+	readonly id: string
+	/** The parent run whose `children/` directory holds this one. */
+	readonly parentRunId: string
+	/** Absolute path to the child's evidence directory. */
+	readonly dir: string
+	readonly agentId?: string
+	readonly agentName?: string
+	/** `metadata.config.model` — the model the child was configured with. */
+	readonly model?: string
+	readonly status?: RunExecutionStatus
+	readonly startedAt?: number
+	readonly endedAt?: number
+	/** `tokenUsage.totalTokens` — this child's own cumulative spend. */
+	readonly totalTokens?: number
+	readonly depth?: number
+}
+
 /** Absence proves no recorded start only when the whole selected log is complete. */
 export interface ToolExecutionSnapshot {
 	readonly complete: boolean

package/src/types/sandbox/index.ts

@@ -261,6 +261,35 @@ export interface SandboxTcpConnectOptions {
 	readonly host?: '127.0.0.1' | '::1'
 }
 
+/**
+ * What to read, and how to stop reading it. Every field is optional, so
+ * `readFile(path)` and `readFile(path, {})` mean the same thing: the whole
+ * file.
+ */
+export interface SandboxReadFileOptions {
+	/** First byte to read. Defaults to 0. */
+	readonly offset?: number
+	/**
+	 * How many bytes to read. Defaults to the rest of the file. A range
+	 * that runs past the end returns the bytes that exist, not an error —
+	 * a caller resuming from a remembered offset must be able to ask
+	 * without knowing the answer first.
+	 *
+	 * **A backend may cap how large a single range it will serve**, and
+	 * one past that cap is REFUSED rather than shortened — a caller that
+	 * asked for 4 MiB, got 1 MiB and was told nothing would read the short
+	 * answer as the end of its range. The agent-backed backends cap it at
+	 * `NAMZU_AGENT_READ_FILE_RANGE_BYTES` (1 MiB by default), because one
+	 * range is one wire frame there; a provider reading from local disk has
+	 * no such ceiling. A caller that wants more than a frame's worth in one
+	 * call iterates {@link Sandbox.readFileStream} instead, which is not
+	 * capped.
+	 */
+	readonly length?: number
+	/** Aborts the read. */
+	readonly signal?: AbortSignal
+}
+
 export interface Sandbox {
 	readonly id: SandboxId
 	readonly status: SandboxStatus
@@ -296,22 +325,23 @@ export interface Sandbox {
 	 * Open a real pseudo-terminal whose complete process tree is confined to
 	 * and owned by this sandbox.
 	 *
-	 * Optional, and a backend that cannot provide one must **throw** rather
-	 * than hand back a pipe — the same rule {@link Sandbox.setNetworkPolicy}
-	 * states one line up, and for a sharper reason. A pipe would appear to
-	 * work: bytes would flow, and every program that calls `isatty` would
-	 * take its non-interactive branch. The prompt never appears, the REPL
-	 * exits immediately, the progress bar prints ten thousand lines, and
-	 * nothing says why.
+	 * Optional, and a backend that cannot provide one must **omit this
+	 * method** rather than hand back a pipe — the same skip-if-unavailable
+	 * rule {@link Sandbox.openTcpConnection} states below, and for a sharper
+	 * reason. A pipe would appear to work: bytes would flow, and every
+	 * program that calls `isatty` would take its non-interactive branch. The
+	 * prompt never appears, the REPL exits immediately, the progress bar
+	 * prints ten thousand lines, and nothing says why.
 	 *
-	 * A backend that implements this method MUST make {@link destroy} kill and
-	 * await every terminal it returned. Merely starting a host pseudo-terminal
-	 * with `rootDir` as its working directory does not satisfy either the
-	 * confinement or the ownership contract.
+	 * A backend that DOES implement this method MUST make {@link destroy}
+	 * kill and await every terminal it returned. Merely starting a host
+	 * pseudo-terminal with `rootDir` as its working directory does not
+	 * satisfy either the confinement or the ownership contract.
 	 *
-	 * The Firecracker backend satisfies both guarantees by owning the PTY in the
-	 * guest and awaiting its exit before the microVM is released. Backends that
-	 * cannot provide that boundary omit the capability.
+	 * The Firecracker backend satisfies both guarantees by owning the PTY in
+	 * the guest and awaiting its exit before the microVM is released.
+	 * Backends that cannot provide that boundary omit the capability, as
+	 * stated above.
 	 */
 	openTerminal?(options: OpenTerminalOptions): Promise<TerminalSession>
 	/**
@@ -322,7 +352,46 @@ export interface Sandbox {
 	 */
 	openTcpConnection?(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection>
 	writeFile(path: string, content: string | Buffer): Promise<void>
-	readFile(path: string): Promise<Buffer>
+	/**
+	 * Read a file out of the sandbox.
+	 *
+	 * `options` is optional in both directions, which is what keeps this
+	 * source-compatible: a caller may go on writing `readFile(path)`, and a
+	 * backend may go on declaring the one-parameter form and still satisfy
+	 * this signature. A backend that accepts the parameter and IGNORES
+	 * `offset`/`length` does not — returning the whole file where a slice
+	 * was asked for is a wrong answer, not a degraded one, so such a
+	 * backend must reject instead.
+	 *
+	 * @param options.offset First byte to read. Defaults to 0.
+	 * @param options.length How many bytes to read. Defaults to the rest of
+	 *   the file. A range that runs past the end returns the bytes that
+	 *   exist rather than failing.
+	 * @param options.signal Aborts the read.
+	 */
+	readFile(path: string, options?: SandboxReadFileOptions): Promise<Buffer>
+	/**
+	 * Read a file as a stream of chunks, so neither the sandbox nor this
+	 * process ever holds the whole of it.
+	 *
+	 * Optional, in the same way {@link Sandbox.openTerminal} is: a backend
+	 * that cannot read a file incrementally must OMIT this rather than
+	 * implement it by reading the file whole and chopping the result up,
+	 * which would give a caller the bounded-memory behaviour it asked for in
+	 * name only. A caller that needs the bound therefore refuses an absent
+	 * method rather than falling back to {@link Sandbox.readFile}.
+	 *
+	 * Chunk boundaries are not part of the contract — only the order and
+	 * the concatenation are. Aborting `options.signal`, or leaving the loop
+	 * early, must stop the transfer and release whatever the sandbox opened
+	 * for it.
+	 *
+	 * Hosts that drain agent-produced output files before {@link destroy}
+	 * (see {@link listFiles}) are the reason this exists: those files are
+	 * routinely tens to hundreds of megabytes, and a whole-file read of one
+	 * of them costs several times its size in the sandbox.
+	 */
+	readFileStream?(path: string, options?: SandboxReadFileOptions): AsyncIterable<Buffer>
 	/**
 	 * Recursively enumerate regular files under `rootPath`. Directories,
 	 * symlinks, sockets, and other non-regular entries are skipped.

package/src/types/tool/index.ts

@@ -113,6 +113,33 @@ export interface BackgroundJobRegistryRef {
 	}
 	kill(id: string): Promise<{ id: string; status: string }>
 	list(): readonly { id: string; command: string; status: string }[]
+	/**
+	 * Await this job's exit instead of reading it in a loop; resolves at
+	 * once for a job that has already stopped. Optional, and added after
+	 * the rest of this surface: a host implementing this interface directly
+	 * rather than through `bindOwner` may not have it yet, so `wait_for_job`
+	 * checks for it and says so rather than assuming every host can wait.
+	 */
+	waitForExit?(
+		id: string,
+		opts?: { signal?: AbortSignal },
+	): Promise<{
+		id: string
+		status: string
+		exitCode?: number
+	}>
+	/**
+	 * Say that the model is waiting on this job, so the run stays open for it
+	 * when the model stops calling tools.
+	 *
+	 * Called by `wait_for_job` and nothing else. The kernel holds a finishing
+	 * run open — bounded, and for no model tokens — only for a job marked
+	 * here; a job nobody marked never delays a run, which is what a dev server
+	 * or a watcher needs. Optional for the reason `waitForExit` is: a host
+	 * implementing this interface directly may have nowhere to record the
+	 * intent, and then there is simply no hold.
+	 */
+	markAwaited?(id: string): void
 }
 
 /**
@@ -138,6 +165,83 @@ export interface FileReadTracker {
 	 * preserves it; different or unknown content clears it. Never infer from a name.
 	 */
 	writeCallId?(key: string): string | undefined
+	/**
+	 * Optional chain of calls whose bodies compose the current content: the
+	 * full-body write that started it, then the successful edits applied on
+	 * top of it, in order.
+	 *
+	 * Defined only while at least one edit sits on a witnessed write — exactly
+	 * when `writeCallId` is not. An edited file's body is no longer the write
+	 * call's body, and a consumer that knows only `writeCallId` has to keep
+	 * seeing nothing there rather than a claim that has quietly stopped being
+	 * true. The chain names INPUTS: reconstructing the body means replaying
+	 * those calls' visible arguments and checking the result against
+	 * `fingerprint(key)`, never asserting it.
+	 */
+	editChain?(key: string): { rootWriteCallId: string; editCallIds: readonly string[] } | undefined
+	/**
+	 * Optional record of a successful edit's resulting content, with the call
+	 * that produced it.
+	 *
+	 * Does everything `recordRead(key, content)` does, and additionally extends
+	 * the chain when this edit ran against content the ledger already had a
+	 * fingerprint for and a witnessed write underneath it — the two facts that
+	 * make the replay reproducible. Missing either, it is an ordinary
+	 * observation of a body nobody can replay: the fingerprint advances and the
+	 * chain is cleared. Pass ToolContext.toolUseId only after the edit succeeded.
+	 */
+	recordEdit?(key: string, content: string, callId: string): void
+	/**
+	 * Optional witness of a read that returned the file WHOLE, with the
+	 * fingerprint of the rendering it returned.
+	 *
+	 * Does everything `recordRead(key, content)` does, and additionally records
+	 * that the body is visible in `callId`'s receipt — not as text this ledger
+	 * holds, but as the exact rendering `callId` emitted, so a consumer can
+	 * check the receipt it can see against `renderedFingerprint` before
+	 * referencing it. A partial read never calls this: a window proves nothing
+	 * about the rest of the file. Pass `ToolContext.toolUseId` and the
+	 * fingerprint of the tool's own output string.
+	 *
+	 * The witness is recorded only where no write witness or chain survives the
+	 * observation, because a write-rooted body is one the model composed and
+	 * can be replayed through. It is cleared by exactly what clears a write
+	 * witness — different or unknown content — and additionally by any
+	 * `recordEdit`, because a read roots no chain: the body it witnesses exists
+	 * only as a rendering, and nothing may be replayed on top of it.
+	 */
+	recordFullRead?(key: string, content: string, callId: string, renderedFingerprint: string): void
+	/**
+	 * Optional witness of the full read above: the call whose receipt holds the
+	 * body, and the fingerprint of what that call emitted.
+	 *
+	 * `renderedFingerprint` is deliberately not the body's fingerprint —
+	 * `fingerprint(key)` is that. It describes the RECEIPT, so a consumer
+	 * admits the reference only while the receipt it can see is byte-for-byte
+	 * what the tool returned; an elided, spilled or cleared one is not.
+	 *
+	 * The derived work context asks a tracker for `writeCallId` and
+	 * `fingerprint` before it reads any witness at all — a name alone does not
+	 * say the ledger is the one execution wrote — so a tracker implementing
+	 * this pair and neither of those still establishes nothing.
+	 */
+	readWitness?(key: string): { callId: string; renderedFingerprint: string } | undefined
+	/**
+	 * Optional note that a built-in mutation has just refused this path because
+	 * the body on disk differs from the fingerprint above.
+	 *
+	 * Not an observation. The refusing tool read the disk, but all it reports
+	 * here is the disagreement — recording the body it found would re-baseline
+	 * the drift check and admit the very mutation that was refused. An
+	 * implementation must therefore leave `fingerprint`, `hasRead`,
+	 * `writeCallId`, `editChain` and `readWitness` exactly as they were, and any
+	 * later content observation clears the flag. It exists so a consumer that
+	 * cannot read the filesystem — the derived work context — can stop
+	 * referencing a body it has been told is stale, without a check of its own.
+	 */
+	recordDriftObserved?(key: string): void
+	/** Whether a refused mutation has reported this path stale since the last observation. */
+	driftObserved?(key: string): boolean
 	/**
 	 * Fingerprint of the body captured at the last read, when one was.
 	 *

package/src/utils/env.ts

@@ -0,0 +1,23 @@
+/**
+ * A positive whole number of milliseconds from the environment, or the
+ * caller's own default.
+ *
+ * Every bound that can be tuned wants the same three answers, and the third
+ * is the one worth sharing: a variable set to `soon`, to `-1` or to nothing
+ * at all falls back rather than parsing, because a run must not wait, hold or
+ * time out for `NaN`.
+ *
+ * `process.env` is read on every call, so where it is called decides when the
+ * value is sampled — `wait_for_job` fixes its bounds at module load and names
+ * them in a tool schema, and the kernel's hold ceiling asks per hold. That
+ * choice is why this lives here rather than being imported from the tool: the
+ * kernel reaching into `wait_for_job` for the parse would pull the tool's
+ * module-load sampling into the runtime's own graph, and move when the
+ * `NAMZU_JOB_WAIT_*` bounds are read.
+ */
+export function readPositiveIntEnv(key: string, fallback: number): number {
+	const value = process.env[key]?.trim()
+	if (!value) return fallback
+	const parsed = Number(value)
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
+}