@gajae-code/coding-agent 0.4.1 → 0.4.3

package/src/session/agent-session.ts

@@ -89,6 +89,15 @@ export interface ForkContextSeedMetadata {
 	skippedReasons: Record<string, number>;
 }
 
+export interface PurgeQueuedCustomMessagesResult {
+	agentSteering: number;
+	agentFollowUp: number;
+	pendingNextTurn: number;
+	displaySteering: number;
+	displayFollowUp: number;
+	totalExecutable: number;
+}
+
 export interface ForkContextSeed {
 	messages: Message[];
 	agentMessages: AgentMessage[];
@@ -822,6 +831,23 @@ function extractPermissionLocations(
  *  rely on the existing text-equality match. */
 type QueuedDisplayEntry = { text: string; tag?: string };
 
+/** A custom message contributed at the before-agent-start point. */
+export type BeforeAgentStartInternalMessage = Pick<
+	CustomMessage,
+	"customType" | "content" | "display" | "details" | "attribution"
+>;
+
+/**
+ * Internal (first-party, non-user-hook) contributor invoked at the active
+ * before-agent-start point alongside the extension runner. Returns an optional
+ * custom message to append to the prompt context. Errors are nonfatal.
+ */
+export type BeforeAgentStartContributor = (event: {
+	prompt: string;
+	images?: ImageContent[];
+	sessionId: string | undefined;
+}) => Promise<BeforeAgentStartInternalMessage | undefined>;
+
 export class AgentSession {
 	readonly agent: Agent;
 	readonly sessionManager: SessionManager;
@@ -922,6 +948,8 @@ export class AgentSession {
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
 	#turnIndex = 0;
+	// First-party internal before-agent-start contributors (not user hooks).
+	#beforeAgentStartContributors: BeforeAgentStartContributor[] = [];
 
 	#skills: Skill[];
 	#skillWarnings: SkillWarning[];
@@ -4344,7 +4372,10 @@ export class AgentSession {
 
 	async #activatePendingGjcGoalModeRequest(): Promise<boolean> {
 		if (!this.settings.get("goal.enabled")) return false;
-		const pendingGoal = await consumePendingGoalModeRequest(this.sessionManager.getCwd());
+		const pendingGoal = await consumePendingGoalModeRequest(
+			this.sessionManager.getCwd(),
+			this.sessionManager.getSessionId(),
+		);
 		if (!pendingGoal) return false;
 		const currentState = this.getGoalModeState();
 		if (currentState?.goal && currentState.goal.status !== "complete" && currentState.goal.status !== "dropped") {
@@ -4756,6 +4787,9 @@ export class AgentSession {
 
 			const beforeAgentStartSystemPrompt = await this.#buildSystemPromptForAgentStart(expandedText);
 
+			const promptAttribution: "user" | "agent" | undefined =
+				"attribution" in message ? message.attribution : undefined;
+
 			// Emit before_agent_start extension event
 			if (this.#extensionRunner) {
 				const result = await this.#extensionRunner.emitBeforeAgentStart(
@@ -4764,19 +4798,7 @@ export class AgentSession {
 					beforeAgentStartSystemPrompt,
 				);
 				if (result?.messages) {
-					const promptAttribution: "user" | "agent" | undefined =
-						"attribution" in message ? message.attribution : undefined;
-					for (const msg of result.messages) {
-						messages.push({
-							role: "custom",
-							customType: msg.customType,
-							content: msg.content,
-							display: msg.display,
-							details: msg.details,
-							attribution: msg.attribution ?? promptAttribution ?? (message.role === "user" ? "user" : "agent"),
-							timestamp: Date.now(),
-						});
-					}
+					this.#appendBeforeAgentStartCustomMessages(messages, result.messages, promptAttribution, message.role);
 				}
 
 				if (result?.systemPrompt !== undefined) {
@@ -4788,6 +4810,26 @@ export class AgentSession {
 				this.agent.setSystemPrompt(beforeAgentStartSystemPrompt);
 			}
 
+			// Invoke first-party internal before-agent-start contributors. These run
+			// alongside the extension runner (not via user-loaded hooks) and append
+			// through the same custom-message attribution path. Errors are nonfatal.
+			if (this.#beforeAgentStartContributors.length > 0) {
+				const contributed: BeforeAgentStartInternalMessage[] = [];
+				for (const contributor of this.#beforeAgentStartContributors) {
+					try {
+						const msg = await contributor({
+							prompt: expandedText,
+							images: options?.images,
+							sessionId: this.sessionId,
+						});
+						if (msg) contributed.push(msg);
+					} catch (err) {
+						logger.debug("before_agent_start contributor failed", { error: String(err) });
+					}
+				}
+				this.#appendBeforeAgentStartCustomMessages(messages, contributed, promptAttribution, message.role);
+			}
+
 			// Bail out if a newer abort/prompt cycle has started since we began setup
 			if (this.#promptGeneration !== generation) {
 				return;
@@ -5028,6 +5070,10 @@ export class AgentSession {
 		this.#queueHiddenNextTurnMessage(message, true);
 	}
 
+	queueDeferredMessageForTests(message: CustomMessage, triggerTurn = true): void {
+		this.#queueHiddenNextTurnMessage(message, triggerTurn);
+	}
+
 	#queueHiddenNextTurnMessage(message: CustomMessage, triggerTurn: boolean): void {
 		this.#pendingNextTurnMessages.push(message);
 		if (!triggerTurn) return;
@@ -5200,6 +5246,46 @@ export class AgentSession {
 		);
 	}
 
+	/** Remove undelivered queued custom messages matching `predicate` from executable queues and tagged display mirrors. */
+	purgeQueuedCustomMessages(predicate: (message: CustomMessage) => boolean): PurgeQueuedCustomMessagesResult {
+		const isMatch = (m: AgentMessage): boolean => m.role === "custom" && predicate(m as CustomMessage);
+		const removedTags = new Set<string>();
+		for (const m of [...this.agent.snapshotSteering(), ...this.agent.snapshotFollowUp()]) {
+			if (isMatch(m)) {
+				const tag = readPendingDisplayTag((m as CustomMessage).details);
+				if (tag) removedTags.add(tag);
+			}
+		}
+		const agentRemoved = this.agent.removeQueuedMessages(isMatch);
+		const beforeNext = this.#pendingNextTurnMessages.length;
+		for (const m of this.#pendingNextTurnMessages) {
+			if (predicate(m)) {
+				const tag = readPendingDisplayTag(m.details);
+				if (tag) removedTags.add(tag);
+			}
+		}
+		this.#pendingNextTurnMessages = this.#pendingNextTurnMessages.filter(m => !predicate(m));
+		const pendingNextTurn = beforeNext - this.#pendingNextTurnMessages.length;
+		let displaySteering = 0;
+		let displayFollowUp = 0;
+		if (removedTags.size > 0) {
+			const beforeS = this.#steeringMessages.length;
+			this.#steeringMessages = this.#steeringMessages.filter(e => !(e.tag && removedTags.has(e.tag)));
+			displaySteering = beforeS - this.#steeringMessages.length;
+			const beforeF = this.#followUpMessages.length;
+			this.#followUpMessages = this.#followUpMessages.filter(e => !(e.tag && removedTags.has(e.tag)));
+			displayFollowUp = beforeF - this.#followUpMessages.length;
+		}
+		return {
+			agentSteering: agentRemoved.steering,
+			agentFollowUp: agentRemoved.followUp,
+			pendingNextTurn,
+			displaySteering,
+			displayFollowUp,
+			totalExecutable: agentRemoved.total + pendingNextTurn,
+		};
+	}
+
 	/**
 	 * Send a user message to the agent.
 	 * When deliverAs is set, queue the message instead of starting a new turn.
@@ -5674,7 +5760,7 @@ export class AgentSession {
 	/**
 	 * Cycle through configured role models in a fixed order.
 	 * Skips missing roles.
-	 * @param roleOrder - Order of roles to cycle through (e.g., ["slow", "default", "smol"])
+	 * @param roleOrder - Order of roles to cycle through (e.g., ["default"])
 	 * @param options - Optional settings: `temporary` to not persist to settings
 	 */
 	async cycleRoleModels(
@@ -6420,7 +6506,7 @@ export class AgentSession {
 		if (pruneResult) {
 			contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
 		}
-		if (shouldCompact(contextTokens, contextWindow, compactionSettings)) {
+		if (shouldCompact(contextTokens, contextWindow, compactionSettings, this.model?.maxTokens ?? 0)) {
 			// Try promotion first — if a larger model is available, switch instead of compacting
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (!promoted) {
@@ -7056,7 +7142,7 @@ export class AgentSession {
 		}
 		return new Error(
 			`Compaction requires usable credentials for ${currentModel.provider}/${currentModel.id}. ` +
-				`Configure ${currentModel.provider} credentials or assign an authenticated fallback role such as modelRoles.smol.`,
+				`Configure ${currentModel.provider} credentials or assign an authenticated fallback via modelRoles.default.`,
 		);
 	}
 
@@ -9622,6 +9708,42 @@ export class AgentSession {
 		return this.#extensionRunner?.hasHandlers(eventType) ?? false;
 	}
 
+	/**
+	 * Register a first-party internal before-agent-start contributor. Returns an
+	 * unregister function. This is NOT user-facing hook discovery; it is an
+	 * in-core seam invoked alongside the extension runner.
+	 */
+	registerBeforeAgentStartContributor(contributor: BeforeAgentStartContributor): () => void {
+		this.#beforeAgentStartContributors.push(contributor);
+		return () => {
+			const idx = this.#beforeAgentStartContributors.indexOf(contributor);
+			if (idx !== -1) this.#beforeAgentStartContributors.splice(idx, 1);
+		};
+	}
+
+	/**
+	 * Append before-agent-start custom messages (from the extension runner or
+	 * internal contributors) using one shared attribution/defaulting path.
+	 */
+	#appendBeforeAgentStartCustomMessages(
+		target: AgentMessage[],
+		returned: readonly BeforeAgentStartInternalMessage[],
+		promptAttribution: "user" | "agent" | undefined,
+		messageRole: string,
+	): void {
+		for (const msg of returned) {
+			target.push({
+				role: "custom",
+				customType: msg.customType,
+				content: msg.content,
+				display: msg.display,
+				details: msg.details,
+				attribution: msg.attribution ?? promptAttribution ?? (messageRole === "user" ? "user" : "agent"),
+				timestamp: Date.now(),
+			});
+		}
+	}
+
 	/**
 	 * Get the extension runner (for setting UI context and error handlers).
 	 */

package/src/session/session-manager.ts

@@ -104,7 +104,7 @@ export interface ModelChangeEntry extends SessionEntryBase {
 	type: "model_change";
 	/** Model in "provider/modelId" format */
 	model: string;
-	/** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
+	/** Role: "default" or an agent role. Undefined treated as "default" */
 	role?: string;
 }
 

package/src/task/agents.ts

@@ -59,7 +59,7 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 			name: "task",
 			description: "General-purpose subagent with full capabilities for delegated multi-step tasks",
 			spawns: "*",
-			model: "pi/task",
+			model: "pi/default",
 			thinkingLevel: Effort.Medium,
 			hide: true,
 		},

package/src/tools/bash.ts

@@ -609,6 +609,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			label?: string;
 			ctx?: AgentToolContext;
 			onRawLine?: (line: string, jobId: string) => void;
+			shouldAcceptRawLine?: (jobId: string) => boolean;
+			lifecycle?: import("../async").AsyncJobLifecycleCleanup;
 		} = {},
 	): Promise<{ jobId: string; label: string; commandCwd: string }> {
 		const manager = AsyncJobManager.instance();
@@ -624,12 +626,14 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		let cursorOffset = 0;
 		let lineBuffer = "";
 		const dispatchLines = (chunk: string) => {
+			if (opts.shouldAcceptRawLine?.(currentJobId) === false) return;
 			if (!onRawLine) return;
 			lineBuffer += chunk;
 			let newlineIndex = lineBuffer.indexOf("\n");
 			while (newlineIndex !== -1) {
 				const line = lineBuffer.slice(0, newlineIndex);
 				lineBuffer = lineBuffer.slice(newlineIndex + 1);
+				if (opts.shouldAcceptRawLine?.(currentJobId) === false) return;
 				try {
 					onRawLine(line, currentJobId);
 				} catch (error) {
@@ -642,6 +646,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		};
 		const flushTrailingLine = () => {
 			if (!onRawLine) return;
+			if (opts.shouldAcceptRawLine?.(currentJobId) === false) return;
 			if (lineBuffer.length === 0) return;
 			const remainder = lineBuffer;
 			lineBuffer = "";
@@ -693,7 +698,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					throw error instanceof Error ? error : new Error(String(error));
 				}
 			},
-			{ ownerId, metadata: { monitor: true } },
+			{ ownerId, metadata: { monitor: true }, lifecycle: opts.lifecycle },
 		);
 		currentJobId = jobId;
 		return { jobId, label, commandCwd: prepared.commandCwd };

package/src/tools/browser/actions.ts

@@ -0,0 +1,189 @@
+/**
+ * Structured browser action space.
+ *
+ * Adapts the SOTA computer-use / browser-use pattern: instead of authoring raw
+ * JavaScript for every interaction, the model emits a list of structured verbs
+ * (navigate / click / type / …) that reference elements by the numeric `id`
+ * returned from {@link Observation}. Each verb is compiled onto the existing
+ * in-tab `tab.*` helpers and executed through the same worker `run` path, so the
+ * worker protocol is unchanged and the raw-JS `run` escape hatch still works.
+ */
+
+export type BrowserActionVerb =
+	| "navigate"
+	| "click"
+	| "type"
+	| "fill"
+	| "select"
+	| "press"
+	| "scroll"
+	| "back"
+	| "wait"
+	| "observe"
+	| "extract"
+	| "screenshot";
+
+export interface BrowserActionStep {
+	verb: BrowserActionVerb;
+	/** Element id from a prior `observe` (preferred for click/type). */
+	id?: number;
+	/** CSS / puppeteer selector when not addressing by `id`. */
+	selector?: string;
+	/** Text to type. */
+	text?: string;
+	/** Value for `fill`. */
+	value?: string;
+	/** Option value(s) for `select`. */
+	values?: string[];
+	/** URL for `navigate`. */
+	url?: string;
+	/** Key for `press` (e.g. "Enter"). */
+	key?: string;
+	/** Horizontal scroll delta. */
+	dx?: number;
+	/** Vertical scroll delta. */
+	dy?: number;
+	/** Sleep duration for `wait` when no selector is given. */
+	ms?: number;
+	/** Extract format. */
+	format?: "markdown" | "text" | "html";
+	/** Navigation wait condition for `navigate`. */
+	wait_until?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+	/** Only return interactive/viewport elements for `observe`. */
+	viewport_only?: boolean;
+	include_all?: boolean;
+}
+
+const VERBS: ReadonlySet<BrowserActionVerb> = new Set([
+	"navigate",
+	"click",
+	"type",
+	"fill",
+	"select",
+	"press",
+	"scroll",
+	"back",
+	"wait",
+	"observe",
+	"extract",
+	"screenshot",
+]);
+
+/**
+ * Validate a single step's required fields. Returns an error string, or
+ * `undefined` when the step is well-formed.
+ */
+export function validateActionStep(step: BrowserActionStep, index: number): string | undefined {
+	const where = `actions[${index}] (${step.verb})`;
+	if (!VERBS.has(step.verb)) return `${where}: unknown verb`;
+	switch (step.verb) {
+		case "navigate":
+			if (!step.url?.trim()) return `${where}: 'url' is required`;
+			return undefined;
+		case "click":
+			if (step.id === undefined && !step.selector?.trim()) return `${where}: 'id' or 'selector' is required`;
+			return undefined;
+		case "type":
+			if (step.id === undefined && !step.selector?.trim()) return `${where}: 'id' or 'selector' is required`;
+			if (step.text === undefined) return `${where}: 'text' is required`;
+			return undefined;
+		case "fill":
+			if (!step.selector?.trim()) return `${where}: 'selector' is required`;
+			if (step.value === undefined) return `${where}: 'value' is required`;
+			return undefined;
+		case "select":
+			if (!step.selector?.trim()) return `${where}: 'selector' is required`;
+			if (!step.values?.length) return `${where}: 'values' is required`;
+			return undefined;
+		case "press":
+			if (!step.key?.trim()) return `${where}: 'key' is required`;
+			return undefined;
+		case "scroll":
+			if (step.dx === undefined && step.dy === undefined) return `${where}: 'dx' or 'dy' is required`;
+			return undefined;
+		case "wait":
+			if (!step.selector?.trim() && step.ms === undefined) return `${where}: 'selector' or 'ms' is required`;
+			return undefined;
+		default:
+			// back / observe / extract / screenshot take no required fields
+			return undefined;
+	}
+}
+
+/** Validate the full step list. Throws on the first invalid step. */
+export function validateActionSteps(steps: readonly BrowserActionStep[]): void {
+	if (steps.length === 0) throw new Error("browser 'act' requires a non-empty 'actions' list");
+	for (let i = 0; i < steps.length; i += 1) {
+		const error = validateActionStep(steps[i]!, i);
+		if (error) throw new Error(error);
+	}
+}
+
+/**
+ * Compile structured steps into a JS program for the in-tab `run` worker. Steps
+ * are embedded as parsed JSON (no string interpolation, so values cannot inject
+ * code) and dispatched by a fixed interpreter against the `tab` / `page` helpers.
+ */
+export function compileActionSteps(steps: readonly BrowserActionStep[]): string {
+	validateActionSteps(steps);
+	const stepsLiteral = JSON.stringify(JSON.stringify(steps));
+	return `
+const __steps = JSON.parse(${stepsLiteral});
+const __results = [];
+for (const s of __steps) {
+	switch (s.verb) {
+		case "navigate":
+			await tab.goto(s.url, s.wait_until ? { waitUntil: s.wait_until } : undefined);
+			__results.push({ verb: "navigate", url: s.url });
+			break;
+		case "click":
+			if (s.id !== undefined && s.id !== null) { await (await tab.id(s.id)).click(); }
+			else { await tab.click(s.selector); }
+			__results.push({ verb: "click", id: s.id ?? null, selector: s.selector ?? null });
+			break;
+		case "type":
+			if (s.id !== undefined && s.id !== null) { await (await tab.id(s.id)).type(s.text); }
+			else { await tab.type(s.selector, s.text); }
+			__results.push({ verb: "type", id: s.id ?? null, selector: s.selector ?? null });
+			break;
+		case "fill":
+			await tab.fill(s.selector, s.value);
+			__results.push({ verb: "fill", selector: s.selector });
+			break;
+		case "select":
+			__results.push({ verb: "select", selected: await tab.select(s.selector, ...(s.values || [])) });
+			break;
+		case "press":
+			await tab.press(s.key, s.selector ? { selector: s.selector } : undefined);
+			__results.push({ verb: "press", key: s.key });
+			break;
+		case "scroll":
+			await tab.scroll(s.dx || 0, s.dy || 0);
+			__results.push({ verb: "scroll", dx: s.dx || 0, dy: s.dy || 0 });
+			break;
+		case "back":
+			await page.goBack();
+			__results.push({ verb: "back" });
+			break;
+		case "wait":
+			if (s.selector) { await tab.waitFor(s.selector); }
+			else { await new Promise(r => setTimeout(r, s.ms)); }
+			__results.push({ verb: "wait", selector: s.selector ?? null, ms: s.ms ?? null });
+			break;
+		case "observe":
+			__results.push({ verb: "observe", observation: await tab.observe({ viewportOnly: s.viewport_only === true, includeAll: s.include_all === true }) });
+			break;
+		case "extract":
+			__results.push({ verb: "extract", content: await tab.extract(s.format || "markdown") });
+			break;
+		case "screenshot":
+			await tab.screenshot({});
+			__results.push({ verb: "screenshot" });
+			break;
+		default:
+			throw new Error("Unknown browser action verb: " + s.verb);
+	}
+}
+return __results;
+`;
+}

package/src/tools/browser.ts

@@ -3,6 +3,7 @@ import { prompt, untilAborted } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import browserDescription from "../prompts/tools/browser.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
+import { type BrowserActionStep, compileActionSteps } from "./browser/actions";
 import { acquireBrowser, type BrowserHandle, type BrowserKind, type BrowserKindTag } from "./browser/registry";
 import type { Observation, ScreenshotResult } from "./browser/tab-protocol";
 import { acquireTab, dropHeadlessTabs, getTab, releaseAllTabs, releaseTab, runInTab } from "./browser/tab-supervisor";
@@ -24,8 +25,44 @@ const appSchema = z.object({
 	target: z.string().describe("substring to pick a window").optional(),
 });
 
+const actionStepSchema = z.object({
+	verb: z
+		.enum([
+			"navigate",
+			"click",
+			"type",
+			"fill",
+			"select",
+			"press",
+			"scroll",
+			"back",
+			"wait",
+			"observe",
+			"extract",
+			"screenshot",
+		])
+		.describe("structured action verb"),
+	id: z.number().describe("element id from a prior observe").optional(),
+	selector: z.string().describe("css/puppeteer selector").optional(),
+	text: z.string().describe("text to type").optional(),
+	value: z.string().describe("value for fill").optional(),
+	values: z.array(z.string()).describe("option value(s) for select").optional(),
+	url: z.string().describe("url for navigate").optional(),
+	key: z.string().describe("key for press, e.g. Enter").optional(),
+	dx: z.number().describe("horizontal scroll delta").optional(),
+	dy: z.number().describe("vertical scroll delta").optional(),
+	ms: z.number().describe("sleep ms for wait without selector").optional(),
+	format: z.enum(["markdown", "text", "html"]).describe("extract format").optional(),
+	wait_until: z
+		.enum(["load", "domcontentloaded", "networkidle0", "networkidle2"])
+		.describe("navigation wait condition for navigate")
+		.optional(),
+	viewport_only: z.boolean().describe("observe: only viewport elements").optional(),
+	include_all: z.boolean().describe("observe: include non-interactive elements").optional(),
+});
+
 const browserSchema = z.object({
-	action: z.enum(["open", "close", "run"] as const).describe("operation"),
+	action: z.enum(["open", "close", "run", "act"] as const).describe("operation"),
 	name: z.string().describe("tab id (default 'main')").optional(),
 	url: z.string().describe("url to open").optional(),
 	app: appSchema.optional(),
@@ -45,6 +82,7 @@ const browserSchema = z.object({
 		.describe("auto-handle dialogs")
 		.optional(),
 	code: z.string().describe("js body to run in tab").optional(),
+	actions: z.array(actionStepSchema).describe("structured action steps for action 'act'").optional(),
 	timeout: z.number().default(30).describe("timeout in seconds (default 30, max 300)").optional(),
 	all: z.boolean().describe("close every tab").optional(),
 	kill: z.boolean().describe("also kill spawned-app browsers").optional(),
@@ -126,6 +164,8 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 					return await this.#close(name, params, details, signal);
 				case "run":
 					return await this.#run(name, params, details, timeoutMs, signal);
+				case "act":
+					return await this.#act(name, params, details, timeoutMs, signal);
 				default:
 					throw new ToolError(`Unsupported action: ${(params as BrowserParams).action}`);
 			}
@@ -259,6 +299,56 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 		details.result = textOnly;
 		return toolResult(details).content(content).done();
 	}
+
+	async #act(
+		name: string,
+		params: BrowserParams,
+		details: BrowserToolDetails,
+		timeoutMs: number,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<BrowserToolDetails>> {
+		const steps = (params.actions ?? []) as BrowserActionStep[];
+		if (steps.length === 0) {
+			throw new ToolError("Missing required parameter 'actions' for action 'act'.");
+		}
+		const tab = getTab(name);
+		if (!tab) {
+			throw new ToolError(`No tab named ${JSON.stringify(name)}. Open it first with action 'open'.`);
+		}
+		details.browser = tab.browser.kind.kind;
+		details.url = tab.info.url;
+
+		// compileActionSteps validates each step and produces injection-safe code
+		// (steps embedded as parsed JSON) for the existing in-tab run worker.
+		let code: string;
+		try {
+			code = compileActionSteps(steps);
+		} catch (error) {
+			throw new ToolError(error instanceof Error ? error.message : String(error));
+		}
+
+		const { displays, returnValue, screenshots } = await runInTab(name, {
+			code,
+			timeoutMs,
+			signal,
+			session: this.session,
+		});
+
+		if (screenshots.length) details.screenshots = screenshots;
+		const content = [...displays];
+		if (returnValue !== undefined) {
+			content.push({ type: "text", text: stringifyReturnValue(returnValue) });
+		}
+		if (!content.length) {
+			content.push({ type: "text", text: `Ran ${steps.length} action(s) on tab ${JSON.stringify(name)}` });
+		}
+		const textOnly = content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map(c => c.text)
+			.join("\n");
+		details.result = textOnly;
+		return toolResult(details).content(content).done();
+	}
 }
 
 function describeBrowser(handle: BrowserHandle): string {