@namzu/sdk 45.1.0 → 46.0.0

package/src/tools/schedules/schedule-tool.ts

@@ -7,7 +7,9 @@ import { scanSchedulePrompt } from './prompt-scan.js'
 import type {
 	ScheduleBrowserGrant,
 	ScheduleBrowserSiteLevel,
+	ScheduleJobChanges,
 	ScheduleJobDraft,
+	ScheduleJobUpdateProposal,
 	ScheduleToolHost,
 } from './types.js'
 
@@ -15,7 +17,8 @@ export const SCHEDULE_TOOL_NAME = 'schedule'
 
 /**
  * A person reads the whole proposal — the prompt, the rules, the schedule,
- * the credential source — before answering `create`, `resume` or `delete`.
+ * the credential source — before answering `create`, `update`, `resume` or
+ * `delete`.
  * The executor's `DEFAULT_TOOL_TIMEOUT_MS` (two minutes) is sized for a tool
  * call, not a person on the other end of a screen, and would abandon the
  * call out from under them mid-read. `save_skill`
@@ -30,18 +33,25 @@ const BROWSER_PROFILE = /^[a-z0-9][a-z0-9-]{0,62}$/
 
 const inputSchema = z.object({
 	action: z
-		.enum(['create', 'list', 'pause', 'resume', 'delete'])
-		.describe('What to do. create, resume and delete ask the operator first.'),
+		.enum(['create', 'list', 'update', 'pause', 'resume', 'delete'])
+		.describe(
+			'What to do. create, update, resume and delete ask the operator first. To change a job, update it: deleting and creating it again loses its history.',
+		),
 	name: z
 		.string()
 		.regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
 		.optional()
 		.describe('create: job name, lowercase letters, digits and dashes'),
-	prompt: z.string().min(1).max(20_000).optional().describe('create: what the run is asked to do'),
+	prompt: z
+		.string()
+		.min(1)
+		.max(20_000)
+		.optional()
+		.describe('create, update: what the run is asked to do'),
 	when: z
 		.string()
 		.optional()
-		.describe('create: "every 30m", "0 9 * * 1-5" (cron), "at 2026-09-24 09:00", "in 2h"'),
+		.describe('create, update: "every 30m", "0 9 * * 1-5" (cron), "at 2026-09-24 09:00", "in 2h"'),
 	folder: z
 		.string()
 		.optional()
@@ -90,7 +100,9 @@ const inputSchema = z.object({
 				.describe('Browser access; omit for none'),
 		})
 		.optional()
-		.describe('create: REQUIRED explicit permission set; there is no default'),
+		.describe(
+			'create: REQUIRED explicit permission set; there is no default. update: the whole new set, only when the permissions change',
+		),
 	budget: z
 		.object({
 			maxIterations: z
@@ -118,7 +130,7 @@ const inputSchema = z.object({
 		})
 		.optional()
 		.describe('Limits of ONE run; omit to use the defaults'),
-	job: z.string().optional().describe('pause/resume/delete: job name'),
+	job: z.string().optional().describe('update/pause/resume/delete: job name'),
 	allFolders: z.boolean().optional().describe('list: include jobs of other folders (names only)'),
 })
 
@@ -208,6 +220,27 @@ function browserGrant(
 	}
 }
 
+/** A proposed permission set as a draft carries it, or why it is refused. */
+function checkPermissions(
+	host: ScheduleToolHost,
+	proposed: NonNullable<Input['permissions']>,
+): { ok: true; permissions: ScheduleJobDraft['permissions'] } | { ok: false; error: string } {
+	if (!proposed.preset && !proposed.rules && !proposed.browser) {
+		return {
+			ok: false,
+			error:
+				'permissions needs a preset, rules or a browser grant; an empty permission set is not a choice.',
+		}
+	}
+	if (!proposed.browser) return { ok: true, permissions: proposed }
+	const grant = browserGrant(host, proposed.browser)
+	if (!grant.ok) return grant
+	return { ok: true, permissions: { ...proposed, browser: grant.grant } }
+}
+
+const NETWORK_WITH_HOST_SHELL =
+	'A scheduled job proposed here cannot combine web or browser access with a shell on the host. Deny bash, use execution "sandbox", or ask the operator to create it with `namzu schedule add`.'
+
 async function create(
 	host: ScheduleToolHost,
 	input: Input,
@@ -221,18 +254,9 @@ async function create(
 			`create needs ${missing.join(', ')}. permissions is required: propose an explicit set (a preset and/or rules, plus unmatched).`,
 		)
 	}
-	const proposed = input.permissions as NonNullable<Input['permissions']>
-	if (!proposed.preset && !proposed.rules && !proposed.browser) {
-		return refuse(
-			'permissions needs a preset, rules or a browser grant; an empty permission set is not a choice.',
-		)
-	}
-	let permissions: ScheduleJobDraft['permissions'] = proposed
-	if (proposed.browser) {
-		const grant = browserGrant(host, proposed.browser)
-		if (!grant.ok) return refuse(grant.error)
-		permissions = { ...proposed, browser: grant.grant }
-	}
+	const checked = checkPermissions(host, input.permissions as NonNullable<Input['permissions']>)
+	if (!checked.ok) return refuse(checked.error)
+	const permissions = checked.permissions
 	const draft: ScheduleJobDraft = {
 		name: input.name as string,
 		prompt: input.prompt as string,
@@ -242,11 +266,7 @@ async function create(
 		permissions,
 		...(input.budget ? { budget: input.budget } : {}),
 	}
-	if (networkWithHostShell(draft)) {
-		return refuse(
-			'A scheduled job proposed here cannot combine web or browser access with a shell on the host. Deny bash, use execution "sandbox", or ask the operator to create it with `namzu schedule add`.',
-		)
-	}
+	if (networkWithHostShell(draft)) return refuse(NETWORK_WITH_HOST_SHELL)
 	let preview: Awaited<ReturnType<ScheduleToolHost['preview']>>
 	try {
 		preview = await host.preview(draft)
@@ -295,11 +315,94 @@ async function list(host: ScheduleToolHost, input: Input): Promise<ToolResult> {
 	if (jobs.length === 0) return { success: true, output: 'No scheduled jobs.', data: { jobs: [] } }
 	const lines = jobs.map(
 		(j) =>
-			`${j.name} · ${j.state} · ${j.schedule}${j.nextFireAt ? ` · next ${j.nextFireAt}` : ''}${j.lastStatus ? ` · last ${j.lastStatus}` : ''} · ${j.folder}`,
+			`${j.name} · ${j.state} · ${j.schedule}${j.nextFireAt ? ` · next ${j.nextFireAt}` : ''}${j.lastStatus ? ` · last ${j.lastStatus}` : ''} · ${j.folder}${j.inSessionFolder ? ' (this folder)' : ''}`,
 	)
 	return { success: true, output: lines.join('\n'), data: { jobs } }
 }
 
+/** The fields `update` may change, as the model set them. */
+const CHANGEABLE = ['prompt', 'when', 'folder', 'tz', 'permissions', 'budget'] as const
+
+async function update(
+	host: ScheduleToolHost,
+	input: Input,
+	signal: AbortSignal | undefined,
+): Promise<ToolResult> {
+	if (!host.previewUpdate || !host.confirmUpdate || !host.update) {
+		return refuse(
+			'This host cannot change a scheduled job. Ask the operator to change it themselves; do not delete and create it again, which loses its history.',
+		)
+	}
+	if (!input.job) return refuse("update needs job (the job's name) and the fields to change.")
+	if (input.name !== undefined) {
+		return refuse(
+			'update cannot rename a job: name the job to change with job, and leave name out.',
+		)
+	}
+	const given = CHANGEABLE.filter((k) => input[k] !== undefined)
+	if (given.length === 0) {
+		return refuse(`update needs at least one of ${CHANGEABLE.join(', ')} to change.`)
+	}
+	let permissions: ScheduleJobDraft['permissions'] | undefined
+	if (input.permissions) {
+		const checked = checkPermissions(host, input.permissions)
+		if (!checked.ok) return refuse(checked.error)
+		permissions = checked.permissions
+		if (networkWithHostShell({ name: '', prompt: '', when: '', permissions }))
+			return refuse(NETWORK_WITH_HOST_SHELL)
+	}
+	const changes: ScheduleJobChanges = {
+		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+		...(input.when !== undefined ? { when: input.when } : {}),
+		...(input.folder !== undefined ? { folder: input.folder } : {}),
+		...(input.tz !== undefined ? { tz: input.tz } : {}),
+		...(permissions ? { permissions } : {}),
+		...(input.budget ? { budget: input.budget } : {}),
+	}
+	let proposal: ScheduleJobUpdateProposal
+	try {
+		proposal = await host.previewUpdate(input.job, changes)
+	} catch (error) {
+		return refuse(error instanceof Error ? error.message : String(error))
+	}
+	let confirmed = false
+	try {
+		confirmed = await host.confirmUpdate(
+			{
+				...proposal,
+				promptFindings: scanSchedulePrompt(proposal.preview.prompt),
+				proposedBy: 'model',
+			},
+			signal,
+		)
+	} catch {
+		confirmed = false
+	}
+	// As for `create`: never save on an answer that came after the
+	// operator was no longer being asked.
+	if (signal?.aborted) confirmed = false
+	if (!confirmed) {
+		return {
+			...refuse(
+				`The operator did not confirm the change; "${proposal.preview.name}" was not changed.`,
+			),
+			data: { cancelled: true },
+		}
+	}
+	let saved: Awaited<ReturnType<NonNullable<ScheduleToolHost['update']>>>
+	try {
+		saved = await host.update(proposal.preview)
+	} catch (error) {
+		return refuse(error instanceof Error ? error.message : String(error))
+	}
+	const said = `Job "${saved.name}" was updated in place and keeps its history. It runs ${proposal.preview.schedule}.`
+	return {
+		success: true,
+		output: saved.note ? `${said} ${saved.note}` : said,
+		data: { name: saved.name, updated: true, changes: proposal.changes },
+	}
+}
+
 async function lifecycle(
 	host: ScheduleToolHost,
 	input: Input,
@@ -331,12 +434,13 @@ async function lifecycle(
 }
 
 /**
- * The `schedule` tool: create, list, pause, resume and delete the operator's
- * scheduled jobs from a conversation.
+ * The `schedule` tool: create, list, update, pause, resume and delete the
+ * operator's scheduled jobs from a conversation.
  *
- * Creation, resuming and deleting are confirmed by a person through the host
- * (`ScheduleToolHost.confirm`), on a screen the host draws from its own
- * computation. The model cannot propose that uncovered calls run without
+ * Creation, updating, resuming and deleting are confirmed by a person
+ * through the host (`ScheduleToolHost.confirm`, `confirmUpdate`), on a
+ * screen the host draws from its own computation. An update changes the
+ * job in place, so it keeps its id and its history. The model cannot propose that uncovered calls run without
  * asking, nor web access beside a host shell. Register it only where a person
  * is present to confirm: never in a headless run, a scheduled run or a
  * sub-agent.
@@ -346,7 +450,7 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 		defineTool({
 			name: SCHEDULE_TOOL_NAME,
 			description:
-				"Manage the operator's scheduled jobs: prompts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, resume and delete are confirmed by the operator; pause is not. A job needs name, prompt, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). Leave every other field (folder, tz, execution, budget, headed) unset unless the user asked for it: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
+				"Manage the operator's scheduled jobs: prompts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, update, resume and delete are confirmed by the operator; pause is not. A job needs name, prompt, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave every other field (folder, tz, execution, budget, headed) unset unless the user asked for it: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
 			inputSchema,
 			category: 'custom',
 			permissions: [],
@@ -358,8 +462,8 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 			concurrencySafe: false,
 			presentCall: presentScheduleCall,
 			presentResult: presentScheduleResult,
-			// A person, not a tool, answers `create`/`resume`/`delete`; see
-			// `OPERATOR_CONFIRM_TIMEOUT_MS`.
+			// A person, not a tool, answers `create`/`update`/`resume`/`delete`;
+			// see `OPERATOR_CONFIRM_TIMEOUT_MS`.
 			timeoutMs: OPERATOR_CONFIRM_TIMEOUT_MS,
 			async execute(input, context: ToolContext) {
 				switch (input.action) {
@@ -367,6 +471,8 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 						return create(host, input, context.abortSignal)
 					case 'list':
 						return list(host, input)
+					case 'update':
+						return update(host, input, context.abortSignal)
 					default:
 						return lifecycle(host, input, input.action, context.abortSignal)
 				}

package/src/tools/schedules/types.ts

@@ -114,6 +114,48 @@ export interface ScheduleJobSummary {
 	readonly lastStatus?: string
 	/** Present only for jobs in the session's own folder. */
 	readonly prompt?: string
+	/**
+	 * True for a job whose folder is the session's own. A host that lists
+	 * other folders' jobs sets it so the model can tell them apart; the tool
+	 * marks such a job `(this folder)`.
+	 */
+	readonly inSessionFolder?: boolean
+}
+
+/**
+ * What the model proposes to change in an existing job. Every field left
+ * out keeps the job's current value. `permissions`, when given, is the whole
+ * new set, with the same limits as a new job's; the host keeps the job's
+ * `execution` when it is not given, and its additional directories.
+ */
+export interface ScheduleJobChanges {
+	readonly prompt?: string
+	readonly when?: string
+	readonly folder?: string
+	readonly tz?: string
+	readonly permissions?: ScheduleJobDraft['permissions']
+	readonly budget?: ScheduleJobDraft['budget']
+}
+
+/** A proposed change to a job, as the host computed it. */
+export interface ScheduleJobUpdateProposal {
+	/** The job as it would be once changed. Every field is the host's own computation. */
+	readonly preview: ScheduleJobPreview
+	/**
+	 * What differs from the job as it stands (and from edits saved since it
+	 * was last confirmed), one line each: `- ` what goes, `+ ` what comes.
+	 */
+	readonly changes: readonly string[]
+	/** The change touches what a run may do: its rules, `unmatched`, where it runs, its browser grant. */
+	readonly permissionsChange: boolean
+}
+
+/** What the person confirming a change is shown. */
+export interface ScheduleUpdateRequest extends ScheduleJobUpdateProposal {
+	/** The prompt tripwire's findings over `preview.prompt`. */
+	readonly promptFindings: readonly string[]
+	/** Always `model` from this tool. */
+	readonly proposedBy: 'model'
 }
 
 /** What the person answered to a proposed job. */
@@ -157,7 +199,14 @@ export interface ScheduleToolHost {
 		preview: ScheduleJobPreview,
 		options: { readonly paused: boolean },
 	): Promise<{ readonly name: string; readonly note?: string }>
-	/** Jobs, the session folder's in full, other folders' without their prompts. */
+	/**
+	 * Jobs, the session folder's in full, other folders' without their
+	 * prompts. `allFolders: false` lets a host list only the session
+	 * folder's; a host may list every job regardless, marking the session
+	 * folder's with {@link ScheduleJobSummary.inSessionFolder}. The tool says
+	 * "No scheduled jobs." when this returns none, so a host that filters
+	 * says so only for its folder.
+	 */
 	list(options: { readonly allFolders: boolean }): Promise<readonly ScheduleJobSummary[]>
 	/** A job by name or id prefix, or undefined. */
 	find(job: string): Promise<ScheduleJobSummary | undefined>
@@ -170,6 +219,25 @@ export interface ScheduleToolHost {
 	pause(job: string): Promise<void>
 	resume(job: string): Promise<void>
 	delete(job: string): Promise<void>
+	/**
+	 * Validate a change to `job` (a name or id prefix) and compute what the
+	 * person will be shown. Throws with a message on a refusal. The tool
+	 * offers `update` only when a host has all three of `previewUpdate`,
+	 * `confirmUpdate` and `update`.
+	 */
+	previewUpdate?(job: string, changes: ScheduleJobChanges): Promise<ScheduleJobUpdateProposal>
+	/**
+	 * Ask the person whether to save the change. Anything but `true` — a
+	 * thrown error, a closed screen — changes nothing. See `confirm` on
+	 * `signal`.
+	 */
+	confirmUpdate?(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<boolean>
+	/**
+	 * Save the change the person confirmed, to the same job: its id and its
+	 * history are kept, and the confirmation is the person's. `note` as for
+	 * `create`.
+	 */
+	update?(preview: ScheduleJobPreview): Promise<{ readonly name: string; readonly note?: string }>
 }
 
 /** A prompt the session re-sends to itself on an interval. */

package/src/types/authorization/index.ts

@@ -115,6 +115,19 @@ export type AuthorizationRule =
 			 */
 			description: string
 			decide: AuthorizationPredicate
+			/**
+			 * The reason for THIS call, when `decide` returned a decision: what
+			 * in the input matched, and where. The gate reports it instead of
+			 * {@link description}. Absent, returning `null` or throwing, the
+			 * gate reports `description`.
+			 *
+			 * A rule that refuses on several grounds and reports one fixed
+			 * sentence leaves the model, and the person reading the refusal,
+			 * to guess which ground it was. A scheduled run's refusal listed
+			 * everything the rule protects when one word of the command had
+			 * matched.
+			 */
+			describe?: (call: AuthorizationPredicateCall) => string | null
 	  }
 
 /** The call an `AuthorizationRule` of type `predicate` is asked about. */
@@ -183,6 +196,14 @@ const PredicateSchema = z.object({
 	decide: z.custom<AuthorizationPredicate>((value) => typeof value === 'function', {
 		message: 'decide must be a function',
 	}),
+	// Named here so the gate's own parse keeps it: zod strips what a schema
+	// does not name.
+	describe: z
+		.custom<(call: AuthorizationPredicateCall) => string | null>(
+			(value) => typeof value === 'function',
+			{ message: 'describe must be a function' },
+		)
+		.optional(),
 })
 
 export const AuthorizationRuleSchema = z.discriminatedUnion('type', [

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

@@ -44,10 +44,41 @@ export interface ComputerUseCapabilities {
 	 * model reads the reason once and does not try again.
 	 */
 	readonly unavailableReason?: string
+	/**
+	 * The host implements {@link ComputerUseHost.listWindows} and
+	 * {@link ComputerUseHost.focusWindow}. Absent or false, the tool does not
+	 * offer `list_windows` or `focus_window`, even when the methods exist.
+	 */
+	readonly windows?: boolean
+	/**
+	 * The host implements {@link ComputerUseHost.captureRegion}. Absent or
+	 * false, `zoom` still works: the tool crops a full capture instead, which
+	 * costs one whole-display capture per zoom.
+	 */
+	readonly regionCapture?: boolean
+	/**
+	 * The host implements {@link ComputerUseHost.uiSnapshot} and
+	 * {@link ComputerUseHost.uiAct}: an accessibility tree (Windows UI
+	 * Automation, macOS AX, AT-SPI, or a driver that wraps one) whose
+	 * elements can be acted on by reference instead of by pixel.
+	 *
+	 * @experimental The UI-tree surface is reserved for the host packages that
+	 * implement it; its shape may still change in a minor release.
+	 */
+	readonly uiTree?: boolean
 }
 
 // ---------------------------------------------------------------------------
 // Geometry + screenshot payload
+//
+// Units, once for the whole file: every coordinate and size a host accepts or
+// returns is in PHYSICAL pixels — the pixels of the captured bitmap, not
+// logical points or DPI-scaled units. A 3440x1440 monitor at 150 % scaling is
+// 3440x1440 here. A point a host is asked to act on is relative to the
+// top-left of the display it last captured (the primary display until a host
+// offers display selection); the host adds that display's origin itself.
+// Window and UI-element bounds are the exception and say so: they are in
+// virtual-desktop physical pixels, because a window can span displays.
 // ---------------------------------------------------------------------------
 
 export interface DisplayGeometry {
@@ -56,11 +87,144 @@ export interface DisplayGeometry {
 	readonly scaleFactor: number
 }
 
+/**
+ * The display a capture shows.
+ *
+ * `x`/`y` place it in the virtual desktop (a monitor left of the primary has
+ * a negative `x`); `width`/`height` are its physical size. `scaleFactor` is
+ * physical pixels per logical pixel — 1 at 96 DPI on Windows, 1.5 at 150 %,
+ * 2 on a Retina panel — reported for the host UI and for diagnosis; the tool
+ * never multiplies by it, because every coordinate crossing this interface
+ * is already physical.
+ */
+export interface DisplayInfo {
+	/** Stable for the host's lifetime; what a host would accept to select this display. */
+	readonly id: string
+	readonly x: number
+	readonly y: number
+	readonly width: number
+	readonly height: number
+	readonly scaleFactor: number
+	/** True for the display the operating system calls primary. */
+	readonly primary?: boolean
+}
+
 export interface ScreenshotResult {
 	readonly data: Buffer
 	readonly mimeType: 'image/png'
+	/** Physical pixel width of `data`. */
 	readonly width: number
+	/** Physical pixel height of `data`. */
 	readonly height: number
+	/**
+	 * The display this capture shows. A host should always set it; one written
+	 * before it existed does not, and the tool then assumes a single display at
+	 * the origin whose size is the capture's own, with a scale factor of 1.
+	 */
+	readonly display?: DisplayInfo
+}
+
+/** A rectangle in physical pixels. What its origin is relative to depends on where it appears. */
+export interface Rect {
+	readonly x: number
+	readonly y: number
+	readonly width: number
+	readonly height: number
+}
+
+/** One top-level window, as {@link ComputerUseHost.listWindows} reports it. */
+export interface WindowInfo {
+	/** Opaque and host-defined (an HWND in hex, a CGWindowID, an X11 window id); valid for {@link ComputerUseHost.focusWindow}. */
+	readonly id: string
+	readonly title: string
+	/** Application or process name, e.g. `msedge`, `Teams`, `Code`. */
+	readonly app: string
+	readonly pid: number
+	/** Virtual-desktop physical pixels — not display-relative. */
+	readonly bounds: Rect
+	readonly focused: boolean
+	readonly minimized: boolean
+}
+
+/**
+ * What {@link ComputerUseHost.focusWindow} achieved. Bringing a window to
+ * the front is a request the operating system can refuse (Windows'
+ * foreground lock is the common case), so a host reports the window that is
+ * actually in front afterwards rather than assuming its request held.
+ */
+export interface FocusWindowResult {
+	/** True only when `focusedId` is the requested window. */
+	readonly ok: boolean
+	/** The window in front after the attempt, or null when none could be read. */
+	readonly focusedId: string | null
+}
+
+/**
+ * An action an accessibility element can take by reference.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export type UiElementAction =
+	| 'invoke'
+	| 'focus'
+	| 'set_value'
+	| 'toggle'
+	| 'select'
+	| 'expand'
+	| 'collapse'
+	| 'scroll_into_view'
+
+/**
+ * One accessibility element.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+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.
+	 */
+	readonly ref: string
+	/** Platform role, e.g. `Button`, `Edit`, `ListItem` (UIA ControlType) or `AXButton`. */
+	readonly role: string
+	readonly name: string
+	readonly value?: string
+	/** A platform automation id, when the element has one. */
+	readonly automationId?: string
+	/** Virtual-desktop physical pixels, when the element is on screen. */
+	readonly bounds?: Rect
+	/** Element states such as `focused`, `disabled`, `selected`, `checked`, `expanded`. */
+	readonly states?: readonly string[]
+	readonly actions?: readonly UiElementAction[]
+	readonly children?: readonly UiElement[]
+}
+
+/**
+ * An accessibility tree for one window.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+export interface UiSnapshot {
+	readonly windowId?: string
+	/** The window's title, as its application sets it. */
+	readonly title?: string
+	/** The owning application or process name, as in {@link WindowInfo.app}. */
+	readonly app?: string
+	readonly root: UiElement
+	/** True when the host stopped walking the tree before it ended (a size or time bound). */
+	readonly truncated?: boolean
+}
+
+/**
+ * What {@link ComputerUseHost.uiAct} did.
+ *
+ * @experimental See {@link ComputerUseCapabilities.uiTree}.
+ */
+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
 }
 
 export interface Point {
@@ -152,8 +316,46 @@ export interface ComputerUseHost {
 	readonly capabilities: ComputerUseCapabilities
 
 	getDisplayGeometry(): Promise<DisplayGeometry>
+	/**
+	 * 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}.
+	 */
 	execute(action: ComputerUseAction): 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[]>
+	/**
+	 * Bring a window to the front, restoring it when minimized. Offered only
+	 * with {@link ComputerUseCapabilities.windows}.
+	 */
+	focusWindow?(id: string): Promise<FocusWindowResult>
+	/**
+	 * 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>
+	/**
+	 * The accessibility tree of one window, or of the focused window when
+	 * `windowId` is omitted. Offered only with {@link ComputerUseCapabilities.uiTree}.
+	 *
+	 * @experimental
+	 */
+	uiSnapshot?(windowId?: string): Promise<UiSnapshot>
+	/**
+	 * Act on an element from the latest {@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>
+
 	initialize?(): Promise<void>
 	dispose?(): Promise<void>
 }

package/src/types/tool/index.ts

@@ -42,6 +42,12 @@ export interface SkillRegistryRef {
 				registeredName: string
 				description: string
 				location: string
+				/**
+				 * The skill's directory as the host reads it. Optional so a registry
+				 * written before it existed still satisfies this interface; what the
+				 * `skill` tool hands a host's `resolveModelDirectory` to map.
+				 */
+				directory?: string
 				allowedTools?: string
 				invocation?: 'model' | 'operator' | 'both'
 		  }[]
@@ -50,6 +56,7 @@ export interface SkillRegistryRef {
 					registeredName: string
 					description: string
 					location: string
+					directory?: string
 					allowedTools?: string
 					invocation?: 'model' | 'operator' | 'both'
 				}[]
@@ -927,6 +934,18 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	isReadOnly?(input: TInput): boolean
 	isDestructive?(input: TInput): boolean
 	isConcurrencySafe?(input: TInput): boolean
+	/**
+	 * This call sends what is on the operator's screen to the model provider:
+	 * a screenshot, the titles of the open windows, a window's accessibility
+	 * tree.
+	 *
+	 * Orthogonal to {@link isReadOnly}: a screenshot changes nothing and is
+	 * still the one read a person may want to allow before it happens. A
+	 * review policy given a consent record (`createReviewHandler`'s
+	 * `screenConsent`) asks once per session before the first such call.
+	 * Absent means the tool never does.
+	 */
+	capturesScreen?(input: TInput): boolean
 
 	/**
 	 * Opt-in ordering boundary in a direct model tool-call batch. Earlier