@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.5

package/src/tools/computer.ts

@@ -5,22 +5,20 @@ import type {
 	AgentToolUpdateCallback,
 	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
-import type { ComputerAction, ComputerSafetyCheck, ComputerToolCallMetadata, Model } from "@oh-my-pi/pi-ai";
+import type { Model } from "@oh-my-pi/pi-ai";
 import { isClaudeModelId } from "@oh-my-pi/pi-catalog/identity";
-import type {
-	DesktopAction,
-	DesktopCapabilities,
-	DesktopCapture,
-	DesktopDisplay,
-	DesktopSessionOptions,
-} from "@oh-my-pi/pi-natives";
-import { once, prompt, sanitizeText } from "@oh-my-pi/pi-utils";
+import type { DesktopCapabilities } from "@oh-my-pi/pi-natives";
+import { once, prompt } from "@oh-my-pi/pi-utils";
 import { type Type, type } from "arktype";
+import { callSessionTool } from "../eval/js/tool-bridge";
 import computerDescription from "../prompts/tools/computer.md" with { type: "text" };
+import { enforceInlineByteCap } from "../session/streaming-output";
 import { truncateForPrompt } from "./approval";
+import type { ComputerScreenshot, ComputerSessionSnapshot } from "./computer/protocol";
 import { type ComputerController, ComputerSupervisor, registerComputerController } from "./computer/supervisor";
 import type { ToolSession } from "./index";
 import { ToolError, throwIfAborted } from "./tool-errors";
+import { clampTimeout } from "./tool-timeouts";
 
 // Image transports that cannot preserve native screenshot detail resize frames
 // without returning transformed dimensions. Keep their native coordinate frames
@@ -41,470 +39,149 @@ function usesCoordinateSafeImageSizing(model: Model | undefined): boolean {
 	);
 }
 
-function captureOptions(session: ToolSession, coordinateSafeImageSizing: boolean): DesktopSessionOptions {
-	const maxWidth = session.settings.get("computer.maxWidth");
-	const maxHeight = session.settings.get("computer.maxHeight");
-	return {
-		backend: session.settings.get("computer.backend"),
-		display: session.settings.get("computer.display"),
-		maxWidth: coordinateSafeImageSizing ? Math.min(maxWidth, COORDINATE_SAFE_MAX_CAPTURE_WIDTH) : maxWidth,
-		maxHeight: coordinateSafeImageSizing ? Math.min(maxHeight, COORDINATE_SAFE_MAX_CAPTURE_HEIGHT) : maxHeight,
-	};
+interface ComputerToolInput {
+	code: string;
+	read_only?: boolean;
+	timeout?: number;
 }
 
-// Desktop actions cross the N-API boundary as i32; out-of-range JS numbers
-// must fail closed here instead of truncating in the napi conversion.
-const INT32_MIN = -2_147_483_648;
-const INT32_MAX = 2_147_483_647;
-
-type ComputerSchemaPoint = {
-	x: number;
-	y: number;
-};
-
-type ComputerSchemaAction = {
-	type: ComputerAction["type"];
-	x?: number;
-	y?: number;
-	button?: "left" | "right" | "wheel" | "back" | "forward";
-	path?: ComputerSchemaPoint[];
-	keys?: string[] | null;
-	scroll_x?: number;
-	scroll_y?: number;
-	text?: string;
-};
-
-export type ComputerParams = {
-	actions?: ComputerSchemaAction[];
-};
-
-type IsSameType<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false;
-type ComputerSchema<Schema extends Type = Type<ComputerParams>> =
-	IsSameType<ComputerParams, Schema["infer"]> extends true ? Schema : never;
+type ComputerSchema = Type<ComputerToolInput>;
 
-const getComputerSchema: () => ComputerSchema = once(() => {
-	const coordinateSchema = type("0 <= number.integer <= 2147483647");
-	const scrollDeltaSchema = type("-2147483648 <= number.integer <= 2147483647");
-
-	const pointSchema = type({
-		x: coordinateSchema.describe("x pixel coordinate"),
-		y: coordinateSchema.describe("y pixel coordinate"),
-		"+": "reject",
-	});
-
-	const computerActionSchema = type({
-		type: type(
-			"'click' | 'double_click' | 'drag' | 'keypress' | 'move' | 'screenshot' | 'scroll' | 'type' | 'wait'",
-		).describe("action kind"),
-		"x?": coordinateSchema.describe(
-			"x pixel coordinate in the most recent screenshot (click, double_click, move, scroll)",
-		),
-		"y?": coordinateSchema.describe(
-			"y pixel coordinate in the most recent screenshot (click, double_click, move, scroll)",
-		),
-		"button?": type("'left' | 'right' | 'wheel' | 'back' | 'forward'").describe("mouse button; required for click"),
-		"path?": pointSchema.array().atLeastLength(2).describe("waypoints from press to release; required for drag"),
-		"keys?": type("string[] | null").describe(
-			"key names (e.g. CTRL, SHIFT, ENTER, A); required chord for keypress, optional held modifiers for pointer actions",
+const getComputerSchema: () => ComputerSchema = once(() =>
+	type({
+		code: type("string").describe(
+			"JavaScript executed in the persistent computer session; top-level await allowed; `desktop`, `wait`, `assert` in scope",
 		),
-		"scroll_x?": scrollDeltaSchema.describe("horizontal scroll delta in pixels; required for scroll"),
-		"scroll_y?": scrollDeltaSchema.describe(
-			"vertical scroll delta in pixels, positive scrolls content down; required for scroll",
+		"read_only?": type("boolean").describe(
+			"true = inspection only: screenshots and ax reads allowed, all input/mutation blocked",
 		),
-		"text?": type("string").describe("literal text to type; required for type"),
+		"timeout?": type("number").describe("run budget in seconds"),
 		"+": "reject",
-	});
-
-	const computerSchema = type({
-		"actions?": computerActionSchema
-			.array()
-			.describe("ordered actions executed as one batch; omit or pass [] to just capture a screenshot"),
-		"+": "reject",
-	});
-	return computerSchema satisfies ComputerSchema<typeof computerSchema>;
-});
+	}),
+);
 
+/** Renderer and artifact metadata produced by a computer tool run. */
 export interface ComputerToolDetails {
-	width: number;
-	height: number;
-	backend: DesktopCapture["backend"];
-	displayServer?: string;
-	capturePermission: string;
-	inputPermission: string;
-	displays: DesktopDisplay[];
-	capabilities?: DesktopCapabilities;
-	actions: ComputerAction["type"][];
-}
-
-export type ComputerControllerFactory = (options: DesktopSessionOptions) => ComputerController;
-
-function isInt32(value: unknown): value is number {
-	return typeof value === "number" && Number.isInteger(value) && value >= INT32_MIN && value <= INT32_MAX;
-}
-
-function isCoordinate(value: unknown): value is number {
-	return isInt32(value) && value >= 0;
-}
-
-type AllowedFields = Record<string, true>;
-
-const POINT_FIELDS: AllowedFields = { x: true, y: true };
-const MOUSE_BUTTONS: AllowedFields = { left: true, right: true, wheel: true, back: true, forward: true };
-const ACTION_FIELDS: Record<ComputerAction["type"], AllowedFields> = {
-	click: { type: true, button: true, x: true, y: true, keys: true },
-	double_click: { type: true, x: true, y: true, keys: true },
-	drag: { type: true, path: true, keys: true },
-	keypress: { type: true, keys: true },
-	move: { type: true, x: true, y: true, keys: true },
-	screenshot: { type: true },
-	scroll: { type: true, x: true, y: true, scroll_x: true, scroll_y: true, keys: true },
-	type: { type: true, text: true },
-	wait: { type: true },
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function fieldsForAction(actionType: string): AllowedFields | undefined {
-	switch (actionType) {
-		case "click":
-		case "double_click":
-		case "drag":
-		case "keypress":
-		case "move":
-		case "screenshot":
-		case "scroll":
-		case "type":
-		case "wait":
-			return ACTION_FIELDS[actionType];
-		default:
-			return undefined;
-	}
-}
-
-function hasOnlyFields(value: Record<string, unknown>, allowed: AllowedFields): boolean {
-	return Object.keys(value).every(key => allowed[key] === true);
-}
-
-function isPoint(value: unknown): value is { x: number; y: number } {
-	return isRecord(value) && hasOnlyFields(value, POINT_FIELDS) && isCoordinate(value.x) && isCoordinate(value.y);
-}
-
-function isStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.every(item => typeof item === "string");
-}
-
-function modifierBit(value: string): number {
-	switch (value.trim().toUpperCase()) {
-		case "CTRL":
-		case "CONTROL":
-			return 1;
-		case "SHIFT":
-			return 2;
-		case "ALT":
-		case "OPTION":
-			return 4;
-		case "META":
-		case "CMD":
-		case "COMMAND":
-		case "SUPER":
-		case "WINDOWS":
-			return 8;
-		default:
-			return 0;
-	}
-}
-
-function isModifierArray(value: unknown): value is string[] | null | undefined {
-	if (value == null) return true;
-	if (!isStringArray(value)) return false;
-	let seen = 0;
-	for (const entry of value) {
-		for (const component of entry.split("+")) {
-			const bit = modifierBit(component);
-			if (bit === 0 || (seen & bit) !== 0) return false;
-			seen |= bit;
-		}
-	}
-	return true;
-}
-
-function isKeypressArray(value: unknown): value is string[] {
-	return (
-		isStringArray(value) &&
-		value.length > 0 &&
-		value.every(key => key.split("+").every(component => component.trim().length > 0))
-	);
-}
-
-function isComputerAction(value: unknown): value is ComputerAction {
-	if (!isRecord(value) || typeof value.type !== "string") return false;
-	const action = value;
-	const actionType = value.type;
-	const allowed = fieldsForAction(actionType);
-	if (!allowed || !hasOnlyFields(action, allowed)) return false;
-	switch (actionType) {
-		case "click":
-			return (
-				isCoordinate(action.x) &&
-				isCoordinate(action.y) &&
-				typeof action.button === "string" &&
-				MOUSE_BUTTONS[action.button] === true &&
-				isModifierArray(action.keys)
-			);
-		case "double_click":
-			return isCoordinate(action.x) && isCoordinate(action.y) && isModifierArray(action.keys);
-		case "drag":
-			return (
-				Array.isArray(action.path) &&
-				action.path.length >= 2 &&
-				action.path.every(isPoint) &&
-				isModifierArray(action.keys)
-			);
-		case "keypress":
-			return isKeypressArray(action.keys);
-		case "move":
-			return isCoordinate(action.x) && isCoordinate(action.y) && isModifierArray(action.keys);
-		case "screenshot":
-		case "wait":
-			return true;
-		case "scroll":
-			return (
-				isCoordinate(action.x) &&
-				isCoordinate(action.y) &&
-				isInt32(action.scroll_x) &&
-				isInt32(action.scroll_y) &&
-				isModifierArray(action.keys)
-			);
-		case "type":
-			return typeof action.text === "string";
-		default:
-			return false;
-	}
-}
-
-function parseActions(value: unknown): ComputerAction[] {
-	// Missing or empty action batches degrade to a plain screenshot so a
-	// function-calling model can observe the screen before acting.
-	if (value == null) return [{ type: "screenshot" }];
-	if (!Array.isArray(value)) throw new ToolError("Computer call requires an array of actions");
-	if (value.length === 0) return [{ type: "screenshot" }];
-	if (!value.every(isComputerAction)) throw new ToolError("Computer call contains an invalid action");
-	return value;
-}
-
-function toDesktopAction(action: ComputerAction): DesktopAction {
-	switch (action.type) {
-		case "click":
-			return {
-				type: "click",
-				x: action.x,
-				y: action.y,
-				button: action.button,
-				...(action.keys ? { keys: action.keys } : {}),
-			};
-		case "double_click":
-			return {
-				type: "double_click",
-				x: action.x,
-				y: action.y,
-				...(action.keys ? { keys: action.keys } : {}),
-			};
-		case "drag":
-			return { type: "drag", path: action.path, ...(action.keys ? { keys: action.keys } : {}) };
-		case "keypress":
-			return { type: "keypress", keys: action.keys };
-		case "move":
-			return { type: "move", x: action.x, y: action.y, ...(action.keys ? { keys: action.keys } : {}) };
-		case "screenshot":
-			return { type: "screenshot" };
-		case "scroll":
-			return {
-				type: "scroll",
-				x: action.x,
-				y: action.y,
-				scroll_x: action.scroll_x,
-				scroll_y: action.scroll_y,
-				...(action.keys ? { keys: action.keys } : {}),
-			};
-		case "type":
-			return { type: "type", text: action.text };
-		case "wait":
-			return { type: "wait" };
-	}
-}
-
-function callMetadata(context: AgentToolContext | undefined): ComputerToolCallMetadata | undefined {
-	const metadata = context?.toolCall?.providerMetadata;
-	return metadata?.type === "computer" ? metadata : undefined;
-}
-
+	code?: string;
+	readOnly?: boolean;
+	screenshots: ComputerScreenshot[];
+	returnValue?: string;
+	backend?: string;
+	capturePermission?: string;
+	inputPermission?: string;
+	axPermission?: string;
+}
+
+/** Creates the session-scoped controller used by the computer tool. */
+export type ComputerControllerFactory = (session: ToolSession) => ComputerController;
+/** Maps inspection-only runs to read approval and all other runs to execution approval. */
 export function computerApproval(args: unknown): ToolApprovalDecision {
-	const actions =
-		args && typeof args === "object" && "actions" in args ? (args as { actions?: unknown }).actions : undefined;
-	if (actions == null) return "read";
-	if (!Array.isArray(actions)) return "exec";
-	return actions.every(action => {
-		if (!action || typeof action !== "object") return false;
-		const actionType = (action as { type?: unknown }).type;
-		return actionType === "screenshot" || actionType === "wait";
-	})
-		? "read"
-		: "exec";
-}
-
-function modifierSummary(keys: unknown): string {
-	return isStringArray(keys) && keys.length > 0 ? ` keys=${JSON.stringify(keys)}` : "";
-}
-
-function approvalActionSummary(actions: unknown): string[] {
-	if (!Array.isArray(actions)) return ["Actions: unavailable"];
-	const lines = actions.slice(0, 12).map((value, index) => {
-		if (!value || typeof value !== "object") return `${index + 1}. invalid`;
-		const action = value as Record<string, unknown>;
-		const type = typeof action.type === "string" ? action.type : "invalid";
-		let detail: string;
-		switch (type) {
-			case "click":
-				detail = `click button=${String(action.button)} at (${String(action.x)}, ${String(action.y)})${modifierSummary(action.keys)}`;
-				break;
-			case "double_click":
-				detail = `double_click at (${String(action.x)}, ${String(action.y)})${modifierSummary(action.keys)}`;
-				break;
-			case "drag":
-				detail = `drag path=${Array.isArray(action.path) ? action.path.map(point => (isPoint(point) ? `(${point.x}, ${point.y})` : "invalid")).join(" -> ") : "invalid"}${modifierSummary(action.keys)}`;
-				break;
-			case "keypress":
-				detail = `keypress keys=${JSON.stringify(action.keys)}`;
-				break;
-			case "move":
-				detail = `move to (${String(action.x)}, ${String(action.y)})${modifierSummary(action.keys)}`;
-				break;
-			case "scroll":
-				detail = `scroll at (${String(action.x)}, ${String(action.y)}) delta=(${String(action.scroll_x)}, ${String(action.scroll_y)})${modifierSummary(action.keys)}`;
-				break;
-			case "type":
-				detail = `type text=${JSON.stringify(action.text)}`;
-				break;
-			case "screenshot":
-			case "wait":
-				detail = type;
-				break;
-			default:
-				detail = type;
-		}
-		return truncateForPrompt(sanitizeText(`${index + 1}. ${detail}`).replace(/[\r\n\t]+/g, " "), 240);
-	});
-	if (actions.length > 12) lines.push(`+${actions.length - 12} more actions`);
-	return truncateForPrompt(lines.join("\n"), 2_000).split("\n");
+	if (args === null || typeof args !== "object" || !("read_only" in args)) return "exec";
+	return args.read_only === true ? "read" : "exec";
 }
 
+/** Executes persistent desktop JavaScript through one lazy worker session. */
 export class ComputerTool implements AgentTool<ComputerSchema, ComputerToolDetails> {
 	readonly name = "computer";
-	readonly native = { type: "computer" } as const;
 	readonly label = "Computer";
 	readonly loadMode = "essential" as const;
 	readonly concurrency = "exclusive" as const;
-	readonly summary = "Capture and control the host desktop through native OS APIs";
-	get parameters(): ComputerSchema {
-		return getComputerSchema();
-	}
+	readonly summary = "Control the host desktop with persistent JavaScript and OS accessibility APIs";
 	readonly strict = false;
 	readonly approval = computerApproval;
 	readonly formatApprovalDetails = (args: unknown): string[] => {
-		const actions = args && typeof args === "object" ? (args as { actions?: unknown }).actions : undefined;
-		return approvalActionSummary(actions);
+		if (args === null || typeof args !== "object") return [""];
+		const code = "code" in args && typeof args.code === "string" ? args.code : "";
+		return [
+			...("read_only" in args && args.read_only === true ? ["read-only"] : []),
+			...truncateForPrompt(code, 2_000).split("\n"),
+		];
 	};
-	/**
-	 * Settings snapshot used to create the tool's current controller; refreshed
-	 * when a model switch crosses the coordinate-safe sizing boundary. Surfaced
-	 * by `/computer status`.
-	 */
-	effectiveConfiguration: Readonly<DesktopSessionOptions>;
-	readonly #createController: ComputerControllerFactory;
-	#controller: ComputerController;
-	#unregisterOwner: () => void;
-	#usesCoordinateSafeImageSizing: boolean;
+
+	readonly #controller: ComputerController;
+	readonly #unregisterOwner: () => void;
 	#closed = false;
 	#description?: string;
 
 	constructor(
 		readonly session: ToolSession,
-		createController: ComputerControllerFactory = options => new ComputerSupervisor(options),
+		createController: ComputerControllerFactory = currentSession =>
+			new ComputerSupervisor(currentSession, undefined, undefined, callSessionTool),
 	) {
-		this.#createController = createController;
-		this.#usesCoordinateSafeImageSizing = usesCoordinateSafeImageSizing(session.getActiveModel?.());
-		this.effectiveConfiguration = Object.freeze(captureOptions(session, this.#usesCoordinateSafeImageSizing));
-		this.#controller = createController(this.effectiveConfiguration);
+		this.#controller = createController(session);
 		this.#unregisterOwner = registerComputerController(
 			session.getEvalKernelOwnerId?.() ?? undefined,
 			this.#controller,
 		);
 	}
+
+	get parameters(): ComputerSchema {
+		return getComputerSchema();
+	}
+
 	get description(): string {
 		this.#description ??= prompt.render(computerDescription);
 		return this.#description;
 	}
 
-	async #refreshControllerForModel(): Promise<void> {
-		const nextUsesCoordinateSafeImageSizing = usesCoordinateSafeImageSizing(this.session.getActiveModel?.());
-		if (nextUsesCoordinateSafeImageSizing === this.#usesCoordinateSafeImageSizing) return;
-
-		const previous = this.#controller;
-		const nextOptions = Object.freeze(captureOptions(this.session, nextUsesCoordinateSafeImageSizing));
-		const next = this.#createController(nextOptions);
-		this.#unregisterOwner();
-		this.#controller = next;
-		this.#unregisterOwner = registerComputerController(this.session.getEvalKernelOwnerId?.() ?? undefined, next);
-		this.#usesCoordinateSafeImageSizing = nextUsesCoordinateSafeImageSizing;
-		this.effectiveConfiguration = nextOptions;
-		await previous.close();
-	}
-
 	async execute(
 		_toolCallId: string,
-		params: ComputerParams,
+		params: ComputerToolInput,
 		signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<ComputerToolDetails>,
-		context?: AgentToolContext,
+		_context?: AgentToolContext,
 	): Promise<AgentToolResult<ComputerToolDetails>> {
 		throwIfAborted(signal);
 		if (this.#closed) throw new ToolError("Computer session is closed");
-		const metadata = callMetadata(context);
-		const actions = parseActions(metadata?.actions ?? params.actions);
-		const pendingSafetyChecks: ComputerSafetyCheck[] = metadata?.pendingSafetyChecks ?? [];
-		if (pendingSafetyChecks.length > 0 && context?.providerSafetyApproved !== true) {
-			throw new ToolError("Provider safety checks require interactive approval before computer input");
-		}
-		await this.#refreshControllerForModel();
-		throwIfAborted(signal);
-		const capture = await this.#controller.execute(actions.map(toDesktopAction), signal);
+
+		const timeoutSeconds = clampTimeout("computer", params.timeout, this.session.settings.get("tools.maxTimeout"));
+		const coordinateSafe = usesCoordinateSafeImageSizing(this.session.getActiveModel?.());
+		const configuredMaxWidth = this.session.settings.get("computer.maxWidth");
+		const configuredMaxHeight = this.session.settings.get("computer.maxHeight");
+		const snapshot: ComputerSessionSnapshot = {
+			cwd: this.session.cwd,
+			sessionId: this.session.getEvalSessionId?.() ?? this.session.getSessionId?.() ?? "computer",
+			captureMaxWidth: coordinateSafe
+				? Math.min(configuredMaxWidth, COORDINATE_SAFE_MAX_CAPTURE_WIDTH)
+				: configuredMaxWidth,
+			captureMaxHeight: coordinateSafe
+				? Math.min(configuredMaxHeight, COORDINATE_SAFE_MAX_CAPTURE_HEIGHT)
+				: configuredMaxHeight,
+			display: this.session.settings.get("computer.display") ?? "all",
+			readOnly: !!params.read_only,
+		};
+		const run = await this.#controller.run(params.code, timeoutSeconds * 1000, snapshot, signal);
 		throwIfAborted(signal);
-		const data = Buffer.from(capture.data).toBase64();
-		return {
-			content: [{ type: "image", data, mimeType: "image/png", detail: "original" }],
-			details: {
-				width: capture.width,
-				height: capture.height,
-				backend: capture.backend,
-				displayServer: capture.displayServer,
-				capturePermission: capture.capturePermission,
-				inputPermission: capture.inputPermission,
-				displays: capture.displays,
-				capabilities: this.#controller.capabilities,
-				actions: actions.map(action => action.type),
-			},
-			...(metadata
-				? {
-						providerMetadata: {
-							type: "computer" as const,
-							screenshot: { type: "computer_screenshot" as const, image_url: `data:image/png;base64,${data}` },
-							acknowledgedSafetyChecks: pendingSafetyChecks,
-						},
-					}
-				: {}),
+
+		const details: ComputerToolDetails = {
+			code: params.code,
+			readOnly: snapshot.readOnly,
+			screenshots: run.screenshots,
 		};
+		if (run.returnValue !== undefined) details.returnValue = stringifyReturnValue(run.returnValue);
+		populateCapabilityDetails(details, run.capabilities);
+
+		const textBlocks = run.displays
+			.filter((content): content is { type: "text"; text: string } => content.type === "text")
+			.map(content => content.text);
+		if (details.returnValue !== undefined) textBlocks.push(details.returnValue);
+		if (!textBlocks.length && !run.displays.some(content => content.type === "image")) {
+			textBlocks.push("Ran computer code");
+		}
+		const textOnly = textBlocks.join("\n");
+		const cappedText = await enforceInlineByteCap(textOnly, {
+			saveArtifact: full => saveComputerOutputArtifact(this.session, full),
+		});
+		const images = run.displays
+			.filter(content => content.type === "image")
+			.map(content => ({ ...content, detail: "original" as const }));
+		const content = [...(cappedText ? [{ type: "text" as const, text: cappedText }] : []), ...images];
+		return { content, details };
+	}
+
+	async capabilities(): Promise<DesktopCapabilities | undefined> {
+		if (this.#closed) return undefined;
+		return await this.#controller.capabilities();
 	}
 
 	async close(): Promise<void> {
@@ -514,3 +191,32 @@ export class ComputerTool implements AgentTool<ComputerSchema, ComputerToolDetai
 		await this.#controller.close();
 	}
 }
+
+function stringifyReturnValue(value: unknown): string {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value, null, 2) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+
+function populateCapabilityDetails(details: ComputerToolDetails, capabilities: DesktopCapabilities | undefined): void {
+	if (!capabilities) return;
+	details.backend = capabilities.backend;
+	details.capturePermission = capabilities.capturePermission;
+	details.inputPermission = capabilities.inputPermission;
+	details.axPermission = capabilities.axPermission;
+}
+
+/** Persist over-cap computer run output as a session artifact; mirrors the browser run save path. */
+async function saveComputerOutputArtifact(session: ToolSession, fullText: string): Promise<string | undefined> {
+	try {
+		const alloc = await session.allocateOutputArtifact?.("computer-original");
+		if (!alloc?.path || !alloc.id) return undefined;
+		await Bun.write(alloc.path, fullText);
+		return alloc.id;
+	} catch {
+		return undefined;
+	}
+}

package/src/tools/context.ts

@@ -13,6 +13,9 @@ declare module "@oh-my-pi/pi-agent-core" {
 		 *  wrapper must not re-prompt for the same action (explicit per-tool
 		 *  policies and overrides still apply). */
 		xdevApproved?: boolean;
+		/** Reports the approval tier resolved after an extension rewrites an
+		 *  xd:// device call, so dispatch metadata describes the input that ran. */
+		xdevTierResolved?(tier: "read" | "write" | "exec"): void;
 		/** Set only after an interactive prompt approves provider computer safety checks. */
 		providerSafetyApproved?: boolean;
 	}

package/src/tools/glob.ts

@@ -13,6 +13,7 @@ import { splitMemoryGlobPattern } from "../internal-urls/memory-protocol";
 import type { Theme } from "../modes/theme/theme";
 import globDescription from "../prompts/tools/glob.md" with { type: "text" };
 import { type TruncationResult, truncateHead } from "../session/streaming-output";
+import { isScoutSpawnable } from "../task/spawn-policy";
 import { Ellipsis, fileHyperlink, renderFileList, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import type { ToolSession } from ".";
 import { applyListLimit } from "./list-limit";
@@ -106,7 +107,14 @@ export class GlobTool implements AgentTool<typeof findSchema, GlobToolDetails> {
 	readonly approval = "read" as const;
 	readonly loadMode = "essential";
 	readonly label = "Glob";
-	readonly description: string;
+	get description(): string {
+		return prompt.render(globDescription, {
+			scoutAvailable: isScoutSpawnable(
+				this.session.settings.get("task.disabledAgents") as string[] | undefined,
+				this.session.getSessionSpawns?.() ?? "*",
+			),
+		});
+	}
 	readonly parameters = findSchema;
 
 	readonly examples: readonly ToolExample<typeof findSchema.infer>[] = [
@@ -138,7 +146,6 @@ export class GlobTool implements AgentTool<typeof findSchema, GlobToolDetails> {
 	) {
 		this.#customOps = options?.operations;
 		this.#rootPathAlias = options?.rootPathAlias === true;
-		this.description = prompt.render(globDescription);
 	}
 
 	async execute(