@xopcai/xopc 0.0.251 → 0.0.253

package/dist/src/agent/tools/browser-automation-tool.d.ts

@@ -0,0 +1,121 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { BrowserAutomationService } from '../../browser/automations/index.js';
+declare const BrowserAutomationToolSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"get">, import("@sinclair/typebox").TLiteral<"save">, import("@sinclair/typebox").TLiteral<"enable">, import("@sinclair/typebox").TLiteral<"disable">, import("@sinclair/typebox").TLiteral<"delete">, import("@sinclair/typebox").TLiteral<"run">]>;
+    automationId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    definition: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        name: import("@sinclair/typebox").TString;
+        description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        allowedDomains: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+        risk: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"draft">, import("@sinclair/typebox").TLiteral<"external_effect">, import("@sinclair/typebox").TLiteral<"destructive">, import("@sinclair/typebox").TLiteral<"sensitive">]>;
+        inputs: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+            type: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"string">, import("@sinclair/typebox").TLiteral<"number">, import("@sinclair/typebox").TLiteral<"boolean">]>;
+            required: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+            default: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean]>>;
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            choices: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean]>>>;
+        }>>;
+        steps: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"navigate">;
+            url: import("@sinclair/typebox").TString;
+            expect: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                urlIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                titleIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                textIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>>;
+            }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"click">;
+            target: import("@sinclair/typebox").TObject<{
+                role: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nameIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>;
+            expect: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                urlIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                titleIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                textIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>>;
+            }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"fill">;
+            target: import("@sinclair/typebox").TObject<{
+                role: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nameIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>;
+            value: import("@sinclair/typebox").TString;
+            submit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+            expect: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                urlIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                titleIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                textIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>>;
+            }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"select">;
+            target: import("@sinclair/typebox").TObject<{
+                role: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nameIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>;
+            value: import("@sinclair/typebox").TString;
+            expect: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                urlIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                titleIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                textIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>>;
+            }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"press">;
+            target: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                role: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nameIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            key: import("@sinclair/typebox").TString;
+            expect: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                urlIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                titleIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                textIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>>;
+            }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"scroll">;
+            target: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                role: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nameIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            deltaY: import("@sinclair/typebox").TNumber;
+            expect: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                urlIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                titleIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                textIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>>;
+            }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            action: import("@sinclair/typebox").TLiteral<"wait">;
+            condition: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"page_idle">, import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"visible">, import("@sinclair/typebox").TLiteral<"hidden">]>;
+            value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            target: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                role: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                nameIncludes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        }>]>>;
+    }>>;
+    inputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+}>;
+export declare function createBrowserAutomationTool(deps: {
+    getBrowserAutomationService: () => BrowserAutomationService | undefined;
+}): AgentTool<typeof BrowserAutomationToolSchema, Record<string, unknown>>;
+export {};

package/dist/src/agent/tools/browser-automation-tool.js

@@ -0,0 +1,197 @@
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/browser-automation-tool.ts
+const ExpectationSchema = Type.Object({
+	urlIncludes: Type.Optional(Type.String()),
+	titleIncludes: Type.Optional(Type.String()),
+	textIncludes: Type.Optional(Type.String()),
+	ref: Type.Optional(Type.String()),
+	state: Type.Optional(Type.Union([Type.Literal("visible"), Type.Literal("hidden")]))
+}, { additionalProperties: false });
+const TargetSchema = Type.Object({
+	role: Type.String(),
+	name: Type.Optional(Type.String()),
+	nameIncludes: Type.Optional(Type.String())
+}, { additionalProperties: false });
+const StepSchema = Type.Union([
+	Type.Object({
+		action: Type.Literal("navigate"),
+		url: Type.String(),
+		expect: Type.Optional(ExpectationSchema)
+	}, { additionalProperties: false }),
+	Type.Object({
+		action: Type.Literal("click"),
+		target: TargetSchema,
+		expect: Type.Optional(ExpectationSchema)
+	}, { additionalProperties: false }),
+	Type.Object({
+		action: Type.Literal("fill"),
+		target: TargetSchema,
+		value: Type.String(),
+		submit: Type.Optional(Type.Boolean()),
+		expect: Type.Optional(ExpectationSchema)
+	}, { additionalProperties: false }),
+	Type.Object({
+		action: Type.Literal("select"),
+		target: TargetSchema,
+		value: Type.String(),
+		expect: Type.Optional(ExpectationSchema)
+	}, { additionalProperties: false }),
+	Type.Object({
+		action: Type.Literal("press"),
+		target: Type.Optional(TargetSchema),
+		key: Type.String(),
+		expect: Type.Optional(ExpectationSchema)
+	}, { additionalProperties: false }),
+	Type.Object({
+		action: Type.Literal("scroll"),
+		target: Type.Optional(TargetSchema),
+		deltaY: Type.Number(),
+		expect: Type.Optional(ExpectationSchema)
+	}, { additionalProperties: false }),
+	Type.Object({
+		action: Type.Literal("wait"),
+		condition: Type.Union([
+			Type.Literal("page_idle"),
+			Type.Literal("text"),
+			Type.Literal("visible"),
+			Type.Literal("hidden")
+		]),
+		value: Type.Optional(Type.String()),
+		target: Type.Optional(TargetSchema),
+		timeoutMs: Type.Optional(Type.Integer())
+	}, { additionalProperties: false })
+]);
+const BrowserAutomationToolSchema = Type.Object({
+	action: Type.Union([
+		Type.Literal("list"),
+		Type.Literal("get"),
+		Type.Literal("save"),
+		Type.Literal("enable"),
+		Type.Literal("disable"),
+		Type.Literal("delete"),
+		Type.Literal("run")
+	]),
+	automationId: Type.Optional(Type.String()),
+	definition: Type.Optional(Type.Object({
+		id: Type.String(),
+		name: Type.String(),
+		description: Type.Optional(Type.String()),
+		allowedDomains: Type.Array(Type.String()),
+		risk: Type.Union([
+			Type.Literal("read"),
+			Type.Literal("draft"),
+			Type.Literal("external_effect"),
+			Type.Literal("destructive"),
+			Type.Literal("sensitive")
+		]),
+		inputs: Type.Record(Type.String(), Type.Object({
+			type: Type.Union([
+				Type.Literal("string"),
+				Type.Literal("number"),
+				Type.Literal("boolean")
+			]),
+			required: Type.Optional(Type.Boolean()),
+			default: Type.Optional(Type.Union([
+				Type.String(),
+				Type.Number(),
+				Type.Boolean()
+			])),
+			description: Type.Optional(Type.String()),
+			choices: Type.Optional(Type.Array(Type.Union([
+				Type.String(),
+				Type.Number(),
+				Type.Boolean()
+			])))
+		}, { additionalProperties: false })),
+		steps: Type.Array(StepSchema)
+	}, { additionalProperties: false })),
+	inputs: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
+}, { additionalProperties: false });
+function createBrowserAutomationTool(deps) {
+	return {
+		name: "browser_automation",
+		label: "Browser Automation",
+		description: "Create and run strict JSON browser automations. Saved steps use semantic role/name targets and exact allowed domains; CSS, XPath, JavaScript, cookies, and network access are not supported.",
+		parameters: BrowserAutomationToolSchema,
+		async execute(_toolCallId, params, signal) {
+			const service = deps.getBrowserAutomationService();
+			if (!service) return output("Browser automation is unavailable.", { ok: false });
+			if (params.action === "list") {
+				const automations = service.list();
+				return output(automations.length ? automations.map((item) => `- ${item.id}: ${item.definition.name} (${item.status}, ${item.definition.risk})`).join("\n") : "No browser automations.", {
+					ok: true,
+					automations
+				});
+			}
+			if (params.action === "save") {
+				if (!params.definition) return output("definition is required.", { ok: false });
+				try {
+					const automation = service.save({ definition: params.definition });
+					return output(`Saved browser automation: ${automation.definition.name}`, {
+						ok: true,
+						automation
+					});
+				} catch (error) {
+					return output(`Could not save browser automation: ${message(error)}`, {
+						ok: false,
+						error: message(error)
+					});
+				}
+			}
+			const id = params.automationId?.trim();
+			if (!id) return output("automationId is required.", { ok: false });
+			const current = service.get(id);
+			if (params.action === "get") return current ? output(JSON.stringify(current.definition, null, 2), {
+				ok: true,
+				automation: current
+			}) : output(`Browser automation not found: ${id}`, { ok: false });
+			if (params.action === "enable" || params.action === "disable") {
+				if (!current) return output(`Browser automation not found: ${id}`, { ok: false });
+				const automation = service.save({
+					definition: current.definition,
+					expectedId: id,
+					status: params.action === "enable" ? "enabled" : "disabled"
+				});
+				return output(`${automation.definition.name} is ${automation.status}.`, {
+					ok: true,
+					automation
+				});
+			}
+			if (params.action === "delete") try {
+				const removed = service.remove(id);
+				return output(removed ? `Deleted browser automation: ${id}` : `Browser automation not found: ${id}`, { ok: removed });
+			} catch (error) {
+				return output(`Could not delete browser automation: ${message(error)}`, {
+					ok: false,
+					error: message(error)
+				});
+			}
+			try {
+				const run = await service.runAndWait(id, params.inputs ?? {}, signal);
+				return output(run.status === "succeeded" ? `Browser automation ${id} completed.` : `Browser automation ${id} ${run.status}: ${run.error ?? "No details"}`, {
+					ok: run.status === "succeeded",
+					run
+				});
+			} catch (error) {
+				return output(`Browser automation failed: ${message(error)}`, {
+					ok: false,
+					error: message(error)
+				});
+			}
+		}
+	};
+}
+function output(text, details) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		details
+	};
+}
+function message(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { createBrowserAutomationTool };

package/dist/src/agent/tools/clarify-tool.d.ts

@@ -3,11 +3,25 @@ export type ClarifyRequestPayload = {
     kind?: 'approval';
     question: string;
     choices?: string[];
-    default?: string;
+    suggestedAnswer?: string;
+    /** Stable hash of the exact operation guarded by an approval. */
+    approvalKey?: string;
 };
-export type GatewayClarifyRequestFn = (sessionKey: string, request: ClarifyRequestPayload) => Promise<string>;
+export type ClarifyRequestResult = {
+    status: 'answered';
+    answer: string;
+} | {
+    status: 'waiting';
+    waitId: string;
+    expiresAt?: number;
+};
+export type GatewayClarifyRequestFn = (context: {
+    sessionKey: string;
+    runId: string;
+    toolCallId: string;
+}, request: ClarifyRequestPayload) => Promise<ClarifyRequestResult>;
 export interface ClarifyToolDeps {
     /** Resolve a per-turn callback; returns null when clarification is unavailable. */
-    resolveAskUser: () => ((request: ClarifyRequestPayload) => Promise<string>) | null;
+    resolveAskUser: (toolCallId: string) => ((request: ClarifyRequestPayload) => Promise<ClarifyRequestResult>) | null;
 }
 export declare function createClarifyTool(deps: ClarifyToolDeps): AgentTool;

package/dist/src/agent/tools/clarify-tool.js

@@ -7,7 +7,7 @@ const ClarifySchema = Type.Object({
 		minItems: 2,
 		maxItems: 10
 	})),
-	default: Type.Optional(Type.String({ description: "Default answer if the user does not respond within timeout." }))
+	suggestedAnswer: Type.Optional(Type.String({ description: "Optional recommendation shown to the user. It is never selected automatically." }))
 });
 function waitForAbort(signal) {
 	return new Promise((_, reject) => {
@@ -23,40 +23,42 @@ function createClarifyTool(deps) {
 	return {
 		name: "clarify",
 		label: "❓ Clarify",
-		description: "Ask the user a clarifying question and wait for their response.\n\nUse this when you need more information to proceed correctly, rather than guessing.\n\nWHEN TO USE:\n- Ambiguous instructions with multiple valid interpretations\n- Missing critical information (which file, which approach, etc.)\n- Confirming destructive or irreversible actions\n\nWHEN NOT TO USE:\n- When you can reasonably infer the answer from context\n- For trivial decisions that do not affect the task\n- When the user explicitly said \"just do it\" or \"your choice\"\n\nTIPS:\n- Provide choices when there are clear options (faster for the user)\n- Keep questions short and specific\n- Include a default when one option is clearly more likely",
+		description: "Ask the user a clarifying question and pause the objective until they respond.\n\nUse this when you need more information to proceed correctly, rather than guessing.\n\nWHEN TO USE:\n- Ambiguous instructions with multiple valid interpretations\n- Missing critical information (which file, which approach, etc.)\n- Confirming destructive or irreversible actions\n\nWHEN NOT TO USE:\n- When you can reasonably infer the answer from context\n- For trivial decisions that do not affect the task\n- When the user explicitly said \"just do it\" or \"your choice\"\n\nTIPS:\n- Provide choices when there are clear options (faster for the user)\n- Keep questions short and specific\n- Include a suggested answer when one option is clearly more likely",
 		parameters: ClarifySchema,
-		async execute(_toolCallId, params, signal) {
+		async execute(toolCallId, params, signal) {
 			const p = params;
-			const askUser = deps.resolveAskUser();
-			if (!askUser) {
-				if (p.default !== void 0 && p.default !== "") return {
-					content: [{
-						type: "text",
-						text: `Interactive clarification is not available in this environment. Using default: ${p.default}`
-					}],
-					details: { answer: p.default }
-				};
-				return {
-					content: [{
-						type: "text",
-						text: "Clarification is not available in this environment (no active webchat run). Provide a default or proceed with the best assumption."
-					}],
-					details: { answer: "" }
-				};
-			}
+			const askUser = deps.resolveAskUser(toolCallId);
+			if (!askUser) return {
+				content: [{
+					type: "text",
+					text: "Clarification is not available in this environment. Proceed with the best safe assumption or explain what is missing."
+				}],
+				details: { answer: "" }
+			};
 			const payload = {
 				question: p.question,
 				choices: p.choices,
-				default: p.default
+				suggestedAnswer: p.suggestedAnswer
 			};
 			try {
-				const answer = await Promise.race([askUser(payload), waitForAbort(signal)]);
+				const result = await Promise.race([askUser(payload), waitForAbort(signal)]);
+				if (result.status === "waiting") return {
+					content: [{
+						type: "text",
+						text: "Waiting for the user to answer this clarification. End the current run now."
+					}],
+					details: {
+						answer: "",
+						waitId: result.waitId,
+						status: result.status
+					}
+				};
 				return {
 					content: [{
 						type: "text",
-						text: `User answered: ${answer}`
+						text: `User answered: ${result.answer}`
 					}],
-					details: { answer }
+					details: { answer: result.answer }
 				};
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
@@ -65,14 +67,7 @@ function createClarifyTool(deps) {
 						type: "text",
 						text: "Clarification cancelled (run aborted)."
 					}],
-					details: { answer: p.default ?? "" }
-				};
-				if (p.default !== void 0 && p.default !== "" && message.toLowerCase().includes("timeout")) return {
-					content: [{
-						type: "text",
-						text: `User did not respond in time. Using default: ${p.default}`
-					}],
-					details: { answer: p.default }
+					details: { answer: "" }
 				};
 				return {
 					content: [{

package/dist/src/agent/tools/cli-clarify.js

@@ -5,7 +5,7 @@ import * as readline from "node:readline/promises";
 * stdin/stdout prompts for `clarify` when running the CLI agent (no gateway).
 */
 function createCliReadlineClarifyRequestFn() {
-	return async (_sessionKey, req) => {
+	return async (_context, req) => {
 		const rl = readline.createInterface({
 			input: stdin,
 			output: stdout
@@ -15,19 +15,34 @@ function createCliReadlineClarifyRequestFn() {
 			if (choices && choices.length >= 2) {
 				stdout.write(`\n${req.question}\n`);
 				choices.forEach((c, i) => stdout.write(`  ${i + 1}) ${c}\n`));
-				if (req.default) stdout.write(`  (default: ${req.default})\n`);
+				if (req.suggestedAnswer) stdout.write(`  (recommended: ${req.suggestedAnswer})\n`);
 				const raw = (await rl.question("Choice (number or exact text): ")).trim();
 				const n = parseInt(raw, 10);
-				if (!Number.isNaN(n) && n >= 1 && n <= choices.length) return choices[n - 1];
-				if (raw) return raw;
-				if (req.default) return req.default;
+				if (!Number.isNaN(n) && n >= 1 && n <= choices.length) return {
+					status: "answered",
+					answer: choices[n - 1]
+				};
+				if (raw) return {
+					status: "answered",
+					answer: raw
+				};
+				if (req.suggestedAnswer) return {
+					status: "answered",
+					answer: req.suggestedAnswer
+				};
 				throw new Error("No answer provided");
 			}
 			stdout.write(`\n${req.question}\n`);
-			if (req.default) stdout.write(`(Press Enter for default: ${req.default})\n`);
+			if (req.suggestedAnswer) stdout.write(`(Press Enter for recommendation: ${req.suggestedAnswer})\n`);
 			const raw = (await rl.question("> ")).trim();
-			if (raw) return raw;
-			if (req.default) return req.default;
+			if (raw) return {
+				status: "answered",
+				answer: raw
+			};
+			if (req.suggestedAnswer) return {
+				status: "answered",
+				answer: req.suggestedAnswer
+			};
 			throw new Error("No answer provided");
 		} finally {
 			rl.close();

package/dist/src/agent/tools/factory.d.ts

@@ -18,7 +18,7 @@ import type { MemoryManager } from '../memory/manager.js';
 import type { SessionStore } from '../../session/store.js';
 import type { GatewayClarifyRequestFn } from './clarify-tool.js';
 import type { AutomationService } from '../../automations/index.js';
-import type { BrowserRecipeService } from '../../browser/recipes/index.js';
+import type { BrowserAutomationService } from '../../browser/automations/index.js';
 import type { NotesService } from '../../notes/index.js';
 import type { ProjectService } from '../../projects/index.js';
 import type { LocalAppService } from '../../local-apps/index.js';
@@ -54,7 +54,8 @@ export interface ToolFactoryDeps {
     };
     /** Gateway: enables the `automation` tool. */
     getAutomationService?: () => AutomationService | undefined;
-    getBrowserRecipeService?: () => BrowserRecipeService | undefined;
+    getBrowserAutomationService?: () => BrowserAutomationService | undefined;
+    emitBrowserEvent?: (type: string, payload: unknown) => void;
     /** Gateway: enables the `xopc_use` product-object tool. */
     getNotesService?: () => NotesService | undefined;
     getProjectService?: () => ProjectService | undefined;
@@ -98,10 +99,8 @@ export interface CreateCoreToolsOptions {
 }
 export declare class AgentToolsFactory {
     private deps;
-    private browserManager;
-    /** One dialog/console supervisor per chat session (browser tab). */
-    private readonly browserTaskSupervisors;
-    /** Cached readiness probe — keyed by backend mode + extension host:port. */
+    private browserRuntime;
+    /** Cached readiness probe keyed by the active driver configuration. */
     private browserReadinessCache;
     constructor(deps: ToolFactoryDeps);
     private prepareRuntimeEnv;
@@ -109,9 +108,7 @@ export declare class AgentToolsFactory {
     private checkBrowserReadinessCached;
     /** Invalidate the readiness cache (config hot-reload, settings-page save, etc.). */
     invalidateBrowserReadinessCache(): void;
-    private browserSupervisorForTask;
-    private acquireBrowserPage;
-    private ensureBrowserManager;
+    private ensureBrowserRuntime;
     /** Close Playwright and all pages (gateway stop, agent manager dispose, or config hot-reload). */
     shutdownBrowser(): Promise<void>;
     /** Drop the tab for a session when its agent instance is removed. */