@namzu/sdk 59.0.0 → 60.1.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/turn/reporter.ts

@@ -422,6 +422,18 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 				})
 				break
 
+			case 'model_refusal':
+				log.warn('Model declined to answer', {
+					[NAMZU.TURN_ID]: event.turnId,
+					[NAMZU.ITERATION]: event.iteration,
+					'namzu.turn.from_model': event.model,
+					'namzu.turn.from_provider_id': event.providerId,
+					'namzu.turn.outcome': event.outcome,
+					'namzu.turn.to_model': event.fallbackModel,
+					'namzu.turn.category': event.category,
+				})
+				break
+
 			case 'provider_fallback':
 				// `warn` for the same reason as a retry, and one stronger: the rest
 				// of this turn is being served by a provider the caller did not pick.

package/src/types/agent/query.ts

@@ -98,6 +98,8 @@ export interface QueryAgentConfig extends BaseAgentConfig {
 	maxToolConcurrency?: number
 	/** See {@link QueryParams.maxOutputContinuations}. */
 	maxOutputContinuations?: QueryParams['maxOutputContinuations']
+	/** See {@link QueryParams.refusalFallback}. */
+	refusalFallback?: QueryParams['refusalFallback']
 	maxToolOutputChars?: number
 	maxToolOutputCharsPerMessage?: number
 	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']

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/message/index.ts

@@ -367,6 +367,7 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'peer-notice',
 	'reminder',
 	'repeat-call',
+	'refusal-retry',
 	'steering',
 	'step-context',
 	'structured-output',
@@ -695,9 +696,10 @@ export function createTurnContextEntry(
 }
 
 /** The key a recorded context entry is filed under, or undefined for any other message. */
-export function turnContextKey(message: { readonly role: string; readonly source?: unknown }):
-	| string
-	| undefined {
+export function turnContextKey(message: {
+	readonly role: string
+	readonly source?: unknown
+}): string | undefined {
 	if (message.role !== 'user') return undefined
 	const source = message.source as RuntimeContextMessageSource | undefined
 	return source?.type === 'runtime-context' && source.kind === 'turn-context'

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/chat.ts

@@ -184,6 +184,24 @@ export type ReasoningEffort =
 	| 'max'
 	| 'ultra'
 
+/**
+ * What a provider says about a reply it declined to give.
+ *
+ * Carried beside `finishReason: 'content_filter'` and set whenever the finish
+ * was a refusal or a safety block, so a host can tell a model that declined
+ * from a reply that was merely empty. Every field is optional because
+ * providers differ in what they report and several report a refusal with no
+ * detail at all: an empty object means "refused, nothing more is known".
+ */
+export interface ProviderRefusal {
+	/** The provider's own classification of why, when it gives one (for example `cyber`). */
+	category?: string
+	/** The provider's own sentence about the refusal. Show it; do not parse it. */
+	explanation?: string
+	/** A model the provider says can usually serve the request instead. */
+	recommendedModel?: string
+}
+
 export interface ChatCompletionResponse {
 	id: string
 	model: string
@@ -206,5 +224,7 @@ export interface ChatCompletionResponse {
 	 * window rather than the output token limit; see `StreamChunk.finishDetail`.
 	 */
 	finishDetail?: 'context_window'
+	/** Set with `finishReason: 'content_filter'` when the provider declined to answer. */
+	refusal?: ProviderRefusal
 	usage: TokenUsage
 }

package/src/types/provider/config.ts

@@ -72,6 +72,8 @@ export interface MockTurn {
 	/** Passages this scripted turn cites, emitted before its text. */
 	citations?: import('../message/index.js').Citation[]
 	finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/** What the provider says about a `'content_filter'` finish. Defaults to `{}`. */
+	refusal?: import('./chat.js').ProviderRefusal
 	usage?: Partial<import('../common/index.js').TokenUsage>
 	/** Text fragment size. */
 	chunkSize?: number
@@ -106,6 +108,11 @@ export interface MockScript {
 	 * registry-level declaration cannot express "a driver with no vision".
 	 */
 	capabilities?: ProviderCapabilities
+	/**
+	 * The model this provider names when asked where to re-run a refused
+	 * request (`LLMProvider.refusalFallbackFor`). Absent means it names none.
+	 */
+	refusalFallbackModel?: string
 	/** Observe every request (assert on tools, toolChoice, cacheControl…). */
 	onRequest?: (params: import('./chat.js').ChatCompletionParams) => void
 }

package/src/types/provider/index.ts

@@ -4,6 +4,7 @@ export type {
 	CacheControl,
 	ChatCompletionParams,
 	ChatCompletionResponse,
+	ProviderRefusal,
 	ReasoningEffort,
 	ThinkingConfig,
 } from './chat.js'

package/src/types/provider/interface.ts

@@ -236,4 +236,24 @@ export interface LLMProvider {
 	 * run that would otherwise work.
 	 */
 	resolveContextWindow?(model: string, signal?: AbortSignal): Promise<number | undefined>
+
+	/**
+	 * The model to re-run a refused request on, when this provider has one.
+	 *
+	 * Called after `model` declined to answer (`finishReason: 'content_filter'`),
+	 * with whatever the provider said about it. Answer with a different model
+	 * this provider and this credential can actually use, or `undefined` when
+	 * there is none: the turn then does not change model. A driver whose
+	 * service names a recommended model in `refusal.recommendedModel` should
+	 * use it only after checking it is one this account can serve, and falls
+	 * back to its own declared order otherwise.
+	 *
+	 * Optional. A provider without it never has its model swapped on a
+	 * refusal. A request that failed for any other reason does not call this.
+	 */
+	refusalFallbackFor?(
+		model: string,
+		refusal: import('./chat.js').ProviderRefusal,
+		signal?: AbortSignal,
+	): Promise<string | undefined>
 }

package/src/types/provider/stream.ts

@@ -132,6 +132,12 @@ export interface StreamChunk {
 	 * room to continue into. Set only with `finishReason: 'length'`.
 	 */
 	finishDetail?: 'context_window'
+	/**
+	 * The provider declined to answer. Set with `finishReason: 'content_filter'`
+	 * by every driver whose finish was a refusal or a safety block; an empty
+	 * object when the provider gave no detail.
+	 */
+	refusal?: import('./chat.js').ProviderRefusal
 	usage?: TokenUsage
 	error?: string
 

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'
 }
 
 // ---------------------------------------------------------------------------