@xopcai/xopc 0.0.251 → 0.0.253

package/dist/src/agent/mcp/oauth/mcp-oauth-store.js

@@ -1,5 +1,5 @@
-import { init_write_file_atomic, writeTextAtomic } from "../../../infra/write-file-atomic.js";
 import { init_paths, resolveMcpOAuthPath } from "../../../config/paths.js";
+import { init_write_file_atomic, writeTextAtomic } from "../../../infra/write-file-atomic.js";
 import { createHash } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";
 //#region src/agent/mcp/oauth/mcp-oauth-store.ts

package/dist/src/agent/service/direct-turn-helpers.js

@@ -1,3 +1,4 @@
+import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput } from "../../storage/sqlite/connection-wait-repository.js";
 import { resolveImageHandlingStrategy } from "../image/vision-detection.js";
 import { hydrateUserTurnForLlm } from "../inbound/attachment-pipeline.js";
@@ -87,6 +88,8 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 async function runDirectAgentTurn(deps, input) {
 	const turnId = input.runId ?? crypto.randomUUID();
 	const isConnectionResume = Boolean(getConnectionResumeInput(input.sessionKey, turnId));
+	const isClarificationResume = Boolean(getClarificationResumeInput(input.sessionKey, turnId));
+	const isResume = isConnectionResume || isClarificationResume;
 	const userPlain = extractAgentUserPlainText(input.userMessage);
 	const userContext = await deps.agentManager.prepareUserTurnContext(input.userMessage, input.sessionKey, turnId);
 	const sourceContexts = input.sourceContexts ?? [];
@@ -111,11 +114,11 @@ async function runDirectAgentTurn(deps, input) {
 		getConfig: () => deps.config,
 		abortSignal: input.abortSignal,
 		deadlineAtMs: input.deadlineAtMs,
-		beforeTurn: isConnectionResume ? void 0 : () => deps.agentManager.beginBackgroundReviewUserTurn(input.sessionKey),
+		beforeTurn: isResume ? void 0 : () => deps.agentManager.beginBackgroundReviewUserTurn(input.sessionKey),
 		onEvent: input.onEvent
 	});
-	if (!isConnectionResume) await deps.agentManager.afterAgentTurn(input.sessionKey, userPlain, turnId);
-	if (!isConnectionResume && result.stopReason !== "connection_required") deps.agentManager.scheduleBackgroundReviewAfterUserTurn(input.sessionKey);
+	if (!isResume) await deps.agentManager.afterAgentTurn(input.sessionKey, userPlain, turnId);
+	if (!isResume && result.stopReason !== "connection_required" && result.stopReason !== "clarification_required") deps.agentManager.scheduleBackgroundReviewAfterUserTurn(input.sessionKey);
 	return result;
 }
 //#endregion

package/dist/src/agent/service/process-direct-streaming.js

@@ -1,3 +1,4 @@
+import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput } from "../../storage/sqlite/connection-wait-repository.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { abortEmbeddedRun } from "../embedded/runs.js";
@@ -126,6 +127,8 @@ function pushAssistantReceipt(queue, text, runId, metadata) {
 async function* runProcessDirectStreaming(deps, input) {
 	const sessionKey = input.sessionKey ?? "agent:main:main";
 	const isConnectionResume = Boolean(input.runId && getConnectionResumeInput(sessionKey, input.runId));
+	const isClarificationResume = Boolean(input.runId && getClarificationResumeInput(sessionKey, input.runId));
+	const isInternalResume = isConnectionResume || isClarificationResume;
 	const { channel, chatId } = await deps.resolveSessionEndpoint(sessionKey);
 	const context = deps.initDirectStreamingSession(sessionKey, channel, chatId, input.origin);
 	const queue = new AsyncQueue({
@@ -276,7 +279,7 @@ async function* runProcessDirectStreaming(deps, input) {
 					if (sourceContext && !sourceContexts.some((context) => context.kind === sourceContext.kind && context.sourceId === sourceContext.sourceId)) sourceContexts.push(sourceContext);
 				}
 			}
-			if (channel === "webchat" && !isConnectionResume) {
+			if (channel === "webchat" && !isInternalResume) {
 				pushVisible({
 					type: "user_message",
 					timestamp: userMessage.timestamp ?? Date.now(),
@@ -287,7 +290,7 @@ async function* runProcessDirectStreaming(deps, input) {
 				if (textForAgent.trim()) deps.enqueueProvisionalSessionTitle?.(sessionKey, textForAgent);
 			}
 			const pendingUserMessage = sourceContexts.length > 0 ? injectSourceContextsIntoUserMessage(userMessage, sourceContexts) : userMessage;
-			if (!isConnectionResume) setPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
+			if (!isInternalResume) setPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
 			try {
 				const result = await deps.agentManager.withSkillCapabilities(sessionKey, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
 					sessionStore: deps.sessionStore,
@@ -314,7 +317,7 @@ async function* runProcessDirectStreaming(deps, input) {
 					content: formatStreamError(result.errorMessage)
 				});
 			} finally {
-				if (!isConnectionResume) clearPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
+				if (!isInternalResume) clearPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
 			}
 		} catch (err) {
 			if (err instanceof AsyncQueueOverflowError) {

package/dist/src/agent/service.d.ts

@@ -121,12 +121,14 @@ export declare class AgentService {
     refreshUserProfileContext(): void;
     getMemoryManager(): import("./memory/manager.js").MemoryManager;
     getModelForSession(sessionKey: string): string;
+    getThinkingLevelForSession(sessionKey: string): ThinkingLevel;
     /** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
     runEphemeralTurn(params: {
         executionSessionKey: string;
         parentSessionKey: string;
         runId: string;
         content: string;
+        attachments?: InboundAttachmentInput[];
         modelRef: string;
         thinkingLevel?: ThinkingLevel;
         transcriptRuntime: EmbeddedTranscriptRuntime;

package/dist/src/agent/service.js

@@ -2,10 +2,10 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
-import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
-import { init_providers, resolveModel } from "../providers/index.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
+import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
 import { extractProfileAgentId } from "../config/agent-profile.js";
+import { init_providers, resolveModel } from "../providers/index.js";
 import { extractTextContent } from "./context/workspace.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";
@@ -19,6 +19,7 @@ import "../user-model/index.js";
 import { resolveAgentTurnTimeoutMs } from "./orchestration/run-agent-turn-with-timeout.js";
 import { onSessionTranscriptUpdate } from "../session/transcript-events.js";
 import { persistInboundAttachments } from "../channels/attachments/inbound-persist.js";
+import { buildTranscriptUserMessage, hydrateUserTurnForLlm } from "./inbound/attachment-pipeline.js";
 import { runXopcEmbeddedTurn } from "./embedded/run-turn.js";
 import { resolveResponseLanguageForSession } from "./prompt/response-language.js";
 import { normalizeSkillInstallTarget } from "./skills/install-target.js";
@@ -229,7 +230,8 @@ var AgentService = class {
 			verboseLevel: config.verboseLevel,
 			gatewayClarify: config.gatewayClarify,
 			getAutomationService: config.getAutomationService,
-			getBrowserRecipeService: config.getBrowserRecipeService,
+			getBrowserAutomationService: config.getBrowserAutomationService,
+			emitBrowserEvent: config.emitBrowserEvent,
 			getNotesService: config.getNotesService,
 			getProjectService: config.getProjectService,
 			getLocalAppService: config.getLocalAppService,
@@ -576,19 +578,31 @@ var AgentService = class {
 	getModelForSession(sessionKey) {
 		return this.modelManager.getModelForSession(sessionKey);
 	}
+	getThinkingLevelForSession(sessionKey) {
+		return this.agentManager.getOrCreateAgent(sessionKey).state.thinkingLevel ?? "medium";
+	}
 	/** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
 	async runEphemeralTurn(params) {
 		const agent = this.agentManager.getOrCreateAgent(params.parentSessionKey);
 		const workspaceDir = this.agentManager.getResolvedWorkspaceForSession(params.parentSessionKey);
 		const model = resolveModel(params.modelRef);
+		const prepared = await this.prepareInboundAttachments(params.executionSessionKey, params.attachments);
+		const userMessage = await buildTranscriptUserMessage({
+			text: params.content,
+			prepared,
+			sessionKey: params.parentSessionKey,
+			modelRef: params.modelRef,
+			config: this.effectiveAppConfig(),
+			agentManager: this.agentManager
+		});
+		const llmTurn = await hydrateUserTurnForLlm({
+			message: userMessage,
+			modelRef: params.modelRef
+		});
 		return runWithEmbeddedExecutionSession(params.executionSessionKey, () => runXopcEmbeddedTurn({
 			sessionKey: params.executionSessionKey,
 			runId: params.runId,
-			userMessage: {
-				role: "user",
-				content: params.content,
-				timestamp: Date.now()
-			},
+			userMessage,
 			model,
 			modelRef: params.modelRef,
 			tools: agent.state.tools,
@@ -599,8 +613,9 @@ var AgentService = class {
 			timeoutMs: resolveAgentTurnTimeoutMs(this.effectiveAppConfig(), params.parentSessionKey),
 			turnPolicy: this.agentManager.createAgentTurnPolicy(params.parentSessionKey),
 			abortSignal: params.abortSignal,
-			onEvent: params.onEvent
-		}));
+			onEvent: params.onEvent,
+			images: llmTurn.images
+		}), params.runId);
 	}
 	async switchModelForSession(sessionKey, modelId) {
 		if (!await this.modelManager.switchModelForSession(sessionKey, modelId)) return false;

package/dist/src/agent/service.types.d.ts

@@ -28,7 +28,8 @@ export interface AgentServiceConfig {
         requestClarification: GatewayClarifyRequestFn;
     };
     getAutomationService?: () => AutomationService | undefined;
-    getBrowserRecipeService?: () => import('../browser/recipes/index.js').BrowserRecipeService | undefined;
+    getBrowserAutomationService?: () => import('../browser/automations/index.js').BrowserAutomationService | undefined;
+    emitBrowserEvent?: (type: string, payload: unknown) => void;
     /** Gateway: exposes first-class xopc product objects for the `xopc_use` tool. */
     getNotesService?: () => NotesService | undefined;
     getProjectService?: () => ProjectService | undefined;

package/dist/src/agent/session/session-inspector.js

@@ -1,8 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_workspace_defaults, resolveDefaultAgentWorkspaceDir } from "../../config/workspace-defaults.js";
-import { init_providers, resolveModel } from "../../providers/index.js";
 import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { init_providers, resolveModel } from "../../providers/index.js";
 import { getExecutionEnvironmentForSession } from "../../execution-environments/subject.js";
 import { effectiveWorkspacePathForSession, projectWorkspacePath } from "../../session/session-workspace.js";
 import { getProjectForSession } from "../../projects/workspace.js";

package/dist/src/agent/skills/hub-lock.js

@@ -1,5 +1,5 @@
-import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { init_paths, resolveSkillsLockPath } from "../../config/paths.js";
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/agent/skills/hub-lock.ts
 /**

package/dist/src/agent/skills/marketplace/adapters/store/store-api-client.js

@@ -1,3 +1,4 @@
+import { init_resolution, resolveConnectedPlatformEndpoint } from "../../../../../platform/resolution.js";
 import { MAX_SKILL_ZIP_BYTES, isValidSkillId } from "../../../managed-store.js";
 import { MAX_EXTENSION_STORE_ZIP_BYTES } from "../../../../../extensions/store-zip-limits.js";
 import { createHash } from "node:crypto";
@@ -8,12 +9,15 @@ import { createHash } from "node:crypto";
 *
 * Facade: {@link ../../../skills-marketplace.js}.
 */
+init_resolution();
 const DEFAULT_STORE_BASE = "https://store.xopc.ai";
 function resolveSkillsStoreBaseUrl(config) {
 	const env = process.env.XOPC_SKILLS_STORE_URL?.trim();
 	if (env) try {
 		return normalizeBaseUrl(new URL(env).toString());
 	} catch {}
+	const fromPlatform = resolveConnectedPlatformEndpoint("storeApi");
+	if (fromPlatform) return normalizeBaseUrl(fromPlatform);
 	const fromConfig = config.gateway?.skillsStoreBaseUrl?.trim();
 	if (fromConfig) try {
 		return normalizeBaseUrl(new URL(fromConfig).toString());

package/dist/src/agent/tasks/task-judge-service.js

@@ -1,15 +1,15 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { TaskRunRepository } from "../../tasks/task-run-repository.js";
-import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";
 import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
-import { getApiKey, init_providers, resolveModel } from "../../providers/index.js";
-import { completeWithResolvedCredentials } from "../../providers/model-call.js";
 import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { getApiKey, init_providers, resolveModel } from "../../providers/index.js";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { readWorkspaceRevision } from "../coding/workspace-revision.js";
+import { completeWithResolvedCredentials } from "../../providers/model-call.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
+import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";
 //#region src/agent/tasks/task-judge-service.ts
 init_schema();
 init_providers();

package/dist/src/agent/tool-manuals/browser.d.ts

@@ -1 +1 @@
-export declare const browserUseManual = "# Browser Tool Manual\n\n## Overview\n\n`browser_use` is XOPC's unified browser tool. It supports four modes:\n\n| Mode | Purpose |\n|------|---------|\n| `command` | Run a single browser action |\n| `pipeline` | Run a multi-step YAML flow |\n| `inspect` | Read current page state |\n| `close` | Close the browser session |\n\n## When to use\n\n- Open pages, click controls, fill forms\n- Capture screenshots or page content\n- Run multi-step automation flows\n- Extract data from pages\n\n## Command mode\n\n### Basic shape\n\n```json\n{\n  \"mode\": \"command\",\n  \"command\": \"<action>\",\n  \"args\": { ... }\n}\n```\n\n### Available commands\n\n| Command | Description | Key arguments |\n|---------|-------------|---------------|\n| `open` / `navigate` | Open a URL | `url`, `wait_until` |\n| `state` / `snapshot` | ARIA snapshot of the page | `selector`, `maxLength` |\n| `click` | Click an element | `selector` / `text` / `role` |\n| `type` / `input` | Type text | `selector` / `label`, `text`, `pressEnter` |\n| `scroll` | Scroll the page | `direction`, `amount` |\n| `screenshot` | Screenshot | `selector`, `full_page`, `path` |\n| `back` | Go back | `waitFor` |\n| `keys` / `press` | Keyboard input | `key` |\n| `console` / `eval` | Run JavaScript | `javascript` |\n| `images` | Collect images on the page | `selector`, `maxImages` |\n| `wait` | Wait for element/text/function/time | `selector` / `text` / `function` / `ms`, `state`, `timeout_ms` |\n| `wait_for_navigation` | Wait for page load state | `wait_until`, `timeout_ms` |\n| `wait_for_network_idle` | Wait until network is idle | `timeout_ms` |\n| `element_text` | Read element text | `selector` |\n| `element_attribute` | Read element attribute | `selector`, `attribute` |\n| `bounding_box` | Read element box | `selector` |\n| `network_start` / `network_events` / `network_stop` | Capture network events | `url_pattern`, `include_body` |\n| `dialog` | Handle dialogs | `action` (accept/dismiss) |\n| `close` | Close the current page | \u2014 |\n\n### Element targeting\n\nPrefer, in order:\n\n1. **ARIA role**: most stable, e.g. `\"role\": \"button:Submit\"`\n2. **Visible text**, e.g. `\"text\": \"Sign In\"`\n3. **CSS selector**, e.g. `\"selector\": \"#login-btn\"`\n\nGuidelines:\n\n- Use `inspect` or `state` first to get a snapshot\n- Pick locators from ARIA info in the snapshot\n- Avoid dynamic class names when possible\n\n## Inspect mode\n\nBefore acting, understand the current page:\n\n```json\n{ \"mode\": \"inspect\" }\n```\n\nReturns: current URL, title, ARIA snapshot.\n\n**Best practice**: after each navigation, inspect, then choose the next step.\n\n## Pipeline mode\n\nFor multi-step, reusable flows. Uses a brocli-style YAML DSL.\n\n### Run from file\n\n```json\n{\n  \"mode\": \"pipeline\",\n  \"pipeline\": {\n    \"path\": \"./browser-flow.yaml\",\n    \"args\": { \"url\": \"https://example.com\" }\n  }\n}\n```\n\n### Run inline YAML\n\n```json\n{\n  \"mode\": \"pipeline\",\n  \"pipeline\": {\n    \"yaml\": \"name: quick-check\\npipeline:\\n  - navigate:\\n      url: https://example.com\\n  - screenshot:\\n      full_page: true\",\n    \"dryRun\": false\n  }\n}\n```\n\n### YAML layout\n\n```yaml\nname: pipeline-name\ndescription: What this flow does\ntimeoutSeconds: 60\ninclude:\n  - ./shared-login.yaml\nargs:\n  url:\n    type: string\n    required: true\n  query:\n    type: string\n    default: \"hello\"\npipeline:\n  - navigate:\n      url: ${{ args.url }}\n      wait_until: domcontentloaded\n  - wait:\n      selector: input[name=\"q\"]\n  - type:\n      selector: input[name=\"q\"]\n      text: ${{ args.query }}\n  - press:\n      key: Enter\n  - wait:\n      selector: body\n      timeout_ms: 10000\n  - element_text:\n      selector: h1\n  - assert:\n      contains: Results\n  - screenshot:\n      path: ./artifacts/result.png\n      full_page: true\n  - output:\n      value:\n        screenshot: ./artifacts/result.png\non_error:\n  - screenshot:\n      path: ./artifacts/error.png\n      full_page: true\n```\n\n### Authoring rules\n\n1. One action per step\n2. Use `${{ args.xxx }}` for parameters\n3. Use `${{ last }}` or `${{ last | json }}` for the previous step result\n4. Use `${{ outputs.0 }}` for prior `output` values and `${{ vars.name }}` for values from `set_var`\n5. Use `include` for shared YAML fragments; relative includes resolve from the current pipeline file\n6. Use `on_error` to collect diagnostics after failure\n\n### Stable pipeline actions\n\n```yaml\npipeline:\n  - network_start:\n      url_pattern: /api/search\n      include_body: true\n  - click:\n      text: Search\n  - wait_for_network_idle:\n      timeout_ms: 10000\n  - collect: {}\n  - filter:\n      path: type\n      equals: response\n  - limit:\n      count: 3\n  - output:\n      value: ${{ last }}\n```\n\nControl flow:\n\n```yaml\npipeline:\n  - retry:\n      times: 3\n      delay_ms: 500\n      pipeline:\n        - wait:\n            selector: button.submit\n            timeout_ms: 3000\n        - click:\n            selector: button.submit\n  - if:\n      condition: ${{ last }}\n      then:\n        - output:\n            value: clicked\n      else:\n        - output:\n            value: missing\n```\n\n### Validate without running\n\n```json\n{\n  \"mode\": \"pipeline\",\n  \"pipeline\": {\n    \"yaml\": \"...\",\n    \"dryRun\": true\n  }\n}\n```\n\n## Recovery when something fails\n\n1. `inspect` to see current state\n2. Confirm the URL (redirects may have changed it)\n3. Use the snapshot to see if the page finished loading\n4. `screenshot` for visual debugging\n5. `wait` for elements, then retry\n\n## Safety\n\n- Do not put API keys or tokens in URLs\n- Do not target private IPs / localhost unless configuration allows it\n- Cloud metadata endpoints are always blocked\n- For destructive actions (submit forms, delete data), confirm intent with the user first\n";
+export declare const browserUseManual = "# Browser Tool Manual\n\n## browser_use\n\nUse one typed action per call. Start with `observe` or `navigate`. Every observation returns a `sessionId`, `revision`, and semantic element refs. Element actions must use refs from the newest revision; never invent refs.\n\nAvailable actions:\n\n- `observe`: return URL, title, interactive semantic nodes, and changes. Set `visual` to `always` only when visual evidence is needed.\n- `navigate`: open an HTTP(S) URL and optionally verify an expectation.\n- `click`, `fill`, `select`: act on a semantic ref with its observation revision.\n- `press`, `scroll`: act on an optional ref or the active page.\n- `wait`: wait for page idle, text, or a ref visibility state.\n- `upload`: attach workspace files to a file input. Local approval may be required.\n- `tabs`: list, create, activate, or close task-owned tabs.\n- `sequence`: run a short list of same-document ref actions.\n- `close`: close the task-owned browser session.\n\nThe tool does not accept CSS, XPath, JavaScript, cookie, storage, or network-inspection commands. Re-observe after navigation or a stale-observation response. Cross-domain, upload, destructive, and external-effect actions follow the configured local-owner approval policy. Sensitive fields expose only their semantic identity; their values are redacted and filling them requires approval.\n\n## browser_automation\n\nReusable browser automations are strict JSON. They use semantic `role` plus `name` or `nameIncludes` targets and an exact `allowedDomains` list. Input templates use `${input.name}`. Save only a flow that has been run and verified; never store passwords, one-time codes, recovery codes, or payment details.\n";

package/dist/src/agent/tool-manuals/browser.js

@@ -1,238 +1,27 @@
 //#region src/agent/tool-manuals/browser.ts
 const browserUseManual = `# Browser Tool Manual
 
-## Overview
+## browser_use
 
-\`browser_use\` is XOPC's unified browser tool. It supports four modes:
+Use one typed action per call. Start with \`observe\` or \`navigate\`. Every observation returns a \`sessionId\`, \`revision\`, and semantic element refs. Element actions must use refs from the newest revision; never invent refs.
 
-| Mode | Purpose |
-|------|---------|
-| \`command\` | Run a single browser action |
-| \`pipeline\` | Run a multi-step YAML flow |
-| \`inspect\` | Read current page state |
-| \`close\` | Close the browser session |
+Available actions:
 
-## When to use
+- \`observe\`: return URL, title, interactive semantic nodes, and changes. Set \`visual\` to \`always\` only when visual evidence is needed.
+- \`navigate\`: open an HTTP(S) URL and optionally verify an expectation.
+- \`click\`, \`fill\`, \`select\`: act on a semantic ref with its observation revision.
+- \`press\`, \`scroll\`: act on an optional ref or the active page.
+- \`wait\`: wait for page idle, text, or a ref visibility state.
+- \`upload\`: attach workspace files to a file input. Local approval may be required.
+- \`tabs\`: list, create, activate, or close task-owned tabs.
+- \`sequence\`: run a short list of same-document ref actions.
+- \`close\`: close the task-owned browser session.
 
-- Open pages, click controls, fill forms
-- Capture screenshots or page content
-- Run multi-step automation flows
-- Extract data from pages
+The tool does not accept CSS, XPath, JavaScript, cookie, storage, or network-inspection commands. Re-observe after navigation or a stale-observation response. Cross-domain, upload, destructive, and external-effect actions follow the configured local-owner approval policy. Sensitive fields expose only their semantic identity; their values are redacted and filling them requires approval.
 
-## Command mode
+## browser_automation
 
-### Basic shape
-
-\`\`\`json
-{
-  "mode": "command",
-  "command": "<action>",
-  "args": { ... }
-}
-\`\`\`
-
-### Available commands
-
-| Command | Description | Key arguments |
-|---------|-------------|---------------|
-| \`open\` / \`navigate\` | Open a URL | \`url\`, \`wait_until\` |
-| \`state\` / \`snapshot\` | ARIA snapshot of the page | \`selector\`, \`maxLength\` |
-| \`click\` | Click an element | \`selector\` / \`text\` / \`role\` |
-| \`type\` / \`input\` | Type text | \`selector\` / \`label\`, \`text\`, \`pressEnter\` |
-| \`scroll\` | Scroll the page | \`direction\`, \`amount\` |
-| \`screenshot\` | Screenshot | \`selector\`, \`full_page\`, \`path\` |
-| \`back\` | Go back | \`waitFor\` |
-| \`keys\` / \`press\` | Keyboard input | \`key\` |
-| \`console\` / \`eval\` | Run JavaScript | \`javascript\` |
-| \`images\` | Collect images on the page | \`selector\`, \`maxImages\` |
-| \`wait\` | Wait for element/text/function/time | \`selector\` / \`text\` / \`function\` / \`ms\`, \`state\`, \`timeout_ms\` |
-| \`wait_for_navigation\` | Wait for page load state | \`wait_until\`, \`timeout_ms\` |
-| \`wait_for_network_idle\` | Wait until network is idle | \`timeout_ms\` |
-| \`element_text\` | Read element text | \`selector\` |
-| \`element_attribute\` | Read element attribute | \`selector\`, \`attribute\` |
-| \`bounding_box\` | Read element box | \`selector\` |
-| \`network_start\` / \`network_events\` / \`network_stop\` | Capture network events | \`url_pattern\`, \`include_body\` |
-| \`dialog\` | Handle dialogs | \`action\` (accept/dismiss) |
-| \`close\` | Close the current page | — |
-
-### Element targeting
-
-Prefer, in order:
-
-1. **ARIA role**: most stable, e.g. \`"role": "button:Submit"\`
-2. **Visible text**, e.g. \`"text": "Sign In"\`
-3. **CSS selector**, e.g. \`"selector": "#login-btn"\`
-
-Guidelines:
-
-- Use \`inspect\` or \`state\` first to get a snapshot
-- Pick locators from ARIA info in the snapshot
-- Avoid dynamic class names when possible
-
-## Inspect mode
-
-Before acting, understand the current page:
-
-\`\`\`json
-{ "mode": "inspect" }
-\`\`\`
-
-Returns: current URL, title, ARIA snapshot.
-
-**Best practice**: after each navigation, inspect, then choose the next step.
-
-## Pipeline mode
-
-For multi-step, reusable flows. Uses a brocli-style YAML DSL.
-
-### Run from file
-
-\`\`\`json
-{
-  "mode": "pipeline",
-  "pipeline": {
-    "path": "./browser-flow.yaml",
-    "args": { "url": "https://example.com" }
-  }
-}
-\`\`\`
-
-### Run inline YAML
-
-\`\`\`json
-{
-  "mode": "pipeline",
-  "pipeline": {
-    "yaml": "name: quick-check\\npipeline:\\n  - navigate:\\n      url: https://example.com\\n  - screenshot:\\n      full_page: true",
-    "dryRun": false
-  }
-}
-\`\`\`
-
-### YAML layout
-
-\`\`\`yaml
-name: pipeline-name
-description: What this flow does
-timeoutSeconds: 60
-include:
-  - ./shared-login.yaml
-args:
-  url:
-    type: string
-    required: true
-  query:
-    type: string
-    default: "hello"
-pipeline:
-  - navigate:
-      url: \${{ args.url }}
-      wait_until: domcontentloaded
-  - wait:
-      selector: input[name="q"]
-  - type:
-      selector: input[name="q"]
-      text: \${{ args.query }}
-  - press:
-      key: Enter
-  - wait:
-      selector: body
-      timeout_ms: 10000
-  - element_text:
-      selector: h1
-  - assert:
-      contains: Results
-  - screenshot:
-      path: ./artifacts/result.png
-      full_page: true
-  - output:
-      value:
-        screenshot: ./artifacts/result.png
-on_error:
-  - screenshot:
-      path: ./artifacts/error.png
-      full_page: true
-\`\`\`
-
-### Authoring rules
-
-1. One action per step
-2. Use \`\${{ args.xxx }}\` for parameters
-3. Use \`\${{ last }}\` or \`\${{ last | json }}\` for the previous step result
-4. Use \`\${{ outputs.0 }}\` for prior \`output\` values and \`\${{ vars.name }}\` for values from \`set_var\`
-5. Use \`include\` for shared YAML fragments; relative includes resolve from the current pipeline file
-6. Use \`on_error\` to collect diagnostics after failure
-
-### Stable pipeline actions
-
-\`\`\`yaml
-pipeline:
-  - network_start:
-      url_pattern: /api/search
-      include_body: true
-  - click:
-      text: Search
-  - wait_for_network_idle:
-      timeout_ms: 10000
-  - collect: {}
-  - filter:
-      path: type
-      equals: response
-  - limit:
-      count: 3
-  - output:
-      value: \${{ last }}
-\`\`\`
-
-Control flow:
-
-\`\`\`yaml
-pipeline:
-  - retry:
-      times: 3
-      delay_ms: 500
-      pipeline:
-        - wait:
-            selector: button.submit
-            timeout_ms: 3000
-        - click:
-            selector: button.submit
-  - if:
-      condition: \${{ last }}
-      then:
-        - output:
-            value: clicked
-      else:
-        - output:
-            value: missing
-\`\`\`
-
-### Validate without running
-
-\`\`\`json
-{
-  "mode": "pipeline",
-  "pipeline": {
-    "yaml": "...",
-    "dryRun": true
-  }
-}
-\`\`\`
-
-## Recovery when something fails
-
-1. \`inspect\` to see current state
-2. Confirm the URL (redirects may have changed it)
-3. Use the snapshot to see if the page finished loading
-4. \`screenshot\` for visual debugging
-5. \`wait\` for elements, then retry
-
-## Safety
-
-- Do not put API keys or tokens in URLs
-- Do not target private IPs / localhost unless configuration allows it
-- Cloud metadata endpoints are always blocked
-- For destructive actions (submit forms, delete data), confirm intent with the user first
+Reusable browser automations are strict JSON. They use semantic \`role\` plus \`name\` or \`nameIncludes\` targets and an exact \`allowedDomains\` list. Input templates use \`\${input.name}\`. Save only a flow that has been run and verified; never store passwords, one-time codes, recovery codes, or payment details.
 `;
 //#endregion
 export { browserUseManual };

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

@@ -1,27 +1,10 @@
-/**
- * browser_use — unified browser AgentTool.
- *
- * Modes: command | inspect | close.
- * Replaces the 14 fine-grained browser_* tools with a single entry point.
- */
 import type { AgentTool } from '@earendil-works/pi-agent-core';
-import type { Config } from '../../../../config/schema.js';
-import type { BrowserManager } from '../../../../browser/manager.js';
-import type { CdpSupervisor } from '../../../../browser/cdp-supervisor.js';
-import type { Page } from 'playwright-core';
 import type { BrowserNotReadyError } from '../../../../browser/readiness.js';
+import type { BrowserRuntime } from '../../../../browser/runtime/browser-runtime.js';
+import { BrowserUseSchema } from './schemas.js';
 export interface CreateBrowserUseToolDeps {
-    getManager: () => BrowserManager;
-    getPageForTask: () => Promise<Page>;
+    getRuntime: () => BrowserRuntime;
     getTaskId: () => string;
-    getConfig: () => Config | undefined;
-    getSupervisor?: () => CdpSupervisor | undefined;
-    notifyBrowserPageClosed?: (taskId: string) => void;
-    /**
-     * Preflight readiness check. Returns `null` when the configured backend is
-     * usable, otherwise a structured hint the chat surface renders as a setup
-     * card. Cache the result upstream (~30s) so back-to-back calls don't reprobe.
-     */
     getReadiness?: () => Promise<BrowserNotReadyError | null>;
 }
-export declare function createBrowserUseTool(deps: CreateBrowserUseToolDeps): AgentTool<any, any>;
+export declare function createBrowserUseTool(deps: CreateBrowserUseToolDeps): AgentTool<typeof BrowserUseSchema, Record<string, unknown>>;