@namzu/sdk 59.0.0 → 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/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/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
@@ -798,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)
@@ -973,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>

package/src/types/tool/index.ts

@@ -173,6 +173,8 @@ export interface BackgroundJobRegistryRef {
 		status: string
 		exitCode?: number
 		error?: string
+		/** When it last wrote output (epoch ms); absent until it has. */
+		lastOutputAt?: number
 	}
 	/**
 	 * Take over a process the caller already started and is waiting on, so a
@@ -224,7 +226,19 @@ export interface BackgroundJobRegistryRef {
 		kind?: 'monitor'
 		/** What a monitor watches. */
 		description?: string
+		/** When the job started (epoch ms). Optional for hosts that do not keep it. */
+		startedAt?: number
+		/** When it last wrote output (epoch ms); absent until it has. */
+		lastOutputAt?: number
+		/** Its last non-empty output line, flattened and clipped. */
+		lastOutputLine?: string
 	}[]
+	/**
+	 * Whether the job's process is still there, asked of the system rather than
+	 * taken from the record. Optional: a host that cannot probe omits it, and a
+	 * running job is then reported as alive on the registry's word.
+	 */
+	isAlive?(id: string): boolean
 	/**
 	 * 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
@@ -259,6 +273,13 @@ export interface BackgroundJobRegistryRef {
 	 * intent, and then there is simply no hold.
 	 */
 	markAwaited?(id: string): void
+	/**
+	 * Say that this job's exit and output have just been handed to the model by
+	 * a tool result (`wait_for_job` returning the exit, `job` read of a stopped
+	 * job), so the exit notice that would announce the same exit is withdrawn
+	 * instead of repeating it. Optional for the reason `markAwaited` is.
+	 */
+	markCollected?(id: string): void
 }
 
 /**
@@ -514,6 +535,15 @@ export interface ToolContext {
 	 * directory; an absolute path inside any of these is accepted.
 	 */
 	additionalDirectories?: readonly string[]
+	/**
+	 * Whether the session's read rules deny an absolute path. The search tools
+	 * (`grep`, `glob`) call it for every file they would list or open and skip
+	 * a denied one, so a search over a folder holding a denied file succeeds
+	 * without showing or reading it. The executor supplies it from the turn's
+	 * authorization gate (what the `read` tool would be told for that path);
+	 * absent, no rules apply.
+	 */
+	readDenied?: (absolutePath: string) => boolean
 	/**
 	 * Absolute path of the directory holding THIS session's retained tool
 	 * output (the files an oversized result was saved to). The `read` tool may

package/src/types/tool/presentation.ts

@@ -175,6 +175,10 @@ export type ToolFacts =
 			readonly filesMatched?: number
 			readonly filesSearched?: number
 			readonly truncated?: boolean
+			/** A page or result cap cut the list; more results exist. */
+			readonly limited?: boolean
+			/** The search stopped before every file was examined. */
+			readonly incomplete?: boolean
 	  }
 	| {
 			readonly kind: 'list'
@@ -182,6 +186,10 @@ export type ToolFacts =
 			readonly path?: string
 			readonly count?: number
 			readonly truncated?: boolean
+			/** A result cap cut the list; more files match. */
+			readonly limited?: boolean
+			/** The search stopped before every file was examined. */
+			readonly incomplete?: boolean
 	  }
 	| {
 			readonly kind: 'edit'