@namzu/sdk 58.1.1 → 60.0.0

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -60,6 +60,8 @@ export type JobWaitOutcome =
 			/** Which clock ran out. */
 			readonly cause: 'idle' | 'wall'
 			readonly elapsedMs: number
+			/** How long the job had been silent when the wait gave up. */
+			readonly quietForMs: number
 	  } & JobWaitProgress)
 
 /**
@@ -167,6 +169,7 @@ export async function waitForJobWithBounds(
 						kind: 'timeout',
 						cause: 'wall',
 						elapsedMs: elapsed,
+						quietForMs: now() - lastProgressAt,
 						output,
 						nextOffset: cursor,
 						droppedBytes,
@@ -182,6 +185,7 @@ export async function waitForJobWithBounds(
 							kind: 'timeout',
 							cause: 'idle',
 							elapsedMs: elapsed,
+							quietForMs: quietFor,
 							output,
 							nextOffset: cursor,
 							droppedBytes,
@@ -214,7 +218,7 @@ export function describeJobWaitTimeout(
 	const seconds = Math.round(outcome.elapsedMs / 1000)
 	const resume = `call wait_for_job or job read with from_offset ${outcome.nextOffset} to see only what comes next`
 	if (outcome.cause === 'idle') {
-		return `Job ${id} went quiet: no new output for a while, after ${seconds}s. It has not been stopped and may still be working — ${resume}.`
+		return `Job ${id} went quiet: no new output for ${Math.round(outcome.quietForMs / 1000)}s (waited ${seconds}s). It has not been stopped and may still be working — ${resume}.`
 	}
 	return `Job ${id} has been running for ${seconds}s without finishing. It has not been stopped — ${resume}.`
 }

package/src/tools/builtins/wait-for-job.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
 import { invalidBackgroundJobIdInput } from '../../runtime/jobs/job-id.js'
+import { LIVENESS_STALLED_MS } from '../../runtime/jobs/liveness.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
 import { defineTool } from '../defineTool.js'
 import { describeJobWaitTimeout, waitForJobWithBounds } from './wait-for-job-bounds.js'
@@ -20,7 +21,7 @@ import { describeJobWaitTimeout, waitForJobWithBounds } from './wait-for-job-bou
  */
 
 const DEFAULT_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_TIMEOUT_MS', 5 * 60 * 1000)
-const DEFAULT_IDLE_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_IDLE_MS', 2 * 60 * 1000)
+const DEFAULT_IDLE_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_IDLE_MS', LIVENESS_STALLED_MS)
 
 /**
  * The longest either bound will accept from the model.
@@ -146,7 +147,11 @@ export const WaitForJobTool = defineTool({
 		}
 
 		if (input.output_stream !== undefined && input.output_contains === undefined) {
-			return { success: false, output: '', error: 'output_stream requires output_contains.' }
+			return {
+				success: false,
+				output: '',
+				error: 'output_stream requires output_contains.',
+			}
 		}
 		if (input.output_contains !== undefined) {
 			if (!jobs.waitForOutput) {
@@ -261,6 +266,13 @@ export const WaitForJobTool = defineTool({
 			}
 		}
 
+		// The exit and its output are in this result, so the notice that would
+		// announce the same exit is withdrawn rather than repeated. Only when
+		// the model was given all of it: output the retention cap dropped, or
+		// that this bounded result omitted, leaves the notice in place.
+		if (outcome.kind === 'exited' && outcome.droppedBytes === 0 && outcome.omittedOutputBytes === 0)
+			jobs.markCollected?.(input.id)
+
 		const notices = [
 			...(outcome.droppedBytes > 0
 				? [`[${outcome.droppedBytes} bytes were dropped by the job's output retention cap]`]

package/src/tools/command-shell.ts

@@ -55,7 +55,7 @@ import { randomUUID } from 'node:crypto'
 import { constants, accessSync, existsSync } from 'node:fs'
 import { delimiter, isAbsolute, join, win32 } from 'node:path'
 
-import { MSYS_TAG_VARIABLE, registerMsysShell } from '../process/kill-tree.js'
+import { MSYS_TAG_VARIABLE, registerMsysShell, registerProcessTag } from '../process/kill-tree.js'
 import type { ShellDialect } from '../types/tool/index.js'
 
 /** The shell a host-side command runs in. */
@@ -452,8 +452,14 @@ export function spawnHostShell(
 	const spawnFn = options.spawnImpl ?? nodeSpawn
 	const shell = options.shell ?? hostCommandShell()
 	const spawned = hostShellSpawn(command, options.env, shell)
-	// Git Bash: tag the shell so a kill can find what a forked command left.
-	const tag = shell.windows === true && shell.path !== undefined ? randomUUID() : undefined
+	// Tag the shell so a kill can find what a forked command left: under Git
+	// Bash, the processes its runtime forked out of the Windows tree's reach; on
+	// Linux, the ones that started their own session and so left the process
+	// group. Other platforms have neither a bash runtime nor `/proc` to look in.
+	const platform = options.platform ?? process.platform
+	const windowsBash = shell.windows === true && shell.path !== undefined
+	const tag =
+		windowsBash || (shell.windows !== true && platform === 'linux') ? randomUUID() : undefined
 	const resolved =
 		tag === undefined ? spawned : { ...spawned, env: { ...spawned.env, [MSYS_TAG_VARIABLE]: tag } }
 	const common: SpawnOptions = {
@@ -471,8 +477,10 @@ export function spawnHostShell(
 	}
 	if (resolved.file !== undefined) {
 		const child = spawnFn(resolved.file, [...resolved.args], common)
-		if (tag !== undefined && child !== null && typeof child === 'object')
-			registerMsysShell(child, { bash: resolved.file, tag })
+		if (tag !== undefined && child !== null && typeof child === 'object') {
+			if (windowsBash) registerMsysShell(child, { bash: resolved.file, tag })
+			else registerProcessTag(child, tag)
+		}
 		return child
 	}
 	const windows = windowsCmdSpawn(command, resolved.env)

package/src/types/computer-use/index.ts

@@ -207,6 +207,15 @@ export interface FocusWindowResult {
 	readonly ok: boolean
 	/** The window in front after the attempt, or null when none could be read. */
 	readonly focusedId: string | null
+	/**
+	 * Set with `detail` when the host did not try at all (the screen was in
+	 * use, a prompt had it, the user said no). `not_delivered` / `safe` means
+	 * nothing was done and asking again later is fine.
+	 */
+	readonly delivery?: ActionDelivery
+	readonly retrySafety?: ActionRetrySafety
+	/** Why, in words the model can act on. */
+	readonly detail?: string
 }
 
 /**
@@ -231,9 +240,13 @@ export type UiElementAction =
  */
 export interface UiElement {
 	/**
-	 * Opaque reference for {@link ComputerUseHost.uiAct}, valid until the
-	 * host's next snapshot. Empty for an element the host cannot act on (a
-	 * label, a group), which is in the tree for what it says.
+	 * Opaque reference for {@link ComputerUseHost.uiAct}. It names the control,
+	 * not one reading of it: a host that can find the control again keeps the
+	 * ref usable across snapshots, and fails with a {@link UiActFailureCode}
+	 * when it cannot. Empty for an element the host cannot act on (a label, a
+	 * group), which is in the tree for what it says. A host may also give a
+	 * ref to a region it left unexpanded (see {@link UiElement.hiddenChildren});
+	 * that ref is the `root` of a drill-down snapshot, not a target for `uiAct`.
 	 */
 	readonly ref: string
 	/** Platform role, e.g. `Button`, `Edit`, `ListItem` (UIA ControlType) or `AXButton`. */
@@ -248,6 +261,12 @@ export interface UiElement {
 	readonly states?: readonly string[]
 	readonly actions?: readonly UiElementAction[]
 	readonly children?: readonly UiElement[]
+	/**
+	 * How many children of this element the host left out of the snapshot to
+	 * keep it short. Read them with a snapshot whose {@link UiSnapshotOptions.root}
+	 * is this element's ref.
+	 */
+	readonly hiddenChildren?: number
 }
 
 /**
@@ -264,8 +283,41 @@ export interface UiSnapshot {
 	readonly root: UiElement
 	/** True when the host stopped walking the tree before it ended (a size or time bound). */
 	readonly truncated?: boolean
+	/**
+	 * True when the tree is an outline of a larger one: regions carry
+	 * {@link UiElement.hiddenChildren} and can be opened with
+	 * {@link UiSnapshotOptions.root}.
+	 */
+	readonly outline?: boolean
+	/** How many controls the whole window holds, when the host knows. */
+	readonly total?: number
+	/** True when this snapshot is one region of the window (it was asked for with `root`). */
+	readonly region?: boolean
+	/** For a region listed in pages: the `offset` that reads the page after this one. */
+	readonly next?: number
+}
+
+/**
+ * What a snapshot is asked to read.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export interface UiSnapshotOptions {
+	/** A ref from an earlier snapshot: read only that element's subtree. Refs outside it stay valid. */
+	readonly root?: string
+	/** With `root`: skip this many of the region's children (the page a snapshot reported as `next`). */
+	readonly offset?: number
+	/** Only controls whose text contains this (case-insensitive), with the elements above them. */
+	readonly query?: string
 }
 
+/** Why a ref could not be acted on, as a typed failure. */
+export type UiActFailureCode =
+	/** The control the ref named is gone, or no longer something that can be acted on. */
+	| 'STALE_REF'
+	/** Several controls fit what the ref named; the host did not guess. */
+	| 'AMBIGUOUS_TARGET'
+
 /**
  * What {@link ComputerUseHost.uiAct} did.
  *
@@ -275,6 +327,51 @@ export interface UiActResult {
 	readonly ok: boolean
 	/** Why it did not, in words the model can act on (a stale ref, a disabled element). */
 	readonly detail?: string
+	/** Set when the ref could not be resolved to one control; nothing was sent. */
+	readonly code?: UiActFailureCode
+	/** What is known about the effect. Absent from a host that does not classify. */
+	readonly delivery?: ActionDelivery
+	/** Whether repeating the action blindly is safe. Set together with `delivery`. */
+	readonly retrySafety?: ActionRetrySafety
+	/** The state read back after a stateful action, when the host could read it. */
+	readonly readBack?: {
+		readonly expected?: string
+		readonly observed?: string
+	}
+}
+
+/**
+ * How far an action is known to have taken effect.
+ *
+ * - `delivered_verified`: the host read the state back and it matches.
+ * - `delivered_unverified`: the input was sent (or may have been) and no
+ *   read-back confirmed it. A failed or impossible read-back lands here, never
+ *   in `not_delivered`.
+ * - `not_delivered`: the action was refused before any input, or a read-back
+ *   proved the state did not change.
+ */
+export type ActionDelivery = 'delivered_verified' | 'delivered_unverified' | 'not_delivered'
+
+/**
+ * `safe`: nothing reached the target, so the same action may be repeated.
+ * `unsafe`: the action may have taken effect; inspect before repeating it.
+ */
+export type ActionRetrySafety = 'safe' | 'unsafe'
+
+/**
+ * What a window-scoped input action learned about its own delivery.
+ *
+ * @experimental See {@link ComputerUseHost.executeWindow}.
+ */
+export interface WindowInputResult {
+	readonly delivery: ActionDelivery
+	readonly retrySafety: ActionRetrySafety
+	readonly detail?: string
+	/** What the window read afterwards, when the host verified the input by reading it. */
+	readonly readBack?: {
+		readonly expected?: string
+		readonly observed?: string
+	}
 }
 
 export interface Point {
@@ -294,7 +391,11 @@ export type ComputerUseAction =
 	| { readonly type: 'screenshot' }
 	| { readonly type: 'cursor_position' }
 	| { readonly type: 'mouse_move'; readonly to: Point }
-	| { readonly type: 'mouse_click'; readonly at: Point; readonly button: MouseButton }
+	| {
+			readonly type: 'mouse_click'
+			readonly at: Point
+			readonly button: MouseButton
+	  }
 	| {
 			readonly type: 'mouse_drag'
 			readonly from: Point
@@ -335,7 +436,13 @@ export function assertComputerUseActionType(type: ComputerUseAction['type']): vo
 export type ComputerUseResult =
 	| { readonly type: 'screenshot'; readonly result: ScreenshotResult }
 	| { readonly type: 'cursor_position'; readonly point: Point }
-	| { readonly type: 'ok' }
+	| {
+			readonly type: 'ok'
+			/** Set by a host that can tell more than "the call returned". */
+			readonly delivery?: ActionDelivery
+			readonly retrySafety?: ActionRetrySafety
+			readonly detail?: string
+	  }
 
 /**
  * A state-changing desktop action started, but its subprocess did not report
@@ -370,49 +477,84 @@ export interface ComputerUseHost {
 	 * Points in `action` are physical pixels relative to the display of the
 	 * most recent capture; a `screenshot` result carries that display in
 	 * {@link ScreenshotResult.display}.
+	 *
+	 * Every method that reaches the desktop takes a trailing `signal`: the
+	 * tool call's cancellation (the user interrupted the turn). On abort a host
+	 * stops waiting for the desktop and answers at once. An action that may
+	 * already have been sent answers `delivered_unverified` with `retrySafety:
+	 * 'unsafe'`; one that provably was not answers `not_delivered` with
+	 * `'safe'`. A read throws.
 	 */
-	execute(action: ComputerUseAction): Promise<ComputerUseResult>
+	execute(action: ComputerUseAction, signal?: AbortSignal): Promise<ComputerUseResult>
 
 	/**
 	 * The visible, titled top-level windows, front to back where the platform
 	 * knows the order. Offered to the model only with
 	 * {@link ComputerUseCapabilities.windows}.
 	 */
-	listWindows?(): Promise<readonly WindowInfo[]>
+	listWindows?(signal?: AbortSignal): Promise<readonly WindowInfo[]>
 	/**
 	 * Bring a window to the front, restoring it when minimized. Offered only
 	 * with {@link ComputerUseCapabilities.windows}.
 	 */
-	focusWindow?(id: string): Promise<FocusWindowResult>
+	focusWindow?(id: string, signal?: AbortSignal): Promise<FocusWindowResult>
+	/**
+	 * The model's turn `turnId` is making a tool call. A host that keeps state
+	 * per turn (an Escape stop, refused permissions) starts a new one when the
+	 * id changes.
+	 */
+	beginTurn?(turnId: string): void
+	/**
+	 * The model's turn ended or was interrupted. A host releases anything it
+	 * holds for the turn: a lease on the screen, an input monitor, a window it
+	 * moved forward.
+	 */
+	endTurn?(): void | Promise<void>
 	/** Capture a named window. Never silently replace a failed capture with the desktop. */
-	captureWindow?(id: string): Promise<WindowScreenshotResult>
+	captureWindow?(id: string, signal?: AbortSignal): Promise<WindowScreenshotResult>
 	/**
 	 * Act in the PNG pixel space of `captureId`. The host must verify the
 	 * capture is current and still belongs to the same process/window before
 	 * dispatching input. No implicit fallback to display input is permitted.
 	 */
-	executeWindow?(captureId: string, action: WindowInputAction): Promise<void>
+	// `void` stays in the union: a host that returns nothing (`Promise<void>`) must keep compiling.
+	executeWindow?(
+		captureId: string,
+		action: WindowInputAction,
+		signal?: AbortSignal,
+		// biome-ignore lint/suspicious/noConfusingVoidType: widening an existing `Promise<void>` return
+	): Promise<void | WindowInputResult>
 	/**
 	 * Capture one region of the current display at full physical resolution.
 	 * `rect` is display-relative physical pixels; the result's `width` and
 	 * `height` are the region's. Used by `zoom` when
 	 * {@link ComputerUseCapabilities.regionCapture} is set.
 	 */
-	captureRegion?(rect: Rect): Promise<ScreenshotResult>
+	captureRegion?(rect: Rect, signal?: AbortSignal): Promise<ScreenshotResult>
 	/**
 	 * The accessibility tree of one window, or of the focused window when
-	 * `windowId` is omitted. Offered only with {@link ComputerUseCapabilities.uiTree}.
+	 * `windowId` is omitted. With `options.root` only that element's subtree is
+	 * read. Offered only with {@link ComputerUseCapabilities.uiTree}.
 	 *
 	 * @experimental
 	 */
-	uiSnapshot?(windowId?: string): Promise<UiSnapshot>
+	uiSnapshot?(
+		windowId?: string,
+		options?: UiSnapshotOptions,
+		signal?: AbortSignal,
+	): Promise<UiSnapshot>
 	/**
-	 * Act on an element from the latest {@link uiSnapshot}. `value` is the text
+	 * Act on an element from an earlier {@link uiSnapshot}. `value` is the text
 	 * for `set_value`. Offered only with {@link ComputerUseCapabilities.uiTree}.
 	 *
 	 * @experimental
 	 */
-	uiAct?(ref: string, action: UiElementAction, value?: string): Promise<UiActResult>
+	uiAct?(
+		ref: string,
+		action: UiElementAction,
+		value?: string,
+		signal?: AbortSignal,
+	): Promise<UiActResult>
 
 	initialize?(): Promise<void>
 	dispose?(): Promise<void>

package/src/types/errors/catalog.ts

@@ -164,6 +164,12 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		message: 'The provider rejected the credentials for this turn.',
 		hint: 'Check that the API key is set, is not expired, and belongs to the account the model is billed to. Retrying will not help until it changes.',
 	},
+	{
+		id: 'provider.usage_limit',
+		when: (facts) => facts.code === 'usage_limit',
+		message: 'The account has used up its allowance until the limit resets.',
+		hint: 'Waiting inside this turn cannot help. Continue on another account or provider, or resume after the reset time the provider reported.',
+	},
 	{
 		id: 'provider.rate_limit',
 		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,

package/src/types/plugin/index.ts

@@ -549,6 +549,10 @@ export interface PluginManifest {
 	 * owns delegation, not by the runtime.
 	 */
 	readonly agents?: readonly string[]
+	/** Operating systems the plugin supports, as `process.platform` names them. Absent means all. */
+	readonly platforms?: readonly string[]
+	/** Runtime versions the plugin supports. Absent means any. */
+	readonly engines?: { readonly namzu?: string }
 }
 
 export const PluginMCPServerConfigSchema = z
@@ -589,6 +593,10 @@ export const PluginManifestSchema = z.object({
 	personas: z.array(z.string()).max(MAX_PERSONAS_PER_PLUGIN).optional(),
 	commands: z.array(PluginRelativeDirSchema).max(MAX_COMMAND_DIRS_PER_PLUGIN).optional(),
 	agents: z.array(PluginRelativeDirSchema).max(MAX_AGENT_DIRS_PER_PLUGIN).optional(),
+	/** Operating systems the plugin supports, as `process.platform` names them. Absent means all. */
+	platforms: z.array(z.string().min(1)).max(16).optional(),
+	/** Runtime versions the plugin supports. Absent means any. */
+	engines: z.object({ namzu: z.string().min(1).max(200).optional() }).optional(),
 })
 
 // ---------------------------------------------------------------------------

package/src/types/provider/errors.ts

@@ -15,6 +15,12 @@
 export type ProviderErrorCode =
 	/** 429. Back off; honour `retryAfterMs` when the server sent one. */
 	| 'rate_limit'
+	/**
+	 * The account's usage allowance is spent until a later reset, as opposed to
+	 * a momentary burst limit. Waiting inside this turn cannot help, so it is
+	 * not retried; a host may offer another account instead.
+	 */
+	| 'usage_limit'
 	/** 529 / 503 — the model is up but saturated. Back off. */
 	| 'overloaded'
 	/** Any other 5xx. Back off. */
@@ -487,7 +493,10 @@ const STRUCTURAL_CODES: Readonly<Record<string, ProviderErrorCode>> = {
 	string_above_max_length: 'context_length_exceeded',
 	rate_limit_exceeded: 'rate_limit',
 	rate_limit_error: 'rate_limit',
-	insufficient_quota: 'rate_limit',
+	insufficient_quota: 'usage_limit',
+	usage_limit_reached: 'usage_limit',
+	usage_limit_exceeded: 'usage_limit',
+	billing_error: 'usage_limit',
 	overloaded_error: 'overloaded',
 	content_filter: 'content_filter',
 	content_policy_violation: 'content_filter',
@@ -497,6 +506,24 @@ const STRUCTURAL_CODES: Readonly<Record<string, ProviderErrorCode>> = {
 	model_not_found: 'not_found',
 }
 
+/**
+ * Is this exact provider code, or the provider's own complaint, a spent
+ * allowance? The codes are the vendors' identifiers (`insufficient_quota`,
+ * `usage_limit_reached`, `usage_limit_exceeded`, `billing_error`); the
+ * sentences are the two vendors that word it only in prose: an exhausted
+ * prepaid balance and an exhausted plan allowance.
+ */
+const USAGE_LIMIT_DETAIL: readonly RegExp[] = [
+	/credit balance is too low/i,
+	/exceeded your current quota/i,
+	/usage limit (?:has been )?(?:reached|exceeded)/i,
+]
+
+export function isUsageLimitSignal(code: string | undefined, detail: string | undefined): boolean {
+	if (code !== undefined && STRUCTURAL_CODES[code.toLowerCase()] === 'usage_limit') return true
+	return detail !== undefined && USAGE_LIMIT_DETAIL.some((re) => re.test(detail))
+}
+
 function codeFromStructure(err: unknown): ProviderErrorCode | undefined {
 	for (const link of causeChain(err)) {
 		for (const field of [link.code, link.type, (link.error as { type?: unknown })?.type]) {
@@ -556,6 +583,8 @@ function classifyFromProviderRequestError(
 	const candidate = err as Error & {
 		kind?: unknown
 		providerId?: unknown
+		providerCode?: unknown
+		detail?: unknown
 		status?: unknown
 		retryAfterMs?: unknown
 		shouldRetry?: unknown
@@ -563,15 +592,23 @@ function classifyFromProviderRequestError(
 	if (typeof candidate.kind !== 'string') return undefined
 	const mapped = KIND_TO_CODE[candidate.kind]
 	if (!mapped) return undefined
+	// A throttle or an invalid request that says the allowance is spent is not
+	// a burst limit: resending the same request cannot succeed.
+	const spent =
+		(candidate.kind === 'throttle' || candidate.kind === 'bad_request') &&
+		isUsageLimitSignal(
+			typeof candidate.providerCode === 'string' ? candidate.providerCode : undefined,
+			typeof candidate.detail === 'string' ? candidate.detail : undefined,
+		)
 
 	const retryAfterMs =
 		typeof candidate.retryAfterMs === 'number' ? candidate.retryAfterMs : readRetryAfterMs(err, now)
 
 	return new ProviderError({
-		code: mapped.code,
+		code: spent ? 'usage_limit' : mapped.code,
 		message: err.message,
 		// The provider saying "do not resend" beats the kind's own verdict.
-		retryable: candidate.shouldRetry === false ? false : mapped.retryable,
+		retryable: spent || candidate.shouldRetry === false ? false : mapped.retryable,
 		cause: err,
 		...(typeof candidate.providerId === 'string'
 			? { providerId: candidate.providerId }

package/src/types/sandbox/index.ts

@@ -89,6 +89,18 @@ export function assertSandboxEnvironment(env: SandboxEnvironment): void {
 // Exec result
 // ---------------------------------------------------------------------------
 
+/**
+ * A backend's reading of why a non-zero result is not simply "the command
+ * failed". Inference from the error text, never proof.
+ *
+ * - `denial`: the sandbox appears to have refused a file access.
+ * - `runner-failure`: the launcher failed before the command ran.
+ */
+export interface SandboxExecAttribution {
+	readonly kind: 'denial' | 'runner-failure'
+	readonly message: string
+}
+
 export interface SandboxExecResult {
 	readonly exitCode: number
 	readonly stdout: string
@@ -107,6 +119,8 @@ export interface SandboxExecResult {
 	 */
 	readonly stdoutTruncated?: boolean
 	readonly stderrTruncated?: boolean
+	/** Set when a non-zero exit looks like a sandbox denial or a launcher failure. */
+	readonly attribution?: SandboxExecAttribution
 }
 
 // ---------------------------------------------------------------------------
@@ -189,10 +203,35 @@ export interface SandboxWalkFilesOptions {
 	readonly maxDepth?: number
 	/** Positive safe integer bounding emitted matching files. */
 	readonly maxEntries: number
-	/** Positive safe integer bounding examined directory entries; defaults to 20,000. */
+	/**
+	 * Positive safe integer bounding examined directory entries; defaults to
+	 * 500,000. Reaching it ends the walk with the entries found so far (see
+	 * {@link SandboxWalkSummary.stopped}) unless `failOnLimit` is set.
+	 */
 	readonly maxVisitedEntries?: number
 	/** Match hidden names through wildcards; explicit dotfile patterns always work. Defaults to false. */
 	readonly includeHidden?: boolean
+	/**
+	 * Skip files and directories matched by `.gitignore`, `.ignore` and
+	 * `.git/info/exclude` (the first only inside a git repository), and never
+	 * descend into version-control directories. The root itself is never
+	 * skipped. Defaults to true; pass false to walk ignored trees too.
+	 */
+	readonly respectIgnore?: boolean
+	/** Throw an error with code `ERR_FILE_WALK_LIMIT` at `maxVisitedEntries` instead of ending. Defaults to false. */
+	readonly failOnLimit?: boolean
+	/** Called once when the walk ends, with how it ended. A walker that cannot report omits the call. */
+	readonly onSummary?: (summary: SandboxWalkSummary) => void
+}
+
+/** How a bounded walk ended. */
+export interface SandboxWalkSummary {
+	/** Directory entries examined. */
+	readonly visited: number
+	/** Directories skipped because an ignore rule matched them. */
+	readonly ignoredDirectories: number
+	/** Present when the walk ended at its entry bound, so the entries are not the whole tree. */
+	readonly stopped?: 'entry-limit'
 }
 
 // ---------------------------------------------------------------------------

package/src/types/session/records.ts

@@ -278,7 +278,9 @@ export const TurnSettlementSchema = z
 const completedSettlement = TurnSettlementSchema.extend({
 	status: z.enum(['completed', 'cancelled']),
 })
-const failedSettlement = TurnSettlementSchema.extend({ status: z.literal('failed') })
+const failedSettlement = TurnSettlementSchema.extend({
+	status: z.literal('failed'),
+})
 
 /** A body too large for one record, written (and fsynced) to `tool-results/` before the record. */
 const spill = z
@@ -576,6 +578,19 @@ export const BudgetBoundRecordSchema = inTurn('budget_bound', {
 	accountId: text.min(1),
 })
 
+/**
+ * The account a session's provider calls run under. Written when a session is
+ * bound to an account other than the provider's `default`, and again on each
+ * switch; never inside an open turn's work, only between turns. Replay reads
+ * the last one. A build that predates this record refuses a log holding it, so
+ * a session that never leaves the default account never writes one.
+ */
+export const AccountBoundRecordSchema = recordSchema('account_bound', {
+	accountId: text.min(1),
+	provider: text.min(1),
+	reason: z.enum(['start', 'user_switch', 'limit_switch']),
+})
+
 export const LogRepairedRecordSchema = recordSchema('log_repaired', {
 	truncatedBytes: positive,
 	lastGoodSeq: positive,
@@ -612,6 +627,7 @@ const RECORD_ONLY_SCHEMAS = {
 	child_session_ended: ChildSessionEndedRecordSchema,
 	audit: AuditRecordSchema,
 	budget_bound: BudgetBoundRecordSchema,
+	account_bound: AccountBoundRecordSchema,
 	log_repaired: LogRepairedRecordSchema,
 } as const
 
@@ -784,6 +800,36 @@ const RECORD_OPTIONS = [
 	...z.ZodDiscriminatedUnionOption<'type'>[],
 ]
 
+/**
+ * A record of a type this reader does not know, written by a newer writer
+ * that flagged it `ignorable: true`: a promise that no reader needs it to
+ * rebuild the conversation. It is kept in the hash chain and verified like any
+ * other record, but never moves the fold. A known type never qualifies (its
+ * own schema decides), and an unknown type without the flag is still refused,
+ * so a record that does move the fold fails loudly on an older reader.
+ */
+export const IgnorableRecordSchema = z
+	.object({
+		...envelopeShape,
+		type: z
+			.string()
+			.min(1)
+			.refine((type) => !(SESSION_RECORD_TYPES as readonly string[]).includes(type), {
+				message: 'a type this reader knows is validated by its own schema',
+			}),
+		ignorable: z.literal(true),
+	})
+	.passthrough()
+	.superRefine((record, context) => {
+		if (record.seq === 1 || record.prev === null) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['type'],
+				message: 'session_started is the first record of a session log, and only the first',
+			})
+		}
+	})
+
 /** Validates one session record: envelope, discriminant, and every specified payload. */
 export const SessionRecordSchema = z
 	.discriminatedUnion('type', RECORD_OPTIONS)
@@ -959,7 +1005,9 @@ export type SessionEventRecord<T extends PersistedSessionEventType = PersistedSe
 		? Omit<EventOf<T>, 'sessionId' | 'turnId' | 'lineage' | 'v' | 'seq' | 'generation'> &
 				RecordEnvelope &
 				(T extends 'tool_completed'
-					? { readonly structuredResultSpill?: z.infer<typeof structuredResultSpill> }
+					? {
+							readonly structuredResultSpill?: z.infer<typeof structuredResultSpill>
+						}
 					: T extends 'turn_completed'
 						? {
 								readonly resultSpill?: z.infer<typeof spill>
@@ -982,6 +1030,7 @@ export type CompactionRecord = z.infer<typeof CompactionRecordSchema>
 export type ChildSessionEndedRecord = z.infer<typeof ChildSessionEndedRecordSchema>
 export type AuditRecord = z.infer<typeof AuditRecordSchema>
 export type BudgetBoundRecord = z.infer<typeof BudgetBoundRecordSchema>
+export type AccountBoundRecord = z.infer<typeof AccountBoundRecordSchema>
 export type LogRepairedRecord = z.infer<typeof LogRepairedRecordSchema>
 
 export type SessionRecordOnly =
@@ -998,6 +1047,7 @@ export type SessionRecordOnly =
 	| ChildSessionEndedRecord
 	| AuditRecord
 	| BudgetBoundRecord
+	| AccountBoundRecord
 	| LogRepairedRecord
 
 /** One line of a session log. */