@oh-my-pi/pi-coding-agent 16.4.2 → 16.4.3

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

@@ -34,7 +34,12 @@ import { resolveResumableSession } from "../session/session-listing";
 import { formatShakeSummary, type ShakeMode } from "../session/shake-types";
 import { expandTilde, resolveToCwd } from "../tools/path-utils";
 import { urlHyperlinkAlways } from "../tui";
-import { getChangelogPath, parseChangelog } from "../utils/changelog";
+import {
+	getChangelogPath,
+	parseChangelog,
+	RECENT_CHANGELOG_ENTRY_LIMIT,
+	renderChangelogEntries,
+} from "../utils/changelog";
 import { copyToClipboard } from "../utils/clipboard";
 import { CollabQrCodeComponent } from "./helpers/collab-qrcode";
 import { buildContextReportText } from "./helpers/context-report";
@@ -250,6 +255,22 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "vibe",
+		description: "Toggle vibe mode (direct persistent fast/good worker sessions; read-only toolset)",
+		inlineHint: "[prompt]",
+		allowArgs: true,
+		getTuiAutocompleteDescription: runtime => {
+			if (runtime.ctx.vibeModeEnabled) return "Vibe: on";
+			if (runtime.ctx.planModeEnabled) return "Vibe: blocked by plan mode";
+			if (runtime.ctx.goalModeEnabled) return "Vibe: blocked by goal mode";
+			return "Vibe: off";
+		},
+		handleTui: async (command, runtime) => {
+			await runtime.ctx.handleVibeModeCommand(command.args || undefined);
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "goal",
 		description: "Toggle goal mode (persistent autonomous objective for this session)",
@@ -1082,17 +1103,12 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			const changelogPath = getChangelogPath();
 			const allEntries = await parseChangelog(changelogPath);
 			const showFull = command.args.trim().toLowerCase() === "full";
-			const entriesToShow = showFull ? allEntries : allEntries.slice(0, 3);
+			const entriesToShow = showFull ? allEntries : allEntries.slice(0, RECENT_CHANGELOG_ENTRY_LIMIT);
 			if (entriesToShow.length === 0) {
 				await runtime.output("No changelog entries found.");
 				return commandConsumed();
 			}
-			await runtime.output(
-				[...entriesToShow]
-					.reverse()
-					.map(entry => entry.content)
-					.join("\n\n"),
-			);
+			await runtime.output(renderChangelogEntries(entriesToShow).markdown);
 			return commandConsumed();
 		},
 		handleTui: async (command, runtime) => {

package/src/task/agents.ts

@@ -10,7 +10,6 @@ import designerMd from "../prompts/agents/designer.md" with { type: "text" };
 // Embed agent markdown files at build time
 import agentFrontmatterTemplate from "../prompts/agents/frontmatter.md" with { type: "text" };
 import librarianMd from "../prompts/agents/librarian.md" with { type: "text" };
-import planMd from "../prompts/agents/plan.md" with { type: "text" };
 import reviewerMd from "../prompts/agents/reviewer.md" with { type: "text" };
 import scoutMd from "../prompts/agents/scout.md" with { type: "text" };
 import taskMd from "../prompts/agents/task.md" with { type: "text" };
@@ -41,7 +40,6 @@ function buildAgentContent(def: EmbeddedAgentDef): string {
 
 const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 	{ fileName: "scout.md", template: scoutMd },
-	{ fileName: "plan.md", template: planMd },
 	{ fileName: "designer.md", template: designerMd },
 	{ fileName: "reviewer.md", template: reviewerMd },
 	{ fileName: "librarian.md", template: librarianMd },

package/src/task/executor.ts

@@ -1880,6 +1880,111 @@ export async function finalizeSubagentLifecycle(args: {
 	});
 }
 
+/** Options for {@link runSubagentFollowUpTurn}. */
+export interface FollowUpTurnOptions {
+	/** Registry id of the (live or parked) subagent to continue. */
+	id: string;
+	/** Agent definition the session was originally spawned with (drives progress labels + finalize). */
+	agent: AgentDefinition;
+	/** The follow-up message; sent as the turn's user prompt. */
+	message: string;
+	index?: number;
+	description?: string;
+	signal?: AbortSignal;
+	onProgress?: (progress: AgentProgress) => void;
+	eventBus?: EventBus;
+	parentToolCallId?: string;
+	/** When set, the turn's raw output is (re)written to `<artifactsDir>/<id>.md` so `agent://<id>` tracks the latest turn. */
+	artifactsDir?: string;
+	/** Wall-clock cap in ms for this turn; 0 disables. */
+	maxRuntimeMs?: number;
+}
+
+/**
+ * Continue a previously spawned (keep-alive) subagent with one more monitored
+ * turn: revive it if parked, send `message` as a real prompt, drive it to
+ * `yield`, and finalize a {@link SingleResult} exactly like a first run.
+ *
+ * The session's full conversation history is retained (live session, or JSONL
+ * replay through the lifecycle reviver), so the turn sees all prior context.
+ * Unlike {@link runSubprocess}, the session is NOT torn down afterwards — it
+ * stays adopted by the {@link AgentLifecycleManager} (idle → TTL park →
+ * revive), and an aborted turn only aborts the in-flight turn.
+ */
+export async function runSubagentFollowUpTurn(options: FollowUpTurnOptions): Promise<SingleResult> {
+	const { id, agent, message, signal } = options;
+	const index = options.index ?? 0;
+	const startTime = Date.now();
+	const session = await AgentLifecycleManager.global().ensureLive(id);
+	const ref = AgentRegistry.global().get(id);
+	const sessionFile = ref?.sessionFile ?? undefined;
+
+	const monitor = createSubagentRunMonitor({
+		index,
+		id,
+		agent,
+		task: message,
+		description: options.description,
+		signal,
+		onProgress: options.onProgress,
+		eventBus: options.eventBus,
+		parentToolCallId: options.parentToolCallId,
+		detached: true,
+		sessionFile,
+		softRequestBudget: 0,
+		softRequestBudgetNotice: false,
+		maxRuntimeMs: options.maxRuntimeMs ?? 0,
+	});
+
+	if (options.eventBus) {
+		options.eventBus.emit(TASK_SUBAGENT_LIFECYCLE_CHANNEL, {
+			id,
+			agent: agent.name,
+			parentToolCallId: options.parentToolCallId,
+			detached: true,
+			agentSource: agent.source,
+			description: options.description,
+			status: "started",
+			sessionFile,
+			index,
+		});
+	}
+
+	monitor.setActiveSession(session);
+	const unsubscribe = monitor.attach(session);
+	let outcome: DriveOutcome;
+	try {
+		outcome = await driveSessionToYield(session, monitor, message);
+	} finally {
+		try {
+			await untilAborted(AbortSignal.timeout(5000), () => monitor.waitForActiveSessionAbort());
+		} catch {
+			// Ignore abort cleanup timeouts; the session stays adopted either way.
+		}
+		unsubscribe();
+		const active = monitor.takeActiveSession();
+		if (active) monitor.captureSalvage(active);
+		monitor.finish();
+	}
+
+	return finalizeRunResult({
+		monitor,
+		done: { ...outcome, abortReason: outcome.abortReasonText, durationMs: Date.now() - startTime },
+		index,
+		id,
+		agent,
+		task: message,
+		description: options.description,
+		signal,
+		artifactsDir: options.artifactsDir,
+		eventBus: options.eventBus,
+		parentToolCallId: options.parentToolCallId,
+		detached: true,
+		sessionFile,
+		startTime,
+	});
+}
+
 /**
  * Run a single agent in-process.
  */

package/src/tools/__tests__/vibe-render.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Contracts: vibe tool renderers.
+ *
+ * 1. spawn/send render a mini composer — the message typed into a tiny CLI
+ *    frame with a prompt glyph and (while pending) a blinking cursor.
+ * 2. wait/list render the TV wall: one boxed screen per worker, stacked, a
+ *    running screen showing its tool-call trace, current tool, and streamed
+ *    text tail; an idle screen its last-activity gist; a settled screen its
+ *    delivery footer.
+ * 3. Animated content (cursor blink, spinner) re-derives from the shared
+ *    mutable options on every paint of the SAME component — spinner ticks
+ *    repaint the block without re-invoking renderCall/renderResult.
+ * 4. Every emitted line respects the render width (sanitized, truncated).
+ */
+import { beforeAll, describe, expect, it } from "bun:test";
+import { Settings } from "../../config/settings";
+import { getThemeByName, setThemeInstance, type Theme } from "../../modes/theme/theme";
+import type { VibeScreenSnapshot } from "../../vibe/runtime";
+import { createVibeToolRenderer, type VibeToolDetails } from "../vibe";
+
+const strip = (lines: readonly string[]): string[] =>
+	lines.map(line => line.replace(/\x1b\]8;[^\x1b\x07]*(?:\x07|\x1b\\)/g, "").replace(/\x1b\[[0-9;]*m/g, ""));
+
+function makeScreen(overrides: Partial<VibeScreenSnapshot> = {}): VibeScreenSnapshot {
+	return {
+		id: "Anna",
+		cli: "fast",
+		state: "running",
+		turns: 1,
+		queued: 0,
+		trace: [],
+		outputTail: [],
+		lastActivityAt: Date.now(),
+		...overrides,
+	};
+}
+
+function renderLines(component: { render(width: number): readonly string[] }, width = 100): string[] {
+	return strip(component.render(width));
+}
+
+describe("vibe tool renderers", () => {
+	let uiTheme: Theme;
+
+	beforeAll(async () => {
+		await Settings.init({ inMemory: true });
+		const loaded = await getThemeByName("dark");
+		if (!loaded) throw new Error("theme unavailable");
+		uiTheme = loaded;
+		setThemeInstance(uiTheme);
+	});
+
+	it("send composer types the message into a mini CLI frame with a blinking cursor while pending", () => {
+		const renderer = createVibeToolRenderer("send");
+		const component = renderer.renderCall(
+			{ session: "Anna", message: "Focus on the API first.\nThen tests." },
+			{ expanded: false, isPartial: true, spinnerFrame: 0 },
+			uiTheme,
+		) as { render(width: number): readonly string[] };
+		const text = renderLines(component).join("\n");
+
+		expect(text).toContain("vibe send → Anna");
+		expect(text).toContain("> Focus on the API first.");
+		expect(text).toContain("Then tests.▌");
+		expect(text).toContain("delivering…");
+		// Odd frame: cursor blinks off.
+		const off = renderLines(
+			renderer.renderCall(
+				{ session: "Anna", message: "Hi" },
+				{ expanded: false, isPartial: true, spinnerFrame: 1 },
+				uiTheme,
+			) as { render(width: number): readonly string[] },
+		).join("\n");
+		expect(off).not.toContain("▌");
+	});
+
+	it("composer cursor re-derives from mutated options on the same component", () => {
+		const renderer = createVibeToolRenderer("send");
+		const options = { expanded: false, isPartial: true, spinnerFrame: 0 };
+		const component = renderer.renderCall({ session: "Anna", message: "Hi" }, options, uiTheme) as {
+			render(width: number): readonly string[];
+		};
+		expect(renderLines(component).join("\n")).toContain("▌");
+		// The tool block mutates ONE shared render-state object per spinner tick
+		// and repaints — the component must not have baked frame 0 in.
+		options.spinnerFrame = 1;
+		expect(renderLines(component).join("\n")).not.toContain("▌");
+	});
+
+	it("wait wall spinner re-derives from mutated options on the same component", () => {
+		const renderer = createVibeToolRenderer("wait");
+		const details: VibeToolDetails = {
+			op: "wait",
+			screens: [makeScreen({ currentTool: "edit" })],
+			wait: { settled: [], stillRunning: ["Anna"], timedOut: false, waiting: true },
+		};
+		const options = { expanded: false, isPartial: true, spinnerFrame: 0 };
+		const component = renderer.renderResult({ content: [{ type: "text", text: "" }], details }, options, uiTheme, {
+			sessions: ["Anna"],
+		}) as { render(width: number): readonly string[] };
+		const first = renderLines(component).join("\n");
+		options.spinnerFrame = 5;
+		const second = renderLines(component).join("\n");
+		// Spinner glyphs for frames 0 and 5 differ; a component that baked its
+		// lines at build time would render byte-identical output.
+		expect(second).not.toBe(first);
+	});
+
+	it("send result frames the ack under the composer", () => {
+		const renderer = createVibeToolRenderer("send");
+		const details: VibeToolDetails = {
+			op: "send",
+			screens: [makeScreen()],
+			send: { id: "Anna", mode: "steered" },
+		};
+		const component = renderer.renderResult(
+			{ content: [{ type: "text", text: "ack" }], details },
+			{ expanded: false, isPartial: false },
+			uiTheme,
+			{ session: "Anna", message: "Focus on the API first." },
+		) as { render(width: number): readonly string[] };
+		const text = renderLines(component).join("\n");
+
+		expect(text).toContain("vibe send → Anna");
+		expect(text).toContain("> Focus on the API first.");
+		expect(text).toContain("steered into the running turn");
+		expect(text).not.toContain("▌");
+	});
+
+	it("wait renders stacked TV screens: live trace + streamed text, idle gist, settled footer", () => {
+		const renderer = createVibeToolRenderer("wait");
+		const details: VibeToolDetails = {
+			op: "wait",
+			screens: [
+				makeScreen({
+					id: "Anna",
+					cli: "fast",
+					state: "running",
+					turnStartedAt: Date.now() - 5000,
+					turnMessage: "Build the widget",
+					trace: ["read(src/foo.ts)", "bash(bun test)"],
+					currentTool: "edit",
+					lastIntent: "Fixing the parser",
+					outputTail: ["The parser now accepts nested arrays"],
+					model: "prov/fast-model",
+				}),
+				makeScreen({ id: "Bob", cli: "good", state: "idle", turns: 2, lastActivity: "turn 2 completed" }),
+			],
+			wait: {
+				settled: [{ id: "Bob", jobId: "Bob-t2", status: "completed" }],
+				stillRunning: ["Anna"],
+				timedOut: false,
+			},
+		};
+		const component = renderer.renderResult(
+			{ content: [{ type: "text", text: "" }], details },
+			{ expanded: true, isPartial: true, spinnerFrame: 2 },
+			uiTheme,
+			{ sessions: ["Anna", "Bob"] },
+		) as { render(width: number): readonly string[] };
+		const lines = renderLines(component);
+		const text = lines.join("\n");
+
+		// One framed screen per worker, stacked.
+		expect(lines.filter(line => line.includes("╭─")).length).toBe(2);
+		expect(lines.filter(line => line.startsWith("╰─")).length).toBe(2);
+		// Live screen: header, typed turn message, trace, current tool, streamed tail.
+		expect(text).toContain("Anna");
+		// Badge glyphs are theme-driven (⟦fast⟧ on dark); assert the flavor label itself.
+		expect(text).toMatch(/fast.\s*Anna/u);
+		expect(text).toContain("> Build the widget");
+		expect(text).toContain("read(src/foo.ts)");
+		expect(text).toContain("bash(bun test)");
+		expect(text).toContain("edit: Fixing the parser");
+		expect(text).toContain("The parser now accepts nested arrays");
+		expect(text).toContain("prov/fast-model");
+		// Idle screen + settled footer.
+		expect(text).toContain("Bob");
+		expect(text).toContain("turn 2 completed");
+		expect(text).toContain("turn completed — result delivered");
+		// Wall header counts what is on air.
+		expect(text).toContain("1 on air");
+	});
+
+	it("clamps every TV line to the render width", () => {
+		const renderer = createVibeToolRenderer("list");
+		const details: VibeToolDetails = {
+			op: "list",
+			screens: [
+				makeScreen({
+					id: "VeryLongSessionNameForTruncation",
+					trace: [`read(${"x".repeat(200)})`],
+					outputTail: ["y".repeat(300)],
+					currentTool: "bash",
+					currentToolArgs: "z".repeat(200),
+				}),
+			],
+		};
+		const component = renderer.renderResult(
+			{ content: [{ type: "text", text: "" }], details },
+			{ expanded: true, isPartial: false },
+			uiTheme,
+			{},
+		) as { render(width: number): readonly string[] };
+		const width = 48;
+		for (const line of renderLines(component, width)) {
+			expect(line.length).toBeLessThanOrEqual(width);
+		}
+	});
+});

package/src/tools/bash-skill-urls.ts

@@ -66,7 +66,7 @@ export function resolveSkillUrlToPath(url: string, skills: readonly Skill[]): st
 	const hasRelativePath = rawPath !== "" && rawPath !== "/";
 
 	if (!hasRelativePath) {
-		return path.resolve(skill.filePath);
+		return path.resolve(skill.baseDir);
 	}
 
 	let relativePath: string;

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

@@ -3,7 +3,6 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { logger, postmortem, Snowflake, untilAborted } from "@oh-my-pi/pi-utils";
 import { JsRuntime, type RuntimeHooks } from "../../../eval/js/shared/runtime";
-import type { JsDisplayOutput } from "../../../eval/js/shared/types";
 import { callSessionTool } from "../../../eval/js/tool-bridge";
 import { resizeImage } from "../../../utils/image-resize";
 import type { ToolSession } from "../../index";
@@ -14,6 +13,7 @@ import { type AriaSnapshotOptions, buildAriaSnapshotScript } from "../aria/aria-
 import { DEFAULT_VIEWPORT } from "../launch";
 import { extractReadableFromHtml, type ReadableFormat } from "../readable";
 import { bindBrowserRunFacade, waitForBrowserRun } from "../run-cancellation";
+import { cloneSafe, RunOutput } from "../run-output";
 import type { Observation, ReadyInfo, RunResultOk, ScreenshotResult, SessionSnapshot } from "../tab-protocol";
 import {
 	type CmuxEvalResult,
@@ -24,7 +24,8 @@ import {
 	cmuxSnapshotToObservation,
 	GEOMETRY_SCRIPT,
 	mapWaitUntil,
-	serializeEval,
+	serializeEvalWithEnvelope,
+	unwrapEvalEnvelope,
 } from "./rpc";
 import type { CmuxSocketClient } from "./socket-client";
 
@@ -43,7 +44,7 @@ interface ObserveOptions {
 
 interface RunContext {
 	session: SessionSnapshot;
-	displays: RunResultOk["displays"];
+	output: RunOutput;
 	screenshots: ScreenshotResult[];
 	signal: AbortSignal;
 	timeoutMs: number;
@@ -445,10 +446,14 @@ export class CmuxTab {
 		fn: string | ((...args: TArgs) => TResult | Promise<TResult>),
 		...args: TArgs
 	): Promise<TResult> {
-		const result = (await this.#request("browser.eval", {
-			script: serializeEval(fn as string | ((...args: unknown[]) => unknown), args),
-		})) as CmuxEvalResult;
-		return result.value as TResult;
+		// A script that throws inside the daemon comes back as a bare
+		// `js_error: A JavaScript exception occurred` with no message or stack.
+		// Catch page-side instead so the exception is diagnosable, and turn the
+		// daemon's other blind spot — Promise return values it cannot
+		// serialize — into an actionable error instead of "unsupported type".
+		const script = serializeEvalWithEnvelope(fn as string | ((...args: unknown[]) => unknown), args);
+		const result = (await this.#request("browser.eval", { script })) as CmuxEvalResult;
+		return unwrapEvalEnvelope<TResult>(result.value, "tab.evaluate()");
 	}
 
 	async scrollIntoView(selector: string): Promise<void> {
@@ -479,10 +484,22 @@ export class CmuxTab {
 
 	async screenshot(opts: ScreenshotOptions = {}): Promise<ScreenshotResult> {
 		const context = this.#requireRunContext("tab.screenshot()");
+		// The cmux daemon's `browser.screenshot` captures the surface viewport
+		// only — it has no element-clip or full-page mode, and Bun.Image cannot
+		// crop locally. Degrade transparently instead of silently mislabeling
+		// the capture: scroll the element into view, then TELL the model the
+		// image is the full viewport (reports showed selector captures being
+		// consumed as element crops).
+		const captureNotes: string[] = [];
 		if (opts.selector) {
 			await this.scrollIntoView(opts.selector);
+			captureNotes.push(
+				`selector ${JSON.stringify(opts.selector)} was scrolled into view, but this surface cannot clip to an element — the image is the full viewport`,
+			);
+		}
+		if (opts.fullPage) {
+			captureNotes.push("fullPage is unavailable on this surface — the image is the viewport only");
 		}
-		void opts.fullPage;
 		const result = await this.#captureScreenshotPng(context.timeoutMs);
 		const buffer = Buffer.from(result.png_base64, "base64");
 		const captureMime = "image/png";
@@ -528,8 +545,11 @@ export class CmuxTab {
 				dest,
 				resized,
 			});
-			context.displays.push({ type: "text", text: lines.join("\n") });
-			context.displays.push({ type: "image", data: resized.data, mimeType: resized.mimeType });
+			if (captureNotes.length > 0) {
+				lines.push(`[cmux surface: ${captureNotes.join("; ")}]`);
+			}
+			context.output.push({ type: "text", text: lines.join("\n") });
+			context.output.push({ type: "image", data: resized.data, mimeType: resized.mimeType });
 		}
 		return info;
 	}
@@ -724,7 +744,12 @@ export class CmuxTab {
 			const callable = (0, eval)("(" + source + ")");
 			return callable(element, ...args);
 		})()`;
-		return await this.#evalScript<TResult>(script);
+		// Envelope so a stale selector or a throwing callback reports its actual
+		// error instead of the daemon's generic js_error (see tab.evaluate()).
+		const result = (await this.#request("browser.eval", {
+			script: serializeEvalWithEnvelope(script, []),
+		})) as CmuxEvalResult;
+		return unwrapEvalEnvelope<TResult>(result.value, "elementHandle.evaluate()");
 	}
 
 	async pageContent(): Promise<string> {
@@ -1097,6 +1122,10 @@ class CmuxElementHandle {
 		await this.#tab.fill(this.#selector, value);
 	}
 
+	async press(key: string): Promise<void> {
+		await this.#tab.press(key, { selector: this.#selector });
+	}
+
 	async focus(): Promise<void> {
 		await this.#tab.focus(this.#selector);
 	}
@@ -1284,10 +1313,10 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 	const signal = AbortSignal.any(
 		opts.signal ? [timeoutSignal, opts.signal, runAc.signal] : [timeoutSignal, runAc.signal],
 	);
-	const displays: RunResultOk["displays"] = [];
+	const output = new RunOutput();
 	const screenshots: ScreenshotResult[] = [];
 	const runId = crypto.randomUUID();
-	tab.setRunContext({ session: opts.snapshot, displays, screenshots, signal, timeoutMs: opts.timeoutMs });
+	tab.setRunContext({ session: opts.snapshot, output, screenshots, signal, timeoutMs: opts.timeoutMs });
 
 	const { promise: cancelRejection, reject } = Promise.withResolvers<never>();
 	// If the synchronous setup below throws (same-realm ownership conflict)
@@ -1329,11 +1358,12 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 		const hooks: RuntimeHooks = {
 			onText: chunk => {
 				throwIfAborted(signal);
+				output.pushText(chunk);
 				logger.debug(chunk.replace(/\n$/, ""));
 			},
-			onDisplay: output => {
+			onDisplay: displayed => {
 				throwIfAborted(signal);
-				pushDisplay(displays, output);
+				output.pushDisplay(displayed);
 			},
 			callTool: (name, args) => {
 				throwIfAborted(signal);
@@ -1346,7 +1376,7 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 			runtime.run(opts.code, `cmux-run-${runId}.js`, hooks, { runId, cwd: opts.snapshot.cwd }),
 			cancelRejection,
 		]);
-		return { displays, returnValue: cloneSafe(returnValue), screenshots };
+		return { displays: output.finish(), returnValue: cloneSafe(returnValue), screenshots };
 	} finally {
 		signal.removeEventListener("abort", onAbort);
 		runAc.abort(postmortem.markExpectedCleanupError(new ToolAbortError("Browser run ended")));
@@ -1354,38 +1384,6 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 	}
 }
 
-function pushDisplay(displays: RunResultOk["displays"], output: JsDisplayOutput): void {
-	if (output.type === "image") {
-		displays.push({ type: "image", data: output.data, mimeType: output.mimeType });
-		return;
-	}
-	if (output.type === "json") {
-		displays.push({ type: "text", text: safeJsonStringify(output.data) });
-		return;
-	}
-	displays.push({ type: "text", text: safeJsonStringify(output.event) });
-}
-
-function safeJsonStringify(value: unknown): string {
-	try {
-		return JSON.stringify(value, null, 2);
-	} catch {
-		return String(value);
-	}
-}
-
-function cloneSafe(value: unknown): unknown {
-	if (value === undefined) return undefined;
-	try {
-		structuredClone(value);
-		return value;
-	} catch {}
-	try {
-		return JSON.parse(JSON.stringify(value)) as unknown;
-	} catch {}
-	return String(value);
-}
-
 function numberFrom(value: unknown, fallback: number): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }

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

@@ -1,3 +1,4 @@
+import { ToolError } from "../../tool-errors";
 import type { Observation, ObservationEntry } from "../tab-protocol";
 
 export interface CmuxKind {
@@ -120,6 +121,55 @@ export function serializeEval(fn: string | ((...args: unknown[]) => unknown), ar
 	return `(${fn.toString()})(${args.map(arg => JSON.stringify(arg)).join(",")})`;
 }
 
+/**
+ * Like {@link serializeEval}, but wraps the expression in a page-side
+ * try/catch envelope so a throwing script surfaces its message + stack
+ * instead of the daemon's opaque `js_error: A JavaScript exception occurred`,
+ * and a Promise return (which the daemon cannot serialize) is flagged
+ * explicitly rather than failing as "unsupported type".
+ *
+ * String scripts run through indirect eval to keep global-scope semantics;
+ * function sources are already expressions and are invoked directly.
+ * `undefined` results come back as `null` (JSON cannot carry `undefined`).
+ * Decode with {@link unwrapEvalEnvelope}.
+ */
+export function serializeEvalWithEnvelope(fn: string | ((...args: unknown[]) => unknown), args: unknown[]): string {
+	const inner = serializeEval(fn, args);
+	const expr = typeof fn === "string" ? `(0, eval)(${JSON.stringify(inner)})` : inner;
+	return `(() => {
+		try {
+			const __v = (${expr});
+			if (__v && typeof __v.then === "function") return { __ompPromise: true };
+			return { __ompOk: __v === undefined ? null : __v };
+		} catch (e) {
+			return { __ompErr: (e && (e.stack || e.message)) || String(e) };
+		}
+	})()`;
+}
+
+/**
+ * Decode a {@link serializeEvalWithEnvelope} result: rethrow page-side
+ * exceptions as rich {@link ToolError}s, reject unserializable Promise
+ * returns with an actionable message, and pass through values from daemons
+ * that did not run the wrapper.
+ */
+export function unwrapEvalEnvelope<TResult>(value: unknown, label: string): TResult {
+	if (value && typeof value === "object") {
+		if ("__ompErr" in value && typeof value.__ompErr === "string") {
+			throw new ToolError(`${label} threw a JavaScript exception:\n${value.__ompErr}`);
+		}
+		if ("__ompPromise" in value && value.__ompPromise === true) {
+			throw new ToolError(
+				`${label} returned a Promise, but this surface evaluates synchronously and cannot await it — return a plain value (poll with waitForFunction for async state instead)`,
+			);
+		}
+		if ("__ompOk" in value) {
+			return value.__ompOk as TResult;
+		}
+	}
+	return value as TResult;
+}
+
 export function mapWaitUntil(waitUntil: string | undefined): "interactive" | "complete" {
 	return waitUntil === "domcontentloaded" ? "interactive" : "complete";
 }