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

package/src/slash-commands/builtin-registry.ts

@@ -102,39 +102,42 @@ function formatFastModeStatus(session: AgentSession): string {
 }
 
 /** Detailed, session-effective `/computer status` diagnostics. */
-function formatComputerUseStatus(session: AgentSession): string {
+async function formatComputerUseStatus(session: AgentSession): Promise<string> {
 	const enabled = session.settings.get("computer.enabled");
 	const active = session.getEnabledToolNames().includes("computer");
 	const model = session.model;
 	const modelName = model ? formatModelString(model) : "none";
-	const exposure = !enabled || !active ? "not exposed" : computerExposureMode(model);
-	const toolState = active ? "active" : enabled ? "unavailable" : "inactive";
+	const exposure = !enabled
+		? "not exposed (disabled)"
+		: !active
+			? "not exposed (tool inactive)"
+			: computerExposureMode(model);
 	const configured = {
-		backend: session.settings.get("computer.backend"),
 		display: session.settings.get("computer.display"),
 		maxWidth: session.settings.get("computer.maxWidth"),
 		maxHeight: session.settings.get("computer.maxHeight"),
 	};
-	const computerTool = session.getToolByName("computer") as Pick<ComputerTool, "effectiveConfiguration"> | undefined;
-	const effective = computerTool?.effectiveConfiguration ?? configured;
-	const configurationChanged =
-		effective.backend !== configured.backend ||
-		effective.display !== configured.display ||
-		effective.maxWidth !== configured.maxWidth ||
-		effective.maxHeight !== configured.maxHeight;
+	const computerTool = active
+		? (session.getToolByName("computer") as Pick<ComputerTool, "capabilities"> | undefined)
+		: undefined;
+	const capabilities = await computerTool?.capabilities();
+	const capabilityStatus = capabilities
+		? [
+				`backend=${capabilities.backend}${capabilities.displayServer ? `/${capabilities.displayServer}` : ""}`,
+				`capture=${capabilities.capture} (${capabilities.capturePermission})`,
+				`input=${capabilities.input} (${capabilities.inputPermission})`,
+				`ax=${capabilities.ax} (${capabilities.axPermission})`,
+				`backgroundWindowInput=${capabilities.backgroundWindowInput}`,
+				`deliveryModes=${capabilities.deliveryModes.join(",") || "none"}`,
+			].join(", ")
+		: "session not started";
 	return [
 		`Computer use: ${enabled ? "enabled" : "disabled"}`,
-		`tool: ${toolState}`,
-		`backend: ${effective.backend}`,
-		`display: ${effective.display}`,
-		`capture: ${effective.maxWidth}×${effective.maxHeight}`,
-		...(configurationChanged
-			? [
-					`next-session settings: backend=${configured.backend}, display=${configured.display}, capture=${configured.maxWidth}×${configured.maxHeight}`,
-				]
-			: []),
-		`model: ${modelName}`,
+		`tool: ${active ? "active" : "inactive"}`,
 		`exposure: ${exposure}`,
+		`model: ${modelName}`,
+		`configured: display=${configured.display}, maxWidth=${configured.maxWidth}, maxHeight=${configured.maxHeight}`,
+		`capabilities: ${capabilityStatus}`,
 	].join(" · ");
 }
 
@@ -151,7 +154,7 @@ async function applyComputerUseToggle(session: AgentSession, enable: boolean): P
 	}
 	session.settings.override("computer.enabled", enable);
 	return enable
-		? `Computer use enabled for this session. ${formatComputerUseStatus(session)}`
+		? `Computer use enabled for this session. ${await formatComputerUseStatus(session)}`
 		: "Computer use disabled for this session.";
 }
 
@@ -673,7 +676,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		handle: async (command, runtime) => {
 			const arg = command.args.trim().toLowerCase();
 			if (arg === "status") {
-				await runtime.output(formatComputerUseStatus(runtime.session));
+				await runtime.output(await formatComputerUseStatus(runtime.session));
 				return commandConsumed();
 			}
 			if (!arg || arg === "toggle" || arg === "on" || arg === "off") {
@@ -686,7 +689,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		handleTui: async (command, runtime) => {
 			const arg = command.args.trim().toLowerCase();
 			if (arg === "status") {
-				runtime.ctx.showStatus(formatComputerUseStatus(runtime.ctx.session));
+				runtime.ctx.showStatus(await formatComputerUseStatus(runtime.ctx.session));
 				runtime.ctx.editor.setText("");
 				return;
 			}
@@ -1716,6 +1719,16 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			await runtime.ctx.handleFreshCommand();
 		},
 	},
+	{
+		name: "reset",
+		description: "Reset the conversation context in place, keeping the session",
+		getTuiAutocompleteDescription: runtime =>
+			runtime.ctx.session.isStreaming ? "Reset: unavailable while streaming" : "Reset: drop context, keep session",
+		handleTui: async (_command, runtime) => {
+			runtime.ctx.editor.setText("");
+			await runtime.ctx.handleResetContextCommand();
+		},
+	},
 	{
 		name: "drop",
 		description: "Delete the current session and start a new one",

package/src/system-prompt.ts

@@ -498,7 +498,8 @@ export interface BuildSystemPromptOptions {
 	/**
 	 * Whether provider-native tool calling is active (no owned/in-band syntax).
 	 * When true and `inlineToolDescriptors` is false, the inventory renders as a
-	 * compact tool-name list; otherwise it renders full `# Tool:` sections. Default: true
+	 * compact tool-name list; otherwise it renders the full Harmony-style
+	 * `namespace functions { … }` catalog. Default: true
 	 */
 	nativeTools?: boolean;
 	/** Skills settings for discovery. */
@@ -525,6 +526,9 @@ export interface BuildSystemPromptOptions {
 	taskMaxConcurrency?: number;
 	/** Whether IRC-backed parallel coordination can be included in delegation policy. */
 	taskIrcEnabled?: boolean;
+	/** Whether the read-only `scout` subagent is spawnable (not disabled, allowed by spawn policy). Defaults to true. */
+	scoutAvailable?: boolean;
+
 	/** Rules with alwaysApply=true — their full content is injected into the prompt. */
 	alwaysApplyRules?: AlwaysApplyRule[];
 	/** Whether secret obfuscation is active. When true, explains the redaction format in the prompt. */
@@ -599,6 +603,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		taskIrcEnabled = false,
 		secretsEnabled = false,
 		workspaceTree: providedWorkspaceTree,
+		scoutAvailable = true,
 		memoryRootEnabled = false,
 		securityEnabled = false,
 		model,
@@ -793,7 +798,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 
 	// List mode shows a compact tool-name list; it only applies when descriptors
 	// stay in provider-native tool schemas AND native tool calling is active.
-	// Otherwise render full `# Tool:` sections inline in the system prompt.
+	// Otherwise render the full functions-namespace catalog in the system prompt.
 	const toolListMode = !inlineToolDescriptors && nativeTools;
 	// Build tool descriptions for system prompt rendering.
 	const toolPromptNames = new Map<string, string>(toolNames.map(name => [name, tools?.get(name)?.wireName ?? name]));
@@ -826,7 +831,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 						examples: meta?.examples,
 					};
 				}),
-				model ?? "",
 			);
 
 	// Filter skills for the rendered system prompt:
@@ -879,6 +883,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		eagerTasksAlways,
 		taskBatch,
 		MAX_CONCURRENCY: normalizeConcurrencyLimit(taskMaxConcurrency),
+		scoutAvailable,
 		taskIrcEnabled,
 		secretsEnabled,
 		hasMemoryRoot: memoryRootEnabled,

package/src/task/index.ts

@@ -27,7 +27,7 @@ import { TASK_EFFORTS, type TaskEffort } from "../thinking";
 import { truncateForPrompt } from "../tools/approval";
 import { isIrcEnabled } from "../tools/hub";
 import { formatBytes, formatDuration } from "../tools/render-utils";
-import { resolveSpawnPolicy } from "./spawn-policy";
+import { isScoutSpawnable, resolveSpawnPolicy } from "./spawn-policy";
 import {
 	type AgentDefinition,
 	type AgentProgress,
@@ -188,8 +188,10 @@ function renderDescription(options: TaskDescriptionOptions): string {
 		readOnly: isReadOnlyAgent(agent),
 		blocking: agent.blocking === true,
 	}));
+	const scoutAvailable = isScoutSpawnable(options.disabledAgents, options.parentSpawns);
 	return prompt.render(taskDescriptionTemplate, {
 		agents: renderedAgents,
+		scoutAvailable,
 		spawningDisabled,
 		defaultAgent: spawnPolicy.defaultAgent,
 		isolationEnabled: options.isolationEnabled,
@@ -398,15 +400,19 @@ const GENERIC_SPAWN_AGENTS: ReadonlySet<string> = new Set(["task", "sonic"]);
  * (DepthCapacity: it currently has the `task` tool). `agentNames` are the
  * per-item resolved agent types. Returns undefined when no nudge applies.
  */
-export function buildSpecializationAdvisory(agentNames: string[], depthCapacity: boolean): string | undefined {
+export function buildSpecializationAdvisory(
+	agentNames: string[],
+	depthCapacity: boolean,
+	scoutAvailable = true,
+): string | undefined {
 	if (!depthCapacity) return undefined;
 	const generics = agentNames.filter(name => GENERIC_SPAWN_AGENTS.has(name));
 	if (generics.length < 2) return undefined;
-	return (
-		`Tip: this call spawned ${generics.length} generic \`${generics[0]}\` workers. ` +
-		`Check the agent list for a closer specialist type — e.g. read-only research belongs on ` +
-		`\`agent: "scout"\`, which runs on a faster model.`
-	);
+	const specialist = scoutAvailable
+		? `Check the agent list for a closer specialist type — e.g. read-only research belongs on ` +
+			`\`agent: "scout"\`, which runs on a faster model.`
+		: `Check the agent list for a closer specialist type.`;
+	return `Tip: this call spawned ${generics.length} generic \`${generics[0]}\` workers. ${specialist}`;
 }
 
 /**
@@ -443,10 +449,11 @@ export function composeSpawnAdvisory(args: {
 	depthCapacity: boolean;
 	ircEnabled: boolean;
 	willRunAsync: boolean;
+	scoutAvailable?: boolean;
 }): string | undefined {
 	return (
 		[
-			buildSpecializationAdvisory(args.agents, args.depthCapacity),
+			buildSpecializationAdvisory(args.agents, args.depthCapacity, args.scoutAvailable),
 			args.willRunAsync ? buildCoordinationAdvisory(args.items, args.depthCapacity, args.ircEnabled) : undefined,
 		]
 			.filter(Boolean)
@@ -751,6 +758,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						depthCapacity,
 						ircEnabled,
 						willRunAsync: false,
+						scoutAvailable: isScoutSpawnable(
+							this.session.settings.get("task.disabledAgents") as string[] | undefined,
+							this.session.getSessionSpawns?.() ?? "*",
+						),
 					});
 			const result = await this.#executeSyncFanout(
 				toolCallId,
@@ -784,6 +795,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					depthCapacity,
 					ircEnabled,
 					willRunAsync: asyncItems.length > 0,
+					scoutAvailable: isScoutSpawnable(
+						this.session.settings.get("task.disabledAgents") as string[] | undefined,
+						this.session.getSessionSpawns?.() ?? "*",
+					),
 				});
 		// Returns a fresh result (copied content array, copied text part) rather
 		// than mutating the caller's — task results are short-lived here, but an

package/src/task/spawn-policy.ts

@@ -56,3 +56,17 @@ export function resolveSpawnPolicy(parentSpawns: string | boolean | null | undef
 		allowedPromptText: allowedAgents.map(agent => `\`${agent}\``).join(", "),
 	};
 }
+
+/**
+ * Whether the `scout` agent is spawnable in a session: not disabled via
+ * `task.disabledAgents`, and permitted by the session spawn policy.
+ */
+export function isScoutSpawnable(
+	disabledAgents: readonly string[] | undefined,
+	spawns: string | boolean | null | undefined,
+): boolean {
+	if (disabledAgents?.includes("scout")) return false;
+	const policy = resolveSpawnPolicy(spawns);
+	if (!policy.enabled) return false;
+	return policy.allowedAgents === null || policy.allowedAgents.includes("scout");
+}

package/src/thinking.ts

@@ -3,6 +3,8 @@ import { Effort, type Model, THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
 import { clampThinkingLevelForModel, getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
 import { modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
 
+export { CLI_THINKING_LEVELS } from "./cli/thinking-levels";
+
 /**
  * Metadata used to render thinking selector values in the coding-agent UI.
  */
@@ -209,14 +211,6 @@ export function getConfiguredThinkingLevelMetadata(level: ConfiguredThinkingLeve
 	return level === AUTO_THINKING ? AUTO_THINKING_METADATA : getThinkingLevelMetadata(level);
 }
 
-/**
- * Thinking selectors accepted by the `--thinking` CLI flag, in display order:
- * `off`, every concrete effort (`minimal`..`max`), then `auto`. Single source
- * for the flag's `options` list, shell completions, and the "invalid level"
- * warning so all three stay in sync.
- */
-export const CLI_THINKING_LEVELS: readonly string[] = [ThinkingLevel.Off, ...THINKING_EFFORTS, AUTO_THINKING];
-
 /**
  * Parses a `--thinking` CLI value. Accepts every {@link parseConfiguredThinkingLevel}
  * selector (`off`, `auto`, `minimal`..`max`) but rejects

package/src/tools/ast-grep.ts

@@ -11,6 +11,7 @@ import { recordFileSnapshot, recordSeenLinesFromBody } from "../edit/file-snapsh
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import astGrepDescription from "../prompts/tools/ast-grep.md" with { type: "text" };
+import { isScoutSpawnable } from "../task/spawn-policy";
 import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
@@ -150,7 +151,14 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 	readonly approval = "read" as const;
 	readonly label = "AST Grep";
 	readonly summary = "Search code with AST patterns (structural grep)";
-	readonly description: string;
+	get description(): string {
+		return prompt.render(astGrepDescription, {
+			scoutAvailable: isScoutSpawnable(
+				this.session.settings.get("task.disabledAgents") as string[] | undefined,
+				this.session.getSessionSpawns?.() ?? "*",
+			),
+		});
+	}
 	readonly parameters = astGrepSchema;
 	readonly strict = true;
 
@@ -178,9 +186,7 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 	];
 	readonly loadMode = "discoverable";
 
-	constructor(private readonly session: ToolSession) {
-		this.description = prompt.render(astGrepDescription);
-	}
+	constructor(private readonly session: ToolSession) {}
 
 	async execute(
 		_toolCallId: string,

package/src/tools/browser/cmux/cmux-tab.ts

@@ -8,16 +8,11 @@ import { resizeImage } from "../../../utils/image-resize";
 import type { ToolSession } from "../../index";
 import { resolveToCwd } from "../../path-utils";
 import { formatScreenshot } from "../../render-utils";
+import { bindRunFacade, resolvePredicateTimeout, type WaitPredicateOptions, waitForRun } from "../../run-scope";
 import { ToolAbortError, ToolError, throwIfAborted } from "../../tool-errors";
 import { type AriaSnapshotOptions, assertSelectorString, buildAriaSnapshotScript } from "../aria/aria-snapshot";
 import { DEFAULT_VIEWPORT } from "../launch";
 import { extractReadableFromHtml, type ReadableFormat } from "../readable";
-import {
-	bindBrowserRunFacade,
-	resolvePredicateTimeout,
-	type WaitPredicateOptions,
-	waitForBrowserRun,
-} from "../run-cancellation";
 import { cloneSafe, RunOutput } from "../run-output";
 import type { Observation, ReadyInfo, RunResultOk, ScreenshotResult, SessionSnapshot } from "../tab-protocol";
 import {
@@ -259,6 +254,65 @@ export interface RunCmuxCodeOptions {
 	snapshot: SessionSnapshot;
 }
 
+interface ActiveCmuxRun {
+	filename: string;
+	floatingRejections: unknown[];
+}
+
+const RECENT_CMUX_RUN_FILES_MAX = 256;
+const activeCmuxRuns = new Map<string, ActiveCmuxRun>();
+const recentCmuxRunFiles = new Set<string>();
+
+function consumeCmuxRunRejection(reason: unknown): boolean {
+	// cmux runs guest JS in the shared main-process realm (TTS/STT/MCP and other
+	// subsystems live here too), so — like the eval inline fallback — only a
+	// guest-file stack frame can safely attribute a rejection. A stackless or
+	// non-run-stack reason is indistinguishable from a subsystem failure and
+	// keeps the default fatal path; worker isolation is the long-term fix.
+	const stack = reason instanceof Error && typeof reason.stack === "string" ? reason.stack : undefined;
+	if (!stack) return false;
+
+	let owner: ActiveCmuxRun | undefined;
+	let ownerIndex = -1;
+	for (const run of activeCmuxRuns.values()) {
+		const index = stack.lastIndexOf(run.filename);
+		if (index > ownerIndex) {
+			ownerIndex = index;
+			owner = run;
+		}
+	}
+	if (owner) {
+		owner.floatingRejections.push(reason);
+		return true;
+	}
+
+	let recent: string | undefined;
+	let recentIndex = -1;
+	for (const filename of recentCmuxRunFiles) {
+		const index = stack.lastIndexOf(filename);
+		if (index > recentIndex) {
+			recentIndex = index;
+			recent = filename;
+		}
+	}
+	if (!recent) return false;
+	logger.warn("Unhandled rejection from a finished cmux browser run (missing await?)", {
+		filename: recent,
+		error: reason,
+	});
+	return true;
+}
+
+function rememberCmuxRunFile(filename: string): void {
+	recentCmuxRunFiles.delete(filename);
+	recentCmuxRunFiles.add(filename);
+	if (recentCmuxRunFiles.size <= RECENT_CMUX_RUN_FILES_MAX) return;
+	const oldest = recentCmuxRunFiles.values().next().value;
+	if (oldest !== undefined) recentCmuxRunFiles.delete(oldest);
+}
+
+postmortem.interceptUnhandledRejections(consumeCmuxRunRejection);
+
 export class CmuxTab {
 	readonly #client: CmuxSocketClient;
 	readonly #surfaceId: string;
@@ -1317,6 +1371,9 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 	const output = new RunOutput();
 	const screenshots: ScreenshotResult[] = [];
 	const runId = crypto.randomUUID();
+	const filename = `cmux-run-${runId}.js`;
+	const activeRun: ActiveCmuxRun = { filename, floatingRejections: [] };
+	activeCmuxRuns.set(filename, activeRun);
 	tab.setRunContext({ session: opts.snapshot, output, screenshots, signal, timeoutMs: opts.timeoutMs });
 
 	const { promise: cancelRejection, reject } = Promise.withResolvers<never>();
@@ -1345,16 +1402,16 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 		// Keep both inside try so a concurrent in-process eval/browser run surfaces as
 		// a rejected promise the supervisor can report, never an unhandled rejection.
 		runtime.setCwd(opts.snapshot.cwd);
-		const runTab = bindBrowserRunFacade(tab, signal);
+		const runTab = bindRunFacade(tab, signal);
 		runtime.setRunScope({
-			page: bindBrowserRunFacade(tab.page, signal),
-			browser: bindBrowserRunFacade(tab.browser, signal),
+			page: bindRunFacade(tab.page, signal),
+			browser: bindRunFacade(tab.browser, signal),
 			tab: runTab,
 			assert: (cond: unknown, text?: string): void => {
 				if (!cond) throw new ToolError(text ?? "Assertion failed");
 			},
 			wait: (msOrPredicate: number | (() => unknown), waitOpts?: WaitPredicateOptions): Promise<unknown> =>
-				waitForBrowserRun(
+				waitForRun(
 					msOrPredicate,
 					signal,
 					typeof msOrPredicate === "number"
@@ -1383,14 +1440,40 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 		};
 		// Like the inline worker fallback, cmux runs user JS in-process: awaited cmux/tool calls
 		// observe this abort signal, but a synchronous infinite loop cannot be interrupted here.
-		const returnValue = await Promise.race([
-			runtime.run(opts.code, `cmux-run-${runId}.js`, hooks, { runId, cwd: opts.snapshot.cwd }),
-			cancelRejection,
-		]);
+		let returnValue: unknown;
+		let runError: unknown;
+		let runFailed = false;
+		try {
+			returnValue = await Promise.race([
+				runtime.run(opts.code, filename, hooks, { runId, cwd: opts.snapshot.cwd }),
+				cancelRejection,
+			]);
+		} catch (error) {
+			runFailed = true;
+			runError = error;
+		}
+		// Let rejection callbacks run while this run can still own guest-created promises.
+		await Bun.sleep(0);
+		if (runFailed) {
+			for (const reason of activeRun.floatingRejections) {
+				logger.warn("Unhandled rejection accompanied a failed cmux browser run", { filename, error: reason });
+			}
+			throw runError;
+		}
+		if (activeRun.floatingRejections.length > 0) {
+			const messages = activeRun.floatingRejections.map(reason =>
+				reason instanceof Error ? reason.message : String(reason),
+			);
+			throw new ToolError(`Unhandled rejection (missing await?): ${messages.join("\n[unhandled rejection] ")}`, {
+				rejections: activeRun.floatingRejections,
+			});
+		}
 		return { displays: output.finish(), returnValue: cloneSafe(returnValue), screenshots };
 	} finally {
 		signal.removeEventListener("abort", onAbort);
 		runAc.abort(postmortem.markExpectedCleanupError(new ToolAbortError("Browser run ended")));
+		activeCmuxRuns.delete(filename);
+		rememberCmuxRunFile(filename);
 		tab.clearRunContext();
 	}
 }

package/src/tools/browser/cmux/rpc.ts

@@ -1,3 +1,4 @@
+import { parseFlag } from "@oh-my-pi/pi-utils";
 import { ToolError } from "../../tool-errors";
 import type { Observation, ObservationEntry } from "../tab-protocol";
 
@@ -174,13 +175,6 @@ export function mapWaitUntil(waitUntil: string | undefined): "interactive" | "co
 	return waitUntil === "domcontentloaded" ? "interactive" : "complete";
 }
 
-const TRUTHY_ENV_VALUES = new Set(["1", "Y", "y", "TRUE", "true", "YES", "yes", "ON", "on"]);
-
-function resolveCmuxEnabled(envValue: string | undefined, settingEnabled: boolean): boolean {
-	if (!envValue) return settingEnabled;
-	return TRUTHY_ENV_VALUES.has(envValue);
-}
-
 export interface ResolveCmuxKindOptions {
 	surface?: string;
 	settingEnabled?: boolean;
@@ -190,7 +184,7 @@ export function resolveCmuxKind(
 	options?: ResolveCmuxKindOptions | null,
 	env: Record<string, string | undefined> = process.env,
 ): CmuxKind | null {
-	if (!resolveCmuxEnabled(env.PI_BROWSER_CMUX, options?.settingEnabled ?? true)) {
+	if (!parseFlag(env.PI_BROWSER_CMUX, options?.settingEnabled ?? true)) {
 		return null;
 	}
 	const socketPath = env.CMUX_SOCKET_PATH;

package/src/tools/browser/registry.ts

@@ -14,12 +14,15 @@ import {
 	removeUserDataDir,
 	type UserAgentOverride,
 } from "./launch";
+import { ensureRelayDaemon, isLoopbackRelayUrl } from "./relay/daemon";
+import type { RelayKind } from "./relay/kind";
 import { ensureSharedBrowser } from "./shared-daemon";
 
 export type PuppeteerBrowserKind =
 	| { kind: "headless"; headless: boolean }
 	| { kind: "spawned"; path: string }
-	| { kind: "connected"; cdpUrl: string };
+	| { kind: "connected"; cdpUrl: string }
+	| RelayKind;
 
 export type BrowserKind = PuppeteerBrowserKind | CmuxKind;
 
@@ -31,6 +34,12 @@ export type BrowserKindTag = BrowserKind["kind"];
  * forever (issue #5260), so we cap the wait and force-kill on timeout.
  */
 const HEADLESS_CLOSE_TIMEOUT_MS = 5_000;
+/**
+ * How long a relay open waits for the extension handshake (503 → 200). A
+ * reaped extension service worker is revived by its 30s keepalive alarm, so
+ * the wait must cover one full alarm period plus the dial.
+ */
+const RELAY_EXTENSION_WAIT_MS = 35_000;
 
 interface BrowserHandleCommon {
 	key: string;
@@ -78,6 +87,8 @@ function browserKey(kind: BrowserKind): string {
 			return `spawned:${kind.path}`;
 		case "connected":
 			return `connected:${kind.cdpUrl}`;
+		case "relay":
+			return `relay:${kind.cdpUrl}`;
 		case "cmux":
 			return `cmux:${kind.socketPath}`;
 	}
@@ -201,6 +212,45 @@ async function openBrowserHandle(kind: BrowserKind, opts: AcquireBrowserOptions)
 			stealth: { browserSession: null, override: null },
 		};
 	}
+	if (kind.kind === "relay") {
+		const cdpUrl = normalizeConnectedCdpUrl(kind.cdpUrl);
+		// Loopback relays are owned by a machine-global broker and auto-started
+		// on demand (the extension dials in on its own). Hosts without a CLI
+		// worker entry (bun test, SDK embedding) never spawn brokers. Remote
+		// relay URLs must already be serving.
+		let autoStarted = false;
+		if (isLoopbackRelayUrl(cdpUrl) && (isCompiledBinary() || workerHostEntry() !== null)) {
+			autoStarted = await ensureRelayDaemon({ cdpUrl, signal: opts.signal });
+		}
+		// The relay answers /json/version with 503 until its extension dials in.
+		// A freshly revived extension service worker can take up to ~30s (its
+		// keepalive alarm) to reconnect, so give the handshake that long.
+		try {
+			await waitForCdp(cdpUrl, RELAY_EXTENSION_WAIT_MS, opts.signal);
+		} catch (err) {
+			if (err instanceof ToolAbortError) throw err;
+			if (err instanceof Error && err.name === "AbortError") throw err;
+			throw new ToolError(
+				autoStarted
+					? `omp browser relay is serving at ${cdpUrl} but its extension never connected. Install it with \`omp browser-relay install\` and check the toolbar badge shows "on".`
+					: `omp browser relay is not reachable at ${cdpUrl}. Start it with \`omp browser-relay\` (or check the endpoint), and make sure the OMP Browser Relay extension is loaded in Chrome.`,
+			);
+		}
+		const puppeteer = await loadPuppeteer();
+		const browser = await puppeteer.connect({
+			browserURL: cdpUrl,
+			defaultViewport: null,
+			protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
+		});
+		return {
+			key: browserKey(kind),
+			kind,
+			browser,
+			cdpUrl,
+			refCount: 0,
+			stealth: { browserSession: null, override: null },
+		};
+	}
 
 	const exe = kind.path;
 	if (!path.isAbsolute(exe)) {
@@ -320,7 +370,8 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: ReleaseBrowserO
 		if (handle.userDataDir) await removeUserDataDir(handle.userDataDir);
 		return;
 	}
-	if (handle.kind.kind === "connected") {
+	// Connected and relay browsers belong to the user: drop our CDP link, never kill.
+	if (handle.kind.kind === "connected" || handle.kind.kind === "relay") {
 		if (handle.browser.connected) {
 			try {
 				handle.browser.disconnect();