fix(vom): bug fix

feat(bsk): add secure, session-scoped file upload and download | 支持安全、会话级的文件上传与下载

.gitignore

@@ -7,6 +7,10 @@ dist/
 .output/
 .wxt/
 .web-extension-id
+.pnpm-store/
+
+# Git worktrees
+.worktrees/
 
 # Logs
 *.log

Cargo.lock

@@ -137,6 +137,7 @@ name = "bsk"
 version = "0.1.11"
 dependencies = [
  "anyhow",
+ "base64",
  "bsk-protocol",
  "clap",
  "console",

Cargo.toml

@@ -36,6 +36,7 @@ flate2 = "1.1.9"
 tar = "0.4.46"
 zip = { version = "7.2.0", default-features = false, features = ["deflate"] }
 sha2 = "0.11.0"
+base64 = "0.22"
 tempfile = "3"
 nix = { version = "0.29", features = ["signal", "process"] }
 rand = "0.8"

apps/extension/PRIVACY.md

@@ -1,6 +1,6 @@
 # BrowserSkill — Privacy Policy
 
-**Last updated:** May 25, 2026
+**Last updated:** August 20, 2026
 
 This Privacy Policy describes how the **BrowserSkill** browser extension (the "Extension") handles information when you install and use it. BrowserSkill is published as part of the open-source [BrowserSkill](https://github.com/Tencent/BrowserSkill) project. The source code is publicly auditable.
 
@@ -14,7 +14,7 @@ BrowserSkill is a local automation bridge that lets AI coding agents (such as Cu
 
 ## 2. Single Purpose
 
-The Extension's single purpose is to expose browser automation primitives (navigation, DOM observation, screenshots, clicks, form filling, tab management) to a locally running BrowserSkill daemon over a WebSocket connection on `127.0.0.1`, so that an AI agent invoked by the user can interact with web pages on the user's behalf.
+The Extension's single purpose is to expose browser automation primitives (navigation, DOM observation, screenshots, clicks, form filling, task-scoped file transfer, and tab management) to a locally running BrowserSkill daemon over a WebSocket connection on `127.0.0.1`, so that an AI agent invoked by the user can interact with web pages on the user's behalf.
 
 ## 3. Data the Extension Accesses
 
@@ -26,6 +26,7 @@ Depending on the commands the user (via their AI agent) sends to the local daemo
 | **User input simulated by the agent** | Mouse clicks, keystrokes, and form values that the AI agent dispatches through the Chrome DevTools Protocol (CDP). | Required to perform automation actions the user has asked the agent to do. |
 | **Tab and window metadata** | Tab IDs, URLs, titles, window IDs of the Agent Window and any tabs the user explicitly authorizes. | Required to target automation commands at the correct tab/window. |
 | **Local extension storage** | A randomly generated 8-character instance ID and an optional user-supplied label. | Used so the local daemon can recognize this browser instance across reconnects. No personal data is stored. |
+| **File transfers requested by the agent** | Local files explicitly supplied to `bsk upload`, and the file created by a single `bsk download` action. | Required to attach a task file to a web page or return a browser-generated download to the invoking local agent. |
 | **OS notifications** | Permission to display a system notification when the agent requests to "borrow" one of the user's existing tabs. | Required to obtain explicit, per-tab user consent before the agent touches any pre-existing tab. |
 
 ## 4. Data the Extension Does **Not** Collect
@@ -34,7 +35,7 @@ BrowserSkill does **not**:
 
 - Send any data to remote servers, the Extension's authors, or any third party.
 - Call any LLM, AI, or cloud API. The Extension contains no API keys, model identifiers, or remote endpoints.
-- Read or transmit cookies, browsing history, bookmarks, downloads, saved passwords, or autofill data.
+- Read or transmit cookies, browsing history, bookmarks, saved passwords, or autofill data. It observes only the download initiated by an active `bsk download` call, not download history generally.
 - Use webcam, microphone, geolocation, or any device sensor.
 - Include analytics, telemetry, crash reporting, advertising SDKs, or fingerprinting code.
 - Track users across websites or across sessions.
@@ -50,6 +51,7 @@ The Extension requests the following Chrome permissions. Each is used solely for
 - **`alarms`** — Periodically wake the service worker to keep the local WebSocket connection alive.
 - **`idle`** — Detect when the device returns from idle/locked so the Extension can promptly re-establish the local WebSocket connection after the machine wakes. No idle data is stored or transmitted.
 - **`notifications`** — Show a system notification to obtain user approval before the agent borrows a user-owned tab.
+- **`downloads`** — Correlate and route the one browser download initiated by an active `bsk download` command. If that claimed transaction fails, BrowserSkill cancels an in-progress file or removes its completed temporary browser file. It is not used to enumerate download history or alter unclaimed downloads.
 - **`storage`** — Persist a random instance ID and optional label in `chrome.storage.local`.
 - **Host permission `<all_urls>`** — Inject a small status overlay (showing "Agent Active") on pages controlled by the agent, and enable automation across whatever sites the user directs the agent to. The Extension does **not** read or transmit page content from sites the agent is not actively driving.
 
@@ -61,6 +63,7 @@ All Extension activity stays on the user's local device. The only network traffi
 
 - The instance ID and optional label persist in `chrome.storage.local` until the user uninstalls the Extension or clears extension storage.
 - Page content, screenshots, DOM snapshots, and other observed data are returned to the local daemon in response to commands and are **not retained by the Extension**. They live only as long as the agent's tool call.
+- Upload and download bytes are staged by the local daemon in a private, session-scoped directory. Download staging is removed after it is copied to the requested destination. Upload staging is retained until the session ends so a later form submission can still read the attached file. Remaining staging is removed when the session ends or disconnects, or when the daemon next starts after a crash.
 
 ## 8. User Control
 

apps/extension/src/content/__tests__/BorrowConfirmationOverlay.test.tsx

@@ -23,7 +23,7 @@ describe("BorrowConfirmationOverlay", () => {
             id: "req-1",
             isActiveTab: true,
             tabTitle: "Example",
-            timeoutMs: 5000,
+            timeoutMs: 60_000,
             onAllow,
             onDeny,
           },
@@ -32,7 +32,7 @@ describe("BorrowConfirmationOverlay", () => {
     );
 
     expect(screen.getByText("允许借用标签页？")).toBeTruthy();
-    for (let i = 0; i < 5; i++) {
+    for (let i = 0; i < 60; i++) {
       await act(async () => {
         await vi.advanceTimersByTimeAsync(1000);
       });
@@ -66,7 +66,7 @@ describe("BorrowConfirmationOverlay", () => {
             id: "req-fallback",
             isActiveTab: true,
             tabTitle: "Example",
-            timeoutMs: 5000,
+            timeoutMs: 60_000,
             onAllow,
             onDeny,
           },
@@ -74,7 +74,7 @@ describe("BorrowConfirmationOverlay", () => {
       />,
     );
 
-    for (let i = 0; i < 5; i++) {
+    for (let i = 0; i < 60; i++) {
       await act(async () => {
         await vi.advanceTimersByTimeAsync(1000);
       });

apps/extension/src/session-manager/__tests__/surface-capture-store.test.ts

@@ -1,67 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { type SurfaceCaptureInput, SurfaceCaptureStore } from "../surface-capture-store";
-
-function input(): SurfaceCaptureInput {
-  return {
-    sessionId: "aa11",
-    tabId: 7,
-    navigationIdentity: "navigation",
-    surface: {
-      ref: "e3",
-      frameId: "main",
-      backendNodeId: 99,
-      observationGeneration: 2,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 50 },
-    imageWidth: 200,
-    imageHeight: 100,
-    viewportSignature: "viewport",
-    frameProjectionSignature: "frame",
-  };
-}
-
-describe("SurfaceCaptureStore", () => {
-  it("creates metadata-only, short-lived captures and consumes them once", () => {
-    let now = 1_000;
-    const store = new SurfaceCaptureStore({
-      now: () => now,
-      ttlMs: 500,
-      createId: () => "sc_test",
-    });
-    const capture = store.create(input());
-
-    expect(capture).toMatchObject({
-      id: "sc_test",
-      createdAt: 1_000,
-      expiresAt: 1_500,
-      consumed: false,
-    });
-    expect(capture).not.toHaveProperty("imageBase64");
-    expect(store.consume("sc_test")).toMatchObject({ ok: true });
-    expect(store.consume("sc_test")).toEqual({ ok: false, reason: "consumed" });
-
-    now = 1_600;
-    expect(store.size()).toBe(0);
-  });
-
-  it("rejects expired and unknown captures", () => {
-    let now = 1_000;
-    const store = new SurfaceCaptureStore({
-      now: () => now,
-      ttlMs: 10,
-      createId: () => "sc_expired",
-    });
-    store.create(input());
-    now = 1_010;
-
-    expect(store.consume("sc_expired")).toEqual({ ok: false, reason: "expired" });
-    expect(store.consume("sc_missing")).toEqual({ ok: false, reason: "not_found" });
-  });
-
-  it("clears every capture on session cleanup", () => {
-    const store = new SurfaceCaptureStore({ createId: () => "sc_clear" });
-    store.create(input());
-    store.clear();
-    expect(store.size()).toBe(0);
-  });
-});

apps/extension/src/session-manager/manager.ts

@@ -1,12 +1,10 @@
 import { AGENT_WINDOW_HOME, type AgentWindowApi, chromeAgentWindowApi } from "./agent-window";
 import { RefStore } from "./ref-store";
-import { SurfaceCaptureStore } from "./surface-capture-store";
 
 export interface SessionContext {
   sessionId: string;
   agentWindowId: number;
   refStore: RefStore;
-  surfaceCaptures: SurfaceCaptureStore;
   borrowedTabs: Map<number, BorrowedTab>;
   createdAtMs: number;
 }
@@ -188,7 +186,6 @@ export class SessionManager {
         sessionId,
         agentWindowId: windowId,
         refStore: new RefStore(),
-        surfaceCaptures: new SurfaceCaptureStore({ now: this.now }),
         borrowedTabs: new Map(),
         createdAtMs: this.now(),
       };

apps/extension/src/session-manager/surface-capture-store.ts

@@ -1,100 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-
-export const SURFACE_CAPTURE_TTL_MS = 30_000;
-
-export interface SurfaceCapture {
-  id: string;
-  sessionId: string;
-  tabId: number;
-  navigationIdentity: string;
-  surface: {
-    ref: string;
-    frameId?: string;
-    backendNodeId: number;
-    observationGeneration: number;
-  };
-  topViewportRect: Rect;
-  imageWidth: number;
-  imageHeight: number;
-  viewportSignature: string;
-  frameProjectionSignature: string;
-  createdAt: number;
-  expiresAt: number;
-  consumed: boolean;
-}
-
-export type SurfaceCaptureInput = Omit<
-  SurfaceCapture,
-  "id" | "createdAt" | "expiresAt" | "consumed"
->;
-
-export type SurfaceCaptureConsumeResult =
-  | { ok: true; capture: SurfaceCapture }
-  | { ok: false; reason: "not_found" | "expired" | "consumed" };
-
-export interface SurfaceCaptureStoreOptions {
-  now?: () => number;
-  ttlMs?: number;
-  createId?: () => string;
-}
-
-function randomCaptureId(): string {
-  const bytes = crypto.getRandomValues(new Uint8Array(12));
-  return `sc_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
-}
-
-/** Per-session, metadata-only store for short-lived screenshot coordinate transactions. */
-export class SurfaceCaptureStore {
-  private readonly captures = new Map<string, SurfaceCapture>();
-  private readonly now: () => number;
-  private readonly ttlMs: number;
-  private readonly createId: () => string;
-
-  constructor(options: SurfaceCaptureStoreOptions = {}) {
-    this.now = options.now ?? Date.now;
-    this.ttlMs = options.ttlMs ?? SURFACE_CAPTURE_TTL_MS;
-    this.createId = options.createId ?? randomCaptureId;
-  }
-
-  create(input: SurfaceCaptureInput): SurfaceCapture {
-    this.purgeExpired();
-    const createdAt = this.now();
-    const capture: SurfaceCapture = {
-      ...input,
-      id: this.createId(),
-      createdAt,
-      expiresAt: createdAt + this.ttlMs,
-      consumed: false,
-    };
-    this.captures.set(capture.id, capture);
-    return capture;
-  }
-
-  consume(id: string): SurfaceCaptureConsumeResult {
-    const capture = this.captures.get(id);
-    if (!capture) return { ok: false, reason: "not_found" };
-    if (capture.expiresAt <= this.now()) {
-      this.captures.delete(id);
-      return { ok: false, reason: "expired" };
-    }
-    if (capture.consumed) return { ok: false, reason: "consumed" };
-    capture.consumed = true;
-    return { ok: true, capture };
-  }
-
-  clear(): void {
-    this.captures.clear();
-  }
-
-  size(): number {
-    this.purgeExpired();
-    return this.captures.size;
-  }
-
-  private purgeExpired(): void {
-    const now = this.now();
-    for (const [id, capture] of this.captures) {
-      if (capture.expiresAt <= now) this.captures.delete(id);
-    }
-  }
-}

apps/extension/src/tools/__tests__/borrow-confirmation.test.ts

@@ -127,6 +127,38 @@ describe("requestBorrowConfirmation", () => {
     expect(message.requestId.length).toBeGreaterThan(0);
   });
 
+  it("proactively focuses the user window before sending the overlay message", async () => {
+    tabs.get.mockResolvedValueOnce({ id: 42, title: "Tab" });
+    windows.getLastFocused.mockResolvedValueOnce(
+      userWindowWithActiveTab({ windowId: 77, tabId: 7, url: "https://app.example/" }),
+    );
+    tabs.sendMessage.mockResolvedValueOnce({ type: "borrow-response", allowed: true });
+
+    const pending = requestBorrowConfirmation(42, {
+      deps: { tabs, windows, notifications },
+    });
+    await vi.runAllTimersAsync();
+    await pending;
+
+    expect(windows.update).toHaveBeenCalledWith(77, { focused: true });
+  });
+
+  it("still proceeds when proactive window focus fails", async () => {
+    tabs.get.mockResolvedValueOnce({ id: 42, title: "Tab" });
+    windows.getLastFocused.mockResolvedValueOnce(
+      userWindowWithActiveTab({ windowId: 77, tabId: 7, url: "https://app.example/" }),
+    );
+    windows.update.mockRejectedValueOnce(new Error("window gone"));
+    tabs.sendMessage.mockResolvedValueOnce({ type: "borrow-response", allowed: true });
+
+    const pending = requestBorrowConfirmation(42, {
+      deps: { tabs, windows, notifications },
+    });
+    await vi.runAllTimersAsync();
+
+    expect(await pending).toBe(true);
+  });
+
   it("sends confirmation to the borrow target when it is the active tab", async () => {
     tabs.get.mockResolvedValueOnce({ id: 42, title: "Active Tab" });
     windows.getLastFocused.mockResolvedValueOnce(

apps/extension/src/tools/__tests__/dispatcher.test.ts

@@ -232,6 +232,107 @@ describe("ToolDispatcher", () => {
     });
   });
 
+  it("bypasses and restores the control overlay for an upload trigger click", async () => {
+    const sendMessage = vi.fn(async () => undefined);
+    vi.stubGlobal("chrome", {
+      tabs: {
+        get: vi.fn(async () => ({ id: 7, windowId: 4242, active: true })),
+        query: vi.fn(async () => [{ id: 7, windowId: 4242, active: true }]),
+        sendMessage,
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => {}),
+      },
+    });
+    const ctx = await sessions.start("aa11");
+    ctx.refStore.set("e1", 123, { tabId: 7 });
+    const send = vi.fn(async <T>(_tabId: number, method: string, params?: object) => {
+      if (method === "Page.getLayoutMetrics") {
+        return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } } as T;
+      }
+      if (method === "DOM.getContentQuads") {
+        return { quads: [[0, 0, 20, 0, 20, 20, 0, 20]] } as T;
+      }
+      if (method === "DOM.resolveNode") {
+        return { object: { objectId: "trigger-object" } } as T;
+      }
+      if (method === "DOM.describeNode") return { node: { backendNodeId: 456 } } as T;
+      if (method === "Runtime.callFunctionOn") {
+        const declaration = (params as { functionDeclaration?: string }).functionDeclaration ?? "";
+        if (declaration.includes("count: state.inputs.length")) {
+          return { result: { value: { count: 1, multiple: false } } } as T;
+        }
+        if (declaration.includes("inputs[0]")) {
+          return { result: { objectId: "input-object" } } as T;
+        }
+        return { result: { value: true } } as T;
+      }
+      if (method === "Runtime.evaluate") {
+        const expression = (params as { expression?: string }).expression ?? "";
+        if (expression.includes("overlayDetails")) {
+          return { result: { value: { hitIndex: 0 } } } as T;
+        }
+        if (expression.includes("overlayHostPresent")) {
+          return {
+            result: {
+              value: { overlayHostPresent: true, overlayHostConnected: true },
+            },
+          } as T;
+        }
+        if (expression.includes("count:")) {
+          return { result: { value: { count: 1, multiple: false } } } as T;
+        }
+        if (expression.includes("?.inputs[0]")) {
+          return { result: { objectId: "input-object" } } as T;
+        }
+        return { result: { value: true } } as T;
+      }
+      return {} as T;
+    });
+    const cdp = {
+      send,
+      detachSession: vi.fn(async () => {}),
+      ensureNetworkCapture: vi.fn(async () => {}),
+      networkEntriesSince: vi.fn(() => ({
+        tab_id: 7,
+        entries: [],
+        next_since: 0,
+        truncated: false,
+      })),
+      setDeviceMetricsOverride: vi.fn(async () => {}),
+      clearDeviceMetricsOverride: vi.fn(async () => {}),
+      setUserAgentOverride: vi.fn(async () => {}),
+      setTouchEmulationEnabled: vi.fn(async () => {}),
+    };
+    const dispatcher = new ToolDispatcher({ transport, sessions, cdp: cdp as TestDispatcherCdp });
+    dispatcher.start();
+
+    deliver(
+      makeRequest("tool.upload", {
+        session_id: "aa11",
+        ref: "@e1",
+        files: [{ transfer_id: "tr_1", name: "test.png", staged_path: "/stage/test.png" }],
+      }),
+    );
+    await flushMicrotasks();
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+
+    expect(sent[0]).toMatchObject({ result: { tab_id: 7, file_names: ["test.png"] } });
+    expect(sendMessage).toHaveBeenNthCalledWith(1, 7, {
+      type: "bh-automation-bypass",
+      enabled: true,
+    });
+    expect(sendMessage).toHaveBeenNthCalledWith(2, 7, {
+      type: "bh-automation-bypass",
+      enabled: false,
+    });
+  });
+
   it("detaches CDP state before stopping a session", async () => {
     const { transport, sent, deliver } = fakeTransport();
     const sessions = new SessionManager({

apps/extension/src/tools/__tests__/editable-input.test.ts

@@ -1,104 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { fillEditable } from "../editable-input";
-import type { CdpRunner } from "../shared";
-
-interface FakeOptions {
-  initialValue?: string;
-  finalValue: string;
-  remount?: boolean;
-}
-
-function editableState(value: string, connected = true, focused = true) {
-  return {
-    result: {
-      value: { supported: true, connected, focused, value, kind: "input" },
-    },
-  };
-}
-
-function makeEditableCdp(options: FakeOptions) {
-  const sent: Array<{ method: string; params?: object }> = [];
-  let inserted = false;
-  const send = vi.fn(async <T>(_tabId: number, method: string, params?: object): Promise<T> => {
-    sent.push({ method, params });
-    if (method === "Input.insertText") {
-      inserted = true;
-      return {} as T;
-    }
-    if (method === "Input.dispatchKeyEvent") {
-      if ((params as { type?: string }).type === "rawKeyDown") inserted = true;
-      return {} as T;
-    }
-    if (method !== "Runtime.callFunctionOn") throw new Error(`unexpected ${method}`);
-
-    const call = params as { objectId?: string; functionDeclaration?: string };
-    const fn = call.functionDeclaration ?? "";
-    if (fn.includes("bsk-editable-selection")) {
-      return { result: { value: { selected: true } } } as T;
-    }
-    if (fn.includes("bsk-editable-sync")) return { result: { value: undefined } } as T;
-    if (fn.includes("bsk-editable-live")) {
-      return {
-        result: options.remount && inserted ? { objectId: "replacement" } : { objectId: "anchor" },
-      } as T;
-    }
-    if (fn.includes("bsk-editable-state")) {
-      if (call.objectId === "replacement") return editableState(options.finalValue) as T;
-      if (options.remount && inserted) {
-        return editableState(options.finalValue, false, false) as T;
-      }
-      return editableState(inserted ? options.finalValue : (options.initialValue ?? "")) as T;
-    }
-    throw new Error("unexpected Runtime.callFunctionOn function");
-  });
-  return { cdp: { send } as CdpRunner, sent };
-}
-
-describe("fillEditable", () => {
-  it("replaces text through the browser input path without synthetic events or value setters", async () => {
-    const fake = makeEditableCdp({ initialValue: "old", finalValue: "新值" });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "新值", true);
-
-    expect(result).toMatchObject({ value: "新值", replacedNode: false });
-    expect(fake.sent).toContainEqual({ method: "Input.insertText", params: { text: "新值" } });
-    const declarations = fake.sent
-      .map((call) => (call.params as { functionDeclaration?: string })?.functionDeclaration ?? "")
-      .join("\n");
-    expect(declarations).not.toMatch(/dispatchEvent|\.value\s*=/);
-  });
-
-  it("reacquires the focused editable after a framework remount", async () => {
-    const fake = makeEditableCdp({ finalValue: "persisted", remount: true });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "persisted", true);
-
-    expect(result).toMatchObject({ value: "persisted", replacedNode: true });
-  });
-
-  it("reports a page rollback after the bounded settlement", async () => {
-    const fake = makeEditableCdp({ finalValue: "" });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "rejected", true);
-
-    expect(result).toMatchObject({
-      code: "cdp_failed",
-      data: {
-        reason: "input_not_applied",
-        expected_value_length: 8,
-        actual_value_length: 0,
-        phase: "readback",
-      },
-    });
-  });
-
-  it("clears to an empty value with a browser Backspace edit", async () => {
-    const fake = makeEditableCdp({ initialValue: "old", finalValue: "" });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "", true);
-
-    expect(result).toMatchObject({ value: "" });
-    expect(fake.sent.some((call) => call.method === "Input.insertText")).toBe(false);
-    expect(fake.sent.filter((call) => call.method === "Input.dispatchKeyEvent")).toHaveLength(2);
-  });
-});

apps/extension/src/tools/__tests__/file-transfer.test.ts

@@ -0,0 +1,809 @@
+import { describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import { type DownloadsApi, handleDownload } from "../download";
+import { captureBrowserDownload } from "../download-capture";
+import { uploadThroughActivatedFileInput } from "../file-input-transaction";
+import type { ResolvedActionTarget } from "../interaction";
+import type { CdpRunner } from "../shared";
+import { handleUpload } from "../upload";
+
+function sessions() {
+  return new SessionManager({
+    agentWindow: {
+      create: vi.fn(async () => 100),
+      remove: vi.fn(async () => {}),
+      ensureActiveTab: vi.fn(async () => {}),
+    },
+  });
+}
+
+function tabsApi() {
+  return {
+    get: vi.fn(
+      async (tabId: number) => ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
+    ),
+    query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+  };
+}
+
+function fakeEvent<T extends (...args: never[]) => unknown>() {
+  const listeners = new Set<T>();
+  return {
+    addListener: (listener: T) => listeners.add(listener),
+    removeListener: (listener: T) => listeners.delete(listener),
+    emit: (...args: Parameters<T>) => {
+      for (const listener of listeners) listener(...args);
+    },
+  };
+}
+
+function actionTarget(frameId?: string): ResolvedActionTarget {
+  return {
+    tab: { tabId: 4, windowId: 100, active: true },
+    backendNodeId: 123,
+    cdpTarget: { tabId: 4 },
+    ...(frameId ? { frameId } : {}),
+    usedRef: "e3",
+  };
+}
+
+function uploadCdp(
+  options: {
+    inputCount?: number;
+    multiple?: boolean;
+    chooser?: { frameId?: string; backendNodeId?: number; mode?: string };
+    pendingResolve?: boolean;
+  } = {},
+) {
+  const calls: Array<{ method: string; params?: object }> = [];
+  let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    calls.push({ method, params });
+    if (method === "Page.setInterceptFileChooserDialog") return {};
+    if (method === "Page.getLayoutMetrics")
+      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
+    if (method === "DOM.getContentQuads") return { quads: [[0, 0, 20, 0, 20, 20, 0, 20]] };
+    if (method === "DOM.resolveNode") {
+      if (options.pendingResolve) return new Promise<never>(() => {});
+      return { object: { objectId: "trigger-object" } };
+    }
+    if (method === "Runtime.callFunctionOn") {
+      const declaration = (params as { functionDeclaration?: string }).functionDeclaration ?? "";
+      if (declaration.includes("Object.defineProperty")) return { result: { value: true } };
+      if (declaration.includes("count: state.inputs.length")) {
+        return {
+          result: {
+            value: {
+              count: options.inputCount ?? 1,
+              multiple: options.multiple ?? true,
+            },
+          },
+        };
+      }
+      if (declaration.includes("inputs[0]")) {
+        return { result: { objectId: "input-object" } };
+      }
+      return { result: { value: true } };
+    }
+    if (method === "DOM.describeNode") return { node: { backendNodeId: 456 } };
+    if (
+      method === "Input.dispatchMouseEvent" &&
+      (params as { type?: string }).type === "mousePressed" &&
+      options.chooser
+    ) {
+      cdpEvent?.({ tabId: 4 }, "Page.fileChooserOpened", options.chooser);
+    }
+    return {};
+  });
+  const cdp: CdpRunner = {
+    send: send as unknown as CdpRunner["send"],
+    onEvent: (handler) => {
+      cdpEvent = handler;
+      return { dispose: vi.fn() };
+    },
+  };
+  return {
+    calls,
+    emitChooser: (event: { frameId?: string; backendNodeId?: number; mode?: string }) =>
+      cdpEvent?.({ tabId: 4 }, "Page.fileChooserOpened", event),
+    cdp,
+  };
+}
+
+describe("file transfer tools", () => {
+  it("captures the file input activated by the requested click and injects only staged paths", async () => {
+    const manager = sessions();
+    const ctx = await manager.start("s1");
+    ctx.refStore.set("e3", 123, { tabId: 4 });
+    const { cdp, calls } = uploadCdp();
+
+    const result = await handleUpload(
+      manager,
+      {
+        session_id: "s1",
+        ref: "@e3",
+        files: [
+          { transfer_id: "tr_1", name: "one.png", staged_path: "/private/stage/one" },
+          { transfer_id: "tr_2", name: "two.png", staged_path: "/private/stage/two" },
+        ],
+      },
+      { cdp, tabsApi: tabsApi() },
+    );
+
+    expect(result).toMatchObject({ tab_id: 4, file_names: ["one.png", "two.png"] });
+    expect(calls[0]).toEqual({
+      method: "Page.setInterceptFileChooserDialog",
+      params: { enabled: true },
+    });
+    expect(calls).toContainEqual({
+      method: "Page.setInterceptFileChooserDialog",
+      params: { enabled: false, cancel: true },
+    });
+    expect(calls).toContainEqual({
+      method: "DOM.setFileInputFiles",
+      params: { files: ["/private/stage/one", "/private/stage/two"], backendNodeId: 456 },
+    });
+  });
+
+  it("fails immediately when the trigger does not activate a file input", async () => {
+    const { cdp } = uploadCdp({ inputCount: 0 });
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger: async () => ({ tab_id: 4, x: 10, y: 10 }),
+    });
+
+    expect(result).toMatchObject({
+      code: "unsupported",
+      data: { reason: "file_input_not_activated", phase: "resolve_input" },
+    });
+  });
+
+  it("fails before clicking when chooser interception is unavailable", async () => {
+    const trigger = vi.fn(async () => ({ tab_id: 4, x: 10, y: 10 }));
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId: number, method: string) => {
+        if (method === "Page.setInterceptFileChooserDialog") {
+          throw new Error("method unavailable");
+        }
+        return {};
+      }) as CdpRunner["send"],
+    };
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger,
+    });
+
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { effect_state: "none", phase: "arm_interception" },
+    });
+    expect(trigger).not.toHaveBeenCalled();
+  });
+
+  it("uses an exact chooser event as an independent input-location signal", async () => {
+    const { cdp, calls, emitChooser } = uploadCdp({ inputCount: 0 });
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget("f1"),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger: async () => {
+        emitChooser({ frameId: "f1", backendNodeId: 789, mode: "selectSingle" });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({ multiple: false });
+    expect(calls).toContainEqual({
+      method: "DOM.setFileInputFiles",
+      params: { files: ["/private/stage/one"], backendNodeId: 789 },
+    });
+  });
+
+  it("reports a File System Access picker without waiting for a timeout", async () => {
+    const { cdp, emitChooser } = uploadCdp({
+      inputCount: 0,
+    });
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget("f1"),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger: async () => {
+        emitChooser({ frameId: "f1", mode: "selectSingle" });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({
+      code: "unsupported",
+      message: "upload trigger invoked a non-input file picker",
+      data: { reason: "file_input_not_activated", phase: "resolve_input" },
+    });
+  });
+
+  it("bounds a stuck file-input probe", async () => {
+    const { cdp } = uploadCdp({ pendingResolve: true });
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 5,
+      trigger: vi.fn(),
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { reason: "file_input_probe_failed", phase: "arm_input_probe" },
+    });
+  });
+
+  it("does not dispatch browser work when upload is already cancelled", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const { cdp, calls } = uploadCdp();
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      signal: controller.signal,
+      trigger: vi.fn(),
+    });
+
+    expect(result).toMatchObject({
+      code: "cancelled",
+      data: { effect_state: "none", phase: "arm_interception" },
+    });
+    expect(calls).not.toContainEqual({
+      method: "Page.setInterceptFileChooserDialog",
+      params: { enabled: true },
+    });
+    expect(calls.some((call) => call.method === "DOM.setFileInputFiles")).toBe(false);
+  });
+
+  it("stops before file assignment when cancellation interrupts input resolution", async () => {
+    const controller = new AbortController();
+    const fixture = uploadCdp();
+    const originalSend = fixture.cdp.send;
+    let markProbeStarted!: () => void;
+    const probeStarted = new Promise<void>((resolve) => {
+      markProbeStarted = resolve;
+    });
+    fixture.cdp.send = vi.fn((tabId: number, method: string, params?: object) => {
+      const declaration = (params as { functionDeclaration?: string } | undefined)
+        ?.functionDeclaration;
+      if (
+        method === "Runtime.callFunctionOn" &&
+        declaration?.includes("count: state.inputs.length")
+      ) {
+        markProbeStarted();
+        return new Promise<never>(() => {});
+      }
+      return originalSend(tabId, method, params);
+    }) as CdpRunner["send"];
+
+    const transaction = uploadThroughActivatedFileInput({
+      cdp: fixture.cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 1_000,
+      signal: controller.signal,
+      trigger: async () => ({ tab_id: 4, x: 10, y: 10 }),
+    });
+    await probeStarted;
+    controller.abort();
+    const result = await transaction;
+
+    expect(result).toMatchObject({
+      code: "cancelled",
+      data: { effect_state: "none", phase: "resolve_input" },
+    });
+    expect(fixture.calls.some((call) => call.method === "DOM.setFileInputFiles")).toBe(false);
+  });
+
+  it("disarms chooser interception when its enable response times out", async () => {
+    const calls: Array<{ method: string; params?: object }> = [];
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId: number, method: string, params?: object) => {
+        calls.push({ method, params });
+        if (
+          method === "Page.setInterceptFileChooserDialog" &&
+          (params as { enabled?: boolean }).enabled
+        ) {
+          return new Promise<never>(() => {});
+        }
+        return {};
+      }) as CdpRunner["send"],
+    };
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 5,
+      trigger: vi.fn(),
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { effect_state: "none", phase: "arm_interception" },
+    });
+    expect(calls).toContainEqual({
+      method: "Page.setInterceptFileChooserDialog",
+      params: { enabled: false, cancel: true },
+    });
+  });
+
+  it("marks a timed-out file assignment unknown and detaches browser state", async () => {
+    const fixture = uploadCdp();
+    const originalSend = fixture.cdp.send;
+    const detach = vi.fn(async () => {});
+    fixture.cdp.detach = detach;
+    fixture.cdp.send = vi.fn((tabId: number, method: string, params?: object) => {
+      if (method === "DOM.setFileInputFiles") return new Promise<never>(() => {});
+      return originalSend(tabId, method, params);
+    }) as CdpRunner["send"];
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp: fixture.cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 10,
+      trigger: async () => ({ tab_id: 4, x: 10, y: 10 }),
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { effect_state: "unknown", phase: "set_files" },
+    });
+    expect(detach).toHaveBeenCalledWith(4);
+  });
+
+  it("routes one exact-target download through a browser-relative capability", async () => {
+    const manager = sessions();
+    const ctx = await manager.start("s1");
+    ctx.refStore.set("e3", 123, { tabId: 4 });
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 9,
+      url: "https://example.test/result.zip",
+      finalUrl: "https://example.test/result.zip",
+      filename: "result.zip",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: 12,
+      mime: "application/zip",
+      danger: "safe",
+    } as chrome.downloads.DownloadItem;
+    const completed = {
+      ...initial,
+      filename: "/profile/Downloads/BrowserSkill/tr_1/result.zip",
+      state: "complete",
+      fileSize: 12,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => [completed]),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    let suggested: chrome.downloads.DownloadFilenameSuggestion | undefined;
+    const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+      if (method === "Page.getLayoutMetrics")
+        return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
+      if (method === "DOM.getContentQuads") return { quads: [[0, 0, 20, 0, 20, 20, 0, 20]] };
+      if (
+        method === "Input.dispatchMouseEvent" &&
+        (params as { type?: string }).type === "mousePressed"
+      ) {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: "result.zip",
+        });
+        await new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, (value) => {
+            suggested = value;
+            resolve();
+          });
+        });
+        onCreated.emit(completed);
+      }
+      return {};
+    });
+    const cdp: CdpRunner = {
+      send: send as unknown as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+
+    const result = await handleDownload(
+      manager,
+      { session_id: "s1", ref: "@e3", browser_relative_dir: "BrowserSkill/tr_1" },
+      { cdp, tabsApi: tabsApi(), downloads },
+    );
+
+    expect(suggested).toEqual({
+      filename: "BrowserSkill/tr_1/result.zip",
+      conflictAction: "overwrite",
+    });
+    expect(result).toMatchObject({
+      tab_id: 4,
+      suggested_filename: "result.zip",
+      byte_size: 12,
+      browser_path: completed.filename,
+    });
+  });
+
+  it("does not claim a download without an intent from the exact target", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => []),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as unknown as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+    const unrelated = {
+      id: 17,
+      url: "https://example.test/unrelated.zip",
+      finalUrl: "https://example.test/unrelated.zip",
+      filename: "unrelated.zip",
+      state: "in_progress",
+    } as chrome.downloads.DownloadItem;
+    let defaultSuggestionCalled = false;
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4, sessionId: "expected-child" },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_1",
+      timeoutMs: 5,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4, sessionId: "other-child" }, "Page.downloadWillBegin", {
+          url: unrelated.url,
+          suggestedFilename: unrelated.filename,
+        });
+        onDeterminingFilename.emit(unrelated, (suggestion) => {
+          defaultSuggestionCalled = suggestion === undefined;
+        });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(defaultSuggestionCalled).toBe(true);
+    expect(downloads.cancel).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "download_capture_failed" },
+    });
+  });
+
+  it("correlates a filename candidate that arrives before the CDP intent", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 21,
+      url: "https://example.test/candidate-first.bin",
+      finalUrl: "https://example.test/candidate-first.bin",
+      filename: "candidate-first.bin",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: 4,
+      bytesReceived: 0,
+    } as chrome.downloads.DownloadItem;
+    const complete = {
+      ...initial,
+      state: "complete",
+      fileSize: 4,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => [complete]),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+    let suggestion: chrome.downloads.DownloadFilenameSuggestion | undefined;
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_21",
+      timeoutMs: 1_000,
+      trigger: async () => {
+        const suggested = new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, (value) => {
+            suggestion = value;
+            resolve();
+          });
+        });
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: initial.filename,
+        });
+        await suggested;
+        onCreated.emit(complete);
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(suggestion).toEqual({
+      filename: "BrowserSkill/tr_21/candidate-first.bin",
+      conflictAction: "overwrite",
+    });
+    expect(result).toMatchObject({ item: { id: 21, state: "complete" } });
+  });
+
+  it("removes a completed download when the final size exceeds the limit", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 22,
+      url: "https://example.test/oversized.bin",
+      finalUrl: "https://example.test/oversized.bin",
+      filename: "oversized.bin",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: -1,
+      bytesReceived: 0,
+    } as chrome.downloads.DownloadItem;
+    const complete = {
+      ...initial,
+      filename: "/profile/Downloads/BrowserSkill/tr_22/oversized.bin",
+      state: "complete",
+      fileSize: 8,
+      totalBytes: 8,
+      bytesReceived: 8,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => [complete]),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_22",
+      maxByteSize: 4,
+      timeoutMs: 1_000,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: initial.filename,
+        });
+        await new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, () => resolve());
+        });
+        onCreated.emit(initial);
+        onChanged.emit({ id: initial.id, state: { current: "complete" } });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "download_capture_failed", effect_state: "committed" },
+    });
+    expect(downloads.removeFile).toHaveBeenCalledWith(initial.id);
+    expect(downloads.cancel).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["cancel resolves", false],
+    ["cancel reports that completion won", true],
+  ])("reconciles a download that completes while %s", async (_label, cancelThrows) => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 23,
+      url: "https://example.test/racing.bin",
+      finalUrl: "https://example.test/racing.bin",
+      filename: "racing.bin",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: -1,
+      bytesReceived: 0,
+    } as chrome.downloads.DownloadItem;
+    const complete = {
+      ...initial,
+      filename: "/profile/Downloads/BrowserSkill/tr_23/racing.bin",
+      state: "complete",
+      fileSize: 4,
+      totalBytes: 4,
+      bytesReceived: 4,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn().mockResolvedValueOnce([initial]).mockResolvedValueOnce([complete]),
+      cancel: vi.fn(async () => {
+        if (cancelThrows) throw new Error("download already complete");
+      }),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_23",
+      timeoutMs: 80,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: initial.filename,
+        });
+        await new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, () => resolve());
+        });
+        onCreated.emit(initial);
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "download_capture_failed", effect_state: "committed" },
+    });
+    expect(downloads.cancel).toHaveBeenCalledWith(initial.id);
+    expect(downloads.removeFile).toHaveBeenCalledWith(initial.id);
+    expect(result).not.toMatchObject({ data: { cleanup_state: "failed" } });
+  });
+
+  it("rejects ambiguous attribution without cancelling either unclaimed download", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => []),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+    const defaults: number[] = [];
+    const candidate = (id: number) =>
+      ({
+        id,
+        url: "https://example.test/same.bin",
+        finalUrl: "https://example.test/same.bin",
+        filename: "same.bin",
+        state: "in_progress",
+      }) as chrome.downloads.DownloadItem;
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_ambiguous",
+      timeoutMs: 100,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: "https://example.test/same.bin",
+          suggestedFilename: "same.bin",
+        });
+        for (const id of [31, 32]) {
+          onDeterminingFilename.emit(candidate(id), (value) => {
+            if (value === undefined) defaults.push(id);
+          });
+        }
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(defaults.sort()).toEqual([31, 32]);
+    expect(downloads.cancel).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { effect_state: "unknown", phase: "attribution" },
+    });
+  });
+});

apps/extension/src/tools/__tests__/interaction.test.ts

@@ -7,12 +7,10 @@ import {
   handleHover,
   handlePress,
   handleSelect,
-  handleType,
   modifiersBitfield,
   parseKeySpec,
   resolveKeyDescriptor,
 } from "../interaction";
-import { captureSurfaceEnvironment } from "../surface-target";
 
 function fakeAgentWindow(ids: number[]) {
   let i = 0;
@@ -35,15 +33,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
     if (!h && method === "Page.getLayoutMetrics") {
       return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
     }
-    if (
-      !h &&
-      method === "Runtime.evaluate" &&
-      String((params as { expression?: string })?.expression ?? "").includes(
-        "bsk-focus-target-probe",
-      )
-    ) {
-      return { result: { value: { hasFocus: true, activeTag: "input" } } };
-    }
     if (!h) throw new Error(`unexpected CDP call ${method}`);
     return h(params);
   };
@@ -55,10 +44,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
       params?: object,
     ) => Promise<T>,
     trackSessionTab: vi.fn(),
-    getFrameGraph: vi.fn(async (tabId) => ({
-      rootFrameId: "main",
-      frames: [{ frameId: "main", target: { tabId } }],
-    })),
   };
   const tabsApi = {
     get: vi.fn(
@@ -69,84 +54,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
   return { cdp, tabsApi, sent };
 }
 
-function fillRuntimeReadback(value: string) {
-  return (params: unknown) => {
-    const fn = String((params as { functionDeclaration?: string }).functionDeclaration ?? "");
-    if (fn.includes("bsk-editable-state")) {
-      return {
-        result: {
-          value: {
-            supported: true,
-            connected: true,
-            focused: true,
-            value,
-            kind: "input",
-          },
-        },
-      };
-    }
-    if (fn.includes("bsk-editable-selection")) {
-      return { result: { value: { selected: true } } };
-    }
-    return { result: { type: "undefined" } };
-  };
-}
-
-async function makeSurfaceClickFixture(onMouse?: (params: Record<string, unknown>) => void) {
-  const manager = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-  const context = await manager.start("aa11");
-  context.refStore.set("e3", 99, {
-    tabId: 4,
-    kind: "surface",
-    visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-  });
-  const fake = makeFakeCdp({
-    "Page.getFrameTree": () => ({
-      frameTree: {
-        frame: { id: "main", loaderId: "loader-1", url: "https://fixture.test/" },
-      },
-    }),
-    "Page.getLayoutMetrics": () => ({
-      cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY: 0 },
-      cssVisualViewport: {
-        clientWidth: 800,
-        clientHeight: 600,
-        pageX: 0,
-        pageY: 0,
-        scale: 1,
-      },
-    }),
-    "DOM.getContentQuads": () => ({ quads: [[10, 20, 110, 20, 110, 60, 10, 60]] }),
-    "Runtime.evaluate": () => ({
-      result: { value: { overlayHostPresent: false, overlayHostConnected: false } },
-    }),
-    "Input.dispatchMouseEvent": (params) => {
-      onMouse?.(params as Record<string, unknown>);
-      return {};
-    },
-  });
-  const environment = await captureSurfaceEnvironment(fake.cdp, 4, undefined);
-  if ("code" in environment) throw new Error(environment.message);
-  const entry = context.refStore.resolveEntry("e3");
-  if (!entry) throw new Error("missing Surface ref");
-  const capture = context.surfaceCaptures.create({
-    sessionId: "aa11",
-    tabId: 4,
-    navigationIdentity: environment.navigationIdentity,
-    surface: {
-      ref: "e3",
-      backendNodeId: 99,
-      observationGeneration: entry.generation,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 40 },
-    imageWidth: 200,
-    imageHeight: 80,
-    viewportSignature: environment.viewportSignature,
-    frameProjectionSignature: environment.frameProjectionSignature,
-  });
-  return { manager, context, fake, capture };
-}
-
 describe("modifiersBitfield", () => {
   it("matches CDP's expected bit layout", () => {
     expect(modifiersBitfield([])).toBe(0);
@@ -283,74 +190,6 @@ describe("handleClick", () => {
     });
   });
 
-  it.each([
-    "left",
-    "middle",
-    "right",
-  ] as const)("uses the common click executor for a %s-button Surface click", async (button) => {
-    const { manager, fake, capture } = await makeSurfaceClickFixture();
-    const result = await handleClick(
-      manager,
-      {
-        session_id: "aa11",
-        ref: "@e3",
-        capture_id: capture.id,
-        image_x: 50,
-        image_y: 20,
-        button,
-        click_count: 2,
-        modifiers: ["ctrl", "shift"],
-      },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      used_ref: "e3",
-      capture_id: capture.id,
-      image_x: 50,
-      image_y: 20,
-      x: 35,
-      y: 30,
-    });
-    const mouse = fake.sent.filter((call) => call.method === "Input.dispatchMouseEvent");
-    expect(mouse).toHaveLength(3);
-    expect(mouse[1].params).toMatchObject({
-      type: "mousePressed",
-      button,
-      clickCount: 2,
-      modifiers: 2 | 8,
-    });
-    expect(mouse[2].params).toMatchObject({
-      type: "mouseReleased",
-      button,
-      clickCount: 2,
-    });
-  });
-
-  it("consumes a Surface capture when the common click executor fails", async () => {
-    let mouseCalls = 0;
-    const { manager, fake, capture } = await makeSurfaceClickFixture((params) => {
-      mouseCalls += 1;
-      if (params.type === "mousePressed") throw new Error("input failed");
-    });
-    const params = {
-      session_id: "aa11",
-      ref: "@e3",
-      capture_id: capture.id,
-      image_x: 50,
-      image_y: 20,
-    };
-
-    expect(
-      await handleClick(manager, params, { cdp: fake.cdp, tabsApi: fake.tabsApi }),
-    ).toMatchObject({ code: "cdp_failed" });
-    expect(mouseCalls).toBe(2);
-    expect(
-      await handleClick(manager, params, { cdp: fake.cdp, tabsApi: fake.tabsApi }),
-    ).toMatchObject({ data: { reason: "surface_capture_consumed" } });
-  });
-
   it("resolves frame refs in their CDP session and dispatches input in top coordinates", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
@@ -770,7 +609,7 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": fillRuntimeReadback("hello"),
+      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(
@@ -784,13 +623,13 @@ describe("handleFill", () => {
     expect(res.used_ref).toBe("e1");
     const insert = fake.sent.find((c) => c.method === "Input.insertText");
     expect(insert?.params).toEqual({ text: "hello" });
-    // clear_before defaults to true, so the edit transaction prepares a
-    // replacement selection and performs a settled live-value readback.
+    // clear_before defaults to true → callFunctionOn invoked once to
+    // clear, once to fire input/change after typing.
     const callFns = fake.sent.filter((c) => c.method === "Runtime.callFunctionOn");
     expect(callFns.length).toBeGreaterThanOrEqual(2);
   });
 
-  it("clear_before=false skips replacement selection", async () => {
+  it("clear_before=false skips the wipe call", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
     ctx.refStore.set("e1", 1, { tabId: 4 });
@@ -803,20 +642,9 @@ describe("handleFill", () => {
       "DOM.resolveNode": () => ({ object: { objectId: "obj-2" } }),
       "Runtime.callFunctionOn": (p) => {
         const fn = (p as { functionDeclaration?: string }).functionDeclaration ?? "";
-        if (fn.includes("bsk-editable-state")) {
-          return {
-            result: {
-              value: {
-                supported: true,
-                connected: true,
-                focused: true,
-                value: "existingx",
-                kind: "textarea",
-              },
-            },
-          };
-        }
-        expect(fn).not.toMatch(/dispatchEvent|\.value\s*=/);
+        // No "this.value = ''" clearing on a no-clear path; only the
+        // post-input dispatchEvent.
+        expect(fn).not.toMatch(/this\.value\s*=\s*''/);
         return { result: { type: "undefined" } };
       },
       "Input.insertText": () => ({}),
@@ -827,7 +655,7 @@ describe("handleFill", () => {
       { cdp: fake.cdp, tabsApi: fake.tabsApi },
     );
     if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(res.value_length).toBe(9);
+    expect(res.value_length).toBe(1);
   });
 
   it("treats contenteditable=true as fillable", async () => {
@@ -845,7 +673,7 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-3" } }),
-      "Runtime.callFunctionOn": fillRuntimeReadback("rich"),
+      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(
@@ -856,103 +684,7 @@ describe("handleFill", () => {
     expect("code" in res).toBe(false);
   });
 
-  it("routes OOPIF focus, text, DOM events, and readback through the node target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, {
-      tabId: 4,
-      frameId: "child-frame",
-      cdpSessionId: "child-session",
-    });
-    const fake = makeFakeCdp({ "DOM.scrollIntoViewIfNeeded": () => ({}) });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          ownerBackendNodeId: 12,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (target, method, params) => {
-      expect(target).toEqual({ tabId: 4, sessionId: "child-session" });
-      childCalls.push(method);
-      if (method === "DOM.describeNode") {
-        return { node: { backendNodeId: 77, nodeName: "INPUT", attributes: [] } };
-      }
-      if (method === "DOM.scrollIntoViewIfNeeded" || method === "DOM.focus") return {};
-      if (method === "DOM.resolveNode") return { object: { objectId: "child-input" } };
-      if (method === "Input.insertText") {
-        expect(params).toEqual({ text: "中文输入" });
-        return {};
-      }
-      if (method === "Runtime.callFunctionOn") {
-        const fn = String((params as { functionDeclaration?: string }).functionDeclaration ?? "");
-        if (fn.includes("bsk-editable-state")) {
-          return {
-            result: {
-              value: {
-                supported: true,
-                connected: true,
-                focused: true,
-                value: "中文输入",
-                kind: "input",
-              },
-            },
-          };
-        }
-        if (fn.includes("bsk-editable-selection")) {
-          return { result: { value: { selected: true } } };
-        }
-        return { result: { type: "undefined" } };
-      }
-      throw new Error(`unexpected child call ${method}`);
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handleFill(
-      sm,
-      { session_id: "aa11", ref: "@e1", value: "中文输入" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in res) throw new Error(JSON.stringify(res));
-    expect(res.value_length).toBe(4);
-    expect(childCalls).toContain("DOM.focus");
-    expect(childCalls).toContain("Input.insertText");
-    expect(childCalls.filter((method) => method === "Runtime.callFunctionOn")).toHaveLength(4);
-    expect(fake.sent.some((call) => call.method === "Input.insertText")).toBe(false);
-  });
-
-  it("returns input_not_applied when a controlled input resets the value", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 8, { tabId: 4 });
-    const fake = makeFakeCdp({
-      "DOM.describeNode": () => ({ node: { backendNodeId: 8, nodeName: "INPUT" } }),
-      "DOM.scrollIntoViewIfNeeded": () => ({}),
-      "DOM.focus": () => ({}),
-      "DOM.resolveNode": () => ({ object: { objectId: "controlled" } }),
-      "Input.insertText": () => ({}),
-      "Runtime.callFunctionOn": fillRuntimeReadback(""),
-    });
-
-    const res = await handleFill(
-      sm,
-      { session_id: "aa11", ref: "@e1", value: "rejected" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(res).toMatchObject({
-      code: "cdp_failed",
-      data: { reason: "input_not_applied", expected_value_length: 8, actual_value_length: 0 },
-    });
-  });
-
-  it("stops before Input.insertText when abort fires after preparing replacement", async () => {
+  it("stops before Input.insertText when abort fires after clearing", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
     ctx.refStore.set("e1", 555, { tabId: 4 });
@@ -964,25 +696,8 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": (params) => {
-        const fn = String((params as { functionDeclaration?: string }).functionDeclaration ?? "");
-        if (fn.includes("bsk-editable-state")) {
-          return {
-            result: {
-              value: {
-                supported: true,
-                connected: true,
-                focused: true,
-                value: "",
-                kind: "input",
-              },
-            },
-          };
-        }
-        if (fn.includes("bsk-editable-selection")) {
-          abort.abort();
-          return { result: { value: { selected: true } } };
-        }
+      "Runtime.callFunctionOn": () => {
+        abort.abort();
         return { result: { type: "undefined" } };
       },
       "Input.insertText": () => ({}),
@@ -1025,204 +740,6 @@ describe("handleFill", () => {
   });
 });
 
-describe("handleType", () => {
-  it("requires an explicit target mode instead of silently using focus", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({});
-
-    const missing = await handleType(
-      sm,
-      { session_id: "aa11", text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-    expect(missing).toMatchObject({
-      code: "invalid_params",
-      message: expect.stringContaining("focused=true"),
-    });
-
-    const mixed = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", focused: true, text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-    expect(mixed).toMatchObject({
-      code: "invalid_params",
-      message: expect.stringContaining("not both"),
-    });
-    expect(fake.sent).toHaveLength(0);
-  });
-
-  it("routes committed IME text through the explicit OOPIF target without DOM readback", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, {
-      tabId: 4,
-      frameId: "child-frame",
-      cdpSessionId: "child-session",
-    });
-    const fake = makeFakeCdp({ "DOM.scrollIntoViewIfNeeded": () => ({}) });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          ownerBackendNodeId: 12,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: Array<{ method: string; params?: object }> = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method, params) => {
-      childCalls.push({ method, params });
-      if (method === "DOM.describeNode") {
-        return { node: { backendNodeId: 77, nodeName: "TEXTAREA", attributes: [] } };
-      }
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", text: "测试" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      tab_id: 4,
-      used_ref: "e1",
-      text_length: 2,
-      verification: "dispatched",
-    });
-    expect(childCalls.map((call) => call.method)).toEqual([
-      "DOM.describeNode",
-      "DOM.scrollIntoViewIfNeeded",
-      "DOM.focus",
-      "Input.dispatchKeyEvent",
-      "Input.insertText",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-    expect(childCalls.some((call) => call.method === "Runtime.callFunctionOn")).toBe(false);
-  });
-
-  it("uses the focused OOPIF only when focused mode resolves a text-entry target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "iframe", textEntry: false } },
-      }),
-    });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method) => {
-      childCalls.push(method);
-      if (method === "Runtime.evaluate") {
-        return {
-          result: { value: { hasFocus: true, activeTag: "textarea", textEntry: true } },
-        };
-      }
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", focused: true, text: "A" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({ text_length: 1, verification: "dispatched" });
-    expect(childCalls).toEqual([
-      "Runtime.evaluate",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-  });
-
-  it("refuses focused mode when focus is not owned by a text-entry target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "button", textEntry: false } },
-      }),
-    });
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", focused: true, text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(result).toMatchObject({
-      code: "cdp_failed",
-      data: { reason: "focus_target_unresolved", candidate_count: 0 },
-    });
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-  });
-
-  it("rejects explicit non-text input controls", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, { tabId: 4 });
-    const fake = makeFakeCdp({
-      "DOM.describeNode": () => ({
-        node: { backendNodeId: 77, nodeName: "INPUT", attributes: ["type", "checkbox"] },
-      }),
-    });
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(result).toMatchObject({
-      code: "invalid_params",
-      data: { reason: "target_not_fillable" },
-    });
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-  });
-
-  it("rejects a Surface ref instead of treating it as a text target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, {
-      tabId: 4,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-    const fake = makeFakeCdp({});
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(result).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "ref_capability_denied", required_capability: "interact" },
-    });
-  });
-});
-
 describe("parseKeySpec", () => {
   it("splits compound expressions into modifiers + base key", () => {
     expect(parseKeySpec("Ctrl+A")).toEqual({ key: "A", modifiers: ["ctrl"] });
@@ -1361,125 +878,6 @@ describe("handlePress", () => {
     expect(res.key).toBe("Enter");
   });
 
-  it("routes ref-targeted key events through the OOPIF session", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 555, {
-      tabId: 4,
-      frameId: "child-frame",
-      cdpSessionId: "child-session",
-    });
-    const fake = makeFakeCdp({ "DOM.scrollIntoViewIfNeeded": () => ({}) });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          ownerBackendNodeId: 12,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method) => {
-      childCalls.push(method);
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handlePress(
-      sm,
-      { session_id: "aa11", key: "Enter", ref: "@e1" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expectPressOk(res);
-    expect(childCalls).toEqual([
-      "DOM.scrollIntoViewIfNeeded",
-      "DOM.focus",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.some((call) => call.method === "Input.dispatchKeyEvent")).toBe(false);
-  });
-
-  it("routes an untargeted press to the uniquely focused OOPIF session", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "iframe" } },
-      }),
-    });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method) => {
-      childCalls.push(method);
-      if (method === "Runtime.evaluate") {
-        return { result: { value: { hasFocus: true, activeTag: "textarea" } } };
-      }
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handlePress(
-      sm,
-      { session_id: "aa11", key: "a" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expectPressOk(res);
-    expect(childCalls).toEqual([
-      "Runtime.evaluate",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-  });
-
-  it("refuses an untargeted press when focus ownership is ambiguous", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "input" } },
-      }),
-    });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        { frameId: "child", target: { tabId: 4, sessionId: "child-session" } },
-      ],
-    }));
-    fake.cdp.sendToTarget = vi.fn(async () => ({
-      result: { value: { hasFocus: true, activeTag: "textarea" } },
-    })) as CdpRunner["sendToTarget"];
-
-    const res = await handlePress(
-      sm,
-      { session_id: "aa11", key: "Enter" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(res).toMatchObject({
-      code: "cdp_failed",
-      data: { reason: "focus_target_unresolved", candidate_count: 2 },
-    });
-    expect(fake.sent.some((call) => call.method === "Input.dispatchKeyEvent")).toBe(false);
-  });
-
   it("stops before focus when abort fires after press scroll", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");

apps/extension/src/tools/__tests__/mouse-input.test.ts

@@ -1,119 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { dispatchMouseClick } from "../mouse-input";
-import type { CdpRunner } from "../shared";
-
-function fakeCdp(onSend?: (method: string, params: Record<string, unknown>) => void): {
-  cdp: CdpRunner;
-  events: Record<string, unknown>[];
-} {
-  const events: Record<string, unknown>[] = [];
-  return {
-    events,
-    cdp: {
-      send: vi.fn(async (_tabId, method, params) => {
-        const event = params as Record<string, unknown>;
-        events.push(event);
-        onSend?.(method, event);
-        return {} as never;
-      }),
-    },
-  };
-}
-
-describe("dispatchMouseClick", () => {
-  it("emits one move, press, and release sequence", async () => {
-    const { cdp, events } = fakeCdp();
-
-    expect(
-      await dispatchMouseClick(
-        cdp,
-        4,
-        { x: 12, y: 34 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          moveSettleMs: 0,
-        },
-      ),
-    ).toBe("completed");
-
-    expect(events).toEqual([
-      {
-        type: "mouseMoved",
-        x: 12,
-        y: 34,
-        modifiers: 0,
-      },
-      {
-        type: "mousePressed",
-        x: 12,
-        y: 34,
-        button: "left",
-        clickCount: 1,
-        modifiers: 0,
-      },
-      {
-        type: "mouseReleased",
-        x: 12,
-        y: 34,
-        button: "left",
-        clickCount: 1,
-        modifiers: 0,
-      },
-    ]);
-  });
-
-  it("releases a pressed button when cancellation arrives", async () => {
-    const controller = new AbortController();
-    const { cdp, events } = fakeCdp((_method, event) => {
-      if (event.type === "mousePressed") controller.abort();
-    });
-
-    expect(
-      await dispatchMouseClick(
-        cdp,
-        4,
-        { x: 1, y: 2 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          signal: controller.signal,
-          moveSettleMs: 0,
-        },
-      ),
-    ).toBe("cancelled");
-    expect(events.at(-1)).toMatchObject({ type: "mouseReleased" });
-  });
-
-  it("settles pointer-move hit testing before pressing", async () => {
-    vi.useFakeTimers();
-    try {
-      const { cdp, events } = fakeCdp();
-      const click = dispatchMouseClick(
-        cdp,
-        4,
-        { x: 1, y: 2 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          moveSettleMs: 32,
-        },
-      );
-
-      await vi.advanceTimersByTimeAsync(31);
-      expect(events.map((event) => event.type)).toEqual(["mouseMoved"]);
-      await vi.advanceTimersByTimeAsync(1);
-      await click;
-      expect(events.map((event) => event.type)).toEqual([
-        "mouseMoved",
-        "mousePressed",
-        "mouseReleased",
-      ]);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});

apps/extension/src/tools/__tests__/observation.test.ts

@@ -36,6 +36,14 @@ function fakeAgentWindow(ids: number[]) {
 const TINY_PNG =
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGBgAAAABQABh6FO1AAAAABJRU5ErkJggg==";
 
+function pngWithIhdrDimensions(width: number, height: number): string {
+  const bytes = Uint8Array.from(atob(TINY_PNG), (character) => character.charCodeAt(0));
+  const view = new DataView(bytes.buffer);
+  view.setUint32(16, width);
+  view.setUint32(20, height);
+  return btoa(String.fromCharCode(...bytes));
+}
+
 function makeScreenshotDeps(
   opts: {
     cdp?: CdpRunner;
@@ -67,9 +75,6 @@ function makeFakeCdp(handlers: Record<string, (params?: object) => unknown>) {
     if (!handler && method === "Page.getLayoutMetrics") {
       return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
     }
-    if (!handler && method === "Page.getFrameTree") {
-      return { frameTree: { frame: { id: "main", loaderId: "loader-1", url: "https://test/" } } };
-    }
     if (!handler) throw new Error(`unexpected CDP call ${method}`);
     return handler(params);
   });
@@ -89,6 +94,7 @@ describe("stripDataUrlPrefix", () => {
 describe("parsePngDimensions", () => {
   it("parses width/height from the IHDR chunk", () => {
     expect(parsePngDimensions(TINY_PNG)).toEqual({ width: 1, height: 1 });
+    expect(parsePngDimensions(pngWithIhdrDimensions(100, 80))).toEqual({ width: 100, height: 80 });
   });
   it("returns null on non-PNG input", () => {
     expect(parsePngDimensions("not-a-png-payload-just-random-base64-text-zzzzzzzzz")).toBeNull();
@@ -123,6 +129,20 @@ describe("handleScreenshot", () => {
     expect(get).not.toHaveBeenCalled();
   });
 
+  it("fails closed when a full-tab capture is not a valid PNG", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    await sm.start("aa11");
+    const res = await handleScreenshot(
+      sm,
+      { session_id: "aa11" },
+      makeScreenshotDeps({
+        captureVisibleTab: vi.fn(async () => "data:image/png;base64,bm90LWEtcG5n"),
+      }),
+    );
+
+    expect(res).toMatchObject({ code: "cdp_failed", message: /invalid PNG data/ });
+  });
+
   it("returns not_found when Agent Window has no active tab", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     await sm.start("aa11");
@@ -337,11 +357,6 @@ describe("handleScreenshot", () => {
     };
     expect(clip.clip).toMatchObject({ width: 4096, height: 4096 });
     expect(clip.clip?.scale).toBeCloseTo(Math.sqrt(4_000_000 / (4096 * 4096)));
-    expect(res.capture).toMatchObject({
-      surface_ref: "@e5",
-      coordinate_space: "capture-image-pixel",
-    });
-    expect(ctx.surfaceCaptures.size()).toBe(1);
   });
 
   it("crops a visual surface screenshot to its observation-time visible region", async () => {
@@ -357,7 +372,7 @@ describe("handleScreenshot", () => {
         cssLayoutViewport: { clientWidth: 800, clientHeight: 600 },
       }),
       "DOM.getContentQuads": () => ({ quads: [[0, 0, 200, 0, 200, 100, 0, 100]] }),
-      "Page.captureScreenshot": () => ({ data: TINY_PNG }),
+      "Page.captureScreenshot": () => ({ data: pngWithIhdrDimensions(100, 80) }),
     });
 
     const res = await handleScreenshot(
@@ -376,7 +391,95 @@ describe("handleScreenshot", () => {
       clip?: { x: number; y: number; width: number; height: number };
     };
     expect(clip.clip).toMatchObject({ x: 25, y: 30, width: 50, height: 40 });
-    expect(res.capture?.id).toMatch(/^sc_/);
+    expect(res).toMatchObject({ width: 100, height: 80 });
+  });
+
+  it("routes OOPIF surface geometry through its child session and captures top coordinates", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e5", 999, {
+      tabId: 7,
+      frameId: "child-frame",
+      cdpSessionId: "child-session",
+      kind: "surface",
+      visibleRect: { x: 224, y: 346, w: 200, h: 80 },
+    });
+    const { cdp, sent } = makeFakeCdp({
+      "DOM.getBoxModel": () => ({
+        model: { content: [204, 306, 604, 306, 604, 506, 204, 506] },
+      }),
+      "Page.getLayoutMetrics": () => ({
+        cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+      }),
+      "Page.captureScreenshot": () => ({ data: TINY_PNG }),
+    });
+    cdp.getFrameGraph = vi.fn(async () => ({
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 7 } },
+        {
+          frameId: "child-frame",
+          parentFrameId: "main",
+          ownerBackendNodeId: 99,
+          target: { tabId: 7, sessionId: "child-session" },
+        },
+      ],
+    }));
+    const targetCalls: Array<{ sessionId?: string; method: string }> = [];
+    cdp.sendToTarget = vi.fn(async (target, method) => {
+      targetCalls.push({ sessionId: target.sessionId, method });
+      if (method === "DOM.getContentQuads") {
+        return { quads: [[10, 20, 110, 20, 110, 60, 10, 60]] };
+      }
+      if (method === "Page.getLayoutMetrics") {
+        return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
+      }
+      throw new Error(`unexpected child CDP call ${method}`);
+    }) as CdpRunner["sendToTarget"];
+
+    const res = await handleScreenshot(
+      sm,
+      { session_id: "aa11", ref: "@e5", tab_id: 7 },
+      makeScreenshotDeps({
+        cdp,
+        get: vi.fn(async () => ({ id: 7, windowId: 100, active: false }) as chrome.tabs.Tab),
+        query: vi.fn(),
+        captureVisibleTab: vi.fn(),
+      }),
+    );
+
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(targetCalls).toEqual([
+      { sessionId: "child-session", method: "DOM.getContentQuads" },
+      { sessionId: "child-session", method: "Page.getLayoutMetrics" },
+    ]);
+    const clip = sent.find((call) => call.method === "Page.captureScreenshot")?.params as {
+      clip?: { x: number; y: number; width: number; height: number };
+    };
+    expect(clip.clip).toMatchObject({ x: 224, y: 346, width: 200, height: 80 });
+  });
+
+  it("fails closed when a ref capture is not a valid PNG", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e5", 999, { tabId: 7, kind: "surface" });
+    const { cdp } = makeFakeCdp({
+      "DOM.getContentQuads": () => ({ quads: [[0, 0, 50, 0, 50, 50, 0, 50]] }),
+      "Page.captureScreenshot": () => ({ data: "bm90LWEtcG5n" }),
+    });
+
+    const res = await handleScreenshot(
+      sm,
+      { session_id: "aa11", ref: "@e5", tab_id: 7 },
+      makeScreenshotDeps({
+        cdp,
+        get: vi.fn(async () => ({ id: 7, windowId: 100, active: false }) as chrome.tabs.Tab),
+        query: vi.fn(),
+        captureVisibleTab: vi.fn(),
+      }),
+    );
+
+    expect(res).toMatchObject({ code: "cdp_failed", message: /invalid PNG data/ });
   });
 
   it("returns not_found for unknown ref", async () => {
@@ -1983,36 +2086,41 @@ describe("buildVomScene", () => {
         backendDOMNodeId: 20,
       },
     ];
-    const scene = buildVomScene(axNodes, {
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      excludedBackendNodeIds: new Set(),
-      surfaceProbes: [
-        { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["Shoes", "Bags"] },
-      ],
-      nodes: [
-        {
-          backendNodeId: 10,
-          parentBackendNodeId: null,
-          tag: "body",
-          attrs: {},
-          rect: { x: 0, y: 0, w: 1000, h: 800 },
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-        },
-        {
-          backendNodeId: 20,
-          parentBackendNodeId: 10,
-          tag: "button",
-          attrs: {},
-          rect: { x: 20, y: 20, w: 120, h: 40 },
-          paintOrder: 1,
-          position: "static",
-          pointerEvents: "auto",
-        },
-      ],
-    });
+    const scene = buildVomScene(
+      axNodes,
+      {
+        viewport: { width: 1000, height: 800 },
+        iframeNodes: new Map(),
+        excludedBackendNodeIds: new Set(),
+        nodes: [
+          {
+            backendNodeId: 10,
+            parentBackendNodeId: null,
+            tag: "body",
+            attrs: {},
+            rect: { x: 0, y: 0, w: 1000, h: 800 },
+            paintOrder: 0,
+            position: "static",
+            pointerEvents: "auto",
+          },
+          {
+            backendNodeId: 20,
+            parentBackendNodeId: 10,
+            tag: "button",
+            attrs: {},
+            rect: { x: 20, y: 20, w: 120, h: 40 },
+            paintOrder: 1,
+            position: "static",
+            pointerEvents: "auto",
+          },
+        ],
+      },
+      {
+        surfaceProbes: [
+          { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["Shoes", "Bags"] },
+        ],
+      },
+    );
 
     expect(scene.surfaces).toEqual([
       { triggerId: 20, triggerAction: "hover", subItems: ["Shoes", "Bags"] },
@@ -2036,46 +2144,51 @@ describe("buildVomScene", () => {
         backendDOMNodeId: 21,
       },
     ];
-    const scene = buildVomScene(axNodes, {
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      excludedBackendNodeIds: new Set(),
-      surfaceProbes: [
-        { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["My profile"] },
-      ],
-      nodes: [
-        {
-          backendNodeId: 10,
-          parentBackendNodeId: null,
-          tag: "body",
-          attrs: {},
-          rect: { x: 0, y: 0, w: 1000, h: 800 },
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-        },
-        {
-          backendNodeId: 20,
-          parentBackendNodeId: 10,
-          tag: "div",
-          attrs: { class: "tg-avatar" },
-          rect: { x: 900, y: 10, w: 30, h: 30 },
-          paintOrder: 1,
-          position: "static",
-          pointerEvents: "auto",
-        },
-        {
-          backendNodeId: 21,
-          parentBackendNodeId: 20,
-          tag: "div",
-          attrs: { class: "tg-avatar__inner" },
-          rect: { x: 902, y: 12, w: 26, h: 26 },
-          paintOrder: 2,
-          position: "static",
-          pointerEvents: "auto",
-        },
-      ],
-    });
+    const scene = buildVomScene(
+      axNodes,
+      {
+        viewport: { width: 1000, height: 800 },
+        iframeNodes: new Map(),
+        excludedBackendNodeIds: new Set(),
+        nodes: [
+          {
+            backendNodeId: 10,
+            parentBackendNodeId: null,
+            tag: "body",
+            attrs: {},
+            rect: { x: 0, y: 0, w: 1000, h: 800 },
+            paintOrder: 0,
+            position: "static",
+            pointerEvents: "auto",
+          },
+          {
+            backendNodeId: 20,
+            parentBackendNodeId: 10,
+            tag: "div",
+            attrs: { class: "tg-avatar" },
+            rect: { x: 900, y: 10, w: 30, h: 30 },
+            paintOrder: 1,
+            position: "static",
+            pointerEvents: "auto",
+          },
+          {
+            backendNodeId: 21,
+            parentBackendNodeId: 20,
+            tag: "div",
+            attrs: { class: "tg-avatar__inner" },
+            rect: { x: 902, y: 12, w: 26, h: 26 },
+            paintOrder: 2,
+            position: "static",
+            pointerEvents: "auto",
+          },
+        ],
+      },
+      {
+        surfaceProbes: [
+          { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["My profile"] },
+        ],
+      },
+    );
 
     expect(renderVom(scene).text).toContain('@e1 button "image" [hover first: My profile]');
   });
@@ -2096,48 +2209,53 @@ describe("buildVomScene", () => {
         backendDOMNodeId: 21,
       },
     ];
-    const scene = buildVomScene(axNodes, {
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      excludedBackendNodeIds: new Set(),
-      surfaceProbes: [
-        { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["My profile"] },
-        { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["Sign out"] },
-        { triggerBackendNodeId: 21, triggerAction: "hover", subItems: ["Settings"] },
-      ],
-      nodes: [
-        {
-          backendNodeId: 10,
-          parentBackendNodeId: null,
-          tag: "body",
-          attrs: {},
-          rect: { x: 0, y: 0, w: 1000, h: 800 },
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-        },
-        {
-          backendNodeId: 20,
-          parentBackendNodeId: 10,
-          tag: "div",
-          attrs: { class: "tg-avatar" },
-          rect: { x: 900, y: 10, w: 30, h: 30 },
-          paintOrder: 1,
-          position: "static",
-          pointerEvents: "auto",
-        },
-        {
-          backendNodeId: 21,
-          parentBackendNodeId: 20,
-          tag: "div",
-          attrs: { class: "tg-avatar__inner" },
-          rect: { x: 902, y: 12, w: 26, h: 26 },
-          paintOrder: 2,
-          position: "static",
-          pointerEvents: "auto",
-        },
-      ],
-    });
+    const scene = buildVomScene(
+      axNodes,
+      {
+        viewport: { width: 1000, height: 800 },
+        iframeNodes: new Map(),
+        excludedBackendNodeIds: new Set(),
+        nodes: [
+          {
+            backendNodeId: 10,
+            parentBackendNodeId: null,
+            tag: "body",
+            attrs: {},
+            rect: { x: 0, y: 0, w: 1000, h: 800 },
+            paintOrder: 0,
+            position: "static",
+            pointerEvents: "auto",
+          },
+          {
+            backendNodeId: 20,
+            parentBackendNodeId: 10,
+            tag: "div",
+            attrs: { class: "tg-avatar" },
+            rect: { x: 900, y: 10, w: 30, h: 30 },
+            paintOrder: 1,
+            position: "static",
+            pointerEvents: "auto",
+          },
+          {
+            backendNodeId: 21,
+            parentBackendNodeId: 20,
+            tag: "div",
+            attrs: { class: "tg-avatar__inner" },
+            rect: { x: 902, y: 12, w: 26, h: 26 },
+            paintOrder: 2,
+            position: "static",
+            pointerEvents: "auto",
+          },
+        ],
+      },
+      {
+        surfaceProbes: [
+          { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["My profile"] },
+          { triggerBackendNodeId: 20, triggerAction: "hover", subItems: ["Sign out"] },
+          { triggerBackendNodeId: 21, triggerAction: "hover", subItems: ["Settings"] },
+        ],
+      },
+    );
 
     expect(scene.surfaces).toEqual([
       { triggerId: 21, triggerAction: "hover", subItems: ["My profile"] },
@@ -2160,54 +2278,59 @@ describe("buildVomScene", () => {
         backendDOMNodeId: 21,
       },
     ];
-    const scene = buildVomScene(axNodes, {
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      excludedBackendNodeIds: new Set(),
-      surfaceProbes: [
-        {
-          triggerBackendNodeId: 20,
-          triggerPoint: { x: 915, y: 25 },
-          triggerAction: "hover",
-          subItems: ["My profile", "Sign out"],
-        },
-      ],
-      nodes: [
-        {
-          backendNodeId: 10,
-          parentBackendNodeId: null,
-          tag: "body",
-          attrs: {},
-          rect: { x: 0, y: 0, w: 1000, h: 800 },
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-          cursor: "auto",
-        },
-        {
-          backendNodeId: 20,
-          parentBackendNodeId: 10,
-          tag: "div",
-          attrs: { class: "tg-avatar" },
-          rect: { x: 900, y: 10, w: 30, h: 30 },
-          paintOrder: 1,
-          position: "static",
-          pointerEvents: "auto",
-          cursor: "pointer",
-        },
-        {
-          backendNodeId: 21,
-          parentBackendNodeId: 20,
-          tag: "div",
-          attrs: { class: "tg-avatar__inner" },
-          rect: { x: 902, y: 12, w: 26, h: 26 },
-          paintOrder: 2,
-          position: "static",
-          pointerEvents: "auto",
-          cursor: "pointer",
-        },
-      ],
-    });
+    const scene = buildVomScene(
+      axNodes,
+      {
+        viewport: { width: 1000, height: 800 },
+        iframeNodes: new Map(),
+        excludedBackendNodeIds: new Set(),
+        nodes: [
+          {
+            backendNodeId: 10,
+            parentBackendNodeId: null,
+            tag: "body",
+            attrs: {},
+            rect: { x: 0, y: 0, w: 1000, h: 800 },
+            paintOrder: 0,
+            position: "static",
+            pointerEvents: "auto",
+            cursor: "auto",
+          },
+          {
+            backendNodeId: 20,
+            parentBackendNodeId: 10,
+            tag: "div",
+            attrs: { class: "tg-avatar" },
+            rect: { x: 900, y: 10, w: 30, h: 30 },
+            paintOrder: 1,
+            position: "static",
+            pointerEvents: "auto",
+            cursor: "pointer",
+          },
+          {
+            backendNodeId: 21,
+            parentBackendNodeId: 20,
+            tag: "div",
+            attrs: { class: "tg-avatar__inner" },
+            rect: { x: 902, y: 12, w: 26, h: 26 },
+            paintOrder: 2,
+            position: "static",
+            pointerEvents: "auto",
+            cursor: "pointer",
+          },
+        ],
+      },
+      {
+        surfaceProbes: [
+          {
+            triggerBackendNodeId: 20,
+            triggerPoint: { x: 915, y: 25 },
+            triggerAction: "hover",
+            subItems: ["My profile", "Sign out"],
+          },
+        ],
+      },
+    );
 
     expect(scene.surfaces).toEqual([
       { triggerId: 20, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
@@ -2233,41 +2356,46 @@ describe("buildVomScene", () => {
         backendDOMNodeId: 42,
       },
     ];
-    const scene = buildVomScene(axNodes, {
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      excludedBackendNodeIds: new Set(),
-      surfaceProbes: [
-        {
-          triggerBackendNodeId: 999,
-          triggerPoint: { x: 900, y: 20 },
-          triggerAction: "hover",
-          subItems: ["My profile"],
-        },
-      ],
-      nodes: [
-        {
-          backendNodeId: 10,
-          parentBackendNodeId: null,
-          tag: "body",
-          attrs: {},
-          rect: { x: 0, y: 0, w: 1000, h: 800 },
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-        },
-        {
-          backendNodeId: 42,
-          parentBackendNodeId: 10,
-          tag: "a",
-          attrs: {},
-          rect: { x: 860, y: 120, w: 40, h: 30 },
-          paintOrder: 1,
-          position: "static",
-          pointerEvents: "auto",
-        },
-      ],
-    });
+    const scene = buildVomScene(
+      axNodes,
+      {
+        viewport: { width: 1000, height: 800 },
+        iframeNodes: new Map(),
+        excludedBackendNodeIds: new Set(),
+        nodes: [
+          {
+            backendNodeId: 10,
+            parentBackendNodeId: null,
+            tag: "body",
+            attrs: {},
+            rect: { x: 0, y: 0, w: 1000, h: 800 },
+            paintOrder: 0,
+            position: "static",
+            pointerEvents: "auto",
+          },
+          {
+            backendNodeId: 42,
+            parentBackendNodeId: 10,
+            tag: "a",
+            attrs: {},
+            rect: { x: 860, y: 120, w: 40, h: 30 },
+            paintOrder: 1,
+            position: "static",
+            pointerEvents: "auto",
+          },
+        ],
+      },
+      {
+        surfaceProbes: [
+          {
+            triggerBackendNodeId: 999,
+            triggerPoint: { x: 900, y: 20 },
+            triggerAction: "hover",
+            subItems: ["My profile"],
+          },
+        ],
+      },
+    );
 
     expect(scene.surfaces).toBeUndefined();
     expect(renderVom(scene).text).not.toContain("[hover first:");
@@ -2685,7 +2813,106 @@ describe("handleSnapshot", () => {
     );
   });
 
-  it("enables conditional surface probing for semantic observe", async () => {
+  it("hovers the page only after the accessibility tree has been captured", async () => {
+    // Hovering can open menus and reflow the page. Probing between the DOM and
+    // AX captures would leave the two halves of one observation describing the
+    // page on either side of that change.
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    await sm.start("aa11");
+    const root: CdpAxNode = {
+      nodeId: "1",
+      role: { type: "role", value: "RootWebArea" },
+      name: { type: "computedString", value: "Example" },
+      backendDOMNodeId: 100,
+      childIds: ["2"],
+    };
+    const button: CdpAxNode = {
+      nodeId: "2",
+      parentId: "1",
+      role: { type: "role", value: "button" },
+      name: { type: "computedString", value: "Products" },
+      backendDOMNodeId: 200,
+    };
+    const strings = ["body", "button", "position", "static", "pointer-events", "auto", "cursor"];
+    const i = (s: string) => strings.indexOf(s);
+    const methodOrder: string[] = [];
+    const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+      methodOrder.push(method);
+      if (method === "Accessibility.enable") return {};
+      if (method === "Accessibility.getFullAXTree") return { nodes: [root, button] };
+      if (method === "Page.getLayoutMetrics") {
+        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+      }
+      if (method === "DOMSnapshot.enable") return {};
+      if (method === "DOMSnapshot.captureSnapshot") {
+        return {
+          strings,
+          documents: [
+            {
+              nodes: {
+                parentIndex: [-1, 0],
+                nodeName: [i("body"), i("button")],
+                backendNodeId: [100, 200],
+                attributes: [[], []],
+              },
+              layout: {
+                nodeIndex: [0, 1],
+                styles: [
+                  [i("static"), i("auto"), i("auto")],
+                  [i("static"), i("auto"), i("auto")],
+                ],
+                bounds: [
+                  [0, 0, 1000, 800],
+                  [20, 20, 120, 40],
+                ],
+                paintOrders: [0, 1],
+              },
+            },
+          ],
+        };
+      }
+      if (method === "Input.dispatchMouseEvent") return {};
+      if (method === "Runtime.evaluate") {
+        const expression = (params as { expression?: string } | undefined)?.expression ?? "";
+        // Report the button as a `:hover` rule target so a real hover fires.
+        if (expression.includes("document.styleSheets")) {
+          return { result: { value: [{ x: 80, y: 40 }] } };
+        }
+        return { result: { value: [] } };
+      }
+      throw new Error(`unexpected CDP method ${method}`);
+    });
+
+    const res = await handleObserve(
+      sm,
+      { session_id: "aa11", probe_hover: true },
+      {
+        cdp: {
+          send: send as unknown as <T = unknown>(
+            tabId: number,
+            method: string,
+            params?: object,
+          ) => Promise<T>,
+          trackSessionTab: vi.fn(),
+        },
+        tabsApi: {
+          get: vi.fn(
+            async (tabId: number) =>
+              ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
+          ),
+          query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+        },
+      },
+    );
+
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    const firstHover = methodOrder.indexOf("Input.dispatchMouseEvent");
+    expect(firstHover).toBeGreaterThan(-1);
+    expect(methodOrder.lastIndexOf("DOMSnapshot.captureSnapshot")).toBeLessThan(firstHover);
+    expect(methodOrder.lastIndexOf("Accessibility.getFullAXTree")).toBeLessThan(firstHover);
+  });
+
+  it("runs conditional surface probing only when observe opts in", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     await sm.start("aa11");
     const root: CdpAxNode = {
@@ -2741,30 +2968,46 @@ describe("handleSnapshot", () => {
       if (method === "Runtime.evaluate") return { result: { value: [] } };
       throw new Error(`unexpected CDP method ${method}`);
     });
-    const res = await handleObserve(
+    const deps = {
+      cdp: {
+        send: send as unknown as <T = unknown>(
+          tabId: number,
+          method: string,
+          params?: object,
+        ) => Promise<T>,
+        trackSessionTab: vi.fn(),
+      },
+      tabsApi: {
+        get: vi.fn(
+          async (tabId: number) => ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
+        ),
+        query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+      },
+    };
+
+    const withoutProbe = await handleObserve(
       sm,
       { session_id: "aa11", debug_surfaces: true },
-      {
-        cdp: {
-          send: send as unknown as <T = unknown>(
-            tabId: number,
-            method: string,
-            params?: object,
-          ) => Promise<T>,
-          trackSessionTab: vi.fn(),
-        },
-        tabsApi: {
-          get: vi.fn(
-            async (tabId: number) =>
-              ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
-          ),
-          query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
-        },
-      },
+      deps,
+    );
+    if ("code" in withoutProbe) {
+      throw new Error(`unexpected error: ${JSON.stringify(withoutProbe)}`);
+    }
+    expect(withoutProbe.hover_probe).toBeUndefined();
+    expect(send).not.toHaveBeenCalledWith(
+      4,
+      "Runtime.evaluate",
+      expect.objectContaining({ returnByValue: true }),
     );
 
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(res.debug).toEqual({ surface_probes: [] });
+    const withProbe = await handleObserve(
+      sm,
+      { session_id: "aa11", debug_surfaces: true, probe_hover: true },
+      deps,
+    );
+    if ("code" in withProbe) throw new Error(`unexpected error: ${JSON.stringify(withProbe)}`);
+    expect(withProbe.debug).toEqual({ surface_probes: [] });
+    expect(withProbe.hover_probe).toEqual({ performed: true, revealed_content: false });
     expect(send).toHaveBeenCalledWith(
       4,
       "Runtime.evaluate",

apps/extension/src/tools/__tests__/session.test.ts

@@ -252,23 +252,12 @@ describe("handleSessionStop with auto-return", () => {
     expect(aw.remove).not.toHaveBeenCalled();
   });
 
-  it("clears refs and Surface captures before window teardown", async () => {
+  it("clears the RefStore before window teardown", async () => {
     const aw = fakeAgentWindow([100]);
     const sm = new SessionManager({ agentWindow: aw });
     const ctx = await sm.start("aa11");
     // Insert a fake ref so we can verify clear() ran.
     ctx.refStore.set("e1", 123, { tabId: 7 });
-    ctx.surfaceCaptures.create({
-      sessionId: "aa11",
-      tabId: 7,
-      navigationIdentity: "navigation",
-      surface: { ref: "e1", backendNodeId: 123, observationGeneration: 0 },
-      topViewportRect: { x: 0, y: 0, w: 100, h: 50 },
-      imageWidth: 100,
-      imageHeight: 50,
-      viewportSignature: "viewport",
-      frameProjectionSignature: "frame",
-    });
     const state: FakeState = {
       tabs: new Map(),
       windowsClosed: new Set(),
@@ -277,6 +266,5 @@ describe("handleSessionStop with auto-return", () => {
     const { tabs, windows } = makeApis(state);
     await handleSessionStop(sm, { session_id: "aa11" }, { tabManagement: { tabs, windows } });
     expect(ctx.refStore.isEmpty()).toBe(true);
-    expect(ctx.surfaceCaptures.size()).toBe(0);
   });
 });

apps/extension/src/tools/__tests__/snapshot-ref.test.ts

@@ -26,14 +26,12 @@ describe("lookupSnapshotRef", () => {
       refKey: "e3",
       kind: "dom",
       capabilities: ["interact", "screenshot"],
-      generation: 0,
     });
     expect(lookupSnapshotRef(ctx, "e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
       kind: "dom",
       capabilities: ["interact", "screenshot"],
-      generation: 0,
     });
   });
 
@@ -70,7 +68,6 @@ describe("resolveSnapshotRef", () => {
       cdpSessionId: "child-session",
       kind: "dom" as const,
       capabilities: ["interact", "screenshot"] as const,
-      generation: 0,
     };
     expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
     expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
@@ -118,7 +115,6 @@ describe("resolveSnapshotRef", () => {
       refKey: "e3",
       kind: "dom",
       capabilities: ["interact", "screenshot"],
-      generation: 0,
     });
   });
 

apps/extension/src/tools/__tests__/surface-coordinate.test.ts

@@ -1,52 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  mapImagePointToViewport,
-  pointInRegion,
-  sameRect,
-  surfaceVisibleRect,
-} from "../surface-coordinate";
-
-describe("surface coordinate mapping", () => {
-  it("maps capture image pixels through the actual screenshot dimensions", () => {
-    expect(mapImagePointToViewport({ x: 100, y: 50, w: 400, h: 200 }, 800, 400, 200, 100)).toEqual({
-      x: 200,
-      y: 100,
-    });
-  });
-
-  it("rejects invalid image coordinates and dimensions", () => {
-    const rect = { x: 0, y: 0, w: 100, h: 50 };
-    expect(mapImagePointToViewport(rect, 100, 50, -1, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, 100, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, 0, 50)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, Number.NaN, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, Number.POSITIVE_INFINITY, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 0, 50, 0, 0)).toBeNull();
-  });
-
-  it("intersects live and observed visible regions and compares them strictly", () => {
-    const clipped = surfaceVisibleRect(
-      { x: 0, y: 0, width: 200, height: 100 },
-      { x: 25, y: 30, w: 50, h: 40 },
-    );
-    expect(clipped).toEqual({ x: 25, y: 30, w: 50, h: 40 });
-    expect(sameRect(clipped as NonNullable<typeof clipped>, { x: 25, y: 30, w: 50, h: 40 })).toBe(
-      true,
-    );
-    expect(sameRect(clipped as NonNullable<typeof clipped>, { x: 26, y: 30, w: 50, h: 40 })).toBe(
-      false,
-    );
-  });
-
-  it("checks the projected visible region rather than only its bounding box", () => {
-    const triangle = [
-      [
-        { x: 0, y: 0 },
-        { x: 100, y: 0 },
-        { x: 0, y: 100 },
-      ],
-    ];
-    expect(pointInRegion({ x: 20, y: 20 }, triangle)).toBe(true);
-    expect(pointInRegion({ x: 90, y: 90 }, triangle)).toBe(false);
-  });
-});

apps/extension/src/tools/__tests__/surface-target.test.ts

@@ -1,306 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { SessionManager } from "@/session-manager/manager";
-import type { CdpRunner } from "../shared";
-import {
-  captureSurfaceEnvironment,
-  resolveSurfacePointerTarget,
-  SURFACE_POINTER_MOVE_SETTLE_MS,
-} from "../surface-target";
-
-function fakeAgentWindow() {
-  return {
-    create: vi.fn(async () => 100),
-    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
-  };
-}
-
-function fakeBrowser() {
-  let loaderId = "loader-1";
-  let pageY = 0;
-  let quad = [10, 20, 110, 20, 110, 60, 10, 60];
-  const sent: Array<{ method: string; params?: object }> = [];
-  const cdp: CdpRunner = {
-    send: vi.fn(async (_tabId: number, method: string, params?: object) => {
-      sent.push({ method, params });
-      if (method === "Page.getFrameTree") {
-        return {
-          frameTree: { frame: { id: "main", loaderId, url: "https://fixture.test/" } },
-        } as never;
-      }
-      if (method === "Page.getLayoutMetrics") {
-        return {
-          cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY },
-          cssVisualViewport: {
-            clientWidth: 800,
-            clientHeight: 600,
-            pageX: 0,
-            pageY,
-            scale: 1,
-          },
-        } as never;
-      }
-      if (method === "DOM.getContentQuads") return { quads: [quad] } as never;
-      throw new Error(`unexpected CDP call ${method}`);
-    }) as CdpRunner["send"],
-    trackSessionTab: vi.fn(),
-  };
-  return {
-    cdp,
-    sent,
-    setLoaderId: (value: string) => {
-      loaderId = value;
-    },
-    setPageY: (value: number) => {
-      pageY = value;
-    },
-    setQuad: (value: number[]) => {
-      quad = value;
-    },
-  };
-}
-
-async function setupCapture() {
-  const manager = new SessionManager({ agentWindow: fakeAgentWindow() });
-  const context = await manager.start("aa11");
-  context.refStore.set("e3", 99, {
-    tabId: 4,
-    kind: "surface",
-    visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-  });
-  const browser = fakeBrowser();
-  const environment = await captureSurfaceEnvironment(browser.cdp, 4, undefined);
-  if ("code" in environment) throw new Error(environment.message);
-  const entry = context.refStore.resolveEntry("e3");
-  if (!entry) throw new Error("missing ref");
-  const capture = context.surfaceCaptures.create({
-    sessionId: "aa11",
-    tabId: 4,
-    navigationIdentity: environment.navigationIdentity,
-    surface: {
-      ref: "e3",
-      backendNodeId: 99,
-      observationGeneration: entry.generation,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 40 },
-    imageWidth: 200,
-    imageHeight: 80,
-    viewportSignature: environment.viewportSignature,
-    frameProjectionSignature: environment.frameProjectionSignature,
-  });
-  return { manager, context, browser, capture };
-}
-
-function pointParams(captureId: string) {
-  return {
-    ref: "@e3",
-    captureId,
-    imageX: 50,
-    imageY: 20,
-  };
-}
-
-describe("Surface screenshot-bound pointer target", () => {
-  it("maps one fresh capture coordinate without executing an action", async () => {
-    const { context, browser, capture } = await setupCapture();
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      usedRef: "e3",
-      point: { x: 35, y: 30 },
-      moveSettleMs: SURFACE_POINTER_MOVE_SETTLE_MS,
-      capture: { id: capture.id, imageX: 50, imageY: 20 },
-    });
-    expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-
-    const repeated = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-    expect(repeated).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "surface_capture_consumed" },
-    });
-  });
-
-  it("rejects a new observation generation before sending input", async () => {
-    const { context, browser, capture } = await setupCapture();
-    context.refStore.replace([
-      [
-        "e3",
-        {
-          backendNodeId: 99,
-          tabId: 4,
-          kind: "surface" as const,
-          visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-        },
-      ],
-    ]);
-
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-    expect(result).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "surface_capture_stale" },
-    });
-    expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-  });
-
-  it("rejects navigation, scroll, and visible geometry changes", async () => {
-    for (const mutate of [
-      (browser: ReturnType<typeof fakeBrowser>) => browser.setLoaderId("loader-2"),
-      (browser: ReturnType<typeof fakeBrowser>) => browser.setPageY(20),
-      (browser: ReturnType<typeof fakeBrowser>) =>
-        browser.setQuad([11, 20, 111, 20, 111, 60, 11, 60]),
-    ]) {
-      const { context, browser, capture } = await setupCapture();
-      mutate(browser);
-      const result = await resolveSurfacePointerTarget(
-        context,
-        { tabId: 4 },
-        pointParams(capture.id),
-        { cdp: browser.cdp },
-      );
-      expect(result).toMatchObject({
-        code: "permission_denied",
-        data: { reason: "surface_capture_stale" },
-      });
-      expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-    }
-  });
-
-  it("consumes the capture when coordinate validation fails", async () => {
-    const invalid = await setupCapture();
-    const outside = await resolveSurfacePointerTarget(
-      invalid.context,
-      { tabId: 4 },
-      { ...pointParams(invalid.capture.id), imageX: 200 },
-      { cdp: invalid.browser.cdp },
-    );
-    expect(outside).toMatchObject({
-      code: "invalid_params",
-      data: { reason: "surface_coordinate_invalid" },
-    });
-    expect(
-      await resolveSurfacePointerTarget(
-        invalid.context,
-        { tabId: 4 },
-        pointParams(invalid.capture.id),
-        { cdp: invalid.browser.cdp },
-      ),
-    ).toMatchObject({ data: { reason: "surface_capture_consumed" } });
-  });
-
-  it("maps image coordinates through an OOPIF frame projection", async () => {
-    const manager = new SessionManager({ agentWindow: fakeAgentWindow() });
-    const context = await manager.start("aa11");
-    context.refStore.set("e3", 99, {
-      tabId: 4,
-      frameId: "child",
-      cdpSessionId: "child-session",
-      kind: "surface",
-      visibleRect: { x: 120, y: 110, w: 100, h: 40 },
-    });
-    const graph = {
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child",
-          parentFrameId: "main",
-          ownerBackendNodeId: 77,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    };
-    const sent: Array<{ method: string; params?: object }> = [];
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId: number, method: string, params?: object) => {
-        sent.push({ method, params });
-        if (method === "Page.getFrameTree") {
-          return {
-            frameTree: {
-              frame: { id: "main", loaderId: "loader-1", url: "https://fixture.test/" },
-            },
-          } as never;
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return {
-            cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY: 0 },
-            cssVisualViewport: {
-              clientWidth: 800,
-              clientHeight: 600,
-              pageX: 0,
-              pageY: 0,
-              scale: 1,
-            },
-          } as never;
-        }
-        if (method === "DOM.getBoxModel") {
-          return { model: { content: [100, 100, 300, 100, 300, 200, 100, 200] } } as never;
-        }
-        if (method === "Input.dispatchMouseEvent") return {} as never;
-        throw new Error(`unexpected root CDP call ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "DOM.getContentQuads") {
-          return { quads: [[20, 10, 120, 10, 120, 50, 20, 50]] } as never;
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } } as never;
-        }
-        throw new Error(`unexpected child CDP call ${method}`);
-      }) as CdpRunner["sendToTarget"],
-      getFrameGraph: vi.fn(async () => graph),
-      trackSessionTab: vi.fn(),
-    };
-    const environment = await captureSurfaceEnvironment(cdp, 4, "child");
-    if ("code" in environment) throw new Error(environment.message);
-    const entry = context.refStore.resolveEntry("e3");
-    if (!entry) throw new Error("missing ref");
-    const capture = context.surfaceCaptures.create({
-      sessionId: "aa11",
-      tabId: 4,
-      navigationIdentity: environment.navigationIdentity,
-      surface: {
-        ref: "e3",
-        frameId: "child",
-        backendNodeId: 99,
-        observationGeneration: entry.generation,
-      },
-      topViewportRect: { x: 120, y: 110, w: 100, h: 40 },
-      imageWidth: 200,
-      imageHeight: 80,
-      viewportSignature: environment.viewportSignature,
-      frameProjectionSignature: environment.frameProjectionSignature,
-    });
-
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      {
-        ref: "@e3",
-        captureId: capture.id,
-        imageX: 100,
-        imageY: 40,
-      },
-      { cdp },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({ point: { x: 170, y: 130 } });
-    expect(sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-  });
-});

apps/extension/src/tools/__tests__/text-input.test.ts

@@ -1,128 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { CdpRunner } from "../shared";
-import { dispatchTextInput } from "../text-input";
-
-function makeCdp(onSend?: (method: string, params?: object) => void) {
-  const sent: Array<{ method: string; params?: object }> = [];
-  const send = vi.fn(async <T>(_tabId: number, method: string, params?: object): Promise<T> => {
-    sent.push({ method, params });
-    onSend?.(method, params);
-    return {} as T;
-  });
-  return { cdp: { send } as CdpRunner, sent };
-}
-
-describe("dispatchTextInput", () => {
-  it("types ASCII through complete keydown, char, and keyup sequences", async () => {
-    const fake = makeCdp();
-
-    const result = await dispatchTextInput(fake.cdp, 4, "Ab");
-
-    expect(result).toBeNull();
-    expect(
-      fake.sent.map((call) => `${call.method}:${(call.params as { type?: string }).type}`),
-    ).toEqual([
-      "Input.dispatchKeyEvent:rawKeyDown",
-      "Input.dispatchKeyEvent:char",
-      "Input.dispatchKeyEvent:keyUp",
-      "Input.dispatchKeyEvent:rawKeyDown",
-      "Input.dispatchKeyEvent:char",
-      "Input.dispatchKeyEvent:keyUp",
-    ]);
-    expect(fake.sent[0].params).toMatchObject({ key: "A", code: "KeyA", modifiers: 8 });
-    expect(fake.sent[1].params).toMatchObject({ text: "A" });
-  });
-
-  it("types non-ASCII through the committed IME insertion path", async () => {
-    const fake = makeCdp();
-
-    const result = await dispatchTextInput(fake.cdp, 4, "测试");
-
-    expect(result).toBeNull();
-    expect(fake.sent).toEqual([
-      {
-        method: "Input.dispatchKeyEvent",
-        params: {
-          type: "rawKeyDown",
-          key: "Process",
-          code: "",
-          windowsVirtualKeyCode: 229,
-          nativeVirtualKeyCode: 229,
-          modifiers: 0,
-        },
-      },
-      { method: "Input.insertText", params: { text: "测试" } },
-      {
-        method: "Input.dispatchKeyEvent",
-        params: {
-          type: "keyUp",
-          key: "Process",
-          code: "",
-          windowsVirtualKeyCode: 229,
-          nativeVirtualKeyCode: 229,
-          modifiers: 0,
-        },
-      },
-    ]);
-  });
-
-  it("preserves text order across keyboard and IME segments", async () => {
-    const fake = makeCdp();
-
-    const result = await dispatchTextInput(fake.cdp, 4, "A测试1");
-
-    expect(result).toBeNull();
-    const meaningful = fake.sent.flatMap((call) => {
-      if (call.method === "Input.insertText") {
-        return [`ime:${(call.params as { text: string }).text}`];
-      }
-      if (
-        call.method === "Input.dispatchKeyEvent" &&
-        (call.params as { type?: string }).type === "char"
-      ) {
-        return [`key:${(call.params as { text: string }).text}`];
-      }
-      return [];
-    });
-    expect(meaningful).toEqual(["key:A", "ime:测试", "key:1"]);
-  });
-
-  it("reports cancellation observed after an accepted IME insertion", async () => {
-    const abort = new AbortController();
-    const fake = makeCdp((method) => {
-      if (method === "Input.insertText") abort.abort();
-    });
-
-    const result = await dispatchTextInput(fake.cdp, 4, "测试", abort.signal);
-
-    expect(result).toMatchObject({ code: "cancelled" });
-    expect(fake.sent.map((call) => call.method)).toEqual([
-      "Input.dispatchKeyEvent",
-      "Input.insertText",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.at(-1)?.params).toMatchObject({ type: "keyUp", key: "Process" });
-  });
-
-  it("releases the IME process key without committing when cancellation follows keydown", async () => {
-    const abort = new AbortController();
-    const fake = makeCdp((method, params) => {
-      if (
-        method === "Input.dispatchKeyEvent" &&
-        (params as { type?: string }).type === "rawKeyDown"
-      ) {
-        abort.abort();
-      }
-    });
-
-    const result = await dispatchTextInput(fake.cdp, 4, "测试", abort.signal);
-
-    expect(result).toMatchObject({ code: "cancelled" });
-    expect(fake.sent.map((call) => call.method)).toEqual([
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent[0].params).toMatchObject({ type: "rawKeyDown", key: "Process" });
-    expect(fake.sent[1].params).toMatchObject({ type: "keyUp", key: "Process" });
-  });
-});

apps/extension/src/tools/borrow-confirmation.ts

@@ -24,7 +24,7 @@ export interface BorrowResponseMessage {
   allowed: boolean;
 }
 
-export const CONFIRMATION_TIMEOUT_MS = 5000;
+export const CONFIRMATION_TIMEOUT_MS = 60_000;
 const EXIT_ANIMATION_MS = 150;
 /** Matches BorrowConfirmationOverlay progress ring/bar transition (duration-1000). */
 export const PROGRESS_TRANSITION_MS = 1000;
@@ -480,6 +480,13 @@ export async function requestBorrowConfirmation(
       settle(false);
     }, BACKGROUND_TIMEOUT_MS);
 
+    // Bring the user window to the front so the overlay is visible even
+    // when the Agent Window has stolen focus. This is fire-and-forget: if
+    // it fails the overlay / OS notification still give the user a path.
+    void windowsApi.update(notificationAnchor.windowId, { focused: true }).catch((err) => {
+      console.debug("[bsk borrow] proactive focus of user window failed", err);
+    });
+
     // Surface the OS notification *before* messaging any candidate so the
     // user has a parallel signal even if every content script is missing.
     // The Allow / Deny buttons let the user authorize explicitly when the

apps/extension/src/tools/dispatcher.ts

@@ -4,6 +4,7 @@ import type { Transport } from "@/transport/transport";
 import type {
   ClickParams,
   ConsoleParams,
+  DownloadParams,
   EmulateParams,
   EvaluateParams,
   FillParams,
@@ -28,22 +29,16 @@ import type {
   ScreenshotParams,
   SelectParams,
   SnapshotParams,
-  TypeParams,
+  UploadParams,
   WaitForNavigationParams,
 } from "@/transport/types";
 import { isRequestFrame } from "@/transport/types";
 import { handleConsole } from "./console";
+import { handleDownload } from "./download";
 import { type EmulateCdpRunner, handleEmulate } from "./emulate";
 import { handleEvaluate } from "./evaluate";
 import { handleRequestHelp } from "./human-loop";
-import {
-  handleClick,
-  handleFill,
-  handleHover,
-  handlePress,
-  handleSelect,
-  handleType,
-} from "./interaction";
+import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "./interaction";
 import {
   handleNavigate,
   handleNavigateBack,
@@ -87,6 +82,7 @@ import {
   type TabReturnParams,
   type TabSelectParams,
 } from "./tabs";
+import { handleUpload } from "./upload";
 import { handleWaitForNavigation } from "./waits";
 import { handleWindowResize, type WindowResizeParams } from "./window";
 
@@ -391,7 +387,11 @@ export class ToolDispatcher {
                 ? {
                     cdp: this.cdp,
                     tabsApi: chromeTabsCaptureApi,
-                    conditionalSurfaceProbe: !this.hasHoverLatchForScope(hoverScope),
+                    // Active hover probing is opt-in. A held hover latch still
+                    // suppresses it, because probing would move the cursor off
+                    // the element the caller is deliberately holding.
+                    conditionalSurfaceProbe:
+                      params.probe_hover === true && !this.hasHoverLatchForScope(hoverScope),
                     hoverProbeBypassOverlay: bypassOverlay,
                   }
                 : undefined,
@@ -499,17 +499,6 @@ export class ToolDispatcher {
             ),
           signal,
         );
-      case "tool.type":
-        return this.withHoverReleaseForRequest(
-          req.params as TypeParams,
-          () =>
-            handleType(
-              this.sessions,
-              req.params as TypeParams,
-              this.cdp ? { cdp: this.cdp, tabsApi: chromeTabsApi, signal } : undefined,
-            ),
-          signal,
-        );
       case "tool.press":
         return this.withHoverReleaseForRequest(
           req.params as PressParams,
@@ -532,6 +521,40 @@ export class ToolDispatcher {
             ),
           signal,
         );
+      case "tool.upload":
+        return this.withHoverReleaseForRequest(
+          req.params as UploadParams,
+          () =>
+            this.cdp
+              ? handleUpload(this.sessions, req.params as UploadParams, {
+                  cdp: this.cdp,
+                  tabsApi: chromeTabsApi,
+                  signal,
+                  bypassOverlay,
+                })
+              : Promise.resolve({
+                  code: "unsupported",
+                  message: "upload requires CDP",
+                } satisfies RpcError),
+          signal,
+        );
+      case "tool.download":
+        return this.withHoverReleaseForRequest(
+          req.params as DownloadParams,
+          () =>
+            this.cdp
+              ? handleDownload(this.sessions, req.params as DownloadParams, {
+                  cdp: this.cdp,
+                  tabsApi: chromeTabsApi,
+                  signal,
+                  bypassOverlay,
+                })
+              : Promise.resolve({
+                  code: "unsupported",
+                  message: "download requires CDP",
+                } satisfies RpcError),
+          signal,
+        );
       case "tool.evaluate":
         return handleEvaluate(
           this.sessions,
@@ -736,9 +759,10 @@ function sessionIdForBrowserControlMethod(req: RequestFrame): string | null {
     case "tool.click":
     case "tool.hover":
     case "tool.fill":
-    case "tool.type":
     case "tool.press":
     case "tool.select":
+    case "tool.upload":
+    case "tool.download":
     case "tool.evaluate":
     case "tool.observe":
     case "tool.request_help":

apps/extension/src/tools/download-capture.ts

@@ -0,0 +1,375 @@
+// Order-independent coordinator for one browser download. CDP supplies the
+// exact target/frame intent while chrome.downloads supplies the download id
+// and filename routing hook; neither event is assumed to arrive first.
+
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { ClickResult, RpcError, TransferEffectState } from "@/transport/types";
+import { transferError } from "./errors";
+import { type CdpRunner, isRpcError } from "./shared";
+
+const CORRELATION_GRACE_MS = 750;
+const UNIQUE_SETTLE_MS = 50;
+const CLEANUP_RECONCILE_MS = 1_000;
+const CLEANUP_POLL_MS = 25;
+const SIZE_POLL_MS = 250;
+
+type DeterminingFilenameListener = (
+  item: chrome.downloads.DownloadItem,
+  suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+) => void | true;
+
+interface ListenerEvent<T> {
+  addListener(listener: T): void;
+  removeListener(listener: T): void;
+}
+
+export interface DownloadsApi {
+  onCreated: ListenerEvent<(item: chrome.downloads.DownloadItem) => void>;
+  onChanged: ListenerEvent<(delta: chrome.downloads.DownloadDelta) => void>;
+  onDeterminingFilename: ListenerEvent<DeterminingFilenameListener>;
+  search(query: chrome.downloads.DownloadQuery): Promise<chrome.downloads.DownloadItem[]>;
+  cancel(downloadId: number): Promise<void>;
+  removeFile(downloadId: number): Promise<void>;
+}
+
+export const chromeDownloadsApi: DownloadsApi = {
+  get onCreated() {
+    return chrome.downloads.onCreated;
+  },
+  get onChanged() {
+    return chrome.downloads.onChanged;
+  },
+  get onDeterminingFilename() {
+    return chrome.downloads.onDeterminingFilename;
+  },
+  search: (query) => chrome.downloads.search(query),
+  cancel: (id) => chrome.downloads.cancel(id),
+  removeFile: (id) => chrome.downloads.removeFile(id),
+};
+
+export interface DownloadCaptureOptions {
+  cdp: CdpRunner;
+  target: CdpTarget;
+  expectedFrameId?: string;
+  downloads: DownloadsApi;
+  browserRelativeDir: string;
+  maxByteSize?: number;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  trigger(): Promise<ClickResult | RpcError>;
+}
+
+export interface DownloadCaptureResult {
+  click: ClickResult;
+  item: chrome.downloads.DownloadItem;
+}
+
+interface DownloadIntent {
+  url: string;
+  suggestedFilename: string;
+  frameId?: string;
+}
+
+interface DownloadCandidate {
+  item: chrome.downloads.DownloadItem;
+  suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void;
+  suggested: boolean;
+  graceTimer: ReturnType<typeof setTimeout>;
+}
+
+function safeBasename(filename: string): string {
+  const basename = filename.split(/[\\/]/).pop()?.trim();
+  return basename && basename !== "." && basename !== ".." ? basename : "download";
+}
+
+function sameTarget(source: { tabId?: number; sessionId?: string }, target: CdpTarget): boolean {
+  return source.tabId === target.tabId && source.sessionId === target.sessionId;
+}
+
+function matchesIntent(item: chrome.downloads.DownloadItem, intent: DownloadIntent): boolean {
+  const urlMatches = item.url === intent.url || item.finalUrl === intent.url;
+  return urlMatches && safeBasename(item.filename) === safeBasename(intent.suggestedFilename);
+}
+
+function knownSize(item: chrome.downloads.DownloadItem): number | undefined {
+  if (item.fileSize >= 0) return item.fileSize;
+  if (item.totalBytes >= 0) return item.totalBytes;
+  return undefined;
+}
+
+function captureError(
+  message: string,
+  effectState: TransferEffectState,
+  phase: string,
+  cleanupFailed = false,
+): RpcError {
+  return transferError("cdp_failed", "download_capture_failed", message, {
+    effectState,
+    phase,
+    ...(cleanupFailed ? { cleanupState: "failed" } : {}),
+  });
+}
+
+async function cleanupClaimedDownload(downloads: DownloadsApi, downloadId: number): Promise<void> {
+  const lookup = async () => (await downloads.search({ id: downloadId }))[0];
+  let item = await lookup();
+  if (!item || item.state === "interrupted") return;
+  if (item.state === "complete") {
+    await downloads.removeFile(downloadId);
+    return;
+  }
+
+  let cancelError: unknown;
+  try {
+    await downloads.cancel(downloadId);
+  } catch (error) {
+    cancelError = error;
+  }
+
+  const deadline = Date.now() + CLEANUP_RECONCILE_MS;
+  while (true) {
+    item = await lookup();
+    if (!item || item.state === "interrupted") return;
+    if (item.state === "complete") {
+      await downloads.removeFile(downloadId);
+      return;
+    }
+    if (Date.now() >= deadline) {
+      if (cancelError instanceof Error) throw cancelError;
+      throw new Error("download remained in progress after cancellation");
+    }
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(CLEANUP_POLL_MS, Math.max(1, deadline - Date.now()))),
+    );
+  }
+}
+
+export async function captureBrowserDownload(
+  options: DownloadCaptureOptions,
+): Promise<DownloadCaptureResult | RpcError> {
+  let click: ClickResult | undefined;
+  let intent: DownloadIntent | undefined;
+  let capturedId: number | undefined;
+  let settled = false;
+  let succeeded = false;
+  let failureResult: RpcError | undefined;
+  let uniquenessTimer: ReturnType<typeof setTimeout> | undefined;
+  let operationTimer: ReturnType<typeof setTimeout> | undefined;
+  let sizePoll: ReturnType<typeof setInterval> | undefined;
+  const candidates = new Map<number, DownloadCandidate>();
+  const createdItems = new Map<number, chrome.downloads.DownloadItem>();
+
+  let resolveCompletion!: (item: chrome.downloads.DownloadItem) => void;
+  let rejectCompletion!: (error: Error) => void;
+  const completion = new Promise<chrome.downloads.DownloadItem>((resolve, reject) => {
+    resolveCompletion = resolve;
+    rejectCompletion = reject;
+  });
+  const fail = (error: Error) => {
+    if (settled) return;
+    settled = true;
+    rejectCompletion(error);
+  };
+  const complete = (item: chrome.downloads.DownloadItem) => {
+    if (settled) return;
+    const size = knownSize(item);
+    if (size !== undefined && options.maxByteSize !== undefined && size > options.maxByteSize) {
+      fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
+      return;
+    }
+    settled = true;
+    resolveCompletion(item);
+  };
+  const suggestDefault = (candidate: DownloadCandidate) => {
+    if (candidate.suggested) return;
+    candidate.suggested = true;
+    candidate.suggest();
+  };
+  const matchingCandidates = (): DownloadCandidate[] => {
+    const currentIntent = intent;
+    return currentIntent
+      ? [...candidates.values()].filter(
+          (candidate) => !candidate.suggested && matchesIntent(candidate.item, currentIntent),
+        )
+      : [];
+  };
+
+  const claimUnique = () => {
+    uniquenessTimer = undefined;
+    if (settled || capturedId !== undefined || !intent) return;
+    const matches = matchingCandidates();
+    if (matches.length !== 1) {
+      if (matches.length > 1) {
+        for (const candidate of matches) suggestDefault(candidate);
+        fail(new Error("download attribution is ambiguous"));
+      }
+      return;
+    }
+    const candidate = matches[0];
+    candidate.suggested = true;
+    clearTimeout(candidate.graceTimer);
+    capturedId = candidate.item.id;
+    candidate.suggest({
+      filename: `${options.browserRelativeDir}/${safeBasename(intent.suggestedFilename)}`,
+      conflictAction: "overwrite",
+    });
+    const size = knownSize(candidate.item);
+    if (size !== undefined && options.maxByteSize !== undefined && size > options.maxByteSize) {
+      fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
+      return;
+    }
+    const created = createdItems.get(candidate.item.id);
+    if (created?.state === "interrupted") {
+      fail(new Error(created.error ?? "download interrupted"));
+    } else if (created?.state === "complete") {
+      complete(created);
+    }
+  };
+  const reconcile = () => {
+    if (settled || capturedId !== undefined || !intent) return;
+    const matches = matchingCandidates();
+    if (matches.length > 1) {
+      for (const candidate of matches) suggestDefault(candidate);
+      fail(new Error("download attribution is ambiguous"));
+      return;
+    }
+    if (matches.length === 1 && !uniquenessTimer) {
+      uniquenessTimer = setTimeout(claimUnique, UNIQUE_SETTLE_MS);
+    }
+  };
+
+  const determiningListener: DeterminingFilenameListener = (item, suggest) => {
+    const candidate: DownloadCandidate = {
+      item,
+      suggest,
+      suggested: false,
+      graceTimer: setTimeout(() => {
+        suggestDefault(candidate);
+        candidates.delete(item.id);
+        if (intent && matchesIntent(item, intent) && capturedId === undefined) {
+          fail(new Error("download correlation grace elapsed before unique attribution"));
+        }
+      }, CORRELATION_GRACE_MS),
+    };
+    candidates.set(item.id, candidate);
+    reconcile();
+    return true;
+  };
+  const createdListener = (item: chrome.downloads.DownloadItem) => {
+    createdItems.set(item.id, item);
+    if (capturedId !== item.id) return;
+    if (item.state === "interrupted") {
+      fail(new Error(item.error ?? "download interrupted"));
+    } else if (item.state === "complete") {
+      complete(item);
+    }
+  };
+  const changedListener = async (delta: chrome.downloads.DownloadDelta) => {
+    if (capturedId === undefined || delta.id !== capturedId || settled) return;
+    if (delta.state?.current === "interrupted" || delta.error?.current) {
+      fail(new Error(delta.error?.current ?? "download interrupted"));
+      return;
+    }
+    if (delta.state?.current === "complete") {
+      try {
+        const [item] = await options.downloads.search({ id: delta.id });
+        if (item) complete(item);
+        else fail(new Error("completed download disappeared"));
+      } catch (err) {
+        fail(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  };
+  const onAbort = () => fail(new DOMException("aborted", "AbortError"));
+  const cdpSubscription = options.cdp.onEvent?.((source, method, raw) => {
+    if (method !== "Page.downloadWillBegin" || !sameTarget(source, options.target)) return;
+    const event = raw as { url?: unknown; suggestedFilename?: unknown; frameId?: unknown };
+    if (typeof event.url !== "string" || typeof event.suggestedFilename !== "string") return;
+    if (options.expectedFrameId && event.frameId !== options.expectedFrameId) {
+      fail(new Error("download originated from a different frame"));
+      return;
+    }
+    if (intent) {
+      fail(new Error("download trigger produced more than one browser download intent"));
+      return;
+    }
+    intent = {
+      url: event.url,
+      suggestedFilename: event.suggestedFilename,
+      ...(typeof event.frameId === "string" ? { frameId: event.frameId } : {}),
+    };
+    reconcile();
+  });
+  if (!cdpSubscription) {
+    return captureError("CDP download intent subscription unavailable", "none", "arm");
+  }
+
+  options.downloads.onDeterminingFilename.addListener(determiningListener);
+  options.downloads.onCreated.addListener(createdListener);
+  options.downloads.onChanged.addListener(changedListener);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  operationTimer = setTimeout(
+    () => fail(new Error("download did not complete before timeout")),
+    options.timeoutMs,
+  );
+  sizePoll = setInterval(() => {
+    if (capturedId === undefined || settled || options.maxByteSize === undefined) return;
+    void options.downloads
+      .search({ id: capturedId })
+      .then(([item]) => {
+        if (!item || settled) return;
+        if (item.bytesReceived > (options.maxByteSize as number)) {
+          fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
+        }
+      })
+      .catch((err) => fail(err instanceof Error ? err : new Error(String(err))));
+  }, SIZE_POLL_MS);
+
+  try {
+    const triggered = await options.trigger();
+    if (isRpcError(triggered)) {
+      void completion.catch(() => undefined);
+      const effect: TransferEffectState =
+        capturedId !== undefined ? "committed" : intent ? "unknown" : "none";
+      failureResult = {
+        ...triggered,
+        data: { ...triggered.data, effect_state: effect, phase: "trigger" },
+      };
+      return failureResult;
+    }
+    click = triggered;
+    const item = await completion;
+    succeeded = true;
+    return { click, item };
+  } catch (err) {
+    const effect: TransferEffectState =
+      capturedId !== undefined ? "committed" : click ? "unknown" : "none";
+    failureResult = captureError(
+      err instanceof Error ? err.message : String(err),
+      effect,
+      capturedId !== undefined ? "download" : "attribution",
+    );
+    return failureResult;
+  } finally {
+    settled = true;
+    if (operationTimer) clearTimeout(operationTimer);
+    if (uniquenessTimer) clearTimeout(uniquenessTimer);
+    if (sizePoll) clearInterval(sizePoll);
+    options.signal?.removeEventListener("abort", onAbort);
+    options.downloads.onDeterminingFilename.removeListener(determiningListener);
+    options.downloads.onCreated.removeListener(createdListener);
+    options.downloads.onChanged.removeListener(changedListener);
+    cdpSubscription.dispose();
+    for (const candidate of candidates.values()) {
+      clearTimeout(candidate.graceTimer);
+      if (candidate.item.id !== capturedId) suggestDefault(candidate);
+    }
+    if (!succeeded && capturedId !== undefined) {
+      try {
+        await cleanupClaimedDownload(options.downloads, capturedId);
+      } catch {
+        if (failureResult?.data) failureResult.data.cleanup_state = "failed";
+      }
+    }
+  }
+}

apps/extension/src/tools/download.ts

@@ -0,0 +1,64 @@
+// Download orchestration: validate session/tab ownership, then delegate one
+// browser-global chrome.downloads transaction to download-capture.ts.
+
+import type { SessionManager } from "@/session-manager/manager";
+import type { DownloadParams, DownloadResult, RpcError } from "@/transport/types";
+import { captureBrowserDownload, chromeDownloadsApi, type DownloadsApi } from "./download-capture";
+import { clickResolvedTarget, type InteractionDeps, resolveActionTarget } from "./interaction";
+import { enforceAgentWindow, isRpcError, lookupSession, resolveTargetTab } from "./shared";
+
+let downloadActive = false;
+
+export type { DownloadsApi } from "./download-capture";
+
+export interface DownloadDeps extends InteractionDeps {
+  downloads?: DownloadsApi;
+}
+
+export async function handleDownload(
+  manager: SessionManager,
+  params: DownloadParams,
+  deps: DownloadDeps,
+): Promise<DownloadResult | RpcError> {
+  if (downloadActive) return { code: "invalid_params", message: "another bsk download is active" };
+  downloadActive = true;
+  try {
+    const ctx = lookupSession(manager, params, "download");
+    if (isRpcError(ctx)) return ctx;
+    const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
+    if (isRpcError(target)) return target;
+    const denied = enforceAgentWindow(ctx, target, "download");
+    if (denied) return denied;
+    if (!params.browser_relative_dir) {
+      return { code: "invalid_params", message: "download requires a daemon capability directory" };
+    }
+    const address = await resolveActionTarget(deps.cdp, ctx, target, params, "download");
+    if (isRpcError(address)) return address;
+
+    const capture = await captureBrowserDownload({
+      cdp: deps.cdp,
+      target: address.cdpTarget,
+      downloads: deps.downloads ?? chromeDownloadsApi,
+      browserRelativeDir: params.browser_relative_dir,
+      maxByteSize: params.max_byte_size,
+      timeoutMs: params.timeout_ms ?? 120_000,
+      signal: deps.signal,
+      expectedFrameId: address.frameId,
+      trigger: () => clickResolvedTarget(ctx, address, {}, deps),
+    });
+    if (isRpcError(capture)) return capture;
+    const { click, item } = capture;
+    return {
+      tab_id: target.tabId,
+      used_ref: click.used_ref,
+      used_selector: click.used_selector,
+      suggested_filename: item.filename.split(/[\\/]/).pop() ?? "download",
+      byte_size: item.fileSize >= 0 ? item.fileSize : item.totalBytes,
+      mime: item.mime || undefined,
+      danger: item.danger,
+      browser_path: item.filename,
+    };
+  } finally {
+    downloadActive = false;
+  }
+}

apps/extension/src/tools/editable-input.ts

@@ -1,282 +0,0 @@
-// Browser-native editing transaction for input, textarea, and contenteditable
-// targets. The CDP target/session is selected by interaction.ts; this module
-// owns the shorter-lived editable identity inside that target.
-
-import type { RpcError } from "@/transport/types";
-import { rpcError } from "./errors";
-import type { CdpRunner } from "./shared";
-
-interface EditableState {
-  supported: boolean;
-  connected: boolean;
-  focused: boolean;
-  value: string;
-  kind: "input" | "textarea" | "contenteditable" | "unsupported";
-}
-
-export interface EditableFillResult {
-  value: string;
-  replacedNode: boolean;
-}
-
-function cancelled(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted ? { code: "cancelled", message: "fill aborted" } : null;
-}
-
-async function inspectEditable(
-  cdp: CdpRunner,
-  tabId: number,
-  objectId: string,
-): Promise<EditableState> {
-  const reply = await cdp.send<{
-    result?: { value?: EditableState };
-  }>(tabId, "Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-state */
-      const doc = this.ownerDocument;
-      const focused = !!doc && doc.activeElement === this;
-      if (this instanceof HTMLInputElement) {
-        return { supported: true, connected: this.isConnected, focused,
-          value: this.value, kind: 'input' };
-      }
-      if (this instanceof HTMLTextAreaElement) {
-        return { supported: true, connected: this.isConnected, focused,
-          value: this.value, kind: 'textarea' };
-      }
-      if (this.isContentEditable) {
-        return { supported: true, connected: this.isConnected, focused,
-          value: this.innerText ?? this.textContent ?? '', kind: 'contenteditable' };
-      }
-      return { supported: false, connected: this.isConnected === true, focused,
-        value: '', kind: 'unsupported' };
-    }`,
-    returnByValue: true,
-  });
-  const state = reply.result?.value;
-  if (!state || typeof state.value !== "string") {
-    throw new Error("editable state probe returned no value");
-  }
-  return state;
-}
-
-/**
- * Return the active editable from the anchor's own document. Using the
- * anchor's execution context also works for same-process nested frames, where
- * a target-level Runtime.evaluate would otherwise see the top document.
- */
-async function focusedEditableFromAnchor(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-): Promise<string | null> {
-  const reply = await cdp.send<{
-    result?: { objectId?: string; subtype?: string };
-  }>(tabId, "Runtime.callFunctionOn", {
-    objectId: anchorObjectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-live */
-      const active = this.ownerDocument?.activeElement;
-      if (!active) return null;
-      const editable = active instanceof HTMLInputElement ||
-        active instanceof HTMLTextAreaElement || active.isContentEditable;
-      return editable ? active : null;
-    }`,
-    returnByValue: false,
-  });
-  if (reply.result?.subtype === "null") return null;
-  return typeof reply.result?.objectId === "string" ? reply.result.objectId : null;
-}
-
-async function resolveLiveEditable(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-): Promise<{ objectId: string; state: EditableState; replaced: boolean } | RpcError> {
-  const anchor = await inspectEditable(cdp, tabId, anchorObjectId);
-  if (anchor.supported && anchor.connected && anchor.focused) {
-    return { objectId: anchorObjectId, state: anchor, replaced: false };
-  }
-
-  const focusedObjectId = await focusedEditableFromAnchor(cdp, tabId, anchorObjectId);
-  if (!focusedObjectId) {
-    return rpcError(
-      "cdp_failed",
-      "input_not_applied",
-      "the target editable lost focus or detached before input",
-      { phase: "resolve_live_editable" },
-    );
-  }
-  const focused = await inspectEditable(cdp, tabId, focusedObjectId);
-  if (!focused.supported || !focused.connected || !focused.focused) {
-    return rpcError(
-      "cdp_failed",
-      "input_not_applied",
-      "the replacement editable was not live and focused",
-      { phase: "resolve_live_editable" },
-    );
-  }
-  return { objectId: focusedObjectId, state: focused, replaced: true };
-}
-
-async function selectEditableContents(
-  cdp: CdpRunner,
-  tabId: number,
-  objectId: string,
-): Promise<void> {
-  const reply = await cdp.send<{
-    result?: { value?: { selected?: boolean } };
-  }>(tabId, "Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-selection */
-      if (!this.isConnected || this.ownerDocument?.activeElement !== this) {
-        return { selected: false };
-      }
-      if (this instanceof HTMLInputElement || this instanceof HTMLTextAreaElement) {
-        try {
-          this.setSelectionRange(0, this.value.length);
-        } catch {
-          if (typeof this.select !== 'function') return { selected: false };
-          this.select();
-        }
-        return { selected: true };
-      }
-      if (this.isContentEditable) {
-        const selection = this.ownerDocument.getSelection();
-        if (!selection) return { selected: false };
-        const range = this.ownerDocument.createRange();
-        range.selectNodeContents(this);
-        selection.removeAllRanges();
-        selection.addRange(range);
-        return { selected: true };
-      }
-      return { selected: false };
-    }`,
-    returnByValue: true,
-  });
-  if (reply.result?.value?.selected !== true) {
-    throw new Error("could not select the live editable contents");
-  }
-}
-
-async function waitForEditableSettlement(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-): Promise<void> {
-  await cdp.send(tabId, "Runtime.callFunctionOn", {
-    objectId: anchorObjectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-sync */
-      return new Promise((resolve) => {
-        let settled = false;
-        const finish = () => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(timer);
-          resolve();
-        };
-        const timer = setTimeout(finish, 100);
-        const view = this.ownerDocument?.defaultView;
-        if (!view || typeof view.requestAnimationFrame !== 'function') { finish(); return; }
-        view.requestAnimationFrame(() => view.requestAnimationFrame(finish));
-      });
-    }`,
-    awaitPromise: true,
-    returnByValue: true,
-  });
-}
-
-async function deleteSelection(cdp: CdpRunner, tabId: number): Promise<void> {
-  await cdp.send(tabId, "Input.dispatchKeyEvent", {
-    type: "rawKeyDown",
-    key: "Backspace",
-    code: "Backspace",
-    windowsVirtualKeyCode: 8,
-  });
-  await cdp.send(tabId, "Input.dispatchKeyEvent", {
-    type: "keyUp",
-    key: "Backspace",
-    code: "Backspace",
-    windowsVirtualKeyCode: 8,
-  });
-}
-
-/**
- * Replace or append text through Chromium's editing pipeline. No value setter
- * or synthetic DOM events are used: controlled components observe the same
- * beforeinput/input path as a real browser edit. The live editable is resolved
- * again after settlement so a framework may remount it without producing a
- * false failure or a stale-object success.
- */
-export async function fillEditable(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-  value: string,
-  clearBefore: boolean,
-  signal?: AbortSignal,
-): Promise<EditableFillResult | RpcError> {
-  try {
-    const abortedBefore = cancelled(signal);
-    if (abortedBefore) return abortedBefore;
-
-    const initial = await resolveLiveEditable(cdp, tabId, anchorObjectId);
-    if ("code" in initial) return initial;
-    let replacedNode = initial.replaced;
-
-    if (clearBefore) await selectEditableContents(cdp, tabId, initial.objectId);
-    const abortedAfterSelection = cancelled(signal);
-    if (abortedAfterSelection) return abortedAfterSelection;
-
-    if (value.length > 0) {
-      await cdp.send(tabId, "Input.insertText", { text: value });
-    } else if (clearBefore) {
-      await deleteSelection(cdp, tabId);
-    }
-
-    const abortedAfterInput = cancelled(signal);
-    if (abortedAfterInput) return abortedAfterInput;
-    await waitForEditableSettlement(cdp, tabId, initial.objectId);
-
-    const abortedAfterSettlement = cancelled(signal);
-    if (abortedAfterSettlement) return abortedAfterSettlement;
-
-    let finalObjectId = initial.objectId;
-    let finalState = await inspectEditable(cdp, tabId, finalObjectId);
-    if (!finalState.connected || !finalState.focused) {
-      const live = await resolveLiveEditable(cdp, tabId, initial.objectId);
-      if ("code" in live) return live;
-      finalObjectId = live.objectId;
-      finalState = live.state;
-      replacedNode ||= live.replaced || finalObjectId !== initial.objectId;
-    }
-
-    const applied = clearBefore
-      ? finalState.value === value
-      : value.length === 0 || finalState.value.includes(value);
-    if (!finalState.supported || !applied) {
-      return rpcError(
-        "cdp_failed",
-        "input_not_applied",
-        "the page did not retain the requested input value",
-        {
-          expected_value_length: value.length,
-          actual_value_length: finalState.value.length,
-          phase: "readback",
-          editable_replaced: replacedNode,
-        },
-      );
-    }
-
-    return { value: finalState.value, replacedNode };
-  } catch (err) {
-    return rpcError(
-      "cdp_failed",
-      "input_not_applied",
-      err instanceof Error ? err.message : String(err),
-      { phase: "edit_transaction" },
-    );
-  }
-}

apps/extension/src/tools/errors.ts

@@ -2,10 +2,23 @@
 // rendering. Extension handlers attach reasons here; human-facing copy
 // lives in bsk-cli `render_error.rs`.
 
-import type { ErrorCode, RpcError, RpcErrorData, RpcErrorReason } from "@/transport/types";
+import type {
+  ErrorCode,
+  RpcError,
+  RpcErrorData,
+  RpcErrorReason,
+  TransferCleanupState,
+  TransferEffectState,
+} from "@/transport/types";
 
 export type { RpcErrorData, RpcErrorReason };
 
+export interface TransferErrorOptions {
+  effectState: TransferEffectState;
+  phase: string;
+  cleanupState?: TransferCleanupState;
+}
+
 export function rpcError(
   code: ErrorCode,
   reason: RpcErrorReason,
@@ -15,3 +28,16 @@ export function rpcError(
   const data: RpcErrorData = { reason, ...extra };
   return { code, message, data };
 }
+
+export function transferError(
+  code: ErrorCode,
+  reason: RpcErrorReason,
+  message: string,
+  options: TransferErrorOptions,
+): RpcError {
+  return rpcError(code, reason, message, {
+    effect_state: options.effectState,
+    phase: options.phase,
+    ...(options.cleanupState ? { cleanup_state: options.cleanupState } : {}),
+  });
+}

apps/extension/src/tools/file-input-transaction.ts

@@ -0,0 +1,528 @@
+// One upload transaction with an explicit browser-side commit boundary.
+// Chrome interception prevents a native chooser from escaping automation;
+// chooser events and a frame-scoped DOM probe are independent input-location
+// signals, so event delivery is not required for standard file inputs.
+
+import type { ClickResult, RpcError, TransferEffectState } from "@/transport/types";
+import { transferError } from "./errors";
+import type { ResolvedActionTarget } from "./interaction";
+import { type CdpRunner, isRpcError, sendToCdpTarget } from "./shared";
+
+const CLEANUP_TIMEOUT_MS = 1_000;
+const DETACH_TIMEOUT_MS = 500;
+const ACTIVATION_GRACE_MS = 1_000;
+const PROBE_INTERVAL_MS = 20;
+
+type UploadPhase =
+  | "arm_interception"
+  | "arm_input_probe"
+  | "trigger"
+  | "resolve_input"
+  | "set_files"
+  | "cleanup";
+
+interface RuntimeReply {
+  result?: { value?: unknown; objectId?: string };
+  exceptionDetails?: { text?: string; exception?: { description?: string } };
+}
+
+interface ChooserEvent {
+  frameId?: string;
+  backendNodeId?: number;
+  mode?: "selectSingle" | "selectMultiple";
+}
+
+export interface FileInputTransactionOptions {
+  cdp: CdpRunner;
+  actionTarget: ResolvedActionTarget;
+  files: string[];
+  timeoutMs: number;
+  signal?: AbortSignal;
+  trigger(): Promise<ClickResult | RpcError>;
+}
+
+export interface FileInputTransactionResult {
+  click: ClickResult;
+  multiple: boolean;
+}
+
+class BoundedWaitError extends Error {
+  constructor(
+    readonly kind: "timeout" | "aborted",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function remainingMs(deadline: number): number {
+  return Math.max(0, deadline - Date.now());
+}
+
+async function waitBounded<T>(
+  operation: () => Promise<T>,
+  deadline: number,
+  signal: AbortSignal | undefined,
+  timeoutMessage: string,
+): Promise<T> {
+  const remaining = remainingMs(deadline);
+  if (signal?.aborted) throw new BoundedWaitError("aborted", "upload transaction aborted");
+  if (remaining === 0) throw new BoundedWaitError("timeout", timeoutMessage);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const boundary = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new BoundedWaitError("timeout", timeoutMessage)), remaining);
+    if (signal) {
+      onAbort = () => reject(new BoundedWaitError("aborted", "upload transaction aborted"));
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+  try {
+    const work = Promise.resolve().then(() => {
+      if (signal?.aborted) throw new BoundedWaitError("aborted", "upload transaction aborted");
+      if (remainingMs(deadline) === 0) throw new BoundedWaitError("timeout", timeoutMessage);
+      return operation();
+    });
+    return await Promise.race([work, boundary]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+
+function runtimeError(reply: RuntimeReply, fallback: string): Error | null {
+  if (!reply.exceptionDetails) return null;
+  return new Error(
+    reply.exceptionDetails.exception?.description ?? reply.exceptionDetails.text ?? fallback,
+  );
+}
+
+function transferFailure(
+  code: RpcError["code"],
+  reason: "file_input_probe_failed" | "file_input_not_activated" | "set_file_input_failed",
+  message: string,
+  effectState: TransferEffectState,
+  phase: UploadPhase,
+): RpcError {
+  return transferError(code, reason, message, { effectState, phase });
+}
+
+function enrichFailure(
+  error: RpcError,
+  effectState: TransferEffectState,
+  phase: UploadPhase,
+): RpcError {
+  return {
+    ...error,
+    data: { ...error.data, effect_state: effectState, phase },
+  };
+}
+
+function sameTarget(
+  source: { tabId?: number; sessionId?: string },
+  target: { tabId: number; sessionId?: string },
+): boolean {
+  return source.tabId === target.tabId && source.sessionId === target.sessionId;
+}
+
+async function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  await waitBounded(
+    () => new Promise((resolve) => setTimeout(resolve, ms)),
+    Date.now() + ms + 1,
+    signal,
+    "upload activation probe timed out",
+  );
+}
+
+function waitErrorCode(error: unknown): RpcError["code"] {
+  if (!(error instanceof BoundedWaitError)) return "cdp_failed";
+  return error.kind === "aborted" ? "cancelled" : "timeout";
+}
+
+async function callOnTrigger<T = RuntimeReply>(
+  options: FileInputTransactionOptions,
+  objectId: string,
+  functionDeclaration: string,
+  args: unknown[],
+  returnByValue: boolean,
+): Promise<T> {
+  return sendToCdpTarget<T>(options.cdp, options.actionTarget.cdpTarget, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration,
+    arguments: args.map((value) => ({ value })),
+    returnByValue,
+    awaitPromise: false,
+  });
+}
+
+export async function uploadThroughActivatedFileInput(
+  options: FileInputTransactionOptions,
+): Promise<FileInputTransactionResult | RpcError> {
+  const deadline = Date.now() + options.timeoutMs;
+  const target = options.actionTarget.cdpTarget;
+  const objectGroup = `bsk-upload-${crypto.randomUUID()}`;
+  const stateKey = `__bskUpload_${crypto.randomUUID().replaceAll("-", "")}`;
+  const chooserEvents: ChooserEvent[] = [];
+  let interceptionState: "not_started" | "possibly_active" | "active" = "not_started";
+  let probeState: "not_started" | "possibly_active" | "active" = "not_started";
+  let triggerObjectId: string | undefined;
+  let outcome: FileInputTransactionResult | RpcError = transferFailure(
+    "protocol_error",
+    "file_input_probe_failed",
+    "upload transaction ended without an outcome",
+    "none",
+    "cleanup",
+  );
+
+  const chooserSubscription = options.cdp.onEvent?.((source, method, raw) => {
+    if (method !== "Page.fileChooserOpened" || !sameTarget(source, target)) return;
+    const event = raw as ChooserEvent;
+    chooserEvents.push(event);
+  });
+
+  try {
+    try {
+      interceptionState = "possibly_active";
+      await waitBounded(
+        () =>
+          sendToCdpTarget(options.cdp, target, "Page.setInterceptFileChooserDialog", {
+            enabled: true,
+          }),
+        deadline,
+        options.signal,
+        "arming native file chooser interception timed out",
+      );
+      interceptionState = "active";
+    } catch (err) {
+      outcome = transferFailure(
+        waitErrorCode(err),
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "arm_interception",
+      );
+      return outcome;
+    }
+
+    try {
+      const resolved = await waitBounded(
+        () =>
+          sendToCdpTarget<{ object?: { objectId?: string } }>(
+            options.cdp,
+            target,
+            "DOM.resolveNode",
+            {
+              backendNodeId: options.actionTarget.backendNodeId,
+              objectGroup,
+            },
+          ),
+        deadline,
+        options.signal,
+        "resolving upload trigger timed out",
+      );
+      triggerObjectId = resolved.object?.objectId;
+      if (!triggerObjectId) throw new Error("DOM.resolveNode returned no trigger objectId");
+
+      probeState = "possibly_active";
+      const armed = await waitBounded(
+        () =>
+          callOnTrigger<RuntimeReply>(
+            options,
+            triggerObjectId as string,
+            `function(key) {
+            const doc = this.ownerDocument;
+            const owner = doc.defaultView;
+            if (!owner) return false;
+            const state = { inputs: [], listener: null };
+            Object.defineProperty(owner, key, { value: state, configurable: true });
+            state.listener = event => {
+              const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+              const candidate = path[0] || event.target;
+              if (candidate && candidate.nodeType === 1 &&
+                  candidate.localName === "input" && candidate.type === "file") {
+                if (!state.inputs.includes(candidate)) state.inputs.push(candidate);
+                event.preventDefault();
+              }
+            };
+            doc.addEventListener("click", state.listener, true);
+            return true;
+          }`,
+            [stateKey],
+            true,
+          ),
+        deadline,
+        options.signal,
+        "arming frame-scoped file input probe timed out",
+      );
+      const armError = runtimeError(armed, "failed to arm file input probe");
+      if (armError || armed.result?.value !== true) {
+        throw armError ?? new Error("file input probe did not arm");
+      }
+      probeState = "active";
+    } catch (err) {
+      outcome = transferFailure(
+        waitErrorCode(err),
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "arm_input_probe",
+      );
+      return outcome;
+    }
+
+    let click: ClickResult | RpcError;
+    try {
+      click = await waitBounded(
+        options.trigger,
+        deadline,
+        options.signal,
+        "upload trigger timed out",
+      );
+    } catch (err) {
+      outcome = transferFailure(
+        waitErrorCode(err),
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "trigger",
+      );
+      return outcome;
+    }
+    if (isRpcError(click)) {
+      outcome = enrichFailure(click, "none", "trigger");
+      return outcome;
+    }
+
+    try {
+      const activationDeadline = Math.min(deadline, Date.now() + ACTIVATION_GRACE_MS);
+      let summary: { count: number; multiple: boolean } = { count: 0, multiple: false };
+      while (Date.now() < activationDeadline) {
+        if (chooserEvents.length > 0) break;
+        const reply = await waitBounded(
+          () =>
+            callOnTrigger<RuntimeReply>(
+              options,
+              triggerObjectId as string,
+              `function(key) {
+            const state = this.ownerDocument.defaultView?.[key];
+            return state
+              ? { count: state.inputs.length, multiple: state.inputs[0]?.multiple === true }
+              : { count: 0, multiple: false };
+          }`,
+              [stateKey],
+              true,
+            ),
+          activationDeadline,
+          options.signal,
+          "inspecting activated file input timed out",
+        );
+        const summaryError = runtimeError(reply, "failed to inspect activated file input");
+        if (summaryError) throw summaryError;
+        const value = reply.result?.value as { count?: unknown; multiple?: unknown } | undefined;
+        summary = {
+          count: typeof value?.count === "number" ? value.count : 0,
+          multiple: value?.multiple === true,
+        };
+        if (summary.count > 0) break;
+        await delay(Math.min(PROBE_INTERVAL_MS, remainingMs(activationDeadline)), options.signal);
+      }
+
+      if (chooserEvents.length > 1) {
+        outcome = transferFailure(
+          "unsupported",
+          "file_input_not_activated",
+          "upload trigger activated more than one file chooser",
+          "none",
+          "resolve_input",
+        );
+        return outcome;
+      }
+
+      const chooser = chooserEvents[0];
+      let backendNodeId: number | undefined;
+      let multiple = summary.multiple;
+      if (chooser) {
+        if (options.actionTarget.frameId && chooser.frameId !== options.actionTarget.frameId) {
+          outcome = transferFailure(
+            "unsupported",
+            "file_input_not_activated",
+            "upload trigger activated a file chooser in a different frame",
+            "none",
+            "resolve_input",
+          );
+          return outcome;
+        }
+        if (typeof chooser.backendNodeId !== "number") {
+          outcome = transferFailure(
+            "unsupported",
+            "file_input_not_activated",
+            "upload trigger invoked a non-input file picker",
+            "none",
+            "resolve_input",
+          );
+          return outcome;
+        }
+        backendNodeId = chooser.backendNodeId;
+        multiple = chooser.mode === "selectMultiple";
+      } else {
+        if (summary.count !== 1) {
+          outcome = transferFailure(
+            "unsupported",
+            "file_input_not_activated",
+            summary.count === 0
+              ? "upload trigger did not activate an input[type=file]"
+              : "upload trigger activated more than one input[type=file]",
+            "none",
+            "resolve_input",
+          );
+          return outcome;
+        }
+        const input = await waitBounded(
+          () =>
+            callOnTrigger<RuntimeReply>(
+              options,
+              triggerObjectId as string,
+              `function(key) { return this.ownerDocument.defaultView?.[key]?.inputs[0]; }`,
+              [stateKey],
+              false,
+            ),
+          deadline,
+          options.signal,
+          "resolving activated file input timed out",
+        );
+        const inputError = runtimeError(input, "failed to resolve activated file input object");
+        if (inputError) throw inputError;
+        if (!input.result?.objectId) throw new Error("activated file input returned no objectId");
+        const described = await waitBounded(
+          () =>
+            sendToCdpTarget<{ node?: { backendNodeId?: number } }>(
+              options.cdp,
+              target,
+              "DOM.describeNode",
+              { objectId: input.result?.objectId },
+            ),
+          deadline,
+          options.signal,
+          "describing activated file input timed out",
+        );
+        backendNodeId = described.node?.backendNodeId;
+        if (typeof backendNodeId !== "number") {
+          throw new Error("DOM.describeNode returned no file input backendNodeId");
+        }
+      }
+
+      if (!multiple && options.files.length !== 1) {
+        outcome = enrichFailure(
+          { code: "invalid_params", message: "file input accepts exactly one file" },
+          "none",
+          "resolve_input",
+        );
+        return outcome;
+      }
+
+      try {
+        await waitBounded(
+          () =>
+            sendToCdpTarget(options.cdp, target, "DOM.setFileInputFiles", {
+              files: options.files,
+              backendNodeId,
+            }),
+          deadline,
+          options.signal,
+          "setting file input files timed out",
+        );
+      } catch (err) {
+        outcome = transferFailure(
+          waitErrorCode(err),
+          "set_file_input_failed",
+          err instanceof Error ? err.message : String(err),
+          "unknown",
+          "set_files",
+        );
+        return outcome;
+      }
+      outcome = { click, multiple };
+      return outcome;
+    } catch (err) {
+      outcome = transferFailure(
+        waitErrorCode(err),
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "resolve_input",
+      );
+      return outcome;
+    }
+  } finally {
+    chooserSubscription?.dispose();
+    const cleanupDeadline = Date.now() + CLEANUP_TIMEOUT_MS;
+    const cleanupTasks: Promise<boolean>[] = [];
+    const cleanup = async (operation: () => Promise<unknown>, message: string) => {
+      try {
+        await waitBounded(operation, cleanupDeadline, undefined, message);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    if (probeState !== "not_started" && triggerObjectId) {
+      cleanupTasks.push(
+        cleanup(
+          () =>
+            callOnTrigger(
+              options,
+              triggerObjectId as string,
+              `function(key) {
+              const owner = this.ownerDocument.defaultView;
+              const state = owner?.[key];
+              if (state?.listener) this.ownerDocument.removeEventListener("click", state.listener, true);
+              if (owner) delete owner[key];
+            }`,
+              [stateKey],
+              true,
+            ),
+          "cleaning file input probe timed out",
+        ),
+      );
+    }
+    if (interceptionState !== "not_started") {
+      cleanupTasks.push(
+        cleanup(
+          () =>
+            sendToCdpTarget(options.cdp, target, "Page.setInterceptFileChooserDialog", {
+              enabled: false,
+              cancel: true,
+            }),
+          "disabling file chooser interception timed out",
+        ),
+      );
+    }
+    let cleanupFailed = (await Promise.all(cleanupTasks)).some((completed) => !completed);
+    if (!cleanupFailed) {
+      cleanupFailed = !(await cleanup(
+        () => sendToCdpTarget(options.cdp, target, "Runtime.releaseObjectGroup", { objectGroup }),
+        "releasing upload object group timed out",
+      ));
+    }
+
+    const effect = isRpcError(outcome)
+      ? (outcome.data?.effect_state as TransferEffectState | undefined)
+      : "committed";
+    if (effect === "unknown" || cleanupFailed) {
+      try {
+        await waitBounded(
+          () => options.cdp.detach?.(target.tabId) ?? Promise.resolve(),
+          Date.now() + DETACH_TIMEOUT_MS,
+          undefined,
+          "detaching upload target timed out",
+        );
+      } catch {
+        cleanupFailed = true;
+      }
+    }
+    if (cleanupFailed && isRpcError(outcome)) {
+      outcome.data = { ...outcome.data, cleanup_state: "failed" };
+    }
+  }
+}

apps/extension/src/tools/interaction.ts

@@ -1,5 +1,5 @@
-// DOM interaction tools — `tool.click`, `tool.fill`, `tool.type`,
-// `tool.press`, and `tool.select`.
+// DOM interaction tools — `tool.click`, `tool.fill`, `tool.press`, and
+// `tool.select`.
 //
 // All interaction tools:
 // 1. Resolve target tab (sandbox: must be inside Agent Window).
@@ -11,7 +11,7 @@
 //    commands.
 
 import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
-import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
 import type { SessionContext, SessionManager } from "@/session-manager/manager";
 import type {
   ClickParams,
@@ -27,15 +27,11 @@ import type {
   RpcError,
   SelectParams,
   SelectResult,
-  TypeParams,
-  TypeResult,
 } from "@/transport/types";
 import { attachDialogs, markDialogCursor } from "./dialogs";
-import { fillEditable } from "./editable-input";
 import { backendNodeToObject } from "./element-geometry";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry, scrollElementAndFramesIntoView } from "./frame-geometry";
-import { dispatchMouseClick } from "./mouse-input";
 import {
   type CdpRunner,
   type ChromeTabsApi,
@@ -44,11 +40,10 @@ import {
   enforceAgentWindow,
   isRpcError,
   lookupSession,
+  type ResolvedTargetTab,
   resolveTargetTab,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { resolveSurfacePointerTarget } from "./surface-target";
-import { dispatchTextInput } from "./text-input";
 
 export interface InteractionDeps {
   cdp: CdpRunner;
@@ -62,6 +57,15 @@ export interface InteractionDeps {
   keepOverlayBypassAfterHover?: boolean;
 }
 
+export interface ResolvedActionTarget {
+  tab: ResolvedTargetTab;
+  backendNodeId: number;
+  cdpTarget: CdpTarget;
+  frameId?: string;
+  usedRef?: string;
+  usedSelector?: string;
+}
+
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_HOVER_SETTLE_MS = 200;
 
@@ -134,7 +138,7 @@ async function wait(ms: number, signal?: AbortSignal): Promise<void> {
  * `RpcError` if the caller supplied neither (or both), or if neither
  * lookup matched.
  */
-async function resolveBackendNode(
+export async function resolveBackendNode(
   cdp: CdpRunner,
   ctx: SessionContext,
   target: { tabId: number },
@@ -221,146 +225,26 @@ async function resolveBackendNode(
   }
 }
 
-interface InputDispatchContext {
-  target: CdpTarget;
-  cdp: CdpRunner;
-  backendNodeId?: number;
-  frameId?: string;
-  usedRef?: string;
-  usedSelector?: string;
-}
-
-function inputContextForNode(
+export async function resolveActionTarget(
   cdp: CdpRunner,
-  node: Awaited<ReturnType<typeof resolveBackendNode>>,
-): (InputDispatchContext & { backendNodeId: number }) | RpcError {
-  if (isRpcError(node)) return node;
-  return {
-    target: node.cdpTarget,
-    cdp: cdpRunnerForTarget(cdp, node.cdpTarget),
-    backendNodeId: node.backendNodeId,
-    frameId: node.frameId,
-    usedRef: node.usedRef,
-    usedSelector: node.usedSelector,
-  };
-}
-
-interface FocusProbe {
-  hasFocus: boolean;
-  activeTag: string;
-  textEntry: boolean;
-}
-
-/** Resolve keyboard input to the CDP target that currently owns focus. */
-async function resolveFocusedInputContext(
-  cdp: CdpRunner,
-  tabId: number,
-  mode: "press" | "type",
-): Promise<InputDispatchContext | RpcError> {
-  if (!cdp.getFrameGraph) {
-    return rpcError(
-      "cdp_failed",
-      "focus_target_unresolved",
-      `${mode} cannot determine the focused frame target`,
-    );
-  }
-
-  let targets: CdpTarget[];
-  try {
-    const graph = await cdp.getFrameGraph(tabId);
-    const unique = new Map<string, CdpTarget>();
-    unique.set(cdpTargetKey({ tabId }), { tabId });
-    for (const frame of graph.frames) unique.set(cdpTargetKey(frame.target), frame.target);
-    targets = [...unique.values()];
-  } catch (err) {
-    return rpcError(
-      "cdp_failed",
-      "focus_target_unresolved",
-      err instanceof Error ? err.message : String(err),
-    );
-  }
-
-  const focused: Array<{ target: CdpTarget; probe: FocusProbe }> = [];
-  await Promise.all(
-    targets.map(async (candidate) => {
-      try {
-        const reply = await cdpRunnerForTarget(cdp, candidate).send<{
-          result?: { value?: FocusProbe };
-        }>(tabId, "Runtime.evaluate", {
-          expression: `(() => {
-            /* bsk-focus-target-probe */
-            const active = document.activeElement;
-            const inputType = active instanceof HTMLInputElement ? active.type.toLowerCase() : '';
-            const nonTextInputTypes = new Set([
-              'button', 'checkbox', 'color', 'date', 'datetime-local', 'file',
-              'hidden', 'image', 'month', 'radio', 'range', 'reset', 'submit',
-              'time', 'week'
-            ]);
-            const role = active instanceof Element ? active.getAttribute('role') : null;
-            return {
-              hasFocus: document.hasFocus(),
-              activeTag: active instanceof Element ? active.tagName.toLowerCase() : '',
-              textEntry:
-                (active instanceof HTMLInputElement && !nonTextInputTypes.has(inputType)) ||
-                active instanceof HTMLTextAreaElement ||
-                (active instanceof HTMLElement && active.isContentEditable) ||
-                role === 'textbox' || role === 'searchbox'
-            };
-          })()`,
-          returnByValue: true,
-        });
-        const probe = reply.result?.value;
-        if (probe?.hasFocus) focused.push({ target: candidate, probe });
-      } catch {
-        // A target may navigate or detach while the graph is being probed.
-      }
-    }),
-  );
-
-  // A top document whose active element is an iframe delegates focus to
-  // that frame. Removing those delegating targets leaves the deepest OOPIF
-  // target while same-process frames continue to use the shared root target.
-  const owners = focused.filter(({ probe }) => {
-    if (probe.activeTag === "iframe" || probe.activeTag === "frame") return false;
-    return mode !== "type" || probe.textEntry;
-  });
-  if (owners.length !== 1) {
-    return rpcError(
-      "cdp_failed",
-      "focus_target_unresolved",
-      owners.length === 0
-        ? `${mode} found no unique focused${mode === "type" ? " text-entry" : " frame"} target`
-        : `${mode} found multiple focused frame targets`,
-      { candidate_count: owners.length },
-    );
-  }
-  const target = owners[0].target;
-  return { target, cdp: cdpRunnerForTarget(cdp, target) };
+  ctx: SessionContext,
+  target: ResolvedTargetTab,
+  params: { ref?: string; selector?: string },
+  toolName: string,
+): Promise<ResolvedActionTarget | RpcError> {
+  const node = await resolveBackendNode(cdp, ctx, target, params, toolName);
+  return isRpcError(node) ? node : { tab: target, ...node };
 }
 
 // ---------------------------------------------------------------------------
 // tool.click
 // ---------------------------------------------------------------------------
 
-interface ResolvedClickPointerTarget {
-  point: { x: number; y: number };
-  usedRef?: string;
-  usedSelector?: string;
-  moveSettleMs: number;
-  capture?: {
-    id: string;
-    imageX: number;
-    imageY: number;
-  };
-}
-
 export async function handleClick(
   manager: SessionManager,
   params: ClickParams,
   deps: InteractionDeps = getDefaultDeps(),
 ): Promise<ClickResult | RpcError> {
-  const hasSurfacePointParams =
-    params.capture_id !== undefined || params.image_x !== undefined || params.image_y !== undefined;
   const ctxOrErr = lookupSession(manager, params, "click");
   if (isRpcError(ctxOrErr)) return ctxOrErr;
   const ctx = ctxOrErr;
@@ -370,69 +254,50 @@ export async function handleClick(
   if (isRpcError(target)) return target;
   const denied = enforceAgentWindow(ctx, target, "click");
   if (denied) return denied;
-  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
+  const resolved = await resolveActionTarget(deps.cdp, ctx, target, params, "click");
+  if (isRpcError(resolved)) return resolved;
+  return clickResolvedTarget(ctx, resolved, params, deps);
+}
 
-  const button: MouseButton = params.button ?? "left";
-  const clickCount = params.click_count ?? 1;
-  if (!Number.isSafeInteger(clickCount) || clickCount < 1) {
-    return { code: "invalid_params", message: "click_count must be a positive integer" };
-  }
-  const modifiers = modifiersBitfield(params.modifiers);
+export async function clickResolvedTarget(
+  ctx: SessionContext,
+  resolved: ResolvedActionTarget,
+  params: Pick<ClickParams, "button" | "click_count" | "modifiers">,
+  deps: InteractionDeps,
+): Promise<ClickResult | RpcError> {
+  const { tab: target } = resolved;
+  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
 
   if (throwIfAborted(deps.signal)) {
     return { code: "cancelled", message: "click aborted" };
   }
 
   deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  const pointerTarget: ResolvedClickPointerTarget | RpcError = hasSurfacePointParams
-    ? await resolveSurfacePointerTarget(
-        ctx,
-        target,
-        {
-          ref: params.ref,
-          selector: params.selector,
-          captureId: params.capture_id,
-          imageX: params.image_x,
-          imageY: params.image_y,
-        },
-        {
-          cdp: deps.cdp,
-          signal: deps.signal,
-        },
-      )
-    : await (async () => {
-        const node = await resolveBackendNode(deps.cdp, ctx, target, params, "click");
-        if (isRpcError(node)) return node;
-        const geometry = await resolveNodeGeometry(
-          deps.cdp,
-          target.tabId,
-          {
-            target: node.cdpTarget,
-            backendNodeId: node.backendNodeId,
-            ...(node.frameId ? { frameId: node.frameId } : {}),
-          },
-          { scrollIntoView: true },
-        );
-        if (isRpcError(geometry)) return geometry;
-        return {
-          point: geometry.actionPoint,
-          usedRef: node.usedRef,
-          usedSelector: node.usedSelector,
-          moveSettleMs: 0,
-        };
-      })();
-  if (isRpcError(pointerTarget)) return pointerTarget;
+  const geometry = await resolveNodeGeometry(
+    deps.cdp,
+    target.tabId,
+    {
+      target: resolved.cdpTarget,
+      backendNodeId: resolved.backendNodeId,
+      ...(resolved.frameId ? { frameId: resolved.frameId } : {}),
+    },
+    { scrollIntoView: true },
+  );
+  if (isRpcError(geometry)) return geometry;
+  const centre = geometry.actionPoint;
 
   if (throwIfAborted(deps.signal)) {
     return { code: "cancelled", message: "click aborted" };
   }
 
-  const overlayBlocking = await checkOverlayAtPoint(
-    deps.cdp,
-    target.tabId,
-    pointerTarget.point.x,
-    pointerTarget.point.y,
-  );
+  const button: MouseButton = params.button ?? "left";
+  const clickCount = params.click_count ?? 1;
+  if (clickCount < 1) {
+    return { code: "invalid_params", message: "click_count must be greater than zero" };
+  }
+  const modifiers = modifiersBitfield(params.modifiers);
+
+  const overlayBlocking = await checkOverlayAtPoint(deps.cdp, target.tabId, centre.x, centre.y);
   let automationBypassEnabled = false;
   if (overlayBlocking && deps.bypassOverlay) {
     try {
@@ -444,16 +309,47 @@ export async function handleClick(
   }
 
   try {
-    const dispatch = await dispatchMouseClick(deps.cdp, target.tabId, pointerTarget.point, {
+    // Move first so hover state activates, then press → release.
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: centre.x,
+      y: centre.y,
+      modifiers,
+    });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "click aborted" };
+    }
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      x: centre.x,
+      y: centre.y,
       button,
       clickCount,
       modifiers,
-      signal: deps.signal,
-      moveSettleMs: pointerTarget.moveSettleMs,
     });
-    if (dispatch === "cancelled") {
+    if (throwIfAborted(deps.signal)) {
+      try {
+        await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+          type: "mouseReleased",
+          x: centre.x,
+          y: centre.y,
+          button,
+          clickCount,
+          modifiers,
+        });
+      } catch (err) {
+        console.debug("[bsk interaction] best-effort mouseReleased after abort failed", err);
+      }
       return { code: "cancelled", message: "click aborted" };
     }
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x: centre.x,
+      y: centre.y,
+      button,
+      clickCount,
+      modifiers,
+    });
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -471,17 +367,10 @@ export async function handleClick(
 
   return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
     tab_id: target.tabId,
-    used_ref: pointerTarget.usedRef,
-    used_selector: pointerTarget.usedSelector,
-    x: pointerTarget.point.x,
-    y: pointerTarget.point.y,
-    ...(pointerTarget.capture
-      ? {
-          capture_id: pointerTarget.capture.id,
-          image_x: pointerTarget.capture.imageX,
-          image_y: pointerTarget.capture.imageY,
-        }
-      : {}),
+    used_ref: resolved.usedRef,
+    used_selector: resolved.usedSelector,
+    x: centre.x,
+    y: centre.y,
   });
 }
 
@@ -701,47 +590,6 @@ function isFillable(node: DescribedNode): boolean {
   return false;
 }
 
-/** `type` also supports custom text-entry widgets that expose an ARIA role. */
-function isTypeTarget(node: DescribedNode): boolean {
-  const tag = (node.nodeName ?? "").toUpperCase();
-  const attrs = node.attributes ?? [];
-  const attributes = new Map<string, string>();
-  for (let i = 0; i + 1 < attrs.length; i += 2) {
-    attributes.set(attrs[i].toLowerCase(), attrs[i + 1].toLowerCase());
-  }
-  if (tag === "TEXTAREA") return true;
-  if (tag === "INPUT") {
-    const type = attributes.get("type") ?? "text";
-    return !new Set([
-      "button",
-      "checkbox",
-      "color",
-      "date",
-      "datetime-local",
-      "file",
-      "hidden",
-      "image",
-      "month",
-      "radio",
-      "range",
-      "reset",
-      "submit",
-      "time",
-      "week",
-    ]).has(type);
-  }
-  const contentEditable = attributes.get("contenteditable");
-  if (
-    contentEditable === "" ||
-    contentEditable === "true" ||
-    contentEditable === "plaintext-only"
-  ) {
-    return true;
-  }
-  const role = attributes.get("role");
-  return role === "textbox" || role === "searchbox";
-}
-
 type SelectMutationResult =
   | {
       ok: true;
@@ -780,9 +628,8 @@ export async function handleFill(
   const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
 
   const node = await resolveBackendNode(deps.cdp, ctx, target, params, "fill");
-  const input = inputContextForNode(deps.cdp, node);
-  if (isRpcError(input)) return input;
-  const nodeCdp = input.cdp;
+  if (isRpcError(node)) return node;
+  const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
@@ -790,7 +637,7 @@ export async function handleFill(
       target.tabId,
       "DOM.describeNode",
       {
-        backendNodeId: input.backendNodeId,
+        backendNodeId: node.backendNodeId,
       },
     );
     if (!described.node || !isFillable(described.node)) {
@@ -803,15 +650,15 @@ export async function handleFill(
     const scrollErr = await scrollElementAndFramesIntoView(
       deps.cdp,
       target.tabId,
-      input.target,
-      input.backendNodeId,
-      input.frameId,
+      node.cdpTarget,
+      node.backendNodeId,
+      node.frameId,
     );
     if (scrollErr) return scrollErr;
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
-    await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: input.backendNodeId });
+    await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -823,118 +670,62 @@ export async function handleFill(
     return { code: "cancelled", message: "fill aborted" };
   }
 
-  const objectIdOrErr = await backendNodeToObject(nodeCdp, target.tabId, input.backendNodeId);
+  const objectIdOrErr = await backendNodeToObject(nodeCdp, target.tabId, node.backendNodeId);
   if (isRpcError(objectIdOrErr)) return objectIdOrErr;
   const objectId = objectIdOrErr;
   const clearBefore = params.clear_before ?? true;
-  const fillResult = await fillEditable(
-    nodeCdp,
-    target.tabId,
-    objectId,
-    params.value,
-    clearBefore,
-    deps.signal,
-  );
-  if (isRpcError(fillResult)) return fillResult;
 
-  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
-    tab_id: target.tabId,
-    used_ref: input.usedRef,
-    used_selector: input.usedSelector,
-    value_length: fillResult.value.length,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// tool.type
-// ---------------------------------------------------------------------------
-
-export async function handleType(
-  manager: SessionManager,
-  params: TypeParams,
-  deps: InteractionDeps = getDefaultDeps(),
-): Promise<TypeResult | RpcError> {
-  if (!params || typeof params.text !== "string") {
-    return { code: "invalid_params", message: "type requires a text string" };
-  }
-  if (params.focused !== undefined && typeof params.focused !== "boolean") {
-    return { code: "invalid_params", message: "type focused must be a boolean" };
-  }
-  const hasExplicitTarget =
-    (typeof params.ref === "string" && params.ref.length > 0) ||
-    (typeof params.selector === "string" && params.selector.length > 0);
-  if (params.focused === true && hasExplicitTarget) {
-    return {
-      code: "invalid_params",
-      message: "type: pass a ref/selector or focused=true, not both",
-    };
-  }
-  if (params.focused !== true && !hasExplicitTarget) {
-    return {
-      code: "invalid_params",
-      message: "type requires a ref/selector or focused=true",
-    };
-  }
-  const ctxOrErr = lookupSession(manager, params, "type");
-  if (isRpcError(ctxOrErr)) return ctxOrErr;
-  const ctx = ctxOrErr;
-  if (throwIfAborted(deps.signal)) return { code: "cancelled", message: "type aborted" };
-  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
-  if (isRpcError(target)) return target;
-  const denied = enforceAgentWindow(ctx, target, "type");
-  if (denied) return denied;
-  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
-
-  let input: InputDispatchContext | RpcError;
-  if (hasExplicitTarget) {
-    const node = await resolveBackendNode(deps.cdp, ctx, target, params, "type");
-    const explicitInput = inputContextForNode(deps.cdp, node);
-    if (isRpcError(explicitInput)) return explicitInput;
-    input = explicitInput;
-    try {
-      const described = await explicitInput.cdp.send<{ node?: DescribedNode }>(
-        target.tabId,
-        "DOM.describeNode",
-        { backendNodeId: explicitInput.backendNodeId },
-      );
-      if (!described.node || !isTypeTarget(described.node)) {
-        return rpcError(
-          "invalid_params",
-          "target_not_fillable",
-          `element ${described.node?.nodeName ?? "?"} not text-editable`,
-        );
-      }
-      deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-      const scrollErr = await scrollElementAndFramesIntoView(
-        deps.cdp,
-        target.tabId,
-        explicitInput.target,
-        explicitInput.backendNodeId,
-        explicitInput.frameId,
-      );
-      if (scrollErr) return scrollErr;
-      if (throwIfAborted(deps.signal)) return { code: "cancelled", message: "type aborted" };
-      await explicitInput.cdp.send(target.tabId, "DOM.focus", {
-        backendNodeId: explicitInput.backendNodeId,
+  try {
+    if (clearBefore) {
+      // Clear input/textarea value or wipe contenteditable innerText,
+      // then fire `input` so frameworks observe the empty state.
+      await nodeCdp.send(target.tabId, "Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+          if (this.isContentEditable) { this.textContent = ''; }
+          else {
+            const proto = this instanceof HTMLTextAreaElement
+              ? HTMLTextAreaElement.prototype
+              : HTMLInputElement.prototype;
+            const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
+            if (descriptor && descriptor.set) descriptor.set.call(this, '');
+            else this.value = '';
+          }
+          this.dispatchEvent(new Event('input', { bubbles: true }));
+        }`,
+        returnByValue: true,
       });
-    } catch (err) {
-      return { code: "cdp_failed", message: err instanceof Error ? err.message : String(err) };
     }
-  } else {
-    input = await resolveFocusedInputContext(deps.cdp, target.tabId, "type");
-    if (isRpcError(input)) return input;
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    // CDP `Input.insertText` handles IME / multi-byte input out of the
+    // box, much more reliably than per-key `dispatchKeyEvent`.
+    await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    // Fire `input` + `change` so React / Vue controlled inputs commit.
+    await nodeCdp.send(target.tabId, "Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function() {
+        this.dispatchEvent(new Event('input', { bubbles: true }));
+        this.dispatchEvent(new Event('change', { bubbles: true }));
+      }`,
+      returnByValue: true,
+    });
+  } catch (err) {
+    return {
+      code: "cdp_failed",
+      message: err instanceof Error ? err.message : String(err),
+    };
   }
 
-  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  const dispatchError = await dispatchTextInput(input.cdp, target.tabId, params.text, deps.signal);
-  if (dispatchError) return dispatchError;
-
   return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
     tab_id: target.tabId,
-    used_ref: input.usedRef,
-    used_selector: input.usedSelector,
-    text_length: params.text.length,
-    verification: "dispatched",
+    used_ref: node.usedRef,
+    used_selector: node.usedSelector,
+    value_length: params.value.length,
   });
 }
 
@@ -1109,38 +900,31 @@ export async function handlePress(
     };
   }
 
-  let input: InputDispatchContext | RpcError;
   // Optional focus before key dispatch.
   if (params.ref || params.selector) {
     const node = await resolveBackendNode(deps.cdp, ctx, target, params, "press");
-    const explicitInput = inputContextForNode(deps.cdp, node);
-    if (isRpcError(explicitInput)) return explicitInput;
-    input = explicitInput;
+    if (isRpcError(node)) return node;
+    const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);
     try {
       deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
       const scrollErr = await scrollElementAndFramesIntoView(
         deps.cdp,
         target.tabId,
-        explicitInput.target,
-        explicitInput.backendNodeId,
-        explicitInput.frameId,
+        node.cdpTarget,
+        node.backendNodeId,
+        node.frameId,
       );
       if (scrollErr) return scrollErr;
       if (throwIfAborted(deps.signal)) {
         return { code: "cancelled", message: "press aborted" };
       }
-      await explicitInput.cdp.send(target.tabId, "DOM.focus", {
-        backendNodeId: explicitInput.backendNodeId,
-      });
+      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
     } catch (err) {
       return {
         code: "cdp_failed",
         message: err instanceof Error ? err.message : String(err),
       };
     }
-  } else {
-    input = await resolveFocusedInputContext(deps.cdp, target.tabId, "press");
-    if (isRpcError(input)) return input;
   }
 
   if (throwIfAborted(deps.signal)) {
@@ -1154,7 +938,7 @@ export async function handlePress(
   try {
     let cancelled = false;
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await input.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
+    await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
       type: "rawKeyDown",
       key: descriptor.key,
       code: descriptor.code,
@@ -1168,7 +952,7 @@ export async function handlePress(
       typeof descriptor.text === "string" &&
       descriptor.text.length > 0
     ) {
-      await input.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
+      await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
         type: "char",
         key: descriptor.key,
         code: descriptor.code,
@@ -1185,7 +969,7 @@ export async function handlePress(
         cancelled = true;
       }
     }
-    await input.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
+    await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
       type: "keyUp",
       key: descriptor.key,
       code: descriptor.code,

apps/extension/src/tools/mouse-input.ts

@@ -1,96 +0,0 @@
-import type { MouseButton } from "@/transport/types";
-import type { Point } from "./geometry";
-import type { CdpRunner } from "./shared";
-
-interface MouseClickDispatchOptions {
-  button: MouseButton;
-  clickCount: number;
-  modifiers: number;
-  signal?: AbortSignal;
-  moveSettleMs?: number;
-}
-
-type MouseClickDispatchResult = "completed" | "cancelled";
-
-function waitForSettle(ms: number, signal: AbortSignal | undefined): Promise<boolean> {
-  if (ms <= 0) return Promise.resolve(signal?.aborted !== true);
-  if (signal?.aborted) return Promise.resolve(false);
-  return new Promise((resolve) => {
-    let settled = false;
-    const finish = (completed: boolean) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      resolve(completed);
-    };
-    const timer = setTimeout(() => finish(true), ms);
-    const onAbort = () => finish(false);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-/**
- * Dispatch one coherent CDP mouse click in top-viewport CSS coordinates.
- *
- * Keeping the sequence here prevents DOM and Surface interaction paths from
- * duplicating cancellation and best-effort release behavior. Callers that
- * target asynchronously hit-tested content may request a settle interval.
- */
-export async function dispatchMouseClick(
-  cdp: CdpRunner,
-  tabId: number,
-  point: Point,
-  options: MouseClickDispatchOptions,
-): Promise<MouseClickDispatchResult> {
-  const { button, clickCount, modifiers, signal, moveSettleMs = 0 } = options;
-  let pressed = false;
-  const release = () =>
-    cdp.send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseReleased",
-      x: point.x,
-      y: point.y,
-      button,
-      clickCount,
-      modifiers,
-    });
-
-  try {
-    await cdp.send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseMoved",
-      x: point.x,
-      y: point.y,
-      modifiers,
-    });
-    if (!(await waitForSettle(moveSettleMs, signal))) return "cancelled";
-
-    await cdp.send(tabId, "Input.dispatchMouseEvent", {
-      type: "mousePressed",
-      x: point.x,
-      y: point.y,
-      button,
-      clickCount,
-      modifiers,
-    });
-    pressed = true;
-
-    if (signal?.aborted) {
-      await release();
-      pressed = false;
-      return "cancelled";
-    }
-
-    await release();
-    pressed = false;
-    return "completed";
-  } catch (error) {
-    if (pressed) {
-      try {
-        await release();
-      } catch (releaseError) {
-        console.debug("[bsk mouse-input] best-effort mouse release failed", releaseError);
-      }
-    }
-    throw error;
-  }
-}

apps/extension/src/tools/observation.ts

@@ -48,15 +48,16 @@ import {
   type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { surfaceVisibleRect } from "./surface-coordinate";
-import { captureSurfaceEnvironment } from "./surface-target";
 import {
   type CapturedNode,
+  type CapturedSurfaceProbe,
   type CapturedViewModel,
   captureViewModel,
   collectOverlayExcludedBackendIds,
+  probeHoverSurfaces,
 } from "./vom/capture";
 import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
+import { withOverlayBypass } from "./vom/hover-perception";
 import { probeTooltipNames } from "./vom/name-enrichment";
 import {
   type CaptureVomObservationResult,
@@ -115,8 +116,8 @@ export function stripDataUrlPrefix(dataUrl: string): string {
 
 /**
  * Parse a PNG's IHDR chunk and return `(width, height)`. Returns
- * `null` on any malformed input so callers fall back to `0/0` instead
- * of throwing.
+ * `null` on malformed input so callers can reject dimensions that are
+ * not authoritative instead of guessing from a CSS-space rectangle.
  *
  * PNG layout: 8-byte signature, then a 4-byte length, 4-byte type
  * ("IHDR"), then the chunk data — width is bytes 16-19 BE, height is
@@ -128,9 +129,9 @@ export function parsePngDimensions(base64: string): { width: number; height: num
     const head = base64.length > 64 ? base64.slice(0, 64) : base64;
     const bin = atob(head);
     if (bin.length < 24) return null;
-    if (bin.charCodeAt(0) !== 0x89 || bin.charCodeAt(1) !== 0x50 || bin.charCodeAt(2) !== 0x4e) {
-      return null;
-    }
+    const expectedSignature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    if (expectedSignature.some((byte, index) => bin.charCodeAt(index) !== byte)) return null;
+    if (bin.slice(12, 16) !== "IHDR") return null;
     const u32 = (off: number) =>
       (bin.charCodeAt(off) << 24) |
       (bin.charCodeAt(off + 1) << 16) |
@@ -196,9 +197,7 @@ async function captureElementScreenshot(
   visualSurface = false,
   observedVisibleRect?: Rect,
   signal?: AbortSignal,
-): Promise<
-  { image_base64: string; width: number; height: number; topViewportRect: Rect } | RpcError
-> {
+): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
   if (signal?.aborted) return cancelled("screenshot");
   const geometry = await resolveNodeGeometry(
     cdp,
@@ -208,19 +207,24 @@ async function captureElementScreenshot(
   );
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
-  const topViewportRect = surfaceVisibleRect(
-    geometry.topBounds,
-    visualSurface ? observedVisibleRect : undefined,
-  );
-  if (!topViewportRect) {
-    return { code: "permission_denied", message: "surface is no longer visible" };
-  }
-  const rect = {
-    x: topViewportRect.x,
-    y: topViewportRect.y,
-    width: topViewportRect.w,
-    height: topViewportRect.h,
-  };
+  const liveRect = geometry.topBounds;
+  const rect =
+    visualSurface && observedVisibleRect
+      ? (() => {
+          const x = Math.max(liveRect.x, observedVisibleRect.x);
+          const y = Math.max(liveRect.y, observedVisibleRect.y);
+          const right = Math.min(
+            liveRect.x + liveRect.width,
+            observedVisibleRect.x + observedVisibleRect.w,
+          );
+          const bottom = Math.min(
+            liveRect.y + liveRect.height,
+            observedVisibleRect.y + observedVisibleRect.h,
+          );
+          return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : null;
+        })()
+      : liveRect;
+  if (!rect) return { code: "permission_denied", message: "surface is no longer visible" };
   const scale = visualSurface
     ? Math.min(
         1,
@@ -246,11 +250,11 @@ async function captureElementScreenshot(
     if (!image_base64) {
       return { code: "cdp_failed", message: "Page.captureScreenshot returned no data" };
     }
-    const dims = parsePngDimensions(image_base64) ?? {
-      width: Math.round(rect.width),
-      height: Math.round(rect.height),
-    };
-    return { image_base64, width: dims.width, height: dims.height, topViewportRect };
+    const dims = parsePngDimensions(image_base64);
+    if (!dims) {
+      return { code: "cdp_failed", message: "Page.captureScreenshot returned invalid PNG data" };
+    }
+    return { image_base64, width: dims.width, height: dims.height };
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -373,46 +377,12 @@ export async function handleScreenshot(
     );
     if (isRpcError(captured)) return captured;
     if (signal?.aborted) return cancelled("screenshot");
-    const capture =
-      node.kind === "surface"
-        ? await (async () => {
-            const environment = await captureSurfaceEnvironment(cdp, target.tabId, node.frameId);
-            if (isRpcError(environment)) return environment;
-            return ctx.surfaceCaptures.create({
-              sessionId: ctx.sessionId,
-              tabId: target.tabId,
-              navigationIdentity: environment.navigationIdentity,
-              surface: {
-                ref: node.refKey,
-                ...(node.frameId ? { frameId: node.frameId } : {}),
-                backendNodeId: node.backendNodeId,
-                observationGeneration: node.generation,
-              },
-              topViewportRect: captured.topViewportRect,
-              imageWidth: captured.width,
-              imageHeight: captured.height,
-              viewportSignature: environment.viewportSignature,
-              frameProjectionSignature: environment.frameProjectionSignature,
-            });
-          })()
-        : null;
-    if (capture && isRpcError(capture)) return capture;
     return withShotDialogs({
       image_base64: captured.image_base64,
       width: captured.width,
       height: captured.height,
       format: "png",
       tab_id: target.tabId,
-      ...(capture
-        ? {
-            capture: {
-              id: capture.id,
-              surface_ref: `@${capture.surface.ref}`,
-              coordinate_space: "capture-image-pixel" as const,
-              expires_at: capture.expiresAt,
-            },
-          }
-        : {}),
     });
   }
 
@@ -432,7 +402,10 @@ export async function handleScreenshot(
   if (isRpcError(captured)) return captured;
   if (signal?.aborted) return cancelled("screenshot");
   const image_base64 = captured;
-  const dims = parsePngDimensions(image_base64) ?? { width: 0, height: 0 };
+  const dims = parsePngDimensions(image_base64);
+  if (!dims) {
+    return { code: "cdp_failed", message: "screenshot capture returned invalid PNG data" };
+  }
   return withShotDialogs({
     image_base64,
     width: dims.width,
@@ -596,8 +569,11 @@ function buildActiveScopeBlocks(nodes: VomNode[], signals: VomNodeDomSignals): A
   return blocks;
 }
 
-function buildConditionalSurfaces(nodes: VomNode[], captured: CapturedViewModel): CondSurface[] {
-  const probes = captured.surfaceProbes ?? [];
+function buildConditionalSurfaces(
+  nodes: VomNode[],
+  captured: CapturedViewModel,
+  probes: CapturedSurfaceProbe[],
+): CondSurface[] {
   if (probes.length === 0) return [];
 
   const surfaces: CondSurface[] = [];
@@ -720,6 +696,7 @@ function findSurfaceNodeByPoint(
 export interface BuildVomSceneOptions {
   pageUrl?: string;
   supplementalNames?: ReadonlyMap<string, string>;
+  surfaceProbes?: CapturedSurfaceProbe[];
 }
 
 export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
@@ -888,18 +865,19 @@ export function buildFrameVomScene(
     excludedBackendNodeIds: captured.excludedBackendNodeIds,
     supplementalNames: options.supplementalNames,
   });
-  return attachCapturedSceneAnnotations(scene, documents, captured);
+  return attachCapturedSceneAnnotations(scene, documents, captured, options.surfaceProbes ?? []);
 }
 
 function attachCapturedSceneAnnotations(
   scene: VomScene,
   documents: VomFrameDocument[],
   captured: CapturedViewModel,
+  surfaceProbes: CapturedSurfaceProbe[],
 ): VomScene {
   const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
   const signals = capturedOnlySignals(rootDocument?.domNodes ?? captured.nodes);
   const activeScopeBlocks = buildActiveScopeBlocks(scene.nodes, signals);
-  const surfaces = buildConditionalSurfaces(scene.nodes, captured);
+  const surfaces = buildConditionalSurfaces(scene.nodes, captured, surfaceProbes);
   return {
     ...scene,
     ...(surfaces.length > 0 ? { surfaces } : {}),
@@ -1081,17 +1059,69 @@ async function captureForVom(
   options: CaptureVomObservationOptions,
 ): Promise<CapturedViewModel> {
   try {
-    return await captureViewModel(cdp, tabId, {
-      conditionalSurfaceProbe: options.conditionalSurfaceProbe ?? false,
-      hoverProbeBypassOverlay: options.hoverProbeBypassOverlay,
-      signal: options.signal,
-    });
+    return await captureViewModel(cdp, tabId, { signal: options.signal });
   } catch (error) {
     if (isAbortError(error)) throw error;
     return fallbackCapturedViewModel(cdp, tabId, options.signal);
   }
 }
 
+export interface HoverProbeOutcome {
+  /** Whether any active hover was dispatched during this observation. */
+  performed: boolean;
+  /**
+   * Whether hovering surfaced content absent from the static snapshot. Cached
+   * tooltip names count, so this may over-report on repeat observations — it
+   * errs towards telling the caller the snapshot is less fresh than it looks.
+   */
+  revealedContent: boolean;
+  surfaceProbes: CapturedSurfaceProbe[];
+  tooltipNames: Map<string, string>;
+}
+
+const NO_HOVER_PROBES: HoverProbeOutcome = {
+  performed: false,
+  revealedContent: false,
+  surfaceProbes: [],
+  tooltipNames: new Map(),
+};
+
+/**
+ * Runs both active-hover chains back to back.
+ *
+ * Ordering matters: this happens after DOM *and* accessibility capture so a
+ * hover that opens a menu cannot leave one half of the observation describing
+ * the page before the change and the other half after it. Sharing one overlay
+ * bypass span also means the agent overlay toggles once per observation
+ * instead of once per chain.
+ */
+async function runHoverProbes(
+  cdp: CdpRunner,
+  tabId: number,
+  captured: CapturedViewModel,
+  documents: VomFrameDocument[],
+  staticSemantics: ReturnType<typeof resolveSemanticGraph>,
+  options: CaptureVomObservationOptions,
+): Promise<HoverProbeOutcome> {
+  if (!options.conditionalSurfaceProbe) return NO_HOVER_PROBES;
+
+  return withOverlayBypass(options.hoverProbeBypassOverlay, tabId, async () => {
+    const surfaceProbes = await probeHoverSurfaces(cdp, tabId, captured.nodes, {
+      signal: options.signal,
+    });
+    throwIfAborted(options.signal, "observation");
+    const tooltipNames = await probeTooltipNames(cdp, tabId, documents, staticSemantics, {
+      signal: options.signal,
+    });
+    return {
+      performed: true,
+      revealedContent: surfaceProbes.length > 0 || tooltipNames.size > 0,
+      surfaceProbes,
+      tooltipNames,
+    };
+  });
+}
+
 export interface CaptureVomObservationOptions extends VomOptions {
   conditionalSurfaceProbe?: boolean;
   renderedSurfaceDiscovery?: boolean;
@@ -1123,19 +1153,26 @@ export async function captureVomObservation(
     excludedBackendNodeIds: captured.excludedBackendNodeIds,
   });
   const staticSemantics = resolveSemanticGraph(semanticGraph, { identifierFallback: false });
-  const tooltipNames = options.conditionalSurfaceProbe
-    ? await probeTooltipNames(cdp, tabId, normalizedDocuments, staticSemantics, {
-        signal: options.signal,
-        hoverProbeBypassOverlay: options.hoverProbeBypassOverlay,
-      })
-    : new Map<string, string>();
+  const hoverProbes = await runHoverProbes(
+    cdp,
+    tabId,
+    captured,
+    normalizedDocuments,
+    staticSemantics,
+    options,
+  );
   throwIfAborted(options.signal, "observation");
   const scene = projectSemanticGraph(
     normalizeSemanticStructure(
-      resolveSemanticGraph(semanticGraph, { supplementalNames: tooltipNames }),
+      resolveSemanticGraph(semanticGraph, { supplementalNames: hoverProbes.tooltipNames }),
     ),
   );
-  const decoratedScene = attachCapturedSceneAnnotations(scene, normalizedDocuments, captured);
+  const decoratedScene = attachCapturedSceneAnnotations(
+    scene,
+    normalizedDocuments,
+    captured,
+    hoverProbes.surfaceProbes,
+  );
   const observedScene = options.renderedSurfaceDiscovery
     ? projectRenderedSurfaces(
         decoratedScene,
@@ -1160,7 +1197,11 @@ export async function captureVomObservation(
     rootFrameId: captured.rootFrameId ?? normalizedDocuments[0]?.frameId ?? "root",
     frameDocuments: normalizedDocuments,
     rendered,
-    surfaceProbes: captured.surfaceProbes,
+    surfaceProbes: hoverProbes.surfaceProbes,
+    hoverProbe: {
+      performed: hoverProbes.performed,
+      revealedContent: hoverProbes.revealedContent,
+    },
   });
 }
 
@@ -1230,6 +1271,14 @@ async function handleVomObservation(
       ref_count: observation.refs.length,
       tab_id: target.tabId,
       truncated: observation.truncated,
+      ...(toolName === "observe" && observation.hoverProbe?.performed
+        ? {
+            hover_probe: {
+              performed: true,
+              revealed_content: observation.hoverProbe.revealedContent,
+            },
+          }
+        : {}),
       ...(toolName === "observe" && (params as ObserveParams).debug_surfaces
         ? {
             debug: {
@@ -1268,5 +1317,13 @@ export async function handleObserve(
   deps: SnapshotDeps = getDefaultDeps(),
   signal?: AbortSignal,
 ): Promise<ObserveResult | RpcError> {
-  return handleVomObservation(manager, params, "observe", "transient_input", true, deps, signal);
+  return handleVomObservation(
+    manager,
+    params,
+    "observe",
+    "transient_input",
+    params.probe_hover === true,
+    deps,
+    signal,
+  );
 }

apps/extension/src/tools/session.ts

@@ -243,7 +243,6 @@ export async function handleSessionStop(
 
   // Step 2: clear the per-session RefStore (review M6/M7 parity).
   ctx.refStore.clear();
-  ctx.surfaceCaptures.clear();
 
   clearRecordingForSession(params.session_id);
 

apps/extension/src/tools/shared.ts

@@ -53,6 +53,7 @@ export type { DialogCursor };
 export interface CdpRunner {
   send<T = unknown>(tabId: number, method: string, params?: object): Promise<T>;
   sendToTarget?<T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T>;
+  detach?(tabId: number): Promise<void>;
   getFrameGraph?(tabId: number): Promise<CdpFrameGraph>;
   ensureAttachedToUrl?(tabId: number, expectedUrl: string | undefined): Promise<void>;
   trackSessionTab?(sessionId: string, tabId: number): void;

apps/extension/src/tools/snapshot-ref.ts

@@ -16,7 +16,6 @@ export interface SnapshotRefLookup {
   visibleRect?: Rect;
   kind: RefTargetKind;
   capabilities: RefCapability[];
-  generation: number;
 }
 
 function refEntryForTab(ctx: SessionContext, refKey: string, tabId: number) {
@@ -45,7 +44,6 @@ export function lookupSnapshotRef(
     ...(entry.visibleRect ? { visibleRect: entry.visibleRect } : {}),
     kind: entry.kind,
     capabilities: entry.capabilities,
-    generation: entry.generation,
   };
 }
 

apps/extension/src/tools/surface-coordinate.ts

@@ -1,88 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-import type { Point, Region, ViewportRect } from "./geometry";
-
-const RECT_EPSILON = 0.01;
-
-export function surfaceVisibleRect(
-  liveRect: ViewportRect,
-  observedRect: Rect | undefined,
-): Rect | null {
-  const observed = observedRect ?? {
-    x: liveRect.x,
-    y: liveRect.y,
-    w: liveRect.width,
-    h: liveRect.height,
-  };
-  const x = Math.max(liveRect.x, observed.x);
-  const y = Math.max(liveRect.y, observed.y);
-  const right = Math.min(liveRect.x + liveRect.width, observed.x + observed.w);
-  const bottom = Math.min(liveRect.y + liveRect.height, observed.y + observed.h);
-  return right > x && bottom > y ? { x, y, w: right - x, h: bottom - y } : null;
-}
-
-export function sameRect(a: Rect, b: Rect): boolean {
-  return (
-    Math.abs(a.x - b.x) <= RECT_EPSILON &&
-    Math.abs(a.y - b.y) <= RECT_EPSILON &&
-    Math.abs(a.w - b.w) <= RECT_EPSILON &&
-    Math.abs(a.h - b.h) <= RECT_EPSILON
-  );
-}
-
-export function mapImagePointToViewport(
-  rect: Rect,
-  imageWidth: number,
-  imageHeight: number,
-  imageX: number,
-  imageY: number,
-): Point | null {
-  if (
-    !Number.isFinite(imageX) ||
-    !Number.isFinite(imageY) ||
-    !Number.isSafeInteger(imageWidth) ||
-    !Number.isSafeInteger(imageHeight) ||
-    imageWidth <= 0 ||
-    imageHeight <= 0 ||
-    imageX < 0 ||
-    imageY < 0 ||
-    imageX >= imageWidth ||
-    imageY >= imageHeight ||
-    !Number.isFinite(rect.x) ||
-    !Number.isFinite(rect.y) ||
-    !Number.isFinite(rect.w) ||
-    !Number.isFinite(rect.h) ||
-    rect.w <= 0 ||
-    rect.h <= 0
-  ) {
-    return null;
-  }
-  return {
-    x: rect.x + (imageX / imageWidth) * rect.w,
-    y: rect.y + (imageY / imageHeight) * rect.h,
-  };
-}
-
-function pointInPolygon(point: Point, polygon: Point[]): boolean {
-  for (let index = 0; index < polygon.length; index += 1) {
-    const a = polygon[index];
-    const b = polygon[(index + 1) % polygon.length];
-    const cross = (point.x - a.x) * (b.y - a.y) - (point.y - a.y) * (b.x - a.x);
-    const withinX = point.x >= Math.min(a.x, b.x) - 1e-9 && point.x <= Math.max(a.x, b.x) + 1e-9;
-    const withinY = point.y >= Math.min(a.y, b.y) - 1e-9 && point.y <= Math.max(a.y, b.y) + 1e-9;
-    if (Math.abs(cross) <= 1e-9 && withinX && withinY) return true;
-  }
-  let inside = false;
-  for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index++) {
-    const a = polygon[index];
-    const b = polygon[previous];
-    const intersects =
-      a.y > point.y !== b.y > point.y &&
-      point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x;
-    if (intersects) inside = !inside;
-  }
-  return inside;
-}
-
-export function pointInRegion(point: Point, region: Region): boolean {
-  return region.some((polygon) => polygon.length >= 3 && pointInPolygon(point, polygon));
-}

apps/extension/src/tools/surface-target.ts

@@ -1,260 +0,0 @@
-import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
-import type { SessionContext } from "@/session-manager/manager";
-import type { RpcError } from "@/transport/types";
-import { rpcError } from "./errors";
-import { resolveNodeGeometry } from "./frame-geometry";
-import { type CdpRunner, isRpcError, normaliseRef } from "./shared";
-import { resolveSnapshotRef } from "./snapshot-ref";
-import {
-  mapImagePointToViewport,
-  pointInRegion,
-  sameRect,
-  surfaceVisibleRect,
-} from "./surface-coordinate";
-
-export interface SurfaceCaptureEnvironment {
-  navigationIdentity: string;
-  viewportSignature: string;
-  frameProjectionSignature: string;
-}
-
-export interface SurfaceTargetResolverDeps {
-  cdp: CdpRunner;
-  signal?: AbortSignal;
-}
-
-export interface SurfacePointerTargetInput {
-  ref?: string;
-  selector?: string;
-  captureId?: string;
-  imageX?: number;
-  imageY?: number;
-}
-
-export interface ResolvedSurfacePointerTarget {
-  point: { x: number; y: number };
-  usedRef: string;
-  moveSettleMs: number;
-  capture: {
-    id: string;
-    imageX: number;
-    imageY: number;
-  };
-}
-
-// Canvas-style controls commonly update their pointer hit-test on the next
-// animation frame. Leave a scheduling boundary after moving and before pressing.
-export const SURFACE_POINTER_MOVE_SETTLE_MS = 32;
-
-function stale(message: string): RpcError {
-  return rpcError("permission_denied", "surface_capture_stale", message);
-}
-
-function finiteObject(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(finiteObject);
-  if (typeof value !== "object" || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value)
-      .filter(
-        ([, entry]) => entry !== undefined && (typeof entry !== "number" || Number.isFinite(entry)),
-      )
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([key, entry]) => [key, finiteObject(entry)]),
-  );
-}
-
-function framePathSignature(graph: CdpFrameGraph, frameId: string | undefined): string | null {
-  if (!frameId) return "top";
-  const frames = new Map(graph.frames.map((frame) => [frame.frameId, frame]));
-  const path: Array<{
-    frameId: string;
-    parentFrameId?: string;
-    ownerBackendNodeId?: number;
-    targetSessionId?: string;
-  }> = [];
-  const seen = new Set<string>();
-  let current = frames.get(frameId);
-  while (current) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    path.push({
-      frameId: current.frameId,
-      ...(current.parentFrameId ? { parentFrameId: current.parentFrameId } : {}),
-      ...(current.ownerBackendNodeId !== undefined
-        ? { ownerBackendNodeId: current.ownerBackendNodeId }
-        : {}),
-      ...(current.target.sessionId ? { targetSessionId: current.target.sessionId } : {}),
-    });
-    if (!current.parentFrameId) return JSON.stringify(path);
-    const parent = frames.get(current.parentFrameId);
-    if (!parent) return null;
-    current = parent;
-  }
-  return null;
-}
-
-export async function captureSurfaceEnvironment(
-  cdp: CdpRunner,
-  tabId: number,
-  frameId: string | undefined,
-): Promise<SurfaceCaptureEnvironment | RpcError> {
-  try {
-    const [tree, metrics, graph] = await Promise.all([
-      cdp.send<{
-        frameTree?: { frame?: { id?: string; loaderId?: string; url?: string } };
-      }>(tabId, "Page.getFrameTree", {}),
-      cdp.send<Record<string, unknown>>(tabId, "Page.getLayoutMetrics", {}),
-      frameId && cdp.getFrameGraph ? cdp.getFrameGraph(tabId) : Promise.resolve(null),
-    ]);
-    const root = tree.frameTree?.frame;
-    if (!root?.id || !root.loaderId) {
-      return { code: "cdp_failed", message: "could not identify the current navigation" };
-    }
-    const frameProjectionSignature = frameId
-      ? graph
-        ? framePathSignature(graph, frameId)
-        : null
-      : "top";
-    if (!frameProjectionSignature) {
-      return { code: "cdp_failed", message: `could not identify frame projection for ${frameId}` };
-    }
-    return {
-      navigationIdentity: JSON.stringify({ id: root.id, loaderId: root.loaderId, url: root.url }),
-      viewportSignature: JSON.stringify(
-        finiteObject({
-          cssLayoutViewport: metrics.cssLayoutViewport,
-          cssVisualViewport: metrics.cssVisualViewport,
-        }),
-      ),
-      frameProjectionSignature,
-    };
-  } catch (error) {
-    return { code: "cdp_failed", message: error instanceof Error ? error.message : String(error) };
-  }
-}
-
-function validatePointParams(input: SurfacePointerTargetInput): RpcError | null {
-  if (!input.captureId || typeof input.captureId !== "string") {
-    return { code: "invalid_params", message: "surface point click requires capture_id" };
-  }
-  if (typeof input.imageX !== "number" || !Number.isFinite(input.imageX)) {
-    return { code: "invalid_params", message: "image_x must be a finite number" };
-  }
-  if (typeof input.imageY !== "number" || !Number.isFinite(input.imageY)) {
-    return { code: "invalid_params", message: "image_y must be a finite number" };
-  }
-  if (!input.ref || input.selector) {
-    return {
-      code: "invalid_params",
-      message: "surface point click requires one Surface ref and does not accept a selector",
-    };
-  }
-  return null;
-}
-
-function captureConsumeError(reason: "not_found" | "expired" | "consumed"): RpcError {
-  const code = reason === "not_found" ? "not_found" : "permission_denied";
-  return rpcError(code, `surface_capture_${reason}`, `surface capture is ${reason}`);
-}
-
-function aborted(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted
-    ? { code: "cancelled", message: "surface target resolution aborted" }
-    : null;
-}
-
-/** Resolve one fresh Surface capture coordinate into a validated top-viewport pointer target. */
-export async function resolveSurfacePointerTarget(
-  ctx: SessionContext,
-  target: { tabId: number; url?: string },
-  input: SurfacePointerTargetInput,
-  deps: SurfaceTargetResolverDeps,
-): Promise<ResolvedSurfacePointerTarget | RpcError> {
-  const invalid = validatePointParams(input);
-  if (invalid) return invalid;
-  const earlyAbort = aborted(deps.signal);
-  if (earlyAbort) return earlyAbort;
-
-  const consumed = ctx.surfaceCaptures.consume(input.captureId as string);
-  if (!consumed.ok) return captureConsumeError(consumed.reason);
-  const capture = consumed.capture;
-  const postConsumeAbort = aborted(deps.signal);
-  if (postConsumeAbort) return postConsumeAbort;
-
-  if (capture.sessionId !== ctx.sessionId || capture.tabId !== target.tabId) {
-    return stale("surface capture belongs to a different session or tab");
-  }
-  if (normaliseRef(input.ref as string) !== capture.surface.ref) {
-    return stale("surface ref does not match the capture");
-  }
-  const node = resolveSnapshotRef(ctx, input.ref as string, target.tabId, "screenshot");
-  if (isRpcError(node)) return stale(node.message);
-  if (
-    node.kind !== "surface" ||
-    node.backendNodeId !== capture.surface.backendNodeId ||
-    node.frameId !== capture.surface.frameId ||
-    node.generation !== capture.surface.observationGeneration
-  ) {
-    return stale("surface observation generation or node identity changed");
-  }
-
-  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  try {
-    await deps.cdp.ensureAttachedToUrl?.(target.tabId, target.url);
-  } catch (error) {
-    return { code: "cdp_failed", message: error instanceof Error ? error.message : String(error) };
-  }
-  const environment = await captureSurfaceEnvironment(deps.cdp, target.tabId, node.frameId);
-  if (isRpcError(environment)) return environment;
-  if (
-    environment.navigationIdentity !== capture.navigationIdentity ||
-    environment.viewportSignature !== capture.viewportSignature ||
-    environment.frameProjectionSignature !== capture.frameProjectionSignature
-  ) {
-    return stale("navigation, viewport, zoom, scroll, or frame projection changed");
-  }
-
-  const geometry = await resolveNodeGeometry(
-    deps.cdp,
-    target.tabId,
-    {
-      target: {
-        tabId: target.tabId,
-        ...(node.cdpSessionId ? { sessionId: node.cdpSessionId } : {}),
-      },
-      backendNodeId: node.backendNodeId,
-      ...(node.frameId ? { frameId: node.frameId } : {}),
-    },
-    { scrollIntoView: false },
-  );
-  if (isRpcError(geometry)) return stale(geometry.message);
-  const currentRect = surfaceVisibleRect(geometry.topBounds, node.visibleRect);
-  if (!currentRect || !sameRect(currentRect, capture.topViewportRect)) {
-    return stale("surface visible region changed");
-  }
-  const point = mapImagePointToViewport(
-    capture.topViewportRect,
-    capture.imageWidth,
-    capture.imageHeight,
-    input.imageX as number,
-    input.imageY as number,
-  );
-  if (!point || !pointInRegion(point, geometry.topVisibleRegions)) {
-    return rpcError(
-      "invalid_params",
-      "surface_coordinate_invalid",
-      "image coordinate is outside the captured Surface",
-    );
-  }
-
-  return {
-    point,
-    usedRef: capture.surface.ref,
-    moveSettleMs: SURFACE_POINTER_MOVE_SETTLE_MS,
-    capture: {
-      id: capture.id,
-      imageX: input.imageX as number,
-      imageY: input.imageY as number,
-    },
-  };
-}

apps/extension/src/tools/text-input.ts

@@ -1,194 +0,0 @@
-// Browser-native text entry for live editing sessions. Unlike fill, this
-// module does not assume that the focused editable retains a DOM value: a
-// Canvas editor may use an input/textarea only as a transient keyboard/IME
-// sink and clear it after consuming each event.
-
-import type { RpcError } from "@/transport/types";
-import type { CdpRunner } from "./shared";
-
-function cancelled(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted ? { code: "cancelled", message: "type aborted" } : null;
-}
-
-interface KeyDescriptor {
-  key: string;
-  code: string;
-  windowsVirtualKeyCode: number;
-  nativeVirtualKeyCode?: number;
-  modifiers: number;
-}
-
-function asciiKeyDescriptor(character: string): KeyDescriptor {
-  if (/^[a-z]$/.test(character)) {
-    return {
-      key: character,
-      code: `Key${character.toUpperCase()}`,
-      windowsVirtualKeyCode: character.toUpperCase().charCodeAt(0),
-      modifiers: 0,
-    };
-  }
-  if (/^[A-Z]$/.test(character)) {
-    return {
-      key: character,
-      code: `Key${character}`,
-      windowsVirtualKeyCode: character.charCodeAt(0),
-      modifiers: 8,
-    };
-  }
-  if (/^[0-9]$/.test(character)) {
-    return {
-      key: character,
-      code: `Digit${character}`,
-      windowsVirtualKeyCode: character.charCodeAt(0),
-      modifiers: 0,
-    };
-  }
-  if (character === " ") {
-    return { key: " ", code: "Space", windowsVirtualKeyCode: 32, modifiers: 0 };
-  }
-  return {
-    key: character,
-    code: "",
-    windowsVirtualKeyCode: character.charCodeAt(0),
-    modifiers: 0,
-  };
-}
-
-/**
- * Run one complete browser key transaction and always release the key. The
- * commit callback owns the text-producing phase: a `char` event for a
- * keyboard character, or `Input.insertText` for committed IME text.
- */
-async function dispatchKeyTransaction(
-  cdp: CdpRunner,
-  tabId: number,
-  descriptor: KeyDescriptor,
-  commit: () => Promise<void>,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  let keyDown = false;
-  try {
-    await cdp.send(tabId, "Input.dispatchKeyEvent", {
-      type: "rawKeyDown",
-      ...descriptor,
-    });
-    keyDown = true;
-    const abortedAfterDown = cancelled(signal);
-    if (!abortedAfterDown) await commit();
-    await cdp.send(tabId, "Input.dispatchKeyEvent", {
-      type: "keyUp",
-      ...descriptor,
-    });
-    keyDown = false;
-    return abortedAfterDown ?? cancelled(signal);
-  } catch (err) {
-    if (keyDown) {
-      try {
-        await cdp.send(tabId, "Input.dispatchKeyEvent", {
-          type: "keyUp",
-          ...descriptor,
-        });
-      } catch {
-        // Best-effort cleanup keeps the page from observing a stuck key.
-      }
-    }
-    throw err;
-  }
-}
-
-async function typeAsciiCharacter(
-  cdp: CdpRunner,
-  tabId: number,
-  character: string,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  const descriptor = asciiKeyDescriptor(character);
-  return dispatchKeyTransaction(
-    cdp,
-    tabId,
-    descriptor,
-    async () => {
-      await cdp.send(tabId, "Input.dispatchKeyEvent", {
-        type: "char",
-        ...descriptor,
-        text: character,
-        unmodifiedText: character,
-      });
-    },
-    signal,
-  );
-}
-
-async function typeImeSegment(
-  cdp: CdpRunner,
-  tabId: number,
-  text: string,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  const abortedBefore = cancelled(signal);
-  if (abortedBefore) return abortedBefore;
-
-  // A committed IME value is still part of a keyboard transaction. The
-  // Process key (VK_PROCESSKEY / 229) is the platform-neutral signal that an
-  // IME owns the keystroke. It lets selection-based editors enter text mode
-  // before insertText commits the Unicode value, without inventing a visible
-  // ASCII prefix or leaving a composition transaction open.
-  const processKey: KeyDescriptor = {
-    key: "Process",
-    code: "",
-    windowsVirtualKeyCode: 229,
-    nativeVirtualKeyCode: 229,
-    modifiers: 0,
-  };
-  return dispatchKeyTransaction(
-    cdp,
-    tabId,
-    processKey,
-    () => cdp.send(tabId, "Input.insertText", { text }).then(() => undefined),
-    signal,
-  );
-}
-
-/**
- * Dispatch text through the browser's keyboard/IME pipelines. ASCII runs are
- * delivered as physical-key-shaped events; non-ASCII runs use CDP's committed
- * IME/software-keyboard insertion path. Successful return means the browser
- * accepted the input commands, not that a DOM value retained the text.
- */
-export async function dispatchTextInput(
-  cdp: CdpRunner,
-  tabId: number,
-  text: string,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  const abortedBefore = cancelled(signal);
-  if (abortedBefore) return abortedBefore;
-
-  const segments: Array<{ ime: boolean; text: string }> = [];
-  for (const character of text) {
-    const ime = character.codePointAt(0)! > 0x7f;
-    const previous = segments.at(-1);
-    if (previous?.ime === ime) previous.text += character;
-    else segments.push({ ime, text: character });
-  }
-
-  try {
-    for (const segment of segments) {
-      if (segment.ime) {
-        const error = await typeImeSegment(cdp, tabId, segment.text, signal);
-        if (error) return error;
-        continue;
-      }
-      for (const character of segment.text) {
-        const error = await typeAsciiCharacter(cdp, tabId, character, signal);
-        if (error) return error;
-      }
-    }
-    return null;
-  } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
-  }
-}

apps/extension/src/tools/upload.ts

@@ -0,0 +1,59 @@
+// Upload orchestration: validate the session-scoped request, resolve its click
+// target, then delegate the browser protocol transaction to the file-input
+// transaction module.
+
+import type { SessionManager } from "@/session-manager/manager";
+import type { RpcError, UploadParams, UploadResult } from "@/transport/types";
+import { uploadThroughActivatedFileInput } from "./file-input-transaction";
+import { clickResolvedTarget, type InteractionDeps, resolveActionTarget } from "./interaction";
+import {
+  type CdpRunner,
+  enforceAgentWindow,
+  isRpcError,
+  lookupSession,
+  resolveTargetTab,
+} from "./shared";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface UploadDeps extends InteractionDeps {
+  cdp: CdpRunner;
+}
+
+export async function handleUpload(
+  manager: SessionManager,
+  params: UploadParams,
+  deps: UploadDeps,
+): Promise<UploadResult | RpcError> {
+  const ctx = lookupSession(manager, params, "upload");
+  if (isRpcError(ctx)) return ctx;
+  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
+  if (isRpcError(target)) return target;
+  const denied = enforceAgentWindow(ctx, target, "upload");
+  if (denied) return denied;
+  if (
+    params.files.length === 0 ||
+    params.files.length > 20 ||
+    params.files.some((file) => !file.staged_path)
+  ) {
+    return { code: "invalid_params", message: "upload requires daemon-staged files" };
+  }
+  const address = await resolveActionTarget(deps.cdp, ctx, target, params, "upload");
+  if (isRpcError(address)) return address;
+  const timeoutMs = params.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+  const transaction = await uploadThroughActivatedFileInput({
+    cdp: deps.cdp,
+    actionTarget: address,
+    files: params.files.map((file) => file.staged_path as string),
+    timeoutMs,
+    signal: deps.signal,
+    trigger: () => clickResolvedTarget(ctx, address, {}, deps),
+  });
+  if (isRpcError(transaction)) return transaction;
+  return {
+    tab_id: target.tabId,
+    used_ref: transaction.click.used_ref,
+    used_selector: transaction.click.used_selector,
+    file_names: params.files.map((file) => file.name),
+  };
+}

apps/extension/src/tools/vom/__tests__/capture.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
-import { captureViewModel, collectOverlayExcludedBackendIds } from "../capture";
+import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
+import { discoverRenderedSurfaces } from "../rendered-surfaces";
 
 // Minimal but format-accurate captureSnapshot reply: a body with one
 // fixed full-screen overlay div carrying a password input.
@@ -251,11 +252,10 @@ describe("captureViewModel", () => {
     expect(input?.attrs).toEqual({ type: "password" });
   });
 
-  it("does not run conditional surface probes by default", async () => {
+  it("never hovers the page while capturing", async () => {
     const cdp = makeCdp(fakeSnapshotReply());
-    const result = await captureViewModel(cdp, 4);
+    await captureViewModel(cdp, 4);
 
-    expect(result.surfaceProbes).toEqual([]);
     expect(cdp.send).not.toHaveBeenCalledWith(4, "Input.dispatchMouseEvent", expect.anything());
   });
 
@@ -319,9 +319,10 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const result = await captureViewModel(cdp, 4, { conditionalSurfaceProbe: true });
+    const captured = await captureViewModel(cdp, 4);
+    const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
-    expect(result.surfaceProbes).toEqual([
+    expect(surfaceProbes).toEqual([
       {
         triggerBackendNodeId: 12,
         triggerPoint: { x: 956, y: 32 },
@@ -378,9 +379,10 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const result = await captureViewModel(cdp, 4, { conditionalSurfaceProbe: true });
+    const captured = await captureViewModel(cdp, 4);
+    const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
-    expect(result.surfaceProbes).toEqual([
+    expect(surfaceProbes).toEqual([
       expect.objectContaining({
         triggerBackendNodeId: 12,
         subItems: ["My profile", "Sign out"],
@@ -422,7 +424,8 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    await captureViewModel(cdp, 4, { conditionalSurfaceProbe: true });
+    const captured = await captureViewModel(cdp, 4);
+    await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(hoverMoves).toBe(1);
   });
@@ -1175,6 +1178,97 @@ describe("captureViewModel", () => {
     expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
   });
 
+  it("keeps same-origin iframe canvas discovery in top-level CSS coordinates at dpr 1 and 2", async () => {
+    const captureAtDpr = async (dpr: number) => {
+      const S = ["html", "body", "iframe", "canvas", "static", "auto"];
+      const i = (s: string) => S.indexOf(s);
+      const scale = (values: number[]) => values.map((value) => value * dpr);
+      const snapshot = {
+        strings: S,
+        documents: [
+          {
+            frameId: "main",
+            nodes: {
+              parentIndex: [-1, 0, 1],
+              nodeName: [i("html"), i("body"), i("iframe")],
+              backendNodeId: [10, 11, 13],
+              attributes: [[], [], []],
+              contentDocumentIndex: { index: [2], value: [1] },
+            },
+            layout: {
+              nodeIndex: [1, 2],
+              styles: [
+                [i("static"), i("auto")],
+                [i("static"), i("auto")],
+              ],
+              bounds: [scale([0, 0, 1000, 800]), scale([100, 150, 300, 200])],
+              paintOrders: [0, 1],
+            },
+          },
+          {
+            frameId: "child",
+            nodes: {
+              parentIndex: [-1, 0],
+              nodeName: [i("body"), i("canvas")],
+              backendNodeId: [20, 21],
+              attributes: [[], []],
+            },
+            layout: {
+              nodeIndex: [0, 1],
+              styles: [
+                [i("static"), i("auto")],
+                [i("static"), i("auto")],
+              ],
+              bounds: [scale([0, 0, 300, 200]), scale([20, 30, 120, 60])],
+              paintOrders: [0, 1],
+            },
+          },
+        ],
+      };
+      const cdp = {
+        send: vi.fn(async (_tabId: number, method: string) => {
+          if (method === "DOMSnapshot.enable") return {};
+          if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+          if (method === "Page.getLayoutMetrics") {
+            return {
+              cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+              layoutViewport: { clientWidth: 1000 * dpr, clientHeight: 800 * dpr },
+            };
+          }
+          throw new Error(method);
+        }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
+      };
+      const captured = await captureViewModel(cdp, 4);
+      const childNodes = captured.frameNodes?.get("child") ?? [];
+      return discoverRenderedSurfaces(
+        [
+          {
+            frameId: "child",
+            contextScopeId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 13,
+            target: { tabId: 4 },
+            domNodes: childNodes,
+            axNodes: [],
+          },
+        ],
+        captured.viewport,
+      );
+    };
+
+    const atDpr1 = await captureAtDpr(1);
+    const atDpr2 = await captureAtDpr(2);
+
+    expect(atDpr1).toEqual([
+      expect.objectContaining({
+        backendNodeId: 21,
+        frameId: "child",
+        visibleRect: { x: 120, y: 180, w: 120, h: 60 },
+      }),
+    ]);
+    expect(atDpr2).toEqual(atDpr1);
+  });
+
   it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);

apps/extension/src/tools/vom/__tests__/hover-perception.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ProbeBudget, resetOverlayBypassDepth, withOverlayBypass } from "../hover-perception";
+
+afterEach(() => {
+  resetOverlayBypassDepth();
+});
+
+describe("ProbeBudget", () => {
+  it("refuses a candidate that cannot finish inside the budget", () => {
+    const budget = new ProbeBudget(500);
+
+    expect(budget.canAfford(400)).toBe(true);
+    expect(budget.canAfford(600)).toBe(false);
+  });
+
+  it("stops admitting candidates once the remaining budget is smaller than one", async () => {
+    const budget = new ProbeBudget(60);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    // A top-of-loop `elapsed > total` check would still admit this candidate
+    // and then overshoot by its full cost.
+    expect(budget.canAfford(50)).toBe(false);
+  });
+});
+
+describe("withOverlayBypass", () => {
+  it("toggles the overlay once around nested probe phases", async () => {
+    const bypass = vi.fn(async () => {});
+
+    await withOverlayBypass(bypass, 4, async () => {
+      await withOverlayBypass(bypass, 4, async () => {
+        expect(bypass).toHaveBeenCalledTimes(1);
+      });
+      expect(bypass).toHaveBeenCalledTimes(1);
+    });
+
+    expect(bypass.mock.calls).toEqual([
+      [4, true],
+      [4, false],
+    ]);
+  });
+
+  it("restores the overlay when the probe throws", async () => {
+    const bypass = vi.fn(async () => {});
+
+    await expect(
+      withOverlayBypass(bypass, 4, async () => {
+        throw new Error("probe exploded");
+      }),
+    ).rejects.toThrow("probe exploded");
+
+    expect(bypass).toHaveBeenLastCalledWith(4, false);
+  });
+
+  it("reports a failed restore instead of swallowing it", async () => {
+    const onRestoreFailure = vi.fn();
+    const bypass = vi.fn(async (_tabId: number, enabled: boolean) => {
+      if (!enabled) throw new Error("tab is gone");
+    });
+
+    await withOverlayBypass(bypass, 4, async () => undefined, { onRestoreFailure });
+
+    expect(onRestoreFailure).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not pin the overlay off for the tab when a restore fails", async () => {
+    const failing = vi.fn(async (_tabId: number, enabled: boolean) => {
+      if (!enabled) throw new Error("tab is gone");
+    });
+    await withOverlayBypass(failing, 4, async () => undefined, { onRestoreFailure: () => {} });
+
+    const bypass = vi.fn(async () => {});
+    await withOverlayBypass(bypass, 4, async () => undefined);
+
+    expect(bypass.mock.calls).toEqual([
+      [4, true],
+      [4, false],
+    ]);
+  });
+
+  it("runs the probe untouched when no bypass is wired up", async () => {
+    await expect(withOverlayBypass(undefined, 4, async () => "done")).resolves.toBe("done");
+  });
+});

apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts

@@ -132,6 +132,37 @@ describe("tooltip name enrichment", () => {
     expect(cdp.sendToTarget).not.toHaveBeenCalled();
   });
 
+  it("remembers controls that revealed no tooltip so the miss is paid once", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 31 };
+        if (method === "DOM.resolveNode") return { object: { objectId: "button-801" } };
+        if (method === "Runtime.callFunctionOn") return { result: { value: [] } };
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [
+      document({ tabId: 11, sessionId: "miss-session" }, 801, undefined, "miss-frame"),
+    ];
+    const graph = semantics(documents);
+
+    const first = await probeTooltipNames(cdp, 11, documents, graph);
+    expect(first.size).toBe(0);
+    const hoversAfterFirst = vi
+      .mocked(cdp.send)
+      .mock.calls.filter(([, method]) => method === "Input.dispatchMouseEvent").length;
+    expect(hoversAfterFirst).toBeGreaterThan(0);
+
+    const second = await probeTooltipNames(cdp, 11, documents, graph);
+    expect(second.size).toBe(0);
+    expect(
+      vi.mocked(cdp.send).mock.calls.filter(([, method]) => method === "Input.dispatchMouseEvent")
+        .length,
+    ).toBe(hoversAfterFirst);
+  });
+
   it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
     let hoveredX = -10;
     const cdp: CdpRunner = {

apps/extension/src/tools/vom/capture.ts

@@ -9,7 +9,7 @@ import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
 import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
 import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
 import type { CdpRunner } from "../shared";
-import { clearHover, waitForHover } from "./hover-perception";
+import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
 
 const REQUESTED_STYLES = [
   "position",
@@ -83,14 +83,11 @@ export interface CapturedViewModel {
   /** Explicit DOMSnapshot frame ancestry; never inferred from backend node ids. */
   frameParentIds?: Map<string, string>;
   rootFrameId?: string;
-  surfaceProbes?: CapturedSurfaceProbe[];
   /** Backend node ids belonging to the agent overlay host + its shadow subtree. */
   excludedBackendNodeIds: Set<number>;
 }
 
 export interface CaptureViewModelOptions {
-  conditionalSurfaceProbe?: boolean;
-  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
   signal?: AbortSignal;
 }
 
@@ -380,7 +377,16 @@ function collectBackendIdsFromDomNode(node: CdpDomNode | undefined, out: Set<num
   }
 }
 
-const MAX_HOVER_PROBE_MS = 2_000;
+/**
+ * Ceiling for the whole hover-surface phase.
+ *
+ * The previous 2000 was only a floor: the loop checked elapsed time at the top,
+ * so a candidate could start with 1ms left and still run its two settle
+ * windows, pushing real cost to ~2.6s. This is that true ceiling, now actually
+ * enforced by an up-front affordability check, so the same number of candidates
+ * get probed under a bound that no longer lies.
+ */
+const MAX_HOVER_PROBE_MS = 2_600;
 const MAX_HOVER_TRIGGERS = 6;
 const MAX_HOVER_SURFACES = 3;
 const HOVER_SETTLE_MS = 300;
@@ -626,13 +632,35 @@ function confidenceForHover(
   return "low";
 }
 
-async function probeHoverSurfaces(
+/**
+ * One candidate costs two settle windows (baseline + post-hover) plus a few
+ * CDP round trips. Used to decide whether the next candidate still fits the
+ * budget before paying for it.
+ */
+const HOVER_CANDIDATE_COST_MS = HOVER_SETTLE_MS * 2;
+
+export interface HoverSurfaceProbeOptions {
+  signal?: AbortSignal;
+}
+
+/**
+ * Hovers a bounded set of likely menu triggers and reports the sub-items each
+ * one reveals.
+ *
+ * Runs after DOM *and* accessibility capture. Hovering can open menus and
+ * change layout, so probing between the two captures would leave the DOM half
+ * of an observation describing the page before the change and the AX half
+ * describing it after.
+ *
+ * The caller owns the overlay bypass span (see `withOverlayBypass`).
+ */
+export async function probeHoverSurfaces(
   cdp: CdpRunner,
   tabId: number,
   nodes: CapturedNode[],
-  options: CaptureViewModelOptions,
+  options: HoverSurfaceProbeOptions = {},
 ): Promise<CapturedSurfaceProbe[]> {
-  const started = Date.now();
+  const budget = new ProbeBudget(MAX_HOVER_PROBE_MS);
   try {
     throwIfAborted(options.signal);
     const cssScan = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
@@ -647,60 +675,54 @@ async function probeHoverSurfaces(
     const results: CapturedSurfaceProbe[] = [];
     const seen = new Set<number>();
     throwIfAborted(options.signal);
-    await options.hoverProbeBypassOverlay?.(tabId, true).catch(() => undefined);
-    try {
+    for (const candidate of candidates.slice(0, MAX_HOVER_TRIGGERS)) {
       throwIfAborted(options.signal);
-      for (const candidate of candidates.slice(0, MAX_HOVER_TRIGGERS)) {
+      if (!budget.canAfford(HOVER_CANDIDATE_COST_MS)) break;
+      if (results.length >= MAX_HOVER_SURFACES) break;
+      if (seen.has(candidate.backendNodeId)) continue;
+      try {
+        await clearHover(cdp, tabId);
         throwIfAborted(options.signal);
-        if (Date.now() - started > MAX_HOVER_PROBE_MS) break;
-        if (results.length >= MAX_HOVER_SURFACES) break;
-        if (seen.has(candidate.backendNodeId)) continue;
-        try {
-          await clearHover(cdp, tabId);
-          throwIfAborted(options.signal);
-          await waitForHover(HOVER_SETTLE_MS, options.signal);
-          const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
-            expression: hoverStateExpression(),
-            returnByValue: true,
-          });
-          throwIfAborted(options.signal);
-          const baselineItems = runtimeValue<HoverRuntimeItem[]>(baselineReply) ?? [];
+        await waitForHover(HOVER_SETTLE_MS, options.signal);
+        const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
+          expression: hoverStateExpression(),
+          returnByValue: true,
+        });
+        throwIfAborted(options.signal);
+        const baselineItems = runtimeValue<HoverRuntimeItem[]>(baselineReply) ?? [];
 
-          throwIfAborted(options.signal);
-          await cdp.send(tabId, "Input.dispatchMouseEvent", {
-            type: "mouseMoved",
-            x: candidate.x,
-            y: candidate.y,
-          });
-          throwIfAborted(options.signal);
-          await waitForHover(HOVER_SETTLE_MS, options.signal);
-          const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
-            expression: hoverStateExpression(),
-            returnByValue: true,
-          });
-          throwIfAborted(options.signal);
-          const subItems = diffHoverItems(
-            baselineItems,
-            runtimeValue<HoverRuntimeItem[]>(collected) ?? [],
-          );
-          if (subItems.length === 0) continue;
-          seen.add(candidate.backendNodeId);
-          results.push({
-            triggerBackendNodeId: candidate.backendNodeId,
-            triggerPoint: { x: candidate.x, y: candidate.y },
-            triggerAction: "hover",
-            subItems,
-            confidence: confidenceForHover(candidate, subItems),
-          });
-        } catch (error) {
-          if (isAbortError(error)) throw error;
-          continue;
-        } finally {
-          await clearHover(cdp, tabId);
-        }
+        throwIfAborted(options.signal);
+        await cdp.send(tabId, "Input.dispatchMouseEvent", {
+          type: "mouseMoved",
+          x: candidate.x,
+          y: candidate.y,
+        });
+        throwIfAborted(options.signal);
+        await waitForHover(HOVER_SETTLE_MS, options.signal);
+        const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
+          expression: hoverStateExpression(),
+          returnByValue: true,
+        });
+        throwIfAborted(options.signal);
+        const subItems = diffHoverItems(
+          baselineItems,
+          runtimeValue<HoverRuntimeItem[]>(collected) ?? [],
+        );
+        if (subItems.length === 0) continue;
+        seen.add(candidate.backendNodeId);
+        results.push({
+          triggerBackendNodeId: candidate.backendNodeId,
+          triggerPoint: { x: candidate.x, y: candidate.y },
+          triggerAction: "hover",
+          subItems,
+          confidence: confidenceForHover(candidate, subItems),
+        });
+      } catch (error) {
+        if (isAbortError(error)) throw error;
+        continue;
+      } finally {
+        await clearHover(cdp, tabId);
       }
-    } finally {
-      await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
     }
     return results;
   } catch (err) {
@@ -1071,7 +1093,6 @@ export async function captureViewModel(
       nodes: [],
       viewport,
       iframeNodes: new Map(),
-      surfaceProbes: [],
       excludedBackendNodeIds: new Set(),
     };
   }
@@ -1100,11 +1121,6 @@ export async function captureViewModel(
   await enrichFormControlStates(cdp, tabId, [nodes, ...iframeNodes.values()], options.signal);
   throwIfAborted(options.signal);
 
-  const surfaceProbes = options.conditionalSurfaceProbe
-    ? await probeHoverSurfaces(cdp, tabId, nodes, options)
-    : [];
-  throwIfAborted(options.signal);
-
   const frameNodes = new Map<string, CapturedNode[]>();
   if (topContext.frameId) frameNodes.set(topContext.frameId, nodes);
   for (const iframeFrameNodes of iframeNodes.values()) {
@@ -1125,7 +1141,6 @@ export async function captureViewModel(
     frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
     frameParentIds: frameParsed.frameParentIds,
     ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
-    surfaceProbes,
     excludedBackendNodeIds,
   };
 }

apps/extension/src/tools/vom/hover-perception.ts

@@ -35,3 +35,91 @@ export async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
       }),
     );
 }
+
+/**
+ * Wall-clock budget for a probe phase.
+ *
+ * Callers ask whether the *next* candidate still fits before starting it,
+ * rather than checking elapsed time at the top of the loop. A top-of-loop
+ * check lets a candidate start with 1ms of budget left and then run to
+ * completion, overshooting by a full settle window.
+ */
+export class ProbeBudget {
+  private readonly startedAt = Date.now();
+
+  constructor(private readonly totalMs: number) {}
+
+  get elapsedMs(): number {
+    return Date.now() - this.startedAt;
+  }
+
+  /** True when a candidate costing `estimatedMs` still fits in the budget. */
+  canAfford(estimatedMs: number): boolean {
+    return this.elapsedMs + estimatedMs <= this.totalMs;
+  }
+}
+
+export type OverlayBypass = (tabId: number, enabled: boolean) => Promise<void>;
+
+export interface OverlayBypassScopeOptions {
+  /**
+   * Called when the overlay could not be restored. Defaults to `console.error`
+   * so a stuck-bypassed overlay is never silent; tests inject a spy.
+   */
+  onRestoreFailure?: (error: unknown) => void;
+}
+
+const overlayBypassDepth = new Map<number, number>();
+
+/**
+ * Runs `body` with the agent overlay bypassed, restoring it afterwards.
+ *
+ * Reference counted per tab so nested probe phases share a single bypass span
+ * instead of toggling the overlay once per phase. Restore failures are
+ * reported rather than swallowed, and the depth is released even when restore
+ * throws so a failure cannot pin the overlay off for the tab's lifetime.
+ */
+export async function withOverlayBypass<T>(
+  bypass: OverlayBypass | undefined,
+  tabId: number,
+  body: () => Promise<T>,
+  options: OverlayBypassScopeOptions = {},
+): Promise<T> {
+  if (!bypass) return body();
+
+  const depth = overlayBypassDepth.get(tabId) ?? 0;
+  overlayBypassDepth.set(tabId, depth + 1);
+  if (depth === 0) {
+    try {
+      await bypass(tabId, true);
+    } catch (error) {
+      // Failing to hide the overlay only risks probing our own UI, so continue.
+      console.debug("[bsk hover] overlay bypass could not be enabled", error);
+    }
+  }
+
+  try {
+    return await body();
+  } finally {
+    const current = overlayBypassDepth.get(tabId) ?? 1;
+    if (current <= 1) {
+      overlayBypassDepth.delete(tabId);
+      try {
+        await bypass(tabId, false);
+      } catch (error) {
+        (options.onRestoreFailure ?? defaultRestoreFailure)(error);
+      }
+    } else {
+      overlayBypassDepth.set(tabId, current - 1);
+    }
+  }
+}
+
+function defaultRestoreFailure(error: unknown): void {
+  console.error("[bsk hover] agent overlay could not be restored after probing", error);
+}
+
+/** Test seam: drops any bypass depth left behind by a crashed probe. */
+export function resetOverlayBypassDepth(): void {
+  overlayBypassDepth.clear();
+}

apps/extension/src/tools/vom/name-enrichment.ts

@@ -1,7 +1,7 @@
 import { isVomReferenceNode } from "@browser-skill/vom";
 import { type CdpRunner, sendToCdpTarget } from "../shared";
 import type { FrameDocument, FrameOwnedAxNode } from "./frame-document";
-import { clearHover, waitForHover } from "./hover-perception";
+import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
 import { stableIdentifierName } from "./semantic-graph/name-evidence";
 import { frameBackendKey, type ResolvedSemanticGraph } from "./semantic-graph/types";
 
@@ -9,11 +9,18 @@ const MAX_TOOLTIP_CANDIDATES = 8;
 const MAX_TOOLTIP_PROBE_MS = 2_400;
 const TOOLTIP_SETTLE_MS = 250;
 const CACHE_TTL_MS = 5 * 60_000;
+/**
+ * Misses expire sooner than hits: a control that gains a tooltip once the app
+ * finishes booting should still be discoverable, but not at the cost of
+ * re-probing every unlabelled control on every observation.
+ */
+const MISS_CACHE_TTL_MS = 60_000;
 const MAX_CACHE_ENTRIES = 500;
 const FORM_CONTROL_TAGS = new Set(["input", "select", "textarea"]);
 
 interface TooltipCacheEntry {
-  name: string;
+  /** `null` records "probed, revealed no tooltip" so the miss is not re-paid. */
+  name: string | null;
   expiresAt: number;
 }
 
@@ -27,7 +34,6 @@ interface TooltipCandidate<T extends FrameOwnedAxNode> {
 
 export interface TooltipNameProbeOptions {
   signal?: AbortSignal;
-  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
 }
 
 const tooltipCache = new Map<string, TooltipCacheEntry>();
@@ -39,10 +45,11 @@ function cacheKey<T extends FrameOwnedAxNode>(
   return `${document.target.tabId}\u0000${document.frameId}\u0000${document.url ?? ""}\u0000${backendNodeId}`;
 }
 
-function cachedName<T extends FrameOwnedAxNode>(
+/** Returns the cache entry, or `undefined` when this control was never probed. */
+function cachedEntry<T extends FrameOwnedAxNode>(
   document: FrameDocument<T>,
   backendNodeId: number,
-): string | undefined {
+): TooltipCacheEntry | undefined {
   const key = cacheKey(document, backendNodeId);
   const entry = tooltipCache.get(key);
   if (!entry) return undefined;
@@ -50,13 +57,13 @@ function cachedName<T extends FrameOwnedAxNode>(
     tooltipCache.delete(key);
     return undefined;
   }
-  return entry.name;
+  return entry;
 }
 
 function storeName<T extends FrameOwnedAxNode>(
   document: FrameDocument<T>,
   backendNodeId: number,
-  name: string,
+  name: string | null,
 ): void {
   if (tooltipCache.size >= MAX_CACHE_ENTRIES) {
     const oldest = tooltipCache.keys().next().value;
@@ -64,7 +71,7 @@ function storeName<T extends FrameOwnedAxNode>(
   }
   tooltipCache.set(cacheKey(document, backendNodeId), {
     name,
-    expiresAt: Date.now() + CACHE_TTL_MS,
+    expiresAt: Date.now() + (name === null ? MISS_CACHE_TTL_MS : CACHE_TTL_MS),
   });
 }
 
@@ -237,22 +244,27 @@ export async function probeTooltipNames<T extends FrameOwnedAxNode>(
   const names = new Map<string, string>();
   const pending: TooltipCandidate<T>[] = [];
   for (const candidate of candidates(documents, graph)) {
-    const cached = cachedName(candidate.document, candidate.backendNodeId);
+    const cached = cachedEntry(candidate.document, candidate.backendNodeId);
     if (cached) {
-      names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), cached);
+      // A cached miss is still a decision: skip the control instead of re-probing.
+      if (cached.name !== null) {
+        names.set(
+          frameBackendKey(candidate.document.frameId, candidate.backendNodeId),
+          cached.name,
+        );
+      }
     } else if (pending.length < MAX_TOOLTIP_CANDIDATES) {
       pending.push(candidate);
     }
   }
   if (pending.length === 0) return names;
 
-  const started = Date.now();
+  const budget = new ProbeBudget(MAX_TOOLTIP_PROBE_MS);
   const contexts = new Map<string, number>();
-  await options.hoverProbeBypassOverlay?.(tabId, true).catch(() => undefined);
   try {
     for (const candidate of pending) {
       if (options.signal?.aborted) throw new DOMException("observation aborted", "AbortError");
-      if (Date.now() - started >= MAX_TOOLTIP_PROBE_MS) break;
+      if (!budget.canAfford(TOOLTIP_SETTLE_MS)) break;
       let objectId: string | undefined;
       try {
         let contextId = contexts.get(candidate.document.frameId);
@@ -278,9 +290,9 @@ export async function probeTooltipNames<T extends FrameOwnedAxNode>(
         await waitForHover(TOOLTIP_SETTLE_MS, options.signal);
         const after = await tooltipTexts(cdp, candidate.document, objectId);
         const name = cleanTooltipDiff(before, after);
+        storeName(candidate.document, candidate.backendNodeId, name ?? null);
         if (!name) continue;
         names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), name);
-        storeName(candidate.document, candidate.backendNodeId, name);
       } catch (error) {
         if (error instanceof Error && error.name === "AbortError") throw error;
       } finally {
@@ -290,7 +302,6 @@ export async function probeTooltipNames<T extends FrameOwnedAxNode>(
     }
   } finally {
     await clearHover(cdp, tabId);
-    await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
   }
   return names;
 }

apps/extension/src/tools/vom/record-safe-observation.ts

@@ -37,6 +37,17 @@ export interface CaptureVomObservationResult {
   frames: CaptureVomFrame[];
   matchNodes: CaptureVomMatchNode[];
   surfaceProbes?: CapturedSurfaceProbe[];
+  /**
+   * Whether this observation actively hovered the page, and whether that
+   * revealed content the static tree does not contain. Lets callers judge how
+   * far the page may have drifted from the returned snapshot.
+   */
+  hoverProbe?: HoverProbeReport;
+}
+
+export interface HoverProbeReport {
+  performed: boolean;
+  revealedContent: boolean;
 }
 
 function projectFrames(documents: CapturedFrameDocument<FrameAxNode>[]): CaptureVomFrame[] {
@@ -75,6 +86,7 @@ export function projectRecordSafeObservation(input: {
   frameDocuments: CapturedFrameDocument<FrameAxNode>[];
   rendered: VomResult;
   surfaceProbes?: CapturedSurfaceProbe[];
+  hoverProbe?: HoverProbeReport;
 }): CaptureVomObservationResult {
   return {
     text: input.rendered.text,
@@ -84,5 +96,6 @@ export function projectRecordSafeObservation(input: {
     frames: projectFrames(input.frameDocuments),
     matchNodes: projectMatchNodes(input.frameDocuments),
     surfaceProbes: input.surfaceProbes,
+    ...(input.hoverProbe ? { hoverProbe: input.hoverProbe } : {}),
   };
 }

apps/extension/src/transport/types.ts

@@ -27,8 +27,6 @@ export type RpcErrorReason =
   | "ref_not_found"
   | "selector_not_found"
   | "target_not_fillable"
-  | "focus_target_unresolved"
-  | "input_not_applied"
   | "target_not_select"
   | "option_not_found"
   | "single_select_value_count"
@@ -36,15 +34,22 @@ export type RpcErrorReason =
   | "restricted_tab_url"
   | "borrow_conflict"
   | "screenshot_capture_failed"
-  | "surface_capture_not_found"
-  | "surface_capture_expired"
-  | "surface_capture_consumed"
-  | "surface_capture_stale"
-  | "surface_coordinate_invalid"
+  | "file_input_probe_failed"
+  | "file_input_not_activated"
+  | "set_file_input_failed"
+  | "download_capture_failed"
+  | "transfer_outcome_unknown"
+  | "transfer_timeout"
   | "cleanup_failed";
 
+export type TransferEffectState = "none" | "committed" | "unknown";
+export type TransferCleanupState = "complete" | "failed";
+
 export interface RpcErrorData {
   reason?: RpcErrorReason;
+  effect_state?: TransferEffectState;
+  phase?: string;
+  cleanup_state?: TransferCleanupState;
   [key: string]: unknown;
 }
 
@@ -306,17 +311,9 @@ export interface ScreenshotResult {
   height: number;
   format: string;
   tab_id: number;
-  capture?: SurfaceCaptureInfo;
   dialogs?: JavaScriptDialogInfo[];
 }
 
-export interface SurfaceCaptureInfo {
-  id: string;
-  surface_ref: string;
-  coordinate_space: "capture-image-pixel";
-  expires_at: number;
-}
-
 export interface SnapshotParams {
   session_id: string;
   tab_id?: number;
@@ -334,9 +331,14 @@ export interface SnapshotResult {
 
 export interface ObserveParams extends SnapshotParams {
   debug_surfaces?: boolean;
+  probe_hover?: boolean;
 }
 
 export interface ObserveResult extends SnapshotResult {
+  hover_probe?: {
+    performed: boolean;
+    revealed_content: boolean;
+  };
   debug?: {
     surface_probes?: Array<{
       trigger_backend_node_id: number;
@@ -430,9 +432,6 @@ export interface ClickParams {
   click_count?: number;
   modifiers?: KeyModifier[];
   timeout_ms?: number;
-  capture_id?: string;
-  image_x?: number;
-  image_y?: number;
 }
 
 export interface ClickResult {
@@ -441,9 +440,6 @@ export interface ClickResult {
   used_selector?: string;
   x: number;
   y: number;
-  capture_id?: string;
-  image_x?: number;
-  image_y?: number;
   dialogs?: JavaScriptDialogInfo[];
 }
 
@@ -484,26 +480,6 @@ export interface FillResult {
   dialogs?: JavaScriptDialogInfo[];
 }
 
-export interface TypeParams {
-  session_id: string;
-  text: string;
-  ref?: string;
-  selector?: string;
-  /** Explicitly dispatch to the unique focused text-entry target. */
-  focused?: boolean;
-  tab_id?: number;
-  timeout_ms?: number;
-}
-
-export interface TypeResult {
-  tab_id: number;
-  used_ref?: string;
-  used_selector?: string;
-  text_length: number;
-  verification: "dispatched";
-  dialogs?: JavaScriptDialogInfo[];
-}
-
 export interface PressParams {
   session_id: string;
   key: string;
@@ -542,6 +518,50 @@ export interface SelectResult {
   dialogs?: JavaScriptDialogInfo[];
 }
 
+export interface UploadFile {
+  transfer_id: string;
+  name: string;
+  staged_path?: string;
+}
+
+export interface UploadParams {
+  session_id: string;
+  ref?: string;
+  selector?: string;
+  tab_id?: number;
+  files: UploadFile[];
+  timeout_ms?: number;
+}
+
+export interface UploadResult {
+  tab_id: number;
+  used_ref?: string;
+  used_selector?: string;
+  file_names: string[];
+}
+
+export interface DownloadParams {
+  session_id: string;
+  ref?: string;
+  selector?: string;
+  tab_id?: number;
+  timeout_ms?: number;
+  browser_relative_dir?: string;
+  max_byte_size?: number;
+}
+
+export interface DownloadResult {
+  tab_id: number;
+  used_ref?: string;
+  used_selector?: string;
+  suggested_filename: string;
+  byte_size: number;
+  mime?: string;
+  danger?: string;
+  browser_path?: string;
+  transfer_id?: string;
+}
+
 // --------------------------------------------------------------------------
 // M9 tool payloads — evaluate / wait_for_navigation / wait_ms
 // --------------------------------------------------------------------------

apps/extension/test-fixtures/rendered-surfaces/README.md

@@ -77,14 +77,6 @@ Expected Surface labels:
 
 The cross-origin frame uses `http://localhost:4173` while the parent uses `http://127.0.0.1:4173`. With Chromium site isolation this exercises the OOPIF path without an external service.
 
-Each frame Canvas also exposes a `pointer status` live region. A successful
-screenshot-bound point click must report
-`down button=0 buttons=1 hoverReady=true; click received` and turn the Canvas
-yellow. The hover flag is set on the animation frame after `pointermove`, so the
-fixture verifies both child-document delivery and the scheduling boundary
-required before `pointerdown`, rather than merely validating projected
-coordinates or a successful CDP response.
-
 ### `viewport.html`
 
 Run with a `900x700` Agent Window.
@@ -93,40 +85,6 @@ Run with a `900x700` Agent Window.
 - `fixture-below-fold` is absent initially.
 - After scrolling it into view and observing again, `fixture-below-fold` must be represented with a fresh ref.
 
-### `input-frames.html`
-
-This page exercises generic frame-aware input routing. It contains a top-level
-input plus same-origin, cross-origin (OOPIF), and nested frame inputs. Each
-frame includes an input, textarea, contenteditable editor, an input that
-replaces its DOM node after accepted input, an input that rejects synthetic
-DOM events, a transient keyboard/IME input proxy that consumes and clears its
-DOM value, and a controlled input that resets its value on the next animation
-frame.
-
-- `fill` must route focus, text insertion, DOM events, and readback through the
-  ref's owning CDP target.
-- `press --ref` must focus and dispatch every key event through that same target.
-- Untargeted `press` must follow the actual focused target or refuse when focus
-  ownership cannot be determined uniquely.
-- The remounting input must retain the value through its replacement node.
-- The trusted input must be filled without synthetic `input` / `change` events.
-- `type` must deliver ASCII key events and committed non-ASCII IME/software
-  keyboard insertion to the input proxy. Its DOM value remains empty while
-  `proxy output` retains the consumed text; the result reports
-  `verification=dispatched`, not a retained DOM value.
-- `type` must reject an omitted target unless `focused=true` is explicit, and
-  focused mode must reject focus that is not owned by a text-entry target.
-- The rejecting input must return `input_not_applied`, never a successful
-  requested-value length.
-
-### `canvas-input.html`
-
-This is the PR3 end-to-end fixture. Its cross-origin frame contains a
-visual-only three-row Canvas. A screenshot-bound click on row 3 exposes and
-focuses a standard textbox; ordinary `fill` must then write and read back its
-real value through the textbox's owning target. The fixture deliberately does
-not provide a Canvas-specific fill action.
-
 ### `dynamic.html`
 
 Use the normal DOM buttons and re-observe after each action:

apps/extension/test-fixtures/rendered-surfaces/canvas-input.html

@@ -1,20 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Canvas to standard input fixture</title>
-    <style>
-      body { padding: 16px; font: 14px system-ui, sans-serif; }
-      iframe { width: 300px; height: 220px; border: 2px solid #5d6d7e; }
-    </style>
-  </head>
-  <body>
-    <h1>Canvas to standard input fixture</h1>
-    <p>Select row 3 in the visual-only Canvas, then fill the exposed standard textbox.</p>
-    <iframe
-      title="cross-origin Canvas editor"
-      src="http://localhost:4173/frame.html?label=canvas-input-grid&interactive=1&editor=1"
-    ></iframe>
-  </body>
-</html>

apps/extension/test-fixtures/rendered-surfaces/frame.html

@@ -8,7 +8,6 @@
       body { padding: 12px; background: #fdfefe; }
       canvas { display: block; width: 220px; height: 90px; background: #d5f5e3; border: 2px solid #1e8449; }
       iframe { width: 280px; height: 150px; margin-top: 10px; border: 2px solid #85929e; }
-      #pointer-status { margin: 8px 0 0; min-height: 20px; }
     </style>
   </head>
   <body>
@@ -17,62 +16,11 @@
       const params = new URLSearchParams(location.search);
       const canvas = document.querySelector("#frame-canvas");
       if (params.get("canvas") === "0") canvas.remove();
-      else {
-        canvas.setAttribute("aria-label", params.get("label") || "fixture-frame-default");
-        if (params.get("editor") === "1") {
-          const context = canvas.getContext("2d");
-          context.font = "14px system-ui, sans-serif";
-          context.textBaseline = "middle";
-          context.strokeStyle = "#1e8449";
-          context.fillStyle = "#145a32";
-          for (let row = 0; row < 3; row += 1) {
-            const top = row * 30;
-            context.strokeRect(0.5, top + 0.5, 219, 29);
-            context.fillText(`Row ${row + 1}`, 12, top + 15);
-          }
-        }
-        if (params.get("interactive") === "1") {
-          const status = document.createElement("p");
-          status.id = "pointer-status";
-          status.setAttribute("aria-live", "polite");
-          status.textContent = "pointer status: idle";
-          canvas.insertAdjacentElement("afterend", status);
-          let hoverReady = false;
-          canvas.addEventListener("pointermove", () => {
-            hoverReady = false;
-            requestAnimationFrame(() => {
-              hoverReady = true;
-            });
-          });
-          canvas.addEventListener("pointerdown", (event) => {
-            status.textContent = `pointer status: down button=${event.button} buttons=${event.buttons} hoverReady=${hoverReady}`;
-            if (event.buttons === 1 && hoverReady) canvas.style.background = "#f9e79f";
-          });
-          canvas.addEventListener("click", () => {
-            status.textContent += "; click received";
-          });
-          if (params.get("editor") === "1") {
-            canvas.addEventListener("click", (event) => {
-              const rect = canvas.getBoundingClientRect();
-              const canvasY = ((event.clientY - rect.top) / rect.height) * canvas.height;
-              const row = Math.min(2, Math.max(0, Math.floor(canvasY / 30)));
-              status.textContent += `; selected row=${row + 1}`;
-              document.querySelector("#canvas-cell-editor")?.remove();
-              if (row !== 2) return;
-              const editor = document.createElement("input");
-              editor.id = "canvas-cell-editor";
-              editor.setAttribute("aria-label", "selected canvas cell editor");
-              editor.placeholder = "Type into selected row 3";
-              canvas.insertAdjacentElement("afterend", editor);
-              editor.focus();
-            });
-          }
-        }
-      }
+      else canvas.setAttribute("aria-label", params.get("label") || "fixture-frame-default");
       if (params.get("nested") === "1") {
         const iframe = document.createElement("iframe");
         iframe.title = "nested fixture frame";
-        iframe.src = "frame.html?label=fixture-nested-frame&interactive=1";
+        iframe.src = "frame.html?label=fixture-nested-frame";
         document.body.append(iframe);
       }
     </script>

apps/extension/test-fixtures/rendered-surfaces/frames.html

@@ -14,8 +14,8 @@
   <body>
     <h1>Frame matrix</h1>
     <div class="frames">
-      <iframe title="same-origin fixture" src="frame.html?label=fixture-same-origin-frame&interactive=1"></iframe>
-      <iframe title="cross-origin fixture" src="http://localhost:4173/frame.html?label=fixture-cross-origin-frame&interactive=1"></iframe>
+      <iframe title="same-origin fixture" src="frame.html?label=fixture-same-origin-frame"></iframe>
+      <iframe title="cross-origin fixture" src="http://localhost:4173/frame.html?label=fixture-cross-origin-frame"></iframe>
       <iframe title="nested fixture" src="frame.html?canvas=0&nested=1"></iframe>
     </div>
   </body>

apps/extension/test-fixtures/rendered-surfaces/input-frame.html

@@ -1,59 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <style>
-      body { margin: 0; padding: 12px; font: 14px system-ui, sans-serif; }
-      label, textarea, input, [contenteditable] { display: block; margin: 8px 0; }
-      input, textarea, [contenteditable] { width: 240px; padding: 6px; border: 1px solid #85929e; }
-      iframe { width: 280px; height: 190px; border: 2px solid #85929e; }
-    </style>
-  </head>
-  <body>
-    <label>Frame input <input aria-label="frame input" /></label>
-    <label>Frame textarea <textarea aria-label="frame textarea"></textarea></label>
-    <div contenteditable="true" aria-label="frame editor"></div>
-    <label>Remounting input <span id="remount-host"><input aria-label="remounting input" /></span></label>
-    <label>Trusted input <input id="trusted" aria-label="trusted input" /></label>
-    <label>Input proxy <input id="proxy" aria-label="input proxy" /></label>
-    <output id="proxy-output" aria-label="proxy output">proxy output: empty</output>
-    <label>Rejecting input <input id="rejecting" aria-label="rejecting input" /></label>
-    <script>
-      const params = new URLSearchParams(location.search);
-      const remountHost = document.querySelector("#remount-host");
-      const armRemount = (input) => {
-        input.addEventListener("input", () => {
-          const replacement = document.createElement("input");
-          replacement.setAttribute("aria-label", "remounting input");
-          replacement.value = input.value;
-          armRemount(replacement);
-          input.replaceWith(replacement);
-          replacement.focus();
-        }, { once: true });
-      };
-      armRemount(remountHost.querySelector("input"));
-      const trusted = document.querySelector("#trusted");
-      trusted.addEventListener("input", (event) => {
-        if (!event.isTrusted) requestAnimationFrame(() => { trusted.value = ""; });
-      });
-      const proxy = document.querySelector("#proxy");
-      const proxyOutput = document.querySelector("#proxy-output");
-      let proxyValue = "";
-      proxy.addEventListener("input", (event) => {
-        if (event.isComposing) return;
-        proxyValue += event.data ?? proxy.value;
-        proxy.value = "";
-        proxyOutput.textContent = `proxy output: ${proxyValue || "empty"}`;
-      });
-      const rejecting = document.querySelector("#rejecting");
-      rejecting.addEventListener("input", () => requestAnimationFrame(() => { rejecting.value = ""; }));
-      if (params.get("nested") === "1") {
-        const iframe = document.createElement("iframe");
-        iframe.title = "nested input frame";
-        iframe.src = "input-frame.html";
-        document.body.append(iframe);
-      }
-    </script>
-  </body>
-</html>

apps/extension/test-fixtures/rendered-surfaces/input-frames.html

@@ -1,23 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Frame input routing matrix</title>
-    <style>
-      body { padding: 16px; font: 14px system-ui, sans-serif; }
-      .frames { display: grid; grid-template-columns: repeat(3, 320px); gap: 16px; }
-      iframe { width: 300px; height: 430px; border: 2px solid #5d6d7e; }
-      input { padding: 6px; }
-    </style>
-  </head>
-  <body>
-    <h1>Frame input routing matrix</h1>
-    <label>Top input <input aria-label="top input" /></label>
-    <div class="frames">
-      <iframe title="same-origin inputs" src="input-frame.html"></iframe>
-      <iframe title="cross-origin inputs" src="http://localhost:4173/input-frame.html"></iframe>
-      <iframe title="nested inputs" src="input-frame.html?nested=1"></iframe>
-    </div>
-  </body>
-</html>

apps/extension/wxt.config.ts

@@ -30,6 +30,7 @@ export default defineConfig({
     permissions: [
       "alarms",
       "debugger",
+      "downloads",
       "idle",
       "notifications",
       "tabs",

crates/bsk-cli/Cargo.toml

@@ -53,6 +53,7 @@ flate2 = { workspace = true }
 tar = { workspace = true }
 zip = { workspace = true }
 sha2 = { workspace = true }
+base64 = { workspace = true }
 
 [target.'cfg(unix)'.dependencies]
 nix = { workspace = true }
@@ -63,6 +64,7 @@ windows-sys = { version = "0.59", features = [
     "Win32_Foundation",
     "Win32_System_Threading",
     "Win32_Security",
+    "Win32_Storage_FileSystem",
 ] }
 
 [dev-dependencies]

crates/bsk-cli/skill/SKILL.md

@@ -1,191 +1,135 @@
 ---
 name: browser-skill
 description: |
-  Use when the user asks to perform browser automation tasks against their
-  logged-in browser: visit and read pages, fill forms, scrape data, click
-  through a flow, regression-test a PR's UI, validate a deployed page.
-  Requires the bsk CLI installed and the browser-skill extension loaded.
+  Use when the user asks to automate their logged-in Chromium browser: visit
+  and read pages, fill forms, scrape data, click through flows, regression-test
+  a PR's UI, validate a deployed page, or operate a tab they identify. Requires
+  the bsk CLI and browser extension.
 ---
 
 # browser-skill
 
-Drive the user's **real Chromium browser** (with their logins and cookies) through the `bsk` CLI. The extension opens an isolated **Agent Window** for automation; the user's normal windows stay protected unless you explicitly borrow a tab.
+Drive the user's real Chromium browser through `bsk`. Automation runs in an isolated **Agent
+Window** with the user's existing logins and cookies. User-window tabs remain protected unless they
+are explicitly borrowed.
 
-## When to use
+Do not use this skill for tasks with no browser, for extension installation, or when the user only
+wants instructions. Never extract credentials, cookies, tokens, or other secrets from pages.
 
-- Open pages, read titles/text, scrape structured data from sites the user can already access
-- Fill forms, click through multi-step flows, smoke-test a UI change
-- Understand pages with `bsk snapshot` first; use `bsk get-html` or `bsk screenshot` only when the snapshot is insufficient
-- Operate on a specific user tab they point you at (after `bsk tab borrow`)
+## Required lifecycle
 
-## When NOT to use
+Every browser task owns a bounded session:
 
-- Tasks with **no browser** involved (files, APIs, databases only)
-- Installing or configuring the extension (point the user to setup docs instead)
-- **Credential harvesting** — never run `bsk evaluate` on banking, SSO, or password-manager pages to extract tokens, cookies, or secrets
-- Long-lived control of a user's personal login window — borrow only for the immediate step, then `bsk tab return` or end the session
-- Replacing the user's manual browsing when they only wanted an explanation
-
-## Prerequisites
-
-1. `bsk` on `PATH` (Rust CLI from browser-skill)
-2. browser-skill **extension** loaded in Chromium and connected (popup shows green, or an upgrade reminder — still connected; continue)
-3. Any `bsk` command auto-starts background services as needed; use `bsk doctor` if anything fails
-
-## Mandatory workflow
-
-Every automation task **must** follow this lifecycle. Do **not** rely on idle timeouts (default session idle is 5 minutes).
-
-```
-1. bsk session start              → capture the 4-letter session id printed on stdout
-2. … every tool command …        → always pass --session <id>
-3. bsk session stop <id>          → REQUIRED when done (even on error paths)
+```text
+1. bsk session start              # retain the printed 4-letter session id
+2. bsk ... --session <id>         # pass it to every session-scoped command
+3. bsk session stop <id>          # always run on success and error paths
 ```
 
-Optional: `bsk session start --browser <instance-id-or-label>` when multiple browsers are connected (`bsk browsers` / error output lists them). Add `--no-focus` to open the Agent Window in the background without stealing focus from the user's current window.
+Do not rely on the idle timeout for cleanup. Stop the session as soon as the goal is met unless the
+user explicitly asks to keep it open. Stopping also returns borrowed tabs.
 
-Emergency cleanup: `bsk session stop --all` or the Agent Window overlay **Stop all**.
+Any `bsk` command auto-starts the background services it needs; never manage the daemon by hand.
+When multiple browsers are connected, use `bsk browsers` and start with
+`bsk session start --browser <id-or-label>`. Add `--no-focus` to that same start command when the
+Agent Window does not need to interrupt the user's current work; it is not a flag on other commands.
+Run `bsk doctor` when startup or transport problems persist after one retry.
 
-## Stop when the goal is met
+## Work toward one observable goal
 
-Every task is a **bounded goal**, not open-ended browsing. The goal may come from the user's request, a recorded `trace.json`, or both.
+- Derive a concrete success condition from the user's request or a supplied trace.
+- Take the shortest purposeful path: observe, act, then make at most one observation to confirm an
+  ambiguous result.
+- Once success is visible, do not click, refresh, navigate, switch tabs, or perform extra checks.
+- If a human-only step appears or two attempts make no progress, request help instead of
+  brute-forcing.
 
-1. **Define success first** — one concrete, observable condition derived from the user's words, `purpose`, or the last meaningful step in a trace (e.g. "form submitted", "item added to cart", "playback started").
-2. **Take the shortest path** — snapshot → act → at most one check. Do not wander, re-try unrelated actions, or stack exploratory steps.
-3. **Stop as soon as success is reached** — run `bsk session stop <id>` immediately unless the user explicitly asked to keep the session open (e.g. "don't close yet", "keep browsing").
-4. **No post-success work** — once the goal is met, do not click, refresh, navigate, re-search, switch tabs, or "double-check" that it worked. Further verification is a new task.
-5. **When blocked, pause — do not brute-force** — if the page requires human input (login, captcha, OTP, payment confirmation) or an action fails twice with no progress, call `bsk request-help` instead of retrying blindly. See **Ask the human for help** below.
-6. **When unsure** — at most one extra `bsk snapshot`. If success looks met, stop. If not, ask the user; do not keep clicking.
+With a trace, follow its semantic target information and values in order, but treat its refs as
+record-local hints. Stop when its purpose or last meaningful effect is satisfied. A trace guides the
+task; it does not expand the user's goal or authorize additional actions.
 
-**With a trace:** replay steps in order using `target` role/name/tag and raw `value`/`selection` fields. After the last step (or when its `effect.navigated_to` / success hint is satisfied), apply rules 3–4 immediately. The trace guides execution; it does not extend control beyond the goal.
+## Observe, act, observe
 
-**Without a trace:** the user's request *is* the success condition. Satisfying it ends the task — same stop rules apply.
+Use this default loop:
 
-## Core interaction loop
-
-Write operations only affect tabs in the **Agent Window** (or tabs you **borrowed** into it).
-
-```
+```text
 bsk navigate <url> --session <id>
-bsk observe --session <id>           → primary semantic VOM view; reveals hover/focus surfaces
-bsk snapshot --session <id>          → static aria tree fallback when VOM is insufficient
-bsk hover @e3 --session <id>          → reveal hover-triggered menus before re-observing/clicking
-bsk click @e4 --session <id>          → or bsk fill, bsk type, bsk select, bsk press
-bsk observe --session <id>             → again after navigation / DOM change
+bsk observe --session <id>
+bsk click|hover|fill|select|press ... --session <id>
+bsk observe --session <id>             # after navigation or a meaningful DOM change
 ```
 
-### Choosing `fill`, `type`, and `press`
+Prefer fresh `@eN` refs over CSS selectors. Navigation invalidates refs; large DOM changes may also
+make them stale. Observe again before the next interaction.
 
-Choose by the intended postcondition, not by whether observation happens to
-render `textbox [empty]`:
+An observation marks a hover-only surface as `@e1 button "Products" [hover first: Shoes | Bags]`.
+The listed items are labels, not usable refs: hover the trigger, observe again, then act on the
+revealed item's own ref. Do not click the trigger itself unless the user wants the trigger's action.
+`[has-submenu]` and `[expanded]` mark the same kind of trigger without listing what it hides.
 
-- `fill` sets a field's retained value. Use it when success means the target
-  value must equal the requested text; it replaces existing content by default.
-- `type` inserts text at the active caret/selection in a live editing session.
-  Use it when the application must consume keyboard/IME text; it never clears
-  first and reports dispatch only.
-- `press` sends a discrete key or shortcut such as `Enter`, `Tab`, or `Ctrl+A`.
-  Do not encode special keys inside `type --text`.
+`bsk observe` does not hover the page on its own. Reach for `--probe-hover` when a control you have
+good reason to expect is absent **and** no marker points at a trigger — that combination is what a
+CSS-only hover menu looks like from here. It hovers a bounded set of likely triggers, so it costs a
+few seconds and touches the live page; once you know which element hides the menu, `bsk hover <ref>`
+is cheaper and more precise.
 
-`type` requires an explicit targeting mode: pass a ref/selector when one is
-available, or pass `--focused` only after an immediately preceding action in
-the same tab deliberately established a text-entry focus. Never use `fill`
-as a probe and never automatically retry a failed `fill` with `type`: an
-application may already have consumed the text before clearing its proxy DOM
-value. Re-observe first. After `type`, verify the application output with one
-observation or screenshot; `verification=dispatched` is not business success.
+When `bsk observe` renders
+`@eN surface ... [visual-only; requires=image-understanding; ...]`, the ref identifies rendered
+canvas content that is not represented by the text observation, not an interactable DOM control.
+Keep using any reliable DOM/AX text and controls that appear alongside it. If you can actually
+inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain the visible crop. If
+you lack multimodal or image-reading capability, do not take a screenshot and pretend to know its
+contents, and never guess coordinates; tell the user that they need to switch to a model with
+image-understanding capability. Do not pass a visual surface ref to click, fill, hover, or select;
+those commands intentionally reject screenshot-only refs.
 
-**Refs invalidate after navigation** — always re-snapshot before clicking, filling, or selecting on a new page.
+Escalate page reading only as needed:
 
-Prefer `@eN` refs from the latest snapshot over raw CSS selectors. Use `--ref` / `--selector` when ambiguous (`bsk click --help`).
+1. `bsk observe` for normal semantic understanding, text, controls, and refs.
+2. `bsk observe --probe-hover` once when an expected control is missing and no marker points at a
+   trigger.
+3. `bsk snapshot` when a stricter static accessibility tree is more useful.
+4. `bsk get-html` for exact markup or hidden metadata that semantic views cannot provide.
+5. `bsk screenshot` for layout, styling, canvas, images, or requested visual evidence.
 
-When VOM renders `[hover first: …]` on an element, the listed items are not currently clickable refs. Run `bsk hover <that-ref> --session <id>`, then immediately run `bsk snapshot` or `bsk observe` again and click the newly visible menu item ref. Do not click the trigger itself unless the user explicitly wants the trigger action.
+Do not start with raw HTML or screenshots merely to discover ordinary controls. When interaction is
+needed, obtain a fresh observation before acting on screenshot or HTML findings.
 
-When `bsk observe` renders `@eN surface ... [visual-only; requires=image-understanding; ...]`, the ref identifies rendered canvas content that is not represented by the text observation, not an interactable DOM control. Keep using any reliable DOM/AX text and controls that appear alongside it. If you lack multimodal or image-reading capability, do not take a screenshot and pretend to know its contents, and never guess coordinates; tell the user that they need to switch to a model with image-understanding capability.
+## Respect the Agent Window boundary
 
-If you can actually inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain the visible crop and its short-lived, single-use Surface capture id. Only when the task requires a point action and the image provides a clear target, bind that exact screenshot to the same general click command:
+Normal page writes affect only Agent Window tabs. To operate a user tab, first list it with
+`bsk tab list --scope user --session <id>`, then `bsk tab borrow <tab-id>`. Return it immediately
+after the relevant step with `bsk tab return <tab-id>`; never invent a tab id or keep a personal tab
+borrowed across unrelated work.
 
-```bash
-bsk click @eN --capture <capture-id> --image-x <px> --image-y <px> --session <id>
+## Ask the human when needed
+
+Use `bsk request-help` for login, captcha, OTP, payment confirmation, consent, or another step the
+user must complete. Give a precise prompt and pass fresh `--target` refs/selectors when concrete
+controls can be highlighted. Use completion criteria only when the page has a clear stable success
+signal.
+
+The result `outcome` is one of `continued`, `completed`, `cancelled`, `timed_out`, or `disabled`
+(`navigated` is deprecated — never treat navigation as a completion signal). Resume only after
+`continued` or `completed`. Treat `cancelled` as rejection, and `timed_out` or `disabled` as a
+blocker rather than a reason to retry. After control returns, run a fresh `bsk observe` before
+reasoning about the page or using refs.
+
+## Command inventory
+
+This list of names is complete. Never invent a command outside it; read
+`bsk <command...> --help` for flags instead of guessing them.
+
+```text
+session start|stop|list   browsers   status   doctor   update   logs
+navigate   navigate-back   navigate-forward   reload   wait-for-navigation   wait-ms
+observe   snapshot   get-html   screenshot   console   network
+click   hover   fill   select   press   evaluate
+tab list|create|close|select|borrow|return   window resize   emulate
+request-help   record start|stop
 ```
 
-Coordinates are pixels in the returned capture image, not viewport CSS coordinates. Re-observing, navigating, scrolling, resizing, zooming, changing Frame projection, expiry, or reusing the capture makes the action fail; take a new Surface screenshot instead of adjusting or retrying coordinates. A point click does not reveal Canvas semantics and must not be followed by an assumed fill/type/press workflow. Re-observe first: if the application exposes a real DOM editable, use its new ref; use `type --focused` only when the observation and immediately preceding click establish a focused text-entry session without a usable ref. Without all three capture arguments, visual Surface refs remain screenshot-only and click/fill/type/hover/select reject them.
-
-## Observation priority
-
-Start with `bsk observe` to understand page structure, text, controls, element refs, and conditional hover/focus surfaces. Use `bsk snapshot` only when you need the stricter static accessibility tree or VOM is insufficient. Only escalate to raw HTML or screenshots when the latest observation cannot answer the question:
-
-1. `bsk observe` — primary semantic VOM observation; may run bounded perception probes such as hover-surface discovery
-2. `bsk snapshot` — strict static accessibility tree fallback
-3. `bsk get-html` — when hidden DOM, metadata, or markup details are required
-4. `bsk screenshot` — when visual layout, canvas/image content, or styling cannot be inferred from the observation. Use `--ref @eN` (from the latest snapshot/observe) to crop to one element; omit `--ref` for the full visible tab.
-
-Do **not** call `bsk get-html` or `bsk screenshot` first just to inspect a page.
-
-## Sandbox rules
-
-| Rule | Detail |
-|------|--------|
-| Agent Window | `bsk tab create`, `bsk navigate`, `bsk click`, etc. work on agent tabs by default |
-| User tabs | Read-only until borrowed: `bsk tab list --session <id> --scope user` then `bsk tab borrow <tab-id> --session <id>` |
-| Return borrowed tabs | Call `bsk tab return <tab-id> --session <id>` when finished; unreturned tabs are **auto-returned** on `bsk session stop` |
-| Writes off-agent | Commands that mutate the page fail if the tab is not in the Agent Window — borrow or create a tab first |
-
-## Global flags
-
-| Flag | Purpose |
-|------|---------|
-| `--json` | Machine-readable JSON on stdout (errors too) |
-| `--quiet` | Suppress informational stderr |
-| `-v` / `-vv` | More verbose logging |
-
-Auto-update is **on by default** — the background daemon upgrades `bsk` itself when a new release is available (postponed while a session is active). Set `BSK_AUTO_UPDATE=off` to disable it and upgrade manually with `bsk update`.
-
-Command-specific flags (timeouts, `--tab-id`, `--wait-until`, …): **`bsk <cmd> --help`**
-
-## CLI command reference (one line each)
-
-Details and flags: **`bsk <cmd> --help`**
-
-### Diagnostics
-
-| Command | Summary |
-|---------|---------|
-| `bsk status` | Connection health, connected browsers, active sessions |
-| `bsk doctor` | Deep diagnostics and repair hints |
-| `bsk browsers` | List connected browser instances (ids, labels, versions) |
-
-### Session
-
-| Command | Summary |
-|---------|---------|
-| `bsk session start` | Open Agent Window (`--width`/`--height` for initial size); prints **4-letter session id** |
-| `bsk session start --no-focus` | Open Agent Window in the background without stealing focus |
-| `bsk session stop <id>` | End session, close Agent Window, auto-return borrowed tabs |
-| `bsk session stop --all` | Stop every active session |
-| `bsk session list` | List active sessions |
-
-### Window (require `--session <id>`)
-
-| Command | Summary |
-|---------|---------|
-| `bsk window resize` | Resize the Agent Window (`--width`, `--height`; 100..=7680 CSS px) |
-
-### Device emulation — `bsk emulate` (requires `--session <id>`)
-
-Emulate a mobile device environment on the agent tab via CDP — viewport, User-Agent, and touch — to debug a page's mobile layout and behaviour:
-
-```bash
-bsk emulate --session <id> --device iphone-14
-bsk emulate --session <id> --width 390 --height 844 --dpr 3 --mobile --ua "Mozilla/5.0 (iPhone…" --touch
-bsk emulate --session <id> --off
-```
-
-- Presets (`--device`): `iphone-14`, `iphone-14-pro-max`, `iphone-se`, `pixel-7`, `galaxy-s23`, `ipad-mini`, `galaxy-tab-s8`. Manual flags (`--width`/`--height`/`--dpr`/`--mobile`/`--ua`/`--accept-language`/`--touch`/`--max-touch-points`) also work without a preset, or override individual preset fields; `--no-mobile`/`--no-touch` turn a preset's mobile viewport / touch emulation back off.
-- Repeated runs merge field by field onto the tab's current emulation state — only the flags you pass change. E.g. after `--device iphone-14`, `bsk emulate --session <id> --width 390 --height 844` keeps the preset's dpr (`3`) and mobile viewport. (The extension remembers the state per tab; after an extension reload the next run applies only the fields it carries.)
-- `--off` clears every override (viewport, UA, touch) and the remembered state, restoring the tab's real environment.
-- Scope: overrides apply to **one tab only** (CDP per-target) and are **not inherited by new tabs** — re-run `bsk emulate` after opening or switching to another tab (default target is the session's active tab; `--tab-id` overrides).
-- Emulation covers viewport/UA/touch only; it does not throttle the network, fake geolocation, or synthesise real touch-event streams.
+Required flags that are easy to get wrong:
 
 ### Tabs (require `--session <id>`)
 
@@ -205,7 +149,7 @@ bsk emulate --session <id> --off
 | `bsk snapshot` | First-choice static page understanding: accessibility tree with `@eN` element refs |
 | `bsk observe` | Semantic VOM observation with bounded perception probes for conditional surfaces |
 | `bsk get-html` | Raw HTML dump after snapshot is insufficient (high token cost) |
-| `bsk screenshot` | PNG capture after snapshot is insufficient: full visible tab, or `--ref @eN` to crop to one element (`--out` path optional); Surface crops return a short-lived capture id |
+| `bsk screenshot` | PNG capture after snapshot is insufficient: full visible tab, or `--ref @eN` to crop to one element (`--out` path optional) |
 
 ### Console & network debugging (read-only; require `--session`)
 
@@ -231,14 +175,35 @@ Both capture from the moment the tab is attached and read a bounded per-tab buff
 
 | Command | Summary |
 |---------|---------|
-| `bsk click <ref-or-selector>` | Click a DOM element (`--button`, `--click-count`, `--modifiers`), or perform one screenshot-bound Surface point click with `--capture`, `--image-x`, and `--image-y` |
+| `bsk click <ref-or-selector>` | Click element (`--button`, `--click-count`, `--modifiers`) |
 | `bsk hover <ref-or-selector>` | Move the mouse to an element and wait for hover UI to settle (`--settle`, `--modifiers`) |
-| `bsk fill <ref-or-selector> --value <text>` | Replace and verify a field's retained value |
-| `bsk type <ref-or-selector> --text <text>` | Insert keyboard/IME text into an explicitly targeted editing session; reports dispatch only |
-| `bsk type --focused --text <text>` | Insert into the unique focused text-entry session after an intentional focus-producing action |
+| `bsk fill <ref-or-selector> --value <text>` | Clear and type into input |
 | `bsk select <ref-or-selector> --value <v>` | Set `<select>` option(s) by `value` (repeat `--value` for multi-select) |
 | `bsk press <key>` | Key/combo (`Enter`, `Ctrl+A`, …; optional `--ref` to focus first) |
 
+### File transfer (require `--session`)
+
+| Command | Summary |
+|---------|---------|
+| `bsk upload <ref-or-selector> --file <path>` | Click one upload trigger and attach an agent-readable local file (`--file` is repeatable) |
+| `bsk download <ref-or-selector> --out <path>` | Click one download trigger and copy the single completed file to an exact local path (`--overwrite` is opt-in) |
+
+The agent/harness decides whether a file transfer is appropriate and which local path belongs to the task. Treat upload as disclosure of that file to the current website, and download as accepting website-controlled bytes onto the local filesystem. Use only paths that are necessary for the user's bounded goal.
+
+BrowserSkill enforces the mechanical boundary: files are staged under a session-scoped opaque transfer, only daemon-minted capabilities reach the extension, upload/download still obey Agent Window tab checks, and transfers are chunk/size bounded. Upload intercepts the native chooser for one transaction, locates the input activated in the resolved target's document, and assigns only the staged file paths. Download uniquely correlates one exact-target browser intent with one Chrome download in either event order, routes it through a daemon-minted relative directory, and lets the daemon validate and import it. Upload staging remains available for a later form submission and is removed when the session ends. Downloads cannot overwrite an existing destination unless `--overwrite` is explicit. BrowserSkill does not inspect file content or decide whether its meaning is sensitive.
+
+Do not use `request-help` merely because a native file chooser or browser download is involved; try these commands first. For transfer failures, use the structured error instead of retrying blindly:
+
+- `reason=file_input_not_activated` means the requested click did not activate exactly one `<input type="file">`; the page may use a non-input picker such as `window.showOpenFilePicker()`. Do not retry blindly. If human help is available, call `request-help` and tell the user the exact original local path to choose. The staged daemon path is internal and must not be shown to the user.
+- `reason=file_input_probe_failed` means BrowserSkill could not safely establish the browser-side upload transaction. Do not repeat the same action; use `request-help` when available.
+- `reason=set_file_input_failed` means BrowserSkill found the activated file input but Chrome rejected the staged path or assignment. Check the extension's file-URL access permission; otherwise use `request-help`.
+- `reason=download_capture_failed` means BrowserSkill could not attribute exactly one completed download to the requested target. Do not retry blindly or accept an unrelated browser download; use `request-help` when available.
+- `effect_state=none` means BrowserSkill confirmed that no file-transfer effect was committed. Follow the accompanying reason; a corrected target or explicit human fallback may be attempted.
+- `effect_state=unknown` means the browser may already have attached or created the file. Do not repeat the transfer. Observe the page if that can establish the result; otherwise stop and report the uncertainty.
+- `effect_state=committed` means the browser-side effect occurred even if later completion or cleanup failed. Do not repeat it; continue only after verifying the resulting page/download state.
+
+If `request-help` returns `outcome="disabled"`, do not retry it. Stop gracefully and report the transfer mechanism that requires human intervention.
+
 ### Scripting & timing
 
 | Command | Summary |
@@ -313,48 +278,26 @@ bsk record start --browser <instance-id-or-label> \
 bsk record stop [--output trace]   # terminal fallback if the browser panel is unavailable
 ```
 
-- **v3 bundle (preferred):** `--output` is a directory (default `./trace`) containing `trace.json` and `states/`. `trace.json` lists `states[]` (page observation ids) and `steps[]` (each step binds `state` = observe snapshot *before* the action and `result.state` = snapshot *after* settle). Page bodies live in `states/sN.txt` using the same VOM format as `bsk observe`.
-- **v2 fallback:** when the connected extension is older, export may contain only legacy `trace.json` with `pages[]` action context and no `states/` observation files. Update the extension for full v3 bundles.
-- Each `states[]` entry is one **settled page observation** (captured after recording start, navigation landing, or action settle — not on a timer).
-- `target.ref` values like `@e12` exist **only inside** the bundle for disambiguation; do **not** copy `@eN` refs into SKILL.md or agent runbooks — use visible names from the observation text instead.
-- `--purpose` is optional context metadata; it does **not** change what gets captured.
-- `--redact-values` masks all form values in page files as `[filled]` / `[empty]`.
-- Do **not** record on banking/SSO/password-manager pages; passwords are redacted but traces may still contain sensitive text.
+`select` matches an option's `value` attribute, not its visible label. Device preset ids are
+lowercase and hyphenated, such as `iphone-14`.
 
-## Error handling
+- `console` and `network` provide bounded, read-only debugging evidence.
+- `emulate` applies viewport, user-agent, and touch overrides to one tab; new tabs do not inherit
+  them. Use `--off` to restore the real environment.
+- `evaluate` is a last resort when observe plus normal interactions cannot complete the task. With
+  `--json`, inspect `.ok`: a JavaScript exception may still have CLI exit code 0 because the RPC
+  succeeded. Never evaluate credential surfaces to read storage, cookies, or auth data.
+- `record` captures a user's actions for later replay. Read `bsk record start --help` before use,
+  and never record banking, SSO, password-manager, or other sensitive pages.
 
-### Exit codes (`echo $?` after `bsk …`)
+## Recover without wandering
 
-| Code | Meaning | What to do |
-|------|---------|------------|
-| `0` | Success (including `evaluate` where JS threw but RPC succeeded) | Continue; for `evaluate`, check `--json` `.ok` to distinguish JS success from RPC success |
-| `1` | User error — bad args, unknown session, tab not in Agent Window, stale ref | Fix args; `bsk session list`; re-snapshot |
-| `2` | Protocol / transport — service unreachable, IPC failure | `bsk doctor`; check extension connected; retry the command |
-| `3` | Browser / CDP execution failed | Retry; simplify selector; check tab still open |
-| `4` | Timeout | Increase `--timeout`; try `--wait-until domcontentloaded` |
-| `5` | Unknown RPC method | This command is not implemented in the current build. Continue the task with other commands. If a newly added command is missing, suggest `bsk update`. |
+- Stale ref: observe again and retry the intended action once.
+- Unknown tab or session: list current tabs/sessions; never guess identifiers.
+- Timeout: inspect current page state before deciding whether one longer purposeful wait is useful.
+- Unsupported command: continue with available capabilities; suggest updating only when the missing
+  command is necessary.
+- Unrecoverable failure: report the blocker and stop the session in a finally-style path.
 
-Human errors print `error:` + `hint:` on stderr; `--json` includes `code`, `message`, `hint`, `exit_code`.
-
-### When to run diagnostics
-
-| Situation | Command |
-|-----------|---------|
-| Before first task in a session | `bsk status` — extension connected? |
-| Any failure you cannot fix in one retry | `bsk doctor` |
-| Multiple browsers / wrong target | `bsk browsers` then `bsk session start --browser <id>` |
-
-Always **`bsk session stop <id>`** in a `finally`-style path so the Agent Window closes and borrowed tabs return.
-
-## Red lines
-
-1. **No token theft** — do not `bsk evaluate` on sensitive sites to read `localStorage`, cookies, or auth headers for exfiltration.
-2. **No long borrow** — do not leave a user's personal tab in the Agent Window across unrelated tasks.
-3. **No skip stop** — always `bsk session stop <id>`; never assume idle timeout will clean up.
-4. **No post-success control** — once the user’s goal (or last trace step) is met, do not keep operating the page; stop the session unless they asked to keep it open.
-5. **No raw observe escalation before snapshot/observe** — use `bsk snapshot` first; use `bsk observe` when VOM semantics or conditional surfaces help. Only use `bsk get-html` or `bsk screenshot` when snapshot/observe is insufficient. Element screenshots (`--ref @eN`) still require a fresh snapshot/observe ref — never skip observation just to grab a visual.
-6. **`evaluate` is powerful and risky** — use only when snapshot + click/fill/select cannot suffice; never on credential surfaces.
-
----
-
-**More detail for any command:** `bsk <cmd> --help`
+The CLI's current help and error hints are authoritative for flags, parameters, and recovery
+details.

crates/bsk-cli/src/cli/atomic_output.rs

@@ -0,0 +1,75 @@
+//! Atomic visibility boundary for files received into a same-directory temp.
+
+use std::path::Path;
+
+pub fn commit(temp: &Path, out: &Path, overwrite: bool) -> std::io::Result<()> {
+    if !overwrite {
+        std::fs::hard_link(temp, out)?;
+        std::fs::remove_file(temp)?;
+        return Ok(());
+    }
+    replace(temp, out)
+}
+
+#[cfg(unix)]
+fn replace(temp: &Path, out: &Path) -> std::io::Result<()> {
+    // POSIX rename replaces an existing non-directory destination atomically.
+    std::fs::rename(temp, out)
+}
+
+#[cfg(windows)]
+fn replace(temp: &Path, out: &Path) -> std::io::Result<()> {
+    use std::os::windows::ffi::OsStrExt;
+    use windows_sys::Win32::Storage::FileSystem::{
+        MOVEFILE_REPLACE_EXISTING, MOVEFILE_WRITE_THROUGH, MoveFileExW,
+    };
+
+    let from: Vec<u16> = temp.as_os_str().encode_wide().chain(Some(0)).collect();
+    let to: Vec<u16> = out.as_os_str().encode_wide().chain(Some(0)).collect();
+    // SAFETY: both buffers are NUL-terminated and remain alive for the call.
+    let ok = unsafe {
+        MoveFileExW(
+            from.as_ptr(),
+            to.as_ptr(),
+            MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,
+        )
+    };
+    if ok == 0 {
+        Err(std::io::Error::last_os_error())
+    } else {
+        Ok(())
+    }
+}
+
+#[cfg(not(any(unix, windows)))]
+fn replace(temp: &Path, out: &Path) -> std::io::Result<()> {
+    std::fs::rename(temp, out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn no_replace_never_overwrites_existing_output() {
+        let dir = tempfile::tempdir().unwrap();
+        let temp = dir.path().join("new.part");
+        let out = dir.path().join("out.bin");
+        std::fs::write(&temp, b"new").unwrap();
+        std::fs::write(&out, b"old").unwrap();
+        assert!(commit(&temp, &out, false).is_err());
+        assert_eq!(std::fs::read(&out).unwrap(), b"old");
+    }
+
+    #[test]
+    fn overwrite_replaces_existing_output_without_predelete() {
+        let dir = tempfile::tempdir().unwrap();
+        let temp = dir.path().join("new.part");
+        let out = dir.path().join("out.bin");
+        std::fs::write(&temp, b"new").unwrap();
+        std::fs::write(&out, b"old").unwrap();
+        commit(&temp, &out, true).unwrap();
+        assert_eq!(std::fs::read(&out).unwrap(), b"new");
+        assert!(!temp.exists());
+    }
+}

crates/bsk-cli/src/cli/download.rs

@@ -0,0 +1,147 @@
+//! `bsk download` — capture one browser download and atomically commit it.
+
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use anyhow::Context;
+use base64::Engine;
+use bsk_protocol::Method;
+use bsk_protocol::tools::{
+    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult, TransferIdParams,
+    TransferReleaseResult,
+};
+use clap::Args;
+use uuid::Uuid;
+
+use crate::cli::atomic_output;
+use crate::cli::ensure_daemon::ensure_daemon;
+use crate::cli::error::{CliError, Format};
+use crate::cli::interaction::split_target;
+use crate::cli::navigate::parse_timeout_ms;
+
+#[derive(Debug, Clone, Args)]
+pub struct DownloadArgs {
+    /// Snapshot ref (`@e3`) or CSS selector for the download trigger.
+    pub target: Option<String>,
+    #[arg(long = "ref")]
+    pub ref_: Option<String>,
+    #[arg(long = "selector")]
+    pub selector: Option<String>,
+    #[arg(long)]
+    pub out: PathBuf,
+    #[arg(long)]
+    pub session: String,
+    #[arg(long = "tab-id")]
+    pub tab_id: Option<i64>,
+    #[arg(long, default_value = "2m", value_parser = parse_timeout_ms)]
+    pub timeout: u32,
+    #[arg(long)]
+    pub overwrite: bool,
+}
+
+pub fn dispatch(args: DownloadArgs, format: Format) -> Result<(), CliError> {
+    if args.out.exists() && !args.overwrite {
+        return Err(CliError::Local(anyhow::anyhow!(
+            "output already exists (pass --overwrite to replace it): {}",
+            args.out.display()
+        )));
+    }
+    let info = ensure_daemon().context("ensure daemon is running")?;
+    let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
+    let params = DownloadParams {
+        session_id: args.session,
+        ref_,
+        selector,
+        tab_id: args.tab_id,
+        timeout_ms: Some(args.timeout),
+        browser_relative_dir: None,
+        max_byte_size: None,
+    };
+    let reply: DownloadResult = crate::cli::business_rpc::call(
+        info.sock_path.clone(),
+        "download",
+        Method::ToolDownload,
+        Some(params),
+        ipc_timeout(args.timeout),
+    )?;
+    let transfer_id = reply.transfer_id.clone().ok_or_else(|| {
+        CliError::Local(anyhow::anyhow!("daemon returned no download transfer id"))
+    })?;
+    let write_result = write_transfer(&info.sock_path, &transfer_id, &args.out, args.overwrite);
+    let _: Result<TransferReleaseResult, CliError> = crate::cli::business_rpc::call(
+        info.sock_path,
+        "transfer-release",
+        Method::TransferRelease,
+        Some(TransferIdParams { transfer_id }),
+        Duration::from_secs(5),
+    );
+    write_result?;
+    match format {
+        Format::Json => {
+            let mut value = serde_json::to_value(&reply).unwrap();
+            value["path"] = serde_json::json!(args.out.to_string_lossy());
+            if let Some(obj) = value.as_object_mut() {
+                obj.remove("transfer_id");
+                obj.remove("browser_path");
+            }
+            println!("{}", serde_json::to_string_pretty(&value).unwrap());
+        }
+        Format::Human => println!("{}", args.out.display()),
+    }
+    Ok(())
+}
+
+fn write_transfer(sock: &Path, id: &str, out: &Path, overwrite: bool) -> Result<(), CliError> {
+    let parent = out
+        .parent()
+        .filter(|p| !p.as_os_str().is_empty())
+        .unwrap_or(Path::new("."));
+    let temp = parent.join(format!(".bsk-download-{}.part", Uuid::new_v4().simple()));
+    let result = (|| {
+        let mut file = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&temp)
+            .with_context(|| format!("create temporary download {}", temp.display()))
+            .map_err(CliError::Local)?;
+        let mut offset = 0u64;
+        loop {
+            let chunk: TransferChunkResult = crate::cli::business_rpc::call(
+                sock.to_path_buf(),
+                "transfer-read",
+                Method::TransferRead,
+                Some(TransferChunkParams {
+                    transfer_id: id.to_string(),
+                    offset,
+                    data_base64: String::new(),
+                }),
+                Duration::from_secs(30),
+            )?;
+            let encoded = chunk.data_base64.as_deref().unwrap_or("");
+            let bytes = base64::engine::general_purpose::STANDARD
+                .decode(encoded)
+                .map_err(|e| CliError::Local(anyhow::anyhow!("decode download chunk: {e}")))?;
+            file.write_all(&bytes)
+                .map_err(|e| CliError::Local(e.into()))?;
+            offset = chunk.next_offset;
+            if chunk.eof {
+                break;
+            }
+        }
+        file.sync_all().map_err(|e| CliError::Local(e.into()))?;
+        drop(file);
+        atomic_output::commit(&temp, out, overwrite)
+            .with_context(|| format!("atomically commit download to {}", out.display()))
+            .map_err(CliError::Local)
+    })();
+    if result.is_err() {
+        let _ = std::fs::remove_file(&temp);
+    }
+    result
+}
+
+fn ipc_timeout(timeout_ms: u32) -> Duration {
+    Duration::from_millis(u64::from(timeout_ms) + 5_000)
+}

crates/bsk-cli/src/cli/interaction.rs

@@ -11,7 +11,7 @@ use anyhow::Context;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
     ClickParams, ClickResult, FillParams, FillResult, HoverParams, HoverResult, KeyModifier,
-    MouseButton, PressParams, PressResult, SelectParams, SelectResult, TypeParams, TypeResult,
+    MouseButton, PressParams, PressResult, SelectParams, SelectResult,
 };
 use clap::{Args, ValueEnum};
 
@@ -71,7 +71,7 @@ pub(crate) fn parse_modifiers(input: &str) -> Result<Vec<KeyModifier>, String> {
     Ok(out)
 }
 
-fn split_target(
+pub(crate) fn split_target(
     positional: Option<String>,
     explicit_ref: Option<String>,
     explicit_selector: Option<String>,
@@ -95,27 +95,6 @@ fn split_target(
     }
 }
 
-fn split_type_target(
-    positional: Option<String>,
-    explicit_ref: Option<String>,
-    explicit_selector: Option<String>,
-    focused: bool,
-) -> Result<(Option<String>, Option<String>), CliError> {
-    if focused {
-        if positional.is_some() || explicit_ref.is_some() || explicit_selector.is_some() {
-            return Err(CliError::Local(anyhow::anyhow!(
-                "pass a target or --focused, not both"
-            )));
-        }
-        return Ok((None, None));
-    }
-    split_target(positional, explicit_ref, explicit_selector).map_err(|_| {
-        CliError::Local(anyhow::anyhow!(
-            "type requires exactly one of: <target>, --ref, --selector, or --focused"
-        ))
-    })
-}
-
 // ---------------------------------------------------------------------------
 // bsk click
 // ---------------------------------------------------------------------------
@@ -157,18 +136,6 @@ pub struct ClickArgs {
 
     #[arg(long, default_value = "30s", value_parser = parse_timeout_ms)]
     pub timeout: u32,
-
-    /// Capture id returned by `bsk screenshot --ref <surface>`.
-    #[arg(long)]
-    pub capture: Option<String>,
-
-    /// X coordinate in capture-image pixels. Requires `--capture` and `--image-y`.
-    #[arg(long = "image-x", allow_hyphen_values = true)]
-    pub image_x: Option<f64>,
-
-    /// Y coordinate in capture-image pixels. Requires `--capture` and `--image-x`.
-    #[arg(long = "image-y", allow_hyphen_values = true)]
-    pub image_y: Option<f64>,
 }
 
 pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
@@ -180,14 +147,6 @@ pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
     )?;
     let modifiers = parse_modifiers(&args.modifiers)
         .map_err(|e| CliError::Local(anyhow::anyhow!("--modifiers: {e}")))?;
-    let point_arg_count = usize::from(args.capture.is_some())
-        + usize::from(args.image_x.is_some())
-        + usize::from(args.image_y.is_some());
-    if point_arg_count != 0 && point_arg_count != 3 {
-        return Err(CliError::Local(anyhow::anyhow!(
-            "--capture, --image-x, and --image-y must be given together"
-        )));
-    }
     let params = ClickParams {
         session_id: args.session.clone(),
         ref_,
@@ -201,9 +160,6 @@ pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
             Some(modifiers)
         },
         timeout_ms: Some(args.timeout),
-        capture_id: args.capture.clone(),
-        image_x: args.image_x,
-        image_y: args.image_y,
     };
     let reply: ClickResult = call(
         info.sock_path,
@@ -227,14 +183,6 @@ pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
                 "click ok tab={} target={target} at=({}, {})",
                 reply.tab_id, reply.x, reply.y
             );
-            if let Some(capture_id) = &reply.capture_id {
-                println!(
-                    "capture={} image=({}, {}) coordinate_space=capture-image-pixel",
-                    capture_id,
-                    reply.image_x.unwrap_or_default(),
-                    reply.image_y.unwrap_or_default()
-                );
-            }
             print_dialog_summaries(&reply.dialogs);
         }
     }
@@ -404,95 +352,6 @@ pub fn dispatch_fill(args: FillArgs, format: Format) -> Result<(), CliError> {
     Ok(())
 }
 
-// ---------------------------------------------------------------------------
-// bsk type
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Clone, Args)]
-#[group(id = "type_destination", required = true, multiple = false)]
-pub struct TypeDestinationArgs {
-    /// Snapshot ref (`@e3`, `e3`) or CSS selector to focus before insertion.
-    #[arg(value_name = "TARGET")]
-    pub target: Option<String>,
-
-    #[arg(long = "ref")]
-    pub ref_: Option<String>,
-
-    #[arg(long = "selector")]
-    pub selector: Option<String>,
-
-    /// Insert into the unique focused text-entry target instead of focusing a target.
-    #[arg(long)]
-    pub focused: bool,
-}
-
-#[derive(Debug, Clone, Args)]
-pub struct TypeArgs {
-    #[command(flatten)]
-    pub destination: TypeDestinationArgs,
-
-    /// Text to dispatch through the live keyboard/IME editing session.
-    #[arg(long)]
-    pub text: String,
-
-    #[arg(long)]
-    pub session: String,
-
-    #[arg(long = "tab-id")]
-    pub tab_id: Option<i64>,
-
-    #[arg(long, default_value = "30s", value_parser = parse_timeout_ms)]
-    pub timeout: u32,
-}
-
-pub fn dispatch_type(args: TypeArgs, format: Format) -> Result<(), CliError> {
-    let (ref_, selector) = split_type_target(
-        args.destination.target.clone(),
-        args.destination.ref_.clone(),
-        args.destination.selector.clone(),
-        args.destination.focused,
-    )?;
-    let info = ensure_daemon().context("ensure daemon is running")?;
-    let params = TypeParams {
-        session_id: args.session.clone(),
-        text: args.text.clone(),
-        ref_,
-        selector,
-        focused: args.destination.focused,
-        tab_id: args.tab_id,
-        timeout_ms: Some(args.timeout),
-    };
-    let reply: TypeResult = call(
-        info.sock_path,
-        Method::ToolType,
-        params,
-        "type-1",
-        args.timeout,
-    )?;
-    match format {
-        Format::Json => {
-            println!(
-                "{}",
-                serde_json::to_string_pretty(&reply)
-                    .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?
-            );
-        }
-        Format::Human => {
-            let target = if args.destination.focused {
-                "focused".into()
-            } else {
-                format_used_target(reply.used_ref.as_deref(), reply.used_selector.as_deref())
-            };
-            println!(
-                "type dispatched tab={} target={target} length={} verification=dispatched",
-                reply.tab_id, reply.text_length
-            );
-            print_dialog_summaries(&reply.dialogs);
-        }
-    }
-    Ok(())
-}
-
 // ---------------------------------------------------------------------------
 // bsk press
 // ---------------------------------------------------------------------------
@@ -769,52 +628,6 @@ mod tests {
         assert_eq!(parsed.args.session, "ohli");
     }
 
-    #[test]
-    fn type_clap_accepts_explicit_target_and_text_flag() {
-        use clap::Parser;
-
-        #[derive(Parser)]
-        #[command(name = "type")]
-        struct Wrapper {
-            #[command(flatten)]
-            args: TypeArgs,
-        }
-
-        let parsed =
-            Wrapper::try_parse_from(["type", "@e138", "--text", "测试", "--session", "ohli"])
-                .expect("type args should parse");
-        assert_eq!(parsed.args.destination.target.as_deref(), Some("@e138"));
-        assert_eq!(parsed.args.text, "测试");
-        assert_eq!(parsed.args.session, "ohli");
-    }
-
-    #[test]
-    fn type_targeting_requires_exactly_one_explicit_mode() {
-        use clap::Parser;
-
-        #[derive(Parser)]
-        #[command(name = "type")]
-        struct Wrapper {
-            #[command(flatten)]
-            args: TypeArgs,
-        }
-
-        let parsed =
-            Wrapper::try_parse_from(["type", "--focused", "--text", "测试", "--session", "ohli"])
-                .expect("focused type args should parse");
-        assert!(parsed.args.destination.focused);
-        assert!(parsed.args.destination.target.is_none());
-
-        let focused = split_type_target(None, None, None, true).unwrap();
-        assert_eq!(focused, (None, None));
-
-        let missing = split_type_target(None, None, None, false).unwrap_err();
-        assert!(missing.to_string().contains("--focused"));
-
-        let mixed = split_type_target(Some("@e1".into()), None, None, true).unwrap_err();
-        assert!(mixed.to_string().contains("not both"));
-    }
-
     #[test]
     fn select_clap_accepts_target_positional_with_repeated_value_flags() {
         use clap::Parser;

crates/bsk-cli/src/cli/mod.rs

@@ -2,6 +2,7 @@
 
 use std::time::Duration;
 
+mod atomic_output;
 pub mod browser_wait;
 pub mod browsers;
 pub mod business_rpc;
@@ -9,6 +10,7 @@ pub mod console;
 pub mod daemon;
 pub mod dialogs;
 pub mod doctor;
+pub mod download;
 pub mod emulate;
 pub mod ensure_daemon;
 pub mod error;
@@ -31,6 +33,7 @@ pub mod snapshot;
 pub mod status;
 pub mod tab;
 pub mod update;
+pub mod upload;
 pub mod waits;
 pub mod window;
 
@@ -38,12 +41,13 @@ use clap::{Args, Parser, Subcommand};
 
 use crate::cli::console::ConsoleArgs;
 use crate::cli::daemon::DaemonCmd;
+use crate::cli::download::DownloadArgs;
 use crate::cli::emulate::EmulateArgs;
 use crate::cli::evaluate::EvaluateArgs;
 use crate::cli::get_html::GetHtmlArgs;
 use crate::cli::human_loop::RequestHelpArgs;
 use crate::cli::install_skill::InstallSkillArgs;
-use crate::cli::interaction::{ClickArgs, FillArgs, HoverArgs, PressArgs, SelectArgs, TypeArgs};
+use crate::cli::interaction::{ClickArgs, FillArgs, HoverArgs, PressArgs, SelectArgs};
 use crate::cli::navigate::{NavigateCommand, NavigateHistoryArgs, ReloadArgs};
 use crate::cli::network::NetworkArgs;
 use crate::cli::observe::ObserveArgs;
@@ -53,6 +57,7 @@ use crate::cli::session::SessionCmd;
 use crate::cli::snapshot::SnapshotArgs;
 use crate::cli::tab::TabCmd;
 use crate::cli::update::UpdateArgs;
+use crate::cli::upload::UploadArgs;
 use crate::cli::waits::{WaitForNavigationArgs, WaitMsArgs};
 use crate::cli::window::WindowCmd;
 
@@ -171,15 +176,18 @@ pub enum Command {
     /// Fill an input / textarea / contenteditable.
     Fill(FillArgs),
 
-    /// Insert text into an explicit target or focused keyboard/IME editing session.
-    Type(TypeArgs),
-
     /// Dispatch a keyboard key combo.
     Press(PressArgs),
 
     /// Set `<select>` option values by `value` attribute.
     Select(SelectArgs),
 
+    /// Upload one or more local files through a page file chooser.
+    Upload(UploadArgs),
+
+    /// Capture one browser download and write it to a local path.
+    Download(DownloadArgs),
+
     /// Evaluate a JavaScript expression inside the Agent Window.
     Evaluate(EvaluateArgs),
 

crates/bsk-cli/src/cli/observe.rs

@@ -33,6 +33,12 @@ pub struct ObserveArgs {
     /// Include conditional surface probe diagnostics in JSON output.
     #[arg(long = "debug-surfaces")]
     pub debug_surfaces: bool,
+
+    /// Actively hover page controls to reveal hover-only menus and tooltips.
+    /// Costs seconds of wall clock and touches the live page, so it is off
+    /// unless a static observation looks like it is missing hover content.
+    #[arg(long = "probe-hover")]
+    pub probe_hover: bool,
 }
 
 pub fn dispatch(args: ObserveArgs, format: Format) -> Result<(), CliError> {
@@ -47,6 +53,7 @@ fn run(sock: PathBuf, args: ObserveArgs, format: Format) -> Result<(), CliError>
         max_depth: args.max_depth,
         max_tokens: args.max_tokens,
         debug_surfaces: args.debug_surfaces,
+        probe_hover: args.probe_hover,
     };
     let reply: ObserveResult = call(sock, params)?;
     match format {

crates/bsk-cli/src/cli/render_error.rs

@@ -44,19 +44,18 @@ pub mod reason {
     pub const REF_NOT_FOUND: &str = "ref_not_found";
     pub const SELECTOR_NOT_FOUND: &str = "selector_not_found";
     pub const TARGET_NOT_FILLABLE: &str = "target_not_fillable";
-    pub const FOCUS_TARGET_UNRESOLVED: &str = "focus_target_unresolved";
-    pub const INPUT_NOT_APPLIED: &str = "input_not_applied";
     pub const TARGET_NOT_SELECT: &str = "target_not_select";
     pub const OPTION_NOT_FOUND: &str = "option_not_found";
     pub const SINGLE_SELECT_VALUE_COUNT: &str = "single_select_value_count";
     pub const TAB_NOT_ACTIVE: &str = "tab_not_active";
     pub const BORROW_CONFLICT: &str = "borrow_conflict";
     pub const SCREENSHOT_CAPTURE_FAILED: &str = "screenshot_capture_failed";
-    pub const SURFACE_CAPTURE_NOT_FOUND: &str = "surface_capture_not_found";
-    pub const SURFACE_CAPTURE_EXPIRED: &str = "surface_capture_expired";
-    pub const SURFACE_CAPTURE_CONSUMED: &str = "surface_capture_consumed";
-    pub const SURFACE_CAPTURE_STALE: &str = "surface_capture_stale";
-    pub const SURFACE_COORDINATE_INVALID: &str = "surface_coordinate_invalid";
+    pub const FILE_INPUT_PROBE_FAILED: &str = "file_input_probe_failed";
+    pub const FILE_INPUT_NOT_ACTIVATED: &str = "file_input_not_activated";
+    pub const SET_FILE_INPUT_FAILED: &str = "set_file_input_failed";
+    pub const DOWNLOAD_CAPTURE_FAILED: &str = "download_capture_failed";
+    pub const TRANSFER_OUTCOME_UNKNOWN: &str = "transfer_outcome_unknown";
+    pub const TRANSFER_TIMEOUT: &str = "transfer_timeout";
     pub const SESSION_BUSY: &str = crate::rpc_reason::SESSION_BUSY;
     pub const RECORD_START_PAGE_UNREACHABLE: &str = "record_start_page_unreachable";
 }
@@ -205,6 +204,20 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         return base;
     };
     match (code, reason) {
+        (_, reason::TRANSFER_OUTCOME_UNKNOWN) => RenderInfo {
+            summary: "the file transfer outcome could not be confirmed",
+            hint: Some(
+                "do not retry the transfer: the browser may already have applied it; inspect the page or stop safely",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::Timeout, reason::TRANSFER_TIMEOUT) => RenderInfo {
+            summary: "the file transfer timed out after browser dispatch",
+            hint: Some(
+                "do not retry when effect_state is unknown or committed; inspect the page before taking another action",
+            ),
+            exit_code: base.exit_code,
+        },
         (ErrorCode::PermissionDenied, reason::ELEMENT_NOT_VISIBLE) => RenderInfo {
             summary: "target element has no visible geometry",
             hint: Some(
@@ -236,24 +249,10 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
-        (ErrorCode::CdpFailed, reason::FOCUS_TARGET_UNRESOLVED) => RenderInfo {
-            summary: "focused frame target could not be determined",
-            hint: Some(
-                "pass an explicit --ref or --selector so the key event can be routed safely",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::CdpFailed, reason::INPUT_NOT_APPLIED) => RenderInfo {
-            summary: "the page did not retain the requested input",
-            hint: Some(
-                "refresh the snapshot and retry; the page may be rejecting or resetting controlled input",
-            ),
-            exit_code: base.exit_code,
-        },
         (ErrorCode::PermissionDenied, reason::REF_CAPABILITY_DENIED) => RenderInfo {
             summary: "snapshot ref does not support this operation",
             hint: Some(
-                "visual Surface refs require image understanding; inspect `bsk screenshot --ref <ref> --session <id>`, then bind its capture id and image coordinates to `bsk click`",
+                "visual surface refs are screenshot-only; inspect `bsk screenshot --ref <ref> --session <id>` with image-understanding capability",
             ),
             exit_code: base.exit_code,
         },
@@ -299,41 +298,6 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
-        (ErrorCode::NotFound, reason::SURFACE_CAPTURE_NOT_FOUND) => RenderInfo {
-            summary: "surface capture transaction was not found",
-            hint: Some(
-                "take a fresh surface screenshot and use its capture id with coordinates from that image",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::PermissionDenied, reason::SURFACE_CAPTURE_EXPIRED) => RenderInfo {
-            summary: "surface capture transaction has expired",
-            hint: Some(
-                "take a fresh surface screenshot, then click promptly with that capture id and image coordinates",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::PermissionDenied, reason::SURFACE_CAPTURE_CONSUMED) => RenderInfo {
-            summary: "surface capture transaction was already used",
-            hint: Some(
-                "each capture id is single-use; take a fresh surface screenshot before another point action",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::PermissionDenied, reason::SURFACE_CAPTURE_STALE) => RenderInfo {
-            summary: "page state changed since the surface screenshot",
-            hint: Some(
-                "take a fresh surface screenshot and choose coordinates from the new image before retrying",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::InvalidParams, reason::SURFACE_COORDINATE_INVALID) => RenderInfo {
-            summary: "surface image coordinate is invalid",
-            hint: Some(
-                "use finite pixel coordinates inside the captured image; its top-left corner is (0, 0)",
-            ),
-            exit_code: base.exit_code,
-        },
         (
             ErrorCode::CdpFailed | ErrorCode::Timeout | ErrorCode::InvalidParams,
             reason::RECORD_START_PAGE_UNREACHABLE,
@@ -344,6 +308,36 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
+        (ErrorCode::Unsupported, reason::FILE_INPUT_NOT_ACTIVATED) => RenderInfo {
+            summary: "the upload trigger did not activate a file input",
+            hint: Some(
+                "the page may use a non-input picker such as showOpenFilePicker(); do not retry blindly — use `bsk request-help` with the exact original local path, or stop if human help is disabled",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::Timeout | ErrorCode::CdpFailed, reason::FILE_INPUT_PROBE_FAILED) => {
+            RenderInfo {
+                summary: "the browser upload transaction could not be established",
+                hint: Some(
+                    "do not retry the same upload blindly; use `bsk request-help` when human help is available",
+                ),
+                exit_code: base.exit_code,
+            }
+        }
+        (ErrorCode::Timeout | ErrorCode::CdpFailed, reason::SET_FILE_INPUT_FAILED) => RenderInfo {
+            summary: "the browser could not attach the staged file to the input",
+            hint: Some(
+                "check that BrowserSkill has Chrome's 'Allow access to file URLs' permission; otherwise use `bsk request-help`",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::DOWNLOAD_CAPTURE_FAILED) => RenderInfo {
+            summary: "the browser download could not be attributed or completed",
+            hint: Some(
+                "do not retry blindly; the target browser may not expose a reliable download intent signal",
+            ),
+            exit_code: base.exit_code,
+        },
         _ => base,
     }
 }
@@ -447,7 +441,7 @@ mod tests {
         let info = info_for_error(ErrorCode::PermissionDenied, Some(&data));
         assert_eq!(info.summary, "snapshot ref does not support this operation");
         assert!(
-            info.hint.unwrap().contains("capture id"),
+            info.hint.unwrap().contains("screenshot-only"),
             "expected visual-surface-specific hint"
         );
         assert_eq!(info.exit_code, 1);
@@ -496,22 +490,35 @@ mod tests {
     }
 
     #[test]
-    fn surface_capture_stale_requests_a_fresh_screenshot() {
-        let data = serde_json::json!({ "reason": reason::SURFACE_CAPTURE_STALE });
-        let info = info_for_error(ErrorCode::PermissionDenied, Some(&data));
+    fn file_transfer_reasons_render_actionable_fallbacks() {
+        let unsupported = serde_json::json!({ "reason": reason::FILE_INPUT_NOT_ACTIVATED });
+        let info = info_for_error(ErrorCode::Unsupported, Some(&unsupported));
         assert_eq!(
             info.summary,
-            "page state changed since the surface screenshot"
+            "the upload trigger did not activate a file input"
         );
-        assert!(info.hint.unwrap().contains("fresh surface screenshot"));
-    }
+        assert!(info.hint.unwrap().contains("exact original local path"));
 
-    #[test]
-    fn surface_coordinate_invalid_explains_image_pixel_bounds() {
-        let data = serde_json::json!({ "reason": reason::SURFACE_COORDINATE_INVALID });
-        let info = info_for_error(ErrorCode::InvalidParams, Some(&data));
-        assert_eq!(info.summary, "surface image coordinate is invalid");
-        assert!(info.hint.unwrap().contains("top-left corner is (0, 0)"));
+        let control = serde_json::json!({ "reason": reason::FILE_INPUT_PROBE_FAILED });
+        let info = info_for_error(ErrorCode::Timeout, Some(&control));
+        assert!(
+            info.summary
+                .contains("transaction could not be established")
+        );
+        assert!(info.hint.unwrap().contains("do not retry"));
+
+        let download = serde_json::json!({ "reason": reason::DOWNLOAD_CAPTURE_FAILED });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&download));
+        assert!(info.summary.contains("download could not be attributed"));
+
+        let unknown = serde_json::json!({ "reason": reason::TRANSFER_OUTCOME_UNKNOWN });
+        let info = info_for_error(ErrorCode::ProtocolError, Some(&unknown));
+        assert!(info.summary.contains("outcome could not be confirmed"));
+        assert!(info.hint.unwrap().contains("do not retry"));
+
+        let timeout = serde_json::json!({ "reason": reason::TRANSFER_TIMEOUT });
+        let info = info_for_error(ErrorCode::Timeout, Some(&timeout));
+        assert!(info.summary.contains("timed out after browser dispatch"));
     }
 
     #[test]
@@ -548,20 +555,4 @@ mod tests {
         );
         assert!(info.hint.unwrap().contains("exactly one"));
     }
-
-    #[test]
-    fn focus_target_unresolved_overrides_cdp_copy() {
-        let data = serde_json::json!({ "reason": reason::FOCUS_TARGET_UNRESOLVED });
-        let info = info_for_error(ErrorCode::CdpFailed, Some(&data));
-        assert_eq!(info.summary, "focused frame target could not be determined");
-        assert!(info.hint.unwrap().contains("--ref"));
-    }
-
-    #[test]
-    fn input_not_applied_overrides_cdp_copy() {
-        let data = serde_json::json!({ "reason": reason::INPUT_NOT_APPLIED });
-        let info = info_for_error(ErrorCode::CdpFailed, Some(&data));
-        assert_eq!(info.summary, "the page did not retain the requested input");
-        assert!(info.hint.unwrap().contains("rejecting"));
-    }
 }

crates/bsk-cli/src/cli/screenshot.rs

@@ -59,7 +59,7 @@ fn run(sock: PathBuf, args: ScreenshotArgs, format: Format) -> Result<(), CliErr
         .map_err(CliError::Local)?;
     match format {
         Format::Json => {
-            let mut json = serde_json::json!({
+            let json = serde_json::json!({
                 "tab_id": reply.tab_id,
                 "width": reply.width,
                 "height": reply.height,
@@ -67,10 +67,6 @@ fn run(sock: PathBuf, args: ScreenshotArgs, format: Format) -> Result<(), CliErr
                 "path": out_path.to_string_lossy(),
                 "byte_size": bytes.len(),
             });
-            if let Some(capture) = &reply.capture {
-                json["capture"] = serde_json::to_value(capture)
-                    .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?;
-            }
             println!(
                 "{}",
                 serde_json::to_string_pretty(&json)
@@ -79,12 +75,6 @@ fn run(sock: PathBuf, args: ScreenshotArgs, format: Format) -> Result<(), CliErr
         }
         Format::Human => {
             println!("{}", out_path.display());
-            if let Some(capture) = &reply.capture {
-                println!(
-                    "capture={} surface={} coordinate_space={} expires_at={}",
-                    capture.id, capture.surface_ref, capture.coordinate_space, capture.expires_at
-                );
-            }
             print_dialog_summaries(&reply.dialogs);
         }
     }

crates/bsk-cli/src/cli/upload.rs

@@ -0,0 +1,185 @@
+//! `bsk upload` — stage caller-readable files and attach them to a page.
+
+use std::fs::File;
+use std::io::Read;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use anyhow::Context;
+use base64::Engine;
+use bsk_protocol::Method;
+use bsk_protocol::tools::{
+    TransferBeginParams, TransferBeginResult, TransferChunkParams, TransferChunkResult,
+    TransferIdParams, TransferReadyResult, TransferReleaseResult, UploadFile, UploadParams,
+    UploadResult,
+};
+use clap::Args;
+
+use crate::cli::ensure_daemon::ensure_daemon;
+use crate::cli::error::{CliError, Format};
+use crate::cli::interaction::split_target;
+use crate::cli::navigate::parse_timeout_ms;
+
+#[derive(Debug, Clone, Args)]
+pub struct UploadArgs {
+    /// Snapshot ref (`@e3`) or CSS selector for the file input / chooser trigger.
+    pub target: Option<String>,
+    #[arg(long = "ref")]
+    pub ref_: Option<String>,
+    #[arg(long = "selector")]
+    pub selector: Option<String>,
+    /// Local file to upload. Repeat for a multiple-file input.
+    #[arg(long = "file", required = true)]
+    pub files: Vec<PathBuf>,
+    #[arg(long)]
+    pub session: String,
+    #[arg(long = "tab-id")]
+    pub tab_id: Option<i64>,
+    #[arg(long, default_value = "2m", value_parser = parse_timeout_ms)]
+    pub timeout: u32,
+}
+
+pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
+    if args.files.len() > crate::daemon::file_transfer::MAX_UPLOAD_FILES {
+        return Err(CliError::Local(anyhow::anyhow!(
+            "upload accepts at most {} files",
+            crate::daemon::file_transfer::MAX_UPLOAD_FILES
+        )));
+    }
+    let info = ensure_daemon().context("ensure daemon is running")?;
+    let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
+    let mut staged = Vec::new();
+    for path in &args.files {
+        match stage_file(&info.sock_path, &args.session, path) {
+            Ok(file) => staged.push(file),
+            Err(err) => {
+                for (id, _) in &staged {
+                    let _ = release(&info.sock_path, id);
+                }
+                return Err(err);
+            }
+        }
+    }
+    let params = UploadParams {
+        session_id: args.session,
+        ref_,
+        selector,
+        tab_id: args.tab_id,
+        files: staged
+            .iter()
+            .map(|(id, name)| UploadFile {
+                transfer_id: id.clone(),
+                name: name.clone(),
+                staged_path: None,
+            })
+            .collect(),
+        timeout_ms: Some(args.timeout),
+    };
+    let result = crate::cli::business_rpc::call::<_, UploadResult>(
+        info.sock_path.clone(),
+        "upload",
+        Method::ToolUpload,
+        Some(params),
+        ipc_timeout(args.timeout),
+    );
+    // Once tool.upload is dispatched, staging ownership belongs to the
+    // session. A transport timeout cannot prove that Chrome did not attach
+    // the file, so releasing here could invalidate a late successful attach.
+    // Session teardown remains the single cleanup boundary after dispatch.
+    let reply = result?;
+    match format {
+        Format::Json => println!("{}", serde_json::to_string_pretty(&reply).unwrap()),
+        Format::Human => println!(
+            "upload ok tab={} files={}",
+            reply.tab_id,
+            reply.file_names.join(", ")
+        ),
+    }
+    Ok(())
+}
+
+fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, String), CliError> {
+    let mut file = File::open(path)
+        .with_context(|| format!("open upload file {}", path.display()))
+        .map_err(CliError::Local)?;
+    let meta = file
+        .metadata()
+        .with_context(|| format!("read upload file metadata {}", path.display()))
+        .map_err(CliError::Local)?;
+    if !meta.is_file() {
+        return Err(CliError::Local(anyhow::anyhow!(
+            "upload source is not a regular file: {}",
+            path.display()
+        )));
+    }
+    let name = path
+        .file_name()
+        .and_then(|v| v.to_str())
+        .filter(|v| !v.is_empty())
+        .ok_or_else(|| CliError::Local(anyhow::anyhow!("upload file has no valid basename")))?
+        .to_string();
+    let begin: TransferBeginResult = crate::cli::business_rpc::call(
+        sock.to_path_buf(),
+        "transfer-begin",
+        Method::TransferBegin,
+        Some(TransferBeginParams {
+            session_id: session.to_string(),
+            name: name.clone(),
+            byte_size: meta.len(),
+        }),
+        Duration::from_secs(10),
+    )?;
+    let staged = (|| {
+        let mut offset = 0u64;
+        let mut buf = vec![0u8; begin.chunk_size as usize];
+        loop {
+            let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
+            if n == 0 {
+                break;
+            }
+            let reply: TransferChunkResult = crate::cli::business_rpc::call(
+                sock.to_path_buf(),
+                "transfer-chunk",
+                Method::TransferChunk,
+                Some(TransferChunkParams {
+                    transfer_id: begin.transfer_id.clone(),
+                    offset,
+                    data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
+                }),
+                Duration::from_secs(30),
+            )?;
+            offset = reply.next_offset;
+        }
+        let _: TransferReadyResult = crate::cli::business_rpc::call(
+            sock.to_path_buf(),
+            "transfer-finish",
+            Method::TransferFinish,
+            Some(TransferIdParams {
+                transfer_id: begin.transfer_id.clone(),
+            }),
+            Duration::from_secs(10),
+        )?;
+        Ok::<_, CliError>(())
+    })();
+    if let Err(err) = staged {
+        let _ = release(sock, &begin.transfer_id);
+        return Err(err);
+    }
+    Ok((begin.transfer_id, name))
+}
+
+fn release(sock: &Path, id: &str) -> Result<TransferReleaseResult, CliError> {
+    crate::cli::business_rpc::call(
+        sock.to_path_buf(),
+        "transfer-release",
+        Method::TransferRelease,
+        Some(TransferIdParams {
+            transfer_id: id.to_string(),
+        }),
+        Duration::from_secs(5),
+    )
+}
+
+fn ipc_timeout(timeout_ms: u32) -> Duration {
+    Duration::from_millis(u64::from(timeout_ms) + 5_000)
+}

crates/bsk-cli/src/daemon/file_transfer.rs

@@ -0,0 +1,728 @@
+//! Session-scoped, content-transparent staging for upload/download tools.
+//!
+//! The registry deliberately exposes no arbitrary-path operations. Upload
+//! bytes arrive from the invoking CLI in bounded chunks; browser downloads
+//! land in a daemon-minted directory and are read back by the invoking CLI.
+
+use std::collections::HashMap;
+use std::fs::{self, File, OpenOptions};
+use std::io::{Read, Seek, SeekFrom, Write};
+use std::path::{Component, Path, PathBuf};
+use std::sync::Mutex;
+
+use base64::Engine;
+use bsk_protocol::tools::{
+    TransferBeginParams, TransferBeginResult, TransferChunkParams, TransferChunkResult,
+    TransferIdParams, TransferReadyResult, TransferReleaseResult,
+};
+use bsk_protocol::{ErrorCode, RpcError};
+use uuid::Uuid;
+
+use super::paths;
+
+pub const TRANSFER_CHUNK_SIZE: u32 = 512 * 1024;
+pub const MAX_TRANSFER_BYTES: u64 = 512 * 1024 * 1024;
+pub const MAX_UPLOAD_FILES: usize = 20;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Direction {
+    Upload,
+    Download,
+}
+
+#[derive(Debug)]
+struct Entry {
+    session_id: String,
+    direction: Direction,
+    path: PathBuf,
+    expected_size: Option<u64>,
+    written: u64,
+    ready: bool,
+}
+
+/// Browser download path after the daemon has verified that it belongs to
+/// the capability minted for this transfer. From this point onward the daemon
+/// owns cleanup on every error path; unvalidated arbitrary paths are never
+/// removed.
+#[derive(Debug)]
+struct ValidatedBrowserFile {
+    path: PathBuf,
+    parent: PathBuf,
+    cleanup_armed: bool,
+}
+
+impl ValidatedBrowserFile {
+    fn validate(reported_path: &Path, transfer_id: &str) -> Result<Self, RpcError> {
+        if !reported_path.is_absolute() {
+            return Err(permission(
+                "download path is outside its browser capability",
+            ));
+        }
+        let expected_parent = Path::new("BrowserSkill").join(transfer_id);
+        let parent = reported_path
+            .parent()
+            .ok_or_else(|| permission("download path has no parent directory"))?;
+        if !parent.ends_with(&expected_parent) {
+            return Err(permission(
+                "download escaped its browser capability directory",
+            ));
+        }
+        for path in [reported_path, parent] {
+            if fs::symlink_metadata(path)
+                .map_err(io_error)?
+                .file_type()
+                .is_symlink()
+            {
+                return Err(permission("download capability path contains a symlink"));
+            }
+        }
+        Ok(Self {
+            path: reported_path.to_path_buf(),
+            parent: parent.to_path_buf(),
+            cleanup_armed: true,
+        })
+    }
+
+    fn remove_source(mut self) -> Result<(), RpcError> {
+        remove_if_present(&self.path).map_err(io_error)?;
+        remove_dir_if_present(&self.parent).map_err(io_error)?;
+        self.cleanup_armed = false;
+        Ok(())
+    }
+}
+
+impl Drop for ValidatedBrowserFile {
+    fn drop(&mut self) {
+        if !self.cleanup_armed {
+            return;
+        }
+        let _ = remove_if_present(&self.path);
+        let _ = remove_dir_if_present(&self.parent);
+    }
+}
+
+#[derive(Debug)]
+pub struct DownloadStaging {
+    pub transfer_id: String,
+    pub browser_relative_dir: String,
+}
+
+#[derive(Debug)]
+pub struct TransferRegistry {
+    root: PathBuf,
+    initialized: Mutex<bool>,
+    entries: Mutex<HashMap<String, Entry>>,
+}
+
+impl TransferRegistry {
+    pub fn new() -> anyhow::Result<Self> {
+        Ok(Self {
+            root: paths::bsk_home()?.join("run").join("transfers"),
+            initialized: Mutex::new(false),
+            entries: Mutex::new(HashMap::new()),
+        })
+    }
+
+    #[cfg(test)]
+    fn at_root(root: PathBuf) -> anyhow::Result<Self> {
+        let registry = Self {
+            root,
+            initialized: Mutex::new(false),
+            entries: Mutex::new(HashMap::new()),
+        };
+        registry.ensure_root()?;
+        Ok(registry)
+    }
+
+    pub fn initialize(&self) -> anyhow::Result<()> {
+        self.ensure_root()
+    }
+
+    fn ensure_root(&self) -> anyhow::Result<()> {
+        let mut initialized = self.initialized.lock().unwrap();
+        if *initialized {
+            return Ok(());
+        }
+        if self.root.exists() {
+            // Transfers never survive a daemon; removing stale directories on
+            // startup gives crash cleanup without a second persistence model.
+            let _ = fs::remove_dir_all(&self.root);
+        }
+        fs::create_dir_all(&self.root)?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&self.root, fs::Permissions::from_mode(0o700))?;
+        }
+        *initialized = true;
+        Ok(())
+    }
+
+    pub fn begin_upload(&self, p: TransferBeginParams) -> Result<TransferBeginResult, RpcError> {
+        self.ensure_root()
+            .map_err(|err| protocol_error(err.to_string()))?;
+        let basename = safe_upload_basename(&p.name)?;
+        if p.byte_size > MAX_TRANSFER_BYTES {
+            return Err(invalid(format!(
+                "file size {} exceeds transfer limit {}",
+                p.byte_size, MAX_TRANSFER_BYTES
+            )));
+        }
+        let mut entries = self.entries.lock().unwrap();
+        let session_bytes: u64 = entries
+            .values()
+            .filter(|entry| entry.session_id == p.session_id)
+            .map(|entry| entry.expected_size.unwrap_or(entry.written))
+            .sum();
+        if session_bytes.saturating_add(p.byte_size) > MAX_TRANSFER_BYTES {
+            return Err(invalid(format!(
+                "session transfer staging exceeds limit {}",
+                MAX_TRANSFER_BYTES
+            )));
+        }
+        let id = new_id();
+        let dir = self.root.join(&id);
+        fs::create_dir(&dir).map_err(io_error)?;
+        set_private_dir(&dir).map_err(io_error)?;
+        let path = dir.join(basename);
+        let file = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&path)
+            .map_err(io_error)?;
+        set_private_file(&file).map_err(io_error)?;
+        entries.insert(
+            id.clone(),
+            Entry {
+                session_id: p.session_id,
+                direction: Direction::Upload,
+                path,
+                expected_size: Some(p.byte_size),
+                written: 0,
+                ready: false,
+            },
+        );
+        Ok(TransferBeginResult {
+            transfer_id: id,
+            chunk_size: TRANSFER_CHUNK_SIZE,
+        })
+    }
+
+    pub fn write_chunk(&self, p: TransferChunkParams) -> Result<TransferChunkResult, RpcError> {
+        let bytes = base64::engine::general_purpose::STANDARD
+            .decode(p.data_base64)
+            .map_err(|e| invalid(format!("invalid transfer chunk: {e}")))?;
+        if bytes.len() > TRANSFER_CHUNK_SIZE as usize {
+            return Err(invalid("transfer chunk exceeds negotiated size"));
+        }
+        let mut entries = self.entries.lock().unwrap();
+        let entry = entries
+            .get_mut(&p.transfer_id)
+            .ok_or_else(|| not_found("transfer not found"))?;
+        if entry.direction != Direction::Upload || entry.ready {
+            return Err(invalid("transfer is not writable"));
+        }
+        if p.offset != entry.written {
+            return Err(invalid(format!(
+                "non-sequential transfer offset: expected {}, got {}",
+                entry.written, p.offset
+            )));
+        }
+        let next = entry.written.saturating_add(bytes.len() as u64);
+        if next > entry.expected_size.unwrap_or(MAX_TRANSFER_BYTES) {
+            return Err(invalid("transfer exceeds declared byte size"));
+        }
+        let mut file = OpenOptions::new()
+            .append(true)
+            .open(&entry.path)
+            .map_err(io_error)?;
+        file.write_all(&bytes).map_err(io_error)?;
+        entry.written = next;
+        Ok(TransferChunkResult {
+            next_offset: next,
+            eof: false,
+            data_base64: None,
+        })
+    }
+
+    pub fn finish_upload(&self, p: TransferIdParams) -> Result<TransferReadyResult, RpcError> {
+        let mut entries = self.entries.lock().unwrap();
+        let entry = entries
+            .get_mut(&p.transfer_id)
+            .ok_or_else(|| not_found("transfer not found"))?;
+        if entry.direction != Direction::Upload {
+            return Err(invalid("transfer is not an upload"));
+        }
+        if entry.written != entry.expected_size.unwrap_or(entry.written) {
+            return Err(invalid(format!(
+                "incomplete transfer: expected {} bytes, received {}",
+                entry.expected_size.unwrap_or(0),
+                entry.written
+            )));
+        }
+        entry.ready = true;
+        Ok(TransferReadyResult {
+            transfer_id: p.transfer_id,
+            byte_size: entry.written,
+        })
+    }
+
+    pub fn resolve_uploads(
+        &self,
+        session_id: &str,
+        ids: &[String],
+    ) -> Result<Vec<PathBuf>, RpcError> {
+        let entries = self.entries.lock().unwrap();
+        ids.iter()
+            .map(|id| {
+                let entry = entries
+                    .get(id)
+                    .ok_or_else(|| not_found("upload transfer not found"))?;
+                if entry.session_id != session_id
+                    || entry.direction != Direction::Upload
+                    || !entry.ready
+                {
+                    return Err(permission(
+                        "upload transfer is outside this session or not ready",
+                    ));
+                }
+                Ok(entry.path.clone())
+            })
+            .collect()
+    }
+
+    pub fn begin_download(&self, session_id: &str) -> Result<DownloadStaging, RpcError> {
+        self.ensure_root()
+            .map_err(|err| protocol_error(err.to_string()))?;
+        let id = new_id();
+        let dir = self.root.join(&id);
+        fs::create_dir(&dir).map_err(io_error)?;
+        set_private_dir(&dir).map_err(io_error)?;
+        self.entries.lock().unwrap().insert(
+            id.clone(),
+            Entry {
+                session_id: session_id.to_string(),
+                direction: Direction::Download,
+                path: dir.clone(),
+                expected_size: None,
+                written: 0,
+                ready: false,
+            },
+        );
+        Ok(DownloadStaging {
+            browser_relative_dir: format!("BrowserSkill/{id}"),
+            transfer_id: id,
+        })
+    }
+
+    pub fn import_download(&self, id: &str, reported_path: &Path) -> Result<u64, RpcError> {
+        let mut entries = self.entries.lock().unwrap();
+        let entry = entries
+            .get_mut(id)
+            .ok_or_else(|| not_found("download transfer not found"))?;
+        if entry.direction != Direction::Download {
+            return Err(permission("transfer is not a download capability"));
+        }
+        let browser_file = ValidatedBrowserFile::validate(reported_path, id)?;
+        let canonical = browser_file.path.canonicalize().map_err(io_error)?;
+        let meta = fs::metadata(&canonical).map_err(io_error)?;
+        if !meta.is_file() || meta.len() > MAX_TRANSFER_BYTES {
+            return Err(invalid(
+                "download is not a regular file or exceeds the transfer limit",
+            ));
+        }
+
+        let destination = entry.path.join("payload");
+        let source = File::open(&canonical).map_err(io_error)?;
+        let mut destination_file = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&destination)
+            .map_err(io_error)?;
+        let copied = std::io::copy(
+            &mut source.take(MAX_TRANSFER_BYTES.saturating_add(1)),
+            &mut destination_file,
+        )
+        .map_err(io_error)?;
+        if copied > MAX_TRANSFER_BYTES {
+            let _ = fs::remove_file(&destination);
+            return Err(invalid("download exceeds the transfer limit"));
+        }
+        entry.path = destination;
+        entry.written = copied;
+        entry.expected_size = Some(copied);
+        entry.ready = true;
+        browser_file.remove_source()?;
+        Ok(copied)
+    }
+
+    pub fn read_chunk(&self, p: TransferChunkParams) -> Result<TransferChunkResult, RpcError> {
+        let entries = self.entries.lock().unwrap();
+        let entry = entries
+            .get(&p.transfer_id)
+            .ok_or_else(|| not_found("transfer not found"))?;
+        if entry.direction != Direction::Download || !entry.ready {
+            return Err(invalid("transfer is not readable"));
+        }
+        if p.offset > entry.written {
+            return Err(invalid("read offset is beyond transfer length"));
+        }
+        let mut file = File::open(&entry.path).map_err(io_error)?;
+        file.seek(SeekFrom::Start(p.offset)).map_err(io_error)?;
+        let mut buf = vec![0u8; TRANSFER_CHUNK_SIZE as usize];
+        let count = file.read(&mut buf).map_err(io_error)?;
+        buf.truncate(count);
+        let next = p.offset + count as u64;
+        Ok(TransferChunkResult {
+            next_offset: next,
+            eof: next >= entry.written,
+            data_base64: Some(base64::engine::general_purpose::STANDARD.encode(buf)),
+        })
+    }
+
+    pub fn release(&self, p: TransferIdParams) -> TransferReleaseResult {
+        let entry = self.entries.lock().unwrap().remove(&p.transfer_id);
+        if let Some(entry) = entry {
+            let dir = if entry.path.is_dir() {
+                entry.path
+            } else {
+                entry.path.parent().unwrap_or(&self.root).to_path_buf()
+            };
+            let _ = fs::remove_dir_all(dir);
+            TransferReleaseResult { released: true }
+        } else {
+            TransferReleaseResult { released: false }
+        }
+    }
+
+    pub fn release_session(&self, session_id: &str) {
+        let ids: Vec<String> = self
+            .entries
+            .lock()
+            .unwrap()
+            .iter()
+            .filter(|(_, entry)| entry.session_id == session_id)
+            .map(|(id, _)| id.clone())
+            .collect();
+        for id in ids {
+            self.release(TransferIdParams { transfer_id: id });
+        }
+    }
+}
+
+fn new_id() -> String {
+    format!("tr_{}", Uuid::new_v4().simple())
+}
+
+fn set_private_dir(path: &Path) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(path, fs::Permissions::from_mode(0o700))?;
+    }
+    Ok(())
+}
+
+fn set_private_file(file: &File) -> std::io::Result<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        file.set_permissions(fs::Permissions::from_mode(0o600))?;
+    }
+    Ok(())
+}
+
+fn remove_if_present(path: &Path) -> std::io::Result<()> {
+    match fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err),
+    }
+}
+
+fn remove_dir_if_present(path: &Path) -> std::io::Result<()> {
+    match fs::remove_dir(path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err),
+    }
+}
+
+fn safe_upload_basename(name: &str) -> Result<&str, RpcError> {
+    if name.is_empty() || name.contains(['/', '\\', '\0']) {
+        return Err(invalid("upload name must be a safe basename"));
+    }
+    let mut components = Path::new(name).components();
+    match (components.next(), components.next()) {
+        (Some(Component::Normal(_)), None) => Ok(name),
+        _ => Err(invalid("upload name must be a safe basename")),
+    }
+}
+
+fn invalid(message: impl Into<String>) -> RpcError {
+    RpcError {
+        code: ErrorCode::InvalidParams,
+        message: message.into(),
+        data: None,
+    }
+}
+fn not_found(message: impl Into<String>) -> RpcError {
+    RpcError {
+        code: ErrorCode::NotFound,
+        message: message.into(),
+        data: None,
+    }
+}
+fn permission(message: impl Into<String>) -> RpcError {
+    RpcError {
+        code: ErrorCode::PermissionDenied,
+        message: message.into(),
+        data: None,
+    }
+}
+fn io_error(err: std::io::Error) -> RpcError {
+    RpcError {
+        code: ErrorCode::ProtocolError,
+        message: err.to_string(),
+        data: None,
+    }
+}
+
+fn protocol_error(message: impl Into<String>) -> RpcError {
+    RpcError {
+        code: ErrorCode::ProtocolError,
+        message: message.into(),
+        data: None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn registry() -> (tempfile::TempDir, TransferRegistry) {
+        let temp = tempfile::tempdir().unwrap();
+        let registry = TransferRegistry::at_root(temp.path().join("transfers")).unwrap();
+        (temp, registry)
+    }
+
+    #[test]
+    fn upload_is_not_resolvable_until_complete_or_from_another_session() {
+        let (_temp, registry) = registry();
+        let begin = registry
+            .begin_upload(TransferBeginParams {
+                session_id: "s1".into(),
+                name: "image.png".into(),
+                byte_size: 3,
+            })
+            .unwrap();
+        assert!(
+            registry
+                .resolve_uploads("s1", std::slice::from_ref(&begin.transfer_id))
+                .is_err()
+        );
+        registry
+            .write_chunk(TransferChunkParams {
+                transfer_id: begin.transfer_id.clone(),
+                offset: 0,
+                data_base64: base64::engine::general_purpose::STANDARD.encode(b"abc"),
+            })
+            .unwrap();
+        registry
+            .finish_upload(TransferIdParams {
+                transfer_id: begin.transfer_id.clone(),
+            })
+            .unwrap();
+        assert!(
+            registry
+                .resolve_uploads("s2", std::slice::from_ref(&begin.transfer_id))
+                .is_err()
+        );
+        let [path] = registry
+            .resolve_uploads("s1", &[begin.transfer_id])
+            .unwrap()
+            .try_into()
+            .unwrap();
+        assert_eq!(path.file_name().unwrap(), "image.png");
+        assert_eq!(fs::read(path).unwrap(), b"abc");
+    }
+
+    #[test]
+    fn upload_name_must_be_one_safe_path_component() {
+        let (_temp, registry) = registry();
+        for name in ["", ".", "..", "../secret", "folder/file", "folder\\file"] {
+            let result = registry.begin_upload(TransferBeginParams {
+                session_id: "s1".into(),
+                name: name.into(),
+                byte_size: 0,
+            });
+            assert!(result.is_err(), "accepted unsafe upload name");
+        }
+        assert!(registry.entries.lock().unwrap().is_empty());
+        assert!(fs::read_dir(&registry.root).unwrap().next().is_none());
+    }
+
+    #[test]
+    fn same_upload_names_are_isolated_by_transfer_directory() {
+        let (_temp, registry) = registry();
+        let first = registry
+            .begin_upload(TransferBeginParams {
+                session_id: "s1".into(),
+                name: "image.png".into(),
+                byte_size: 0,
+            })
+            .unwrap();
+        let second = registry
+            .begin_upload(TransferBeginParams {
+                session_id: "s1".into(),
+                name: "image.png".into(),
+                byte_size: 0,
+            })
+            .unwrap();
+        let entries = registry.entries.lock().unwrap();
+        let first_path = &entries[&first.transfer_id].path;
+        let second_path = &entries[&second.transfer_id].path;
+        assert_ne!(first_path.parent(), second_path.parent());
+        assert_eq!(first_path.file_name().unwrap(), "image.png");
+        assert_eq!(second_path.file_name().unwrap(), "image.png");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn upload_staging_is_private() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let (_temp, registry) = registry();
+        let begin = registry
+            .begin_upload(TransferBeginParams {
+                session_id: "s1".into(),
+                name: "private.png".into(),
+                byte_size: 0,
+            })
+            .unwrap();
+        let entries = registry.entries.lock().unwrap();
+        let path = &entries[&begin.transfer_id].path;
+        assert_eq!(
+            fs::metadata(path.parent().unwrap())
+                .unwrap()
+                .permissions()
+                .mode()
+                & 0o777,
+            0o700
+        );
+        assert_eq!(
+            fs::metadata(path).unwrap().permissions().mode() & 0o777,
+            0o600
+        );
+    }
+
+    #[test]
+    fn download_must_import_from_its_browser_capability_directory() {
+        let (temp, registry) = registry();
+        let staging = registry.begin_download("s1").unwrap();
+        let outside = temp.path().join("outside.bin");
+        fs::write(&outside, b"secret").unwrap();
+        assert!(
+            registry
+                .import_download(&staging.transfer_id, &outside)
+                .is_err()
+        );
+        assert_eq!(fs::read(&outside).unwrap(), b"secret");
+
+        let browser_dir = temp
+            .path()
+            .join("Downloads")
+            .join("BrowserSkill")
+            .join(&staging.transfer_id);
+        fs::create_dir_all(&browser_dir).unwrap();
+        let inside = browser_dir.join("result.bin");
+        fs::write(&inside, b"result").unwrap();
+        assert_eq!(
+            registry
+                .import_download(&staging.transfer_id, &inside)
+                .unwrap(),
+            6
+        );
+        assert!(!inside.exists());
+        let chunk = registry
+            .read_chunk(TransferChunkParams {
+                transfer_id: staging.transfer_id,
+                offset: 0,
+                data_base64: String::new(),
+            })
+            .unwrap();
+        assert_eq!(
+            base64::engine::general_purpose::STANDARD
+                .decode(chunk.data_base64.unwrap())
+                .unwrap(),
+            b"result"
+        );
+    }
+
+    #[test]
+    fn validated_oversized_browser_download_is_removed_on_rejection() {
+        let (temp, registry) = registry();
+        let staging = registry.begin_download("s1").unwrap();
+        let browser_dir = temp
+            .path()
+            .join("Downloads")
+            .join("BrowserSkill")
+            .join(&staging.transfer_id);
+        fs::create_dir_all(&browser_dir).unwrap();
+        let inside = browser_dir.join("oversized.bin");
+        File::create(&inside)
+            .unwrap()
+            .set_len(MAX_TRANSFER_BYTES + 1)
+            .unwrap();
+
+        assert!(
+            registry
+                .import_download(&staging.transfer_id, &inside)
+                .is_err()
+        );
+        assert!(!inside.exists());
+        assert!(!browser_dir.exists());
+    }
+
+    #[test]
+    fn releasing_a_session_removes_all_staging() {
+        let (_temp, registry) = registry();
+        let first = registry.begin_download("s1").unwrap();
+        let second = registry.begin_download("s2").unwrap();
+        let first_directory = registry.root.join(&first.transfer_id);
+        let second_directory = registry.root.join(&second.transfer_id);
+        registry.release_session("s1");
+        assert!(!first_directory.exists());
+        assert!(second_directory.exists());
+    }
+
+    #[test]
+    fn upload_staging_is_bounded_across_a_session() {
+        let (_temp, registry) = registry();
+        registry
+            .begin_upload(TransferBeginParams {
+                session_id: "s1".into(),
+                name: "large.bin".into(),
+                byte_size: MAX_TRANSFER_BYTES,
+            })
+            .unwrap();
+        assert!(
+            registry
+                .begin_upload(TransferBeginParams {
+                    session_id: "s1".into(),
+                    name: "one-more-byte.bin".into(),
+                    byte_size: 1,
+                })
+                .is_err()
+        );
+        assert!(
+            registry
+                .begin_upload(TransferBeginParams {
+                    session_id: "s2".into(),
+                    name: "other-session.bin".into(),
+                    byte_size: 1,
+                })
+                .is_ok()
+        );
+    }
+}

crates/bsk-cli/src/daemon/ipc.rs

@@ -27,7 +27,8 @@ use bsk_protocol::system::{
     VersionSkewEntry,
 };
 use bsk_protocol::tools::{
-    HelpOutcome, RequestHelpResult, ReturnFailure, WaitMsParams, WaitMsResult,
+    DownloadParams, DownloadResult, HelpOutcome, RequestHelpResult, ReturnFailure,
+    TransferBeginParams, TransferIdParams, UploadParams, WaitMsParams, WaitMsResult,
 };
 use bsk_protocol::{
     CancelParams, CancelResult, ErrorCode, Method, PingResult, ResponseBody, RpcError, RpcId,
@@ -61,6 +62,10 @@ pub type RpcHandler = Arc<
 >;
 
 const DEFAULT_RPC_TIMEOUT: Duration = Duration::from_secs(15);
+// The upload transaction owns its operation deadline and may need a bounded
+// cleanup before it can return a useful structured error. Keep only that
+// transport alive slightly longer so it does not replace the result.
+const EXTENSION_RESPONSE_GRACE: Duration = Duration::from_secs(2);
 /// Upper bound on `wait_for_browser_ms` accepted over IPC.
 const MAX_BROWSER_WAIT: Duration = Duration::from_secs(60);
 // `session.stop` fast-fails while another tool is active; this budget
@@ -223,6 +228,11 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
                     Ok(v) => ResponseBody::Ok(v),
                     Err(e) => ResponseBody::Err(e),
                 },
+                Method::TransferBegin => handle_transfer_begin(&state, params),
+                Method::TransferChunk => handle_transfer_chunk(&state, params),
+                Method::TransferFinish => handle_transfer_finish(&state, params),
+                Method::TransferRead => handle_transfer_read(&state, params),
+                Method::TransferRelease => handle_transfer_release(&state, params),
                 Method::ToolTabList
                 | Method::ToolTabCreate
                 | Method::ToolTabClose
@@ -244,9 +254,10 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
                 | Method::ToolClick
                 | Method::ToolHover
                 | Method::ToolFill
-                | Method::ToolType
                 | Method::ToolPress
                 | Method::ToolSelect
+                | Method::ToolUpload
+                | Method::ToolDownload
                 | Method::ToolEvaluate
                 | Method::ToolWaitForNavigation
                 | Method::ToolRequestHelp
@@ -325,7 +336,7 @@ async fn handle_tool_dispatch(
             data: None,
         });
     }
-    let timeout = match tool_dispatch_timeout(&params) {
+    let timeout = match tool_dispatch_transport_timeout(&method, &params) {
         Ok(timeout) => timeout,
         Err(err) => return ResponseBody::Err(err),
     };
@@ -339,24 +350,180 @@ async fn handle_tool_dispatch(
             });
         }
     };
+    let mut params = params;
+    let mut download_transfer_id: Option<String> = None;
+    if method == Method::ToolUpload {
+        let mut upload: UploadParams = match serde_json::from_value(params) {
+            Ok(v) => v,
+            Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+        };
+        if upload.files.is_empty() || upload.files.len() > super::file_transfer::MAX_UPLOAD_FILES {
+            return ResponseBody::Err(invalid_params(format!(
+                "upload requires 1..={} files",
+                super::file_transfer::MAX_UPLOAD_FILES
+            )));
+        }
+        let ids: Vec<String> = upload.files.iter().map(|f| f.transfer_id.clone()).collect();
+        let paths = match state.transfers.resolve_uploads(&session_id.0, &ids) {
+            Ok(v) => v,
+            Err(err) => return ResponseBody::Err(err),
+        };
+        for (file, path) in upload.files.iter_mut().zip(paths) {
+            file.staged_path = Some(path.to_string_lossy().into_owned());
+        }
+        params = serde_json::to_value(upload).unwrap_or(Value::Null);
+    } else if method == Method::ToolDownload {
+        let mut download: DownloadParams = match serde_json::from_value(params) {
+            Ok(v) => v,
+            Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+        };
+        let staging = match state.transfers.begin_download(&session_id.0) {
+            Ok(v) => v,
+            Err(err) => return ResponseBody::Err(err),
+        };
+        download.browser_relative_dir = Some(staging.browser_relative_dir);
+        download.max_byte_size = Some(super::file_transfer::MAX_TRANSFER_BYTES);
+        download_transfer_id = Some(staging.transfer_id);
+        params = serde_json::to_value(download).unwrap_or(Value::Null);
+    }
     let entry = inflight_guard.entry();
     // `record_stop` must reach the extension while `record_await` holds the
     // serial busy lock — finishing the recording unblocks await.
     let outcome = if method == Method::ToolRecordStop {
         state
             .tool_queues
-            .dispatch_unlocked(&session_id, method, params, timeout, Some(entry))
+            .dispatch_unlocked(&session_id, method.clone(), params, timeout, Some(entry))
             .await
     } else {
         state
             .tool_queues
-            .dispatch(&session_id, method, params, timeout, Some(entry))
+            .dispatch(&session_id, method.clone(), params, timeout, Some(entry))
             .await
     };
     drop(inflight_guard);
     match outcome {
+        Ok(v) if method == Method::ToolDownload => {
+            let id = download_transfer_id.expect("download transfer allocated");
+            let mut result: DownloadResult = match serde_json::from_value(v) {
+                Ok(v) => v,
+                Err(err) => {
+                    state
+                        .transfers
+                        .release(TransferIdParams { transfer_id: id });
+                    return ResponseBody::Err(RpcError {
+                        code: ErrorCode::ProtocolError,
+                        message: format!("invalid tool.download result: {err}"),
+                        data: None,
+                    });
+                }
+            };
+            let Some(path) = result.browser_path.take() else {
+                state
+                    .transfers
+                    .release(TransferIdParams { transfer_id: id });
+                return ResponseBody::Err(RpcError {
+                    code: ErrorCode::ProtocolError,
+                    message: "tool.download returned no browser_path".into(),
+                    data: None,
+                });
+            };
+            match state
+                .transfers
+                .import_download(&id, std::path::Path::new(&path))
+            {
+                Ok(size) => {
+                    result.byte_size = size;
+                    result.transfer_id = Some(id);
+                    ResponseBody::Ok(serde_json::to_value(result).unwrap_or(Value::Null))
+                }
+                Err(err) => {
+                    state
+                        .transfers
+                        .release(TransferIdParams { transfer_id: id });
+                    ResponseBody::Err(err)
+                }
+            }
+        }
         Ok(v) => ResponseBody::Ok(v),
-        Err(err) => ResponseBody::Err(err.into_rpc()),
+        Err(err) => {
+            if let Some(id) = download_transfer_id {
+                state
+                    .transfers
+                    .release(TransferIdParams { transfer_id: id });
+            }
+            ResponseBody::Err(err.into_rpc())
+        }
+    }
+}
+
+fn handle_transfer_begin(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
+    let p: TransferBeginParams = match serde_json::from_value(params) {
+        Ok(v) => v,
+        Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+    };
+    if state
+        .sessions
+        .get(&SessionId(p.session_id.clone()))
+        .is_none()
+    {
+        return ResponseBody::Err(RpcError {
+            code: ErrorCode::NotFound,
+            message: format!("session {} unknown", p.session_id),
+            data: None,
+        });
+    }
+    match state.transfers.begin_upload(p) {
+        Ok(v) => ResponseBody::Ok(serde_json::to_value(v).unwrap_or(Value::Null)),
+        Err(err) => ResponseBody::Err(err),
+    }
+}
+
+fn handle_transfer_chunk(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
+    let p = match serde_json::from_value(params) {
+        Ok(v) => v,
+        Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+    };
+    match state.transfers.write_chunk(p) {
+        Ok(v) => ResponseBody::Ok(serde_json::to_value(v).unwrap_or(Value::Null)),
+        Err(err) => ResponseBody::Err(err),
+    }
+}
+
+fn handle_transfer_finish(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
+    let p = match serde_json::from_value(params) {
+        Ok(v) => v,
+        Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+    };
+    match state.transfers.finish_upload(p) {
+        Ok(v) => ResponseBody::Ok(serde_json::to_value(v).unwrap_or(Value::Null)),
+        Err(err) => ResponseBody::Err(err),
+    }
+}
+
+fn handle_transfer_read(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
+    let p = match serde_json::from_value(params) {
+        Ok(v) => v,
+        Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+    };
+    match state.transfers.read_chunk(p) {
+        Ok(v) => ResponseBody::Ok(serde_json::to_value(v).unwrap_or(Value::Null)),
+        Err(err) => ResponseBody::Err(err),
+    }
+}
+
+fn handle_transfer_release(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
+    let p: TransferIdParams = match serde_json::from_value(params) {
+        Ok(v) => v,
+        Err(err) => return ResponseBody::Err(invalid_params(err.to_string())),
+    };
+    ResponseBody::Ok(serde_json::to_value(state.transfers.release(p)).unwrap_or(Value::Null))
+}
+
+fn invalid_params(message: impl Into<String>) -> RpcError {
+    RpcError {
+        code: ErrorCode::InvalidParams,
+        message: message.into(),
+        data: None,
     }
 }
 
@@ -534,6 +701,16 @@ fn tool_dispatch_timeout(params: &Value) -> Result<Duration, RpcError> {
     Ok(Duration::from_millis(u64::from(ms)))
 }
 
+fn tool_dispatch_transport_timeout(method: &Method, params: &Value) -> Result<Duration, RpcError> {
+    tool_dispatch_timeout(params).map(|timeout| {
+        if matches!(method, Method::ToolUpload | Method::ToolDownload) {
+            timeout.saturating_add(EXTENSION_RESPONSE_GRACE)
+        } else {
+            timeout
+        }
+    })
+}
+
 // Local CLI-facing shapes. Intentionally distinct from
 // `bsk_protocol::tools::SessionStart*` (which describes the WS-facing
 // `tool.session_*` round-trip with the extension) so the two sides can
@@ -799,6 +976,7 @@ async fn handle_session_stop(
     .await
     {
         Ok(stop) => {
+            state.transfers.release_session(&session_id.0);
             let result = CliSessionStopResult {
                 stopped: vec![session_id.0],
                 failed: Vec::new(),
@@ -898,6 +1076,7 @@ async fn handle_session_stop_all(
         .await
         {
             Ok(stop) => {
+                state.transfers.release_session(&id.0);
                 stopped.push(id.0);
                 returned_tab_ids.extend(stop.returned_tab_ids);
                 return_failures.extend(stop.return_failures);
@@ -1330,6 +1509,30 @@ mod tests {
         assert_eq!(got, std::time::Duration::from_millis(300_000));
     }
 
+    #[test]
+    fn extension_transport_outlives_the_operation_deadline() {
+        let params = serde_json::json!({
+            "session_id": "abcd",
+            "timeout_ms": 60_000,
+        });
+        let dispatch_timeout =
+            tool_dispatch_transport_timeout(&Method::ToolUpload, &params).unwrap();
+
+        assert_eq!(dispatch_timeout, Duration::from_secs(62));
+    }
+
+    #[test]
+    fn extension_response_grace_does_not_change_other_tools() {
+        let params = serde_json::json!({
+            "session_id": "abcd",
+            "timeout_ms": 60_000,
+        });
+        let dispatch_timeout =
+            tool_dispatch_transport_timeout(&Method::ToolClick, &params).unwrap();
+
+        assert_eq!(dispatch_timeout, Duration::from_secs(60));
+    }
+
     #[test]
     fn tool_dispatch_timeout_rejects_zero_timeout_ms() {
         let params = serde_json::json!({

crates/bsk-cli/src/daemon/mod.rs

@@ -3,6 +3,7 @@
 pub mod abort;
 pub mod browsers;
 mod cancel_forward;
+pub mod file_transfer;
 pub mod inflight;
 pub mod info;
 pub mod ipc;

crates/bsk-cli/src/daemon/queue.rs

@@ -438,6 +438,7 @@ async fn dispatch_with_sender(
     lifecycle_cancel: Option<AbortToken>,
     cancel_cleanup_timeout: Duration,
 ) -> Result<Value, DispatchError> {
+    let effect_aware_transfer = is_effect_aware_transfer(&method);
     let (respond_tx, respond_rx) = oneshot::channel();
     let job = ToolJob {
         method,
@@ -474,15 +475,21 @@ async fn dispatch_with_sender(
             mpsc::error::TrySendError::Closed(_) => DispatchError::QueueClosed,
         });
     }
-    let mut response_timeout = timeout.saturating_add(Duration::from_secs(1));
-    if lifecycle_cancellable {
-        // A lifecycle cancel can arrive at the original RPC deadline and
-        // intentionally keeps the worker alive while extension cleanup
-        // settles. Do not let this outer waiter abandon that reconciliation
-        // early, which could reopen a daemon session whose window is gone.
-        response_timeout = response_timeout.saturating_add(cancel_cleanup_timeout);
-    }
-    let waited = tokio::time::timeout(response_timeout, respond_rx).await;
+    // Lifecycle teardown and effect-aware transfers both keep the worker busy
+    // for bounded compensation after their original deadline. Keep the outer
+    // waiter alive for the same grace period so it cannot abandon reconciliation.
+    let response_grace = if lifecycle_cancellable || effect_aware_transfer {
+        cancel_cleanup_timeout
+    } else {
+        Duration::ZERO
+    };
+    let waited = tokio::time::timeout(
+        timeout
+            .saturating_add(response_grace)
+            .saturating_add(Duration::from_secs(1)),
+        respond_rx,
+    )
+    .await;
     match waited {
         Ok(Ok(Ok(v))) => Ok(v),
         Ok(Ok(Err(rpc))) => Err(DispatchError::Rpc(rpc)),
@@ -636,44 +643,85 @@ async fn forward_one(
         .lifecycle_cancel
         .as_ref()
         .map(|_| &forward_lifecycle_cancel as &(dyn Fn() + Sync));
+    let send_deadline_cancel = || {
+        client
+            .sink
+            .send(Frame::Request(RequestFrame {
+                id: format!("deadline-cancel-{rpc_id}"),
+                method: Method::Cancel,
+                params: Some(serde_json::json!({ "rpc_id": rpc_id })),
+            }))
+            .is_ok()
+    };
+    let deadline_cancel: Option<&(dyn Fn() -> bool + Sync)> =
+        is_effect_aware_transfer(&job.method).then_some(&send_deadline_cancel);
     let waited = await_with_optional_cancel(
         job.timeout,
         job.cancel_cleanup_timeout,
         waiter,
         cancel_token.as_ref(),
         on_abort,
+        deadline_cancel,
     )
     .await;
     let response = match waited {
         WaitOutcome::Response(resp) => resp,
         WaitOutcome::CancelledAfterResponse(resp) => {
             if job.method == Method::ToolSessionStop
-                && let ResponseBody::Ok(value) = resp.body
+                && let ResponseBody::Ok(value) = &resp.body
             {
                 // Teardown crossed its final irreversible boundary before
                 // the cancel landed. Commit the real extension result so the
                 // daemon does not retain a session whose window is gone.
-                return Ok(value);
+                return Ok(value.clone());
             }
-            // Cancellation wins the external verdict, but only after the
-            // extension's original RPC has settled. Preserve any non-cancel
-            // error so compensation failures remain explicit instead of
-            // being hidden behind a generic cancelled result.
-            if let ResponseBody::Err(err) = resp.body
-                && !matches!(err.code, ErrorCode::Cancelled | ErrorCode::UserAborted)
-            {
-                return Err(err);
+            // File transfer commits are irreversible. A late cancel cannot
+            // overwrite a confirmed success, and an unknown transfer effect
+            // must remain explicit so callers do not retry or release upload
+            // staging as though nothing happened.
+            if is_effect_aware_transfer(&job.method) {
+                match &resp.body {
+                    ResponseBody::Ok(_) => resp,
+                    ResponseBody::Err(err)
+                        if transfer_effect(err) == Some("unknown")
+                            || transfer_effect(err) == Some("committed") =>
+                    {
+                        return Err(err.clone());
+                    }
+                    ResponseBody::Err(err)
+                        if !matches!(err.code, ErrorCode::Cancelled | ErrorCode::UserAborted) =>
+                    {
+                        return Err(err.clone());
+                    }
+                    ResponseBody::Err(_) => {
+                        return Err(cancelled_error(
+                            job.inflight.as_deref(),
+                            "tool dispatch cancelled after extension cleanup",
+                        ));
+                    }
+                }
+            } else {
+                // For ordinary tools cancellation keeps the existing verdict,
+                // while non-cancel errors still expose compensation failures.
+                if let ResponseBody::Err(err) = resp.body
+                    && !matches!(err.code, ErrorCode::Cancelled | ErrorCode::UserAborted)
+                {
+                    return Err(err);
+                }
+                return Err(cancelled_error(
+                    job.inflight.as_deref(),
+                    "tool dispatch cancelled after extension cleanup",
+                ));
             }
-            return Err(cancelled_error(
-                job.inflight.as_deref(),
-                "tool dispatch cancelled after extension cleanup",
-            ));
         }
         WaitOutcome::TimedOutAfterResponse(resp) => match resp.body {
-            ResponseBody::Ok(value) if job.method == Method::ToolSessionStop => {
+            ResponseBody::Ok(value)
+                if job.method == Method::ToolSessionStop
+                    || is_effect_aware_transfer(&job.method) =>
+            {
                 // The close crossed its irreversible boundary during the
-                // timeout cleanup grace. Reconcile daemon state instead of
-                // reopening a session whose window is already gone.
+                // timeout cleanup grace, or the transfer committed before its
+                // deadline cancel settled. Preserve the irreversible result.
                 return Ok(value);
             }
             ResponseBody::Err(err)
@@ -681,6 +729,9 @@ async fn forward_one(
             {
                 return Err(err);
             }
+            ResponseBody::Err(err) if is_effect_aware_transfer(&job.method) => {
+                return Err(timed_out_transfer_error(&err));
+            }
             _ => {
                 return Err(RpcError {
                     code: ErrorCode::Timeout,
@@ -691,6 +742,14 @@ async fn forward_one(
         },
         WaitOutcome::CleanupTimeout => {
             client.pending.lock().unwrap().cancel(&rpc_id);
+            if is_effect_aware_transfer(&job.method) {
+                return Err(unknown_transfer_error(
+                    ErrorCode::Timeout,
+                    "cancelled file transfer did not confirm its outcome before cleanup timed out",
+                    "cleanup",
+                    true,
+                ));
+            }
             return Err(RpcError {
                 code: ErrorCode::Timeout,
                 message: format!(
@@ -700,8 +759,25 @@ async fn forward_one(
                 data: Some(serde_json::json!({ "reason": "cancel_cleanup_timeout" })),
             });
         }
+        WaitOutcome::TimeoutCleanupFailed => {
+            client.pending.lock().unwrap().cancel(&rpc_id);
+            return Err(unknown_transfer_error(
+                ErrorCode::Timeout,
+                "file transfer timed out and cleanup could not be confirmed",
+                "cleanup",
+                true,
+            ));
+        }
         WaitOutcome::WaiterClosed => {
             client.pending.lock().unwrap().cancel(&rpc_id);
+            if is_effect_aware_transfer(&job.method) {
+                return Err(unknown_transfer_error(
+                    ErrorCode::ProtocolError,
+                    "file transfer transport closed after dispatch; outcome is unknown",
+                    "transport",
+                    false,
+                ));
+            }
             return Err(RpcError {
                 code: ErrorCode::ProtocolError,
                 message: "transport closed mid-call".into(),
@@ -710,6 +786,14 @@ async fn forward_one(
         }
         WaitOutcome::Timeout => {
             client.pending.lock().unwrap().cancel(&rpc_id);
+            if is_effect_aware_transfer(&job.method) {
+                return Err(unknown_transfer_error(
+                    ErrorCode::Timeout,
+                    "file transfer timed out after dispatch; outcome is unknown",
+                    "transport",
+                    false,
+                ));
+            }
             return Err(RpcError {
                 code: ErrorCode::Timeout,
                 message: format!("tool RPC timed out after {:?}", job.timeout),
@@ -723,12 +807,65 @@ async fn forward_one(
     }
 }
 
+fn is_effect_aware_transfer(method: &Method) -> bool {
+    matches!(method, Method::ToolUpload | Method::ToolDownload)
+}
+
+fn transfer_effect(err: &RpcError) -> Option<&str> {
+    err.data.as_ref()?.get("effect_state")?.as_str()
+}
+
+fn unknown_transfer_error(
+    code: ErrorCode,
+    message: impl Into<String>,
+    phase: &str,
+    cleanup_failed: bool,
+) -> RpcError {
+    let mut data = serde_json::json!({
+        "reason": "transfer_outcome_unknown",
+        "effect_state": "unknown",
+        "phase": phase,
+    });
+    if cleanup_failed {
+        data["cleanup_state"] = serde_json::json!("failed");
+    }
+    RpcError {
+        code,
+        message: message.into(),
+        data: Some(data),
+    }
+}
+
+fn timed_out_transfer_error(err: &RpcError) -> RpcError {
+    let data = err.data.as_ref();
+    RpcError {
+        code: ErrorCode::Timeout,
+        message: "file transfer timed out after dispatch".into(),
+        data: Some(serde_json::json!({
+            "reason": "transfer_timeout",
+            "effect_state": data
+                .and_then(|value| value.get("effect_state"))
+                .and_then(Value::as_str)
+                .unwrap_or("unknown"),
+            "phase": data
+                .and_then(|value| value.get("phase"))
+                .and_then(Value::as_str)
+                .unwrap_or("cleanup"),
+            "cleanup_state": data
+                .and_then(|value| value.get("cleanup_state"))
+                .and_then(Value::as_str)
+                .unwrap_or("complete"),
+        })),
+    }
+}
+
 #[derive(Debug)]
 enum WaitOutcome {
     Response(bsk_protocol::ResponseFrame),
     CancelledAfterResponse(bsk_protocol::ResponseFrame),
     TimedOutAfterResponse(bsk_protocol::ResponseFrame),
     CleanupTimeout,
+    TimeoutCleanupFailed,
     WaiterClosed,
     Timeout,
 }
@@ -739,6 +876,7 @@ async fn await_with_optional_cancel(
     mut waiter: oneshot::Receiver<bsk_protocol::ResponseFrame>,
     cancel: Option<&super::abort::AbortToken>,
     on_abort: Option<&(dyn Fn() + Sync)>,
+    on_deadline: Option<&(dyn Fn() -> bool + Sync)>,
 ) -> WaitOutcome {
     match cancel {
         Some(token) => {
@@ -764,6 +902,16 @@ async fn await_with_optional_cancel(
                     Err(_) => WaitOutcome::WaiterClosed,
                 },
                 _ = &mut deadline => {
+                    if let Some(send_cancel) = on_deadline {
+                        return if send_cancel() {
+                            match tokio::time::timeout(cleanup_timeout, &mut waiter).await {
+                                Ok(Ok(resp)) => WaitOutcome::TimedOutAfterResponse(resp),
+                                Ok(Err(_)) | Err(_) => WaitOutcome::TimeoutCleanupFailed,
+                            }
+                        } else {
+                            WaitOutcome::TimeoutCleanupFailed
+                        };
+                    }
                     let Some(on_abort) = on_abort else {
                         return WaitOutcome::Timeout;
                     };
@@ -779,7 +927,16 @@ async fn await_with_optional_cancel(
         None => match tokio::time::timeout(timeout, &mut waiter).await {
             Ok(Ok(resp)) => WaitOutcome::Response(resp),
             Ok(Err(_)) => WaitOutcome::WaiterClosed,
-            Err(_) => WaitOutcome::Timeout,
+            Err(_) => match on_deadline {
+                Some(send_cancel) if send_cancel() => {
+                    match tokio::time::timeout(cleanup_timeout, &mut waiter).await {
+                        Ok(Ok(resp)) => WaitOutcome::TimedOutAfterResponse(resp),
+                        Ok(Err(_)) | Err(_) => WaitOutcome::TimeoutCleanupFailed,
+                    }
+                }
+                Some(_) => WaitOutcome::TimeoutCleanupFailed,
+                None => WaitOutcome::Timeout,
+            },
         },
     }
 }
@@ -864,6 +1021,7 @@ mod await_with_optional_cancel_tests {
             rx,
             Some(&token),
             None,
+            None,
         )
         .await;
         assert!(
@@ -887,6 +1045,7 @@ mod await_with_optional_cancel_tests {
             rx,
             Some(&token),
             None,
+            None,
         )
         .await;
         match outcome {
@@ -907,6 +1066,7 @@ mod await_with_optional_cancel_tests {
             rx,
             None,
             None,
+            None,
         )
         .await;
         assert!(matches!(outcome, WaitOutcome::Response(_)));
@@ -924,6 +1084,7 @@ mod await_with_optional_cancel_tests {
                 rx,
                 Some(&token),
                 None,
+                None,
             )
             .await
         });
@@ -948,6 +1109,7 @@ mod await_with_optional_cancel_tests {
             rx,
             Some(&token),
             None,
+            None,
         )
         .await;
         assert!(matches!(outcome, WaitOutcome::CleanupTimeout));
@@ -972,12 +1134,49 @@ mod await_with_optional_cancel_tests {
             rx,
             Some(&token),
             Some(&forward_abort),
+            None,
         )
         .await;
 
         assert!(abort_forwarded.load(Ordering::SeqCst));
         assert!(matches!(outcome, WaitOutcome::TimedOutAfterResponse(_)));
     }
+
+    #[tokio::test]
+    async fn transfer_deadline_sends_cancel_and_waits_for_cleanup_response() {
+        let (tx, rx) = oneshot::channel();
+        tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(5)).await;
+            tx.send(dummy_response()).unwrap();
+        });
+        let send_cancel = || true;
+        let outcome = await_with_optional_cancel(
+            Duration::from_millis(1),
+            Duration::from_secs(1),
+            rx,
+            None,
+            None,
+            Some(&send_cancel),
+        )
+        .await;
+        assert!(matches!(outcome, WaitOutcome::TimedOutAfterResponse(_)));
+    }
+
+    #[tokio::test]
+    async fn transfer_deadline_is_unknown_when_cancel_cannot_be_sent() {
+        let (_tx, rx) = oneshot::channel();
+        let send_cancel = || false;
+        let outcome = await_with_optional_cancel(
+            Duration::from_millis(1),
+            Duration::from_secs(1),
+            rx,
+            None,
+            None,
+            Some(&send_cancel),
+        )
+        .await;
+        assert!(matches!(outcome, WaitOutcome::TimeoutCleanupFailed));
+    }
 }
 
 #[cfg(test)]

crates/bsk-cli/src/daemon/start.rs

@@ -225,6 +225,10 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
             .with_context(|| format!("bind IPC endpoint {}", sock_path.display()))?;
 
         let state = Arc::new(DaemonState::new(cfg.clone()));
+        state
+            .transfers
+            .initialize()
+            .context("initialize transfer staging")?;
         let session_idle_task = spawn_session_idle_reaper(Arc::clone(&state));
         let browser_liveness_task = spawn_browser_liveness_reaper(Arc::clone(&state));
         // Fired by the update check task after a successful auto-update:
@@ -448,6 +452,7 @@ pub(crate) fn spawn_browser_liveness_reaper(
                     for s in state.sessions.purge_browser(&client.id) {
                         state.tool_queues.remove(&s.id);
                         state.session_interrupts.drop_session(&s.id);
+                        state.transfers.release_session(&s.id.0);
                         debug!(session = %s.id, "purged session on browser liveness timeout");
                     }
                 }
@@ -485,7 +490,10 @@ pub(crate) fn spawn_session_idle_reaper(state: Arc<DaemonState>) -> tokio::task:
                 )
                 .await
                 {
-                    Ok(_) => info!(session = %session_id, "idle session stopped"),
+                    Ok(_) => {
+                        state.transfers.release_session(&session_id.0);
+                        info!(session = %session_id, "idle session stopped");
+                    }
                     Err(StopSessionError::SessionBusy | StopSessionError::Stopping) => {
                         debug!(session = %session_id, "idle session still active; retrying later");
                     }
@@ -496,6 +504,7 @@ pub(crate) fn spawn_session_idle_reaper(state: Arc<DaemonState>) -> tokio::task:
                             &state.session_interrupts,
                             &session_id,
                         );
+                        state.transfers.release_session(&session_id.0);
                     }
                     Err(err) => {
                         warn!(session = %session_id, error = %err, "failed to stop idle session");

crates/bsk-cli/src/daemon/state.rs

@@ -7,6 +7,7 @@ use tokio::task::JoinHandle;
 
 use super::abort::AbortRegistry;
 use super::browsers::BrowserRegistry;
+use super::file_transfer::TransferRegistry;
 use super::inflight::ToolInflightRegistry;
 use super::ipc::IpcHandle;
 use super::queue::ToolQueueRegistry;
@@ -51,6 +52,9 @@ pub struct DaemonState {
     /// `SessionRegistry` because the signal is a transient runtime
     /// control state.
     pub session_interrupts: Arc<SessionInterruptRegistry>,
+    /// Operation-scoped local file staging. The extension only sees paths
+    /// minted here; agent-facing RPCs use opaque transfer ids.
+    pub transfers: Arc<TransferRegistry>,
 }
 
 impl DaemonState {
@@ -64,6 +68,7 @@ impl DaemonState {
         ));
         let abort_registry = Arc::new(AbortRegistry::new());
         let session_interrupts = Arc::new(SessionInterruptRegistry::new());
+        let transfers = Arc::new(TransferRegistry::new().expect("initialise transfer staging"));
         Self {
             config,
             browsers,
@@ -72,6 +77,7 @@ impl DaemonState {
             abort_registry,
             tool_inflight,
             session_interrupts,
+            transfers,
         }
     }
 }

crates/bsk-cli/src/daemon/ws.rs

@@ -295,6 +295,7 @@ async fn drive_connection(
     for session in state.sessions.purge_browser(&browser_id) {
         state.tool_queues.remove(&session.id);
         state.session_interrupts.drop_session(&session.id);
+        state.transfers.release_session(&session.id.0);
         debug!(session = %session.id, "purged stale session before browser reconnect");
     }
     let (tx, mut rx) = mpsc::unbounded_channel::<Frame>();
@@ -407,6 +408,7 @@ async fn drive_connection(
         for s in state.sessions.purge_browser(&browser_id) {
             state.tool_queues.remove(&s.id);
             state.session_interrupts.drop_session(&s.id);
+            state.transfers.release_session(&s.id.0);
             debug!(session = %s.id, "purged session on browser disconnect");
         }
     } else {
@@ -503,6 +505,7 @@ fn handle_session_window_closed(
         &state.session_interrupts,
         &session_id,
     ) {
+        state.transfers.release_session(&session_id.0);
         info!(session = %session_id, "session removed: user closed Agent Window");
     } else {
         debug!(session = %session_id, "session.window_closed for unknown session id");

crates/bsk-cli/src/main.rs

@@ -95,9 +95,10 @@ fn dispatch(cli: Cli, format: Format) -> Result<(), CliError> {
         Command::Click(args) => cli::interaction::dispatch_click(args, format),
         Command::Hover(args) => cli::interaction::dispatch_hover(args, format),
         Command::Fill(args) => cli::interaction::dispatch_fill(args, format),
-        Command::Type(args) => cli::interaction::dispatch_type(args, format),
         Command::Press(args) => cli::interaction::dispatch_press(args, format),
         Command::Select(args) => cli::interaction::dispatch_select(args, format),
+        Command::Upload(args) => cli::upload::dispatch(args, format),
+        Command::Download(args) => cli::download::dispatch(args, format),
         Command::Evaluate(args) => cli::evaluate::dispatch(args, format),
         Command::WaitForNavigation(args) => cli::waits::dispatch_wait_for_navigation(args, format),
         Command::WaitMs(args) => cli::waits::dispatch_wait_ms(args, format),

crates/bsk-cli/tests/cli_parse.rs

@@ -188,29 +188,6 @@ fn parses_click_count_alias() {
     assert_eq!(args.click_count, 2);
 }
 
-#[test]
-fn parses_surface_capture_image_coordinates() {
-    let cli = parse(&[
-        "bsk",
-        "click",
-        "@e1",
-        "--session",
-        "s1",
-        "--capture",
-        "sc_test",
-        "--image-x",
-        "160.5",
-        "--image-y",
-        "-1",
-    ]);
-    let Command::Click(args) = cli.command else {
-        panic!("expected click command");
-    };
-    assert_eq!(args.capture.as_deref(), Some("sc_test"));
-    assert_eq!(args.image_x, Some(160.5));
-    assert_eq!(args.image_y, Some(-1.0));
-}
-
 #[test]
 fn parses_hover_with_settle() {
     let cli = parse(&[
@@ -236,6 +213,45 @@ fn rejects_zero_click_count() {
     );
 }
 
+#[test]
+fn parses_upload_with_repeated_files() {
+    let cli = parse(&[
+        "bsk",
+        "upload",
+        "@e3",
+        "--file",
+        "one.png",
+        "--file",
+        "two.png",
+        "--session",
+        "s1",
+    ]);
+    let Command::Upload(args) = cli.command else {
+        panic!("expected upload command");
+    };
+    assert_eq!(args.target.as_deref(), Some("@e3"));
+    assert_eq!(args.files.len(), 2);
+}
+
+#[test]
+fn parses_download_with_exact_output_policy() {
+    let cli = parse(&[
+        "bsk",
+        "download",
+        "#export",
+        "--out",
+        "result.zip",
+        "--session",
+        "s1",
+        "--overwrite",
+    ]);
+    let Command::Download(args) = cli.command else {
+        panic!("expected download command");
+    };
+    assert_eq!(args.target.as_deref(), Some("#export"));
+    assert!(args.overwrite);
+}
+
 #[test]
 fn parses_record_start_with_browser_and_url() {
     let cli = parse(&[

crates/bsk-cli/tests/tools_ipc.rs

@@ -238,7 +238,6 @@ async fn screenshot_returns_image_base64_with_dimensions() {
                 height: 600,
                 format: "png".into(),
                 tab_id: 7,
-                capture: None,
                 dialogs: vec![],
             })
             .unwrap(),
@@ -287,7 +286,6 @@ async fn screenshot_forwards_ref_to_extension() {
                 height: 60,
                 format: "png".into(),
                 tab_id: 7,
-                capture: None,
                 dialogs: vec![],
             })
             .unwrap(),
@@ -480,6 +478,7 @@ async fn observe_returns_semantic_text_and_ref_count() {
                 tab_id: 13,
                 truncated: false,
                 dialogs: vec![],
+                hover_probe: None,
                 debug: None,
             })
             .unwrap(),
@@ -496,6 +495,7 @@ async fn observe_returns_semantic_text_and_ref_count() {
             max_depth: None,
             max_tokens: None,
             debug_surfaces: false,
+            probe_hover: false,
         },
     )
     .await

crates/bsk-cli/tests/tools_m7_ipc.rs

@@ -1,4 +1,5 @@
-//! M7 integration: drive the navigation and interaction tool RPCs
+//! M7 integration: drive the 7 new tool RPCs (navigate /
+//! navigate_back / navigate_forward / reload / click / fill / press)
 //! through the IPC + per-session queue + fake extension and assert
 //! the wire shapes line up. The extension stub mirrors each method's
 //! `*Result` so we exercise the daemon's serialise → forward →
@@ -15,8 +16,7 @@ use bsk_protocol::tools::{
     ClickParams, ClickResult, FillParams, FillResult, KeyModifier, MouseButton, NavigateBackParams,
     NavigateBackResult, NavigateForwardParams, NavigateForwardResult, NavigateParams,
     NavigateResult, PressParams, PressResult, ReloadParams, ReloadResult, SelectParams,
-    SelectResult, SessionStartParams, SessionStartResult, TypeParams, TypeResult, TypeVerification,
-    WaitUntil,
+    SelectResult, SessionStartParams, SessionStartResult, WaitUntil,
 };
 use bsk_protocol::{
     BrowserPeerInfo, ErrorCode, Frame, Method, RequestFrame, ResponseBody, ResponseFrame, RpcError,
@@ -354,9 +354,6 @@ async fn click_round_trips_ref_and_modifiers() {
                 used_selector: None,
                 x: 12.5,
                 y: 34.0,
-                capture_id: None,
-                image_x: None,
-                image_y: None,
                 dialogs: vec![],
             })
             .unwrap(),
@@ -376,9 +373,6 @@ async fn click_round_trips_ref_and_modifiers() {
             click_count: Some(1),
             modifiers: Some(vec![KeyModifier::Ctrl, KeyModifier::Shift]),
             timeout_ms: Some(5_000),
-            capture_id: None,
-            image_x: None,
-            image_y: None,
         },
     )
     .await
@@ -433,51 +427,6 @@ async fn fill_round_trips_clear_before_default() {
     handle.shutdown().await;
 }
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn type_round_trips_dispatched_verification() {
-    let (handle, sock) = spawn_daemon().await;
-    let mut ws = connect_ext(handle.ws_addr()).await;
-    let _ = do_handshake(&mut ws).await;
-
-    run_extension(ws, |req| {
-        assert_eq!(req.method, Method::ToolType);
-        let p: TypeParams = serde_json::from_value(req.params.clone().unwrap()).unwrap();
-        assert_eq!(p.text, "测试");
-        assert!(!p.focused);
-        ResponseBody::Ok(
-            serde_json::to_value(TypeResult {
-                tab_id: 12,
-                used_ref: Some("e3".into()),
-                used_selector: None,
-                text_length: 2,
-                verification: TypeVerification::Dispatched,
-                dialogs: vec![],
-            })
-            .unwrap(),
-        )
-    });
-
-    let session_id = ipc_session_start(&sock).await;
-    let result: TypeResult = ipc_tool_call(
-        &sock,
-        Method::ToolType,
-        TypeParams {
-            session_id,
-            text: "测试".into(),
-            ref_: Some("@e3".into()),
-            selector: None,
-            focused: false,
-            tab_id: None,
-            timeout_ms: Some(5_000),
-        },
-    )
-    .await
-    .expect("type ok");
-    assert_eq!(result.text_length, 2);
-    assert_eq!(result.verification, TypeVerification::Dispatched);
-    handle.shutdown().await;
-}
-
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn press_round_trips_compound_key() {
     let (handle, sock) = spawn_daemon().await;
@@ -580,7 +529,6 @@ async fn m7_tools_propagate_extension_errors() {
         | Method::ToolReload
         | Method::ToolClick
         | Method::ToolFill
-        | Method::ToolType
         | Method::ToolPress
         | Method::ToolSelect => ResponseBody::Err(RpcError {
             code: ErrorCode::CdpFailed,
@@ -662,9 +610,6 @@ async fn m7_tools_propagate_extension_errors() {
             click_count: None,
             modifiers: None,
             timeout_ms: Some(5_000),
-            capture_id: None,
-            image_x: None,
-            image_y: None,
         },
     )
     .await
@@ -688,23 +633,6 @@ async fn m7_tools_propagate_extension_errors() {
     .unwrap_err();
     assert_eq!(fill.code, ErrorCode::CdpFailed);
 
-    let type_result = ipc_tool_call::<_, Value>(
-        &sock,
-        Method::ToolType,
-        TypeParams {
-            session_id: session_id.clone(),
-            text: "hello".into(),
-            ref_: Some("@e1".into()),
-            selector: None,
-            focused: false,
-            tab_id: None,
-            timeout_ms: Some(5_000),
-        },
-    )
-    .await
-    .unwrap_err();
-    assert_eq!(type_result.code, ErrorCode::CdpFailed);
-
     let press = ipc_tool_call::<_, Value>(
         &sock,
         Method::ToolPress,

crates/bsk-protocol/schema/tool_click_params.json

@@ -16,13 +16,6 @@
         }
       ]
     },
-    "capture_id": {
-      "description": "Short-lived capture id returned by a visual Surface screenshot.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
     "click_count": {
       "description": "Number of consecutive mouse presses (double-click = 2).",
       "type": [
@@ -32,22 +25,6 @@
       "format": "uint32",
       "minimum": 1.0
     },
-    "image_x": {
-      "description": "X coordinate in the capture image's pixel coordinate space.",
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
-    "image_y": {
-      "description": "Y coordinate in the capture image's pixel coordinate space.",
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
     "modifiers": {
       "type": [
         "array",

crates/bsk-protocol/schema/tool_click_result.json

@@ -8,12 +8,6 @@
     "y"
   ],
   "properties": {
-    "capture_id": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
     "dialogs": {
       "description": "Native JS dialogs observed and auto-handled during this call.",
       "type": "array",
@@ -21,20 +15,6 @@
         "$ref": "#/definitions/JavaScriptDialogInfo"
       }
     },
-    "image_x": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
-    "image_y": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
     "tab_id": {
       "type": "integer",
       "format": "int64"

crates/bsk-protocol/schema/tool_download_params.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DownloadParams",
+  "type": "object",
+  "required": [
+    "session_id"
+  ],
+  "properties": {
+    "browser_relative_dir": {
+      "description": "Daemon-injected relative directory beneath Chrome's Downloads root.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "max_byte_size": {
+      "description": "Daemon-injected authoritative transfer size limit. The extension uses it only for early cancellation; daemon import remains the final check.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tab_id": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "int64"
+    },
+    "timeout_ms": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0.0
+    }
+  }
+}

crates/bsk-protocol/schema/tool_download_result.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DownloadResult",
+  "type": "object",
+  "required": [
+    "byte_size",
+    "suggested_filename",
+    "tab_id"
+  ],
+  "properties": {
+    "browser_path": {
+      "description": "Extension-internal completed Chrome download path, stripped by the daemon.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "byte_size": {
+      "type": "integer",
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "danger": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "mime": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "suggested_filename": {
+      "type": "string"
+    },
+    "tab_id": {
+      "type": "integer",
+      "format": "int64"
+    },
+    "transfer_id": {
+      "description": "Opaque id returned by the daemon to the CLI.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "used_ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "used_selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

crates/bsk-protocol/schema/tool_observe_params.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "ObserveParams",
-  "description": "Parameters for `tool.observe` — produce a semantic VOM observation for one tab plus a fresh `@e<N>` ref-store on the extension side.\n\nUnlike `tool.snapshot`, this path may run bounded perception probes such as hover-surface discovery. It must not submit input, click, navigate, or otherwise commit page state.",
+  "description": "Parameters for `tool.observe` — produce a semantic VOM observation for one tab plus a fresh `@e<N>` ref-store on the extension side.\n\nUnlike `tool.snapshot`, this path may run bounded perception probes such as hover-surface discovery, but only when `probe_hover` asks for them. It must not submit input, click, navigate, or otherwise commit page state.",
   "type": "object",
   "required": [
     "session_id"
@@ -30,6 +30,11 @@
       "format": "uint32",
       "minimum": 0.0
     },
+    "probe_hover": {
+      "description": "Opt in to active hover probing: the extension moves the real cursor over a bounded set of controls to discover hover-only menus and tooltips.\n\nOff by default. Probing costs seconds of wall clock, mutates the live page, and pays off only on pages whose content is genuinely hidden behind hover. Request it when a static observation looks like it is missing hover-revealed structure.",
+      "default": false,
+      "type": "boolean"
+    },
     "session_id": {
       "type": "string"
     },

crates/bsk-protocol/schema/tool_observe_result.json

@@ -24,6 +24,17 @@
         "$ref": "#/definitions/JavaScriptDialogInfo"
       }
     },
+    "hover_probe": {
+      "description": "Present only when `probe_hover` was requested and probing actually ran.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/HoverProbeReport"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "ref_count": {
       "description": "Number of `@e<N>` refs registered for this session by this observation. Equivalent to the size of the new ref-store map.",
       "type": "integer",
@@ -46,6 +57,24 @@
     }
   },
   "definitions": {
+    "HoverProbeReport": {
+      "description": "Reports what active hover probing did during an observation, so the agent can judge how far the live page may have drifted from the returned text.",
+      "type": "object",
+      "required": [
+        "performed",
+        "revealed_content"
+      ],
+      "properties": {
+        "performed": {
+          "description": "The real cursor was moved over page content during this observation.",
+          "type": "boolean"
+        },
+        "revealed_content": {
+          "description": "Hovering surfaced content the static tree does not contain, so the page reacts to the cursor and may not have fully reverted.",
+          "type": "boolean"
+        }
+      }
+    },
     "JavaScriptDialogHandledAction": {
       "description": "How the extension resolved the dialog so CDP could continue.",
       "type": "string",

crates/bsk-protocol/schema/tool_screenshot_result.json

@@ -8,16 +8,6 @@
     "tab_id"
   ],
   "properties": {
-    "capture": {
-      "anyOf": [
-        {
-          "$ref": "#/definitions/SurfaceCaptureInfo"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
     "dialogs": {
       "type": "array",
       "items": {
@@ -119,31 +109,6 @@
         "prompt",
         "beforeunload"
       ]
-    },
-    "SurfaceCaptureInfo": {
-      "type": "object",
-      "required": [
-        "coordinate_space",
-        "expires_at",
-        "id",
-        "surface_ref"
-      ],
-      "properties": {
-        "coordinate_space": {
-          "type": "string"
-        },
-        "expires_at": {
-          "type": "integer",
-          "format": "uint64",
-          "minimum": 0.0
-        },
-        "id": {
-          "type": "string"
-        },
-        "surface_ref": {
-          "type": "string"
-        }
-      }
     }
   }
 }

crates/bsk-protocol/schema/tool_snapshot_result.json

@@ -26,7 +26,7 @@
       "format": "int64"
     },
     "text": {
-      "description": "Indented aria-snapshot text. Refs are rendered as `@e<N>` so the agent can copy them into subsequent `tool.click` / `tool.fill` / `tool.type` targets.",
+      "description": "Indented aria-snapshot text. Refs are rendered as `@e<N>` so the agent can copy them into subsequent `tool.click` / `tool.fill` selectors.",
       "type": "string"
     },
     "truncated": {

crates/bsk-protocol/schema/tool_type_params.json

@@ -1,50 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "TypeParams",
-  "type": "object",
-  "required": [
-    "session_id",
-    "text"
-  ],
-  "properties": {
-    "focused": {
-      "description": "Explicitly dispatch to the unique focused text-entry target instead of focusing a ref or selector.",
-      "type": "boolean"
-    },
-    "ref": {
-      "description": "Target to focus before dispatching text. Exactly one targeting mode must be selected: `ref` / `selector`, or `focused=true`.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "selector": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "session_id": {
-      "type": "string"
-    },
-    "tab_id": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "format": "int64"
-    },
-    "text": {
-      "description": "Text to dispatch to the live editing session. Unlike `fill`, `type` does not require the focused DOM editable to retain this text.",
-      "type": "string"
-    },
-    "timeout_ms": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "format": "uint32",
-      "minimum": 1.0
-    }
-  }
-}

crates/bsk-protocol/schema/tool_type_result.json

@@ -1,124 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "TypeResult",
-  "type": "object",
-  "required": [
-    "tab_id",
-    "text_length",
-    "verification"
-  ],
-  "properties": {
-    "dialogs": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/JavaScriptDialogInfo"
-      }
-    },
-    "tab_id": {
-      "type": "integer",
-      "format": "int64"
-    },
-    "text_length": {
-      "description": "UTF-16 code-unit length of text accepted for dispatch.",
-      "type": "integer",
-      "format": "uint32",
-      "minimum": 0.0
-    },
-    "used_ref": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "used_selector": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "verification": {
-      "$ref": "#/definitions/TypeVerification"
-    }
-  },
-  "definitions": {
-    "JavaScriptDialogHandledAction": {
-      "description": "How the extension resolved the dialog so CDP could continue.",
-      "type": "string",
-      "enum": [
-        "accepted",
-        "dismissed"
-      ]
-    },
-    "JavaScriptDialogInfo": {
-      "description": "One observed + handled JavaScript dialog during a tool call.",
-      "type": "object",
-      "required": [
-        "handled",
-        "message",
-        "sequence",
-        "tab_id",
-        "type"
-      ],
-      "properties": {
-        "default_prompt": {
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "handled": {
-          "$ref": "#/definitions/JavaScriptDialogHandledAction"
-        },
-        "has_browser_handler": {
-          "type": [
-            "boolean",
-            "null"
-          ]
-        },
-        "message": {
-          "type": "string"
-        },
-        "sequence": {
-          "description": "Monotonic per-tab sequence for ordering within a session.",
-          "type": "integer",
-          "format": "uint64",
-          "minimum": 0.0
-        },
-        "tab_id": {
-          "type": "integer",
-          "format": "int64"
-        },
-        "type": {
-          "$ref": "#/definitions/JavaScriptDialogType"
-        },
-        "url": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      }
-    },
-    "JavaScriptDialogType": {
-      "description": "Native JS dialog kind reported by CDP.",
-      "type": "string",
-      "enum": [
-        "alert",
-        "confirm",
-        "prompt",
-        "beforeunload"
-      ]
-    },
-    "TypeVerification": {
-      "oneOf": [
-        {
-          "description": "Chromium accepted the complete keyboard/IME dispatch transaction. The caller must observe the application output to verify business state.",
-          "type": "string",
-          "enum": [
-            "dispatched"
-          ]
-        }
-      ]
-    }
-  }
-}

crates/bsk-protocol/schema/tool_upload_params.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UploadParams",
+  "type": "object",
+  "required": [
+    "files",
+    "session_id"
+  ],
+  "properties": {
+    "files": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/UploadFile"
+      }
+    },
+    "ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tab_id": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "int64"
+    },
+    "timeout_ms": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0.0
+    }
+  },
+  "definitions": {
+    "UploadFile": {
+      "type": "object",
+      "required": [
+        "name",
+        "transfer_id"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "staged_path": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "transfer_id": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

crates/bsk-protocol/schema/tool_upload_result.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UploadResult",
+  "type": "object",
+  "required": [
+    "file_names",
+    "tab_id"
+  ],
+  "properties": {
+    "file_names": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tab_id": {
+      "type": "integer",
+      "format": "int64"
+    },
+    "used_ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "used_selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

crates/bsk-protocol/src/bin/dump-schema.rs

@@ -81,12 +81,14 @@ fn main() {
     dump!(HoverResult, "tool_hover_result");
     dump!(FillParams, "tool_fill_params");
     dump!(FillResult, "tool_fill_result");
-    dump!(TypeParams, "tool_type_params");
-    dump!(TypeResult, "tool_type_result");
     dump!(PressParams, "tool_press_params");
     dump!(PressResult, "tool_press_result");
     dump!(SelectParams, "tool_select_params");
     dump!(SelectResult, "tool_select_result");
+    dump!(UploadParams, "tool_upload_params");
+    dump!(UploadResult, "tool_upload_result");
+    dump!(DownloadParams, "tool_download_params");
+    dump!(DownloadResult, "tool_download_result");
 
     dump!(SnapshotParams, "tool_snapshot_params");
     dump!(SnapshotResult, "tool_snapshot_result");

crates/bsk-protocol/src/method.rs

@@ -74,12 +74,14 @@ pub enum Method {
     ToolHover,
     #[serde(rename = "tool.fill")]
     ToolFill,
-    #[serde(rename = "tool.type")]
-    ToolType,
     #[serde(rename = "tool.press")]
     ToolPress,
     #[serde(rename = "tool.select")]
     ToolSelect,
+    #[serde(rename = "tool.upload")]
+    ToolUpload,
+    #[serde(rename = "tool.download")]
+    ToolDownload,
     #[serde(rename = "tool.snapshot")]
     ToolSnapshot,
     #[serde(rename = "tool.observe")]
@@ -107,6 +109,17 @@ pub enum Method {
     #[serde(rename = "tool.record_await")]
     ToolRecordAwait,
 
+    #[serde(rename = "transfer.begin")]
+    TransferBegin,
+    #[serde(rename = "transfer.chunk")]
+    TransferChunk,
+    #[serde(rename = "transfer.finish")]
+    TransferFinish,
+    #[serde(rename = "transfer.read")]
+    TransferRead,
+    #[serde(rename = "transfer.release")]
+    TransferRelease,
+
     #[serde(rename = "cancel")]
     Cancel,
 }
@@ -156,9 +169,10 @@ impl Method {
             | Method::ToolReload
             | Method::ToolClick
             | Method::ToolFill
-            | Method::ToolType
             | Method::ToolPress
             | Method::ToolSelect
+            | Method::ToolUpload
+            | Method::ToolDownload
             | Method::ToolEvaluate
             // May navigate via optional `url` and changes Agent Window
             // chrome; gate behind pending-interrupt like other writes.
@@ -197,6 +211,11 @@ impl Method {
             | Method::SystemPing
             | Method::SystemStatus
             | Method::BrowserList
+            | Method::TransferBegin
+            | Method::TransferChunk
+            | Method::TransferFinish
+            | Method::TransferRead
+            | Method::TransferRelease
             | Method::Cancel => MethodEffect::ControlPlane,
         }
     }
@@ -249,13 +268,6 @@ mod tests {
         assert_eq!(serde_json::to_value(method).unwrap(), json!("tool.emulate"));
     }
 
-    #[test]
-    fn type_method_round_trips() {
-        let method: Method = serde_json::from_value(json!("tool.type")).unwrap();
-        assert_eq!(method, Method::ToolType);
-        assert_eq!(serde_json::to_value(method).unwrap(), json!("tool.type"));
-    }
-
     #[test]
     fn cancel_params_and_result_round_trip() {
         let params: CancelParams = serde_json::from_value(json!({ "rpc_id": "wait-1" })).unwrap();
@@ -294,7 +306,6 @@ mod tests {
         assert!(Method::ToolReload.is_mutating());
         assert!(Method::ToolClick.is_mutating());
         assert!(Method::ToolFill.is_mutating());
-        assert!(Method::ToolType.is_mutating());
         assert!(Method::ToolPress.is_mutating());
         assert!(Method::ToolSelect.is_mutating());
         assert!(Method::ToolEvaluate.is_mutating());

crates/bsk-protocol/src/tools/file_transfer.rs

@@ -0,0 +1,176 @@
+//! Content-transparent file transfer contracts.
+//!
+//! Public tool calls carry opaque transfer ids. Filesystem paths are injected
+//! by the daemon only on the daemon -> extension hop and are never accepted as
+//! an agent-facing source or destination.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct UploadFile {
+    pub transfer_id: String,
+    pub name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub staged_path: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct UploadParams {
+    pub session_id: String,
+    #[serde(
+        rename = "ref",
+        alias = "ref_",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub ref_: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tab_id: Option<i64>,
+    pub files: Vec<UploadFile>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout_ms: Option<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct UploadResult {
+    pub tab_id: i64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_ref: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_selector: Option<String>,
+    pub file_names: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct DownloadParams {
+    pub session_id: String,
+    #[serde(
+        rename = "ref",
+        alias = "ref_",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub ref_: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tab_id: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout_ms: Option<u32>,
+    /// Daemon-injected relative directory beneath Chrome's Downloads root.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub browser_relative_dir: Option<String>,
+    /// Daemon-injected authoritative transfer size limit. The extension uses
+    /// it only for early cancellation; daemon import remains the final check.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_byte_size: Option<u64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct DownloadResult {
+    pub tab_id: i64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_ref: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_selector: Option<String>,
+    pub suggested_filename: String,
+    pub byte_size: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mime: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub danger: Option<String>,
+    /// Extension-internal completed Chrome download path, stripped by the daemon.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub browser_path: Option<String>,
+    /// Opaque id returned by the daemon to the CLI.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub transfer_id: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferBeginParams {
+    pub session_id: String,
+    pub name: String,
+    pub byte_size: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferBeginResult {
+    pub transfer_id: String,
+    pub chunk_size: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferChunkParams {
+    pub transfer_id: String,
+    pub offset: u64,
+    pub data_base64: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferChunkResult {
+    pub next_offset: u64,
+    #[serde(default)]
+    pub eof: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data_base64: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferIdParams {
+    pub transfer_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferReadyResult {
+    pub transfer_id: String,
+    pub byte_size: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TransferReleaseResult {
+    pub released: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn upload_agent_shape_omits_daemon_path_and_uses_ref_wire_name() {
+        let value = serde_json::to_value(UploadParams {
+            session_id: "s1".into(),
+            ref_: Some("@e3".into()),
+            selector: None,
+            tab_id: None,
+            files: vec![UploadFile {
+                transfer_id: "tr_1".into(),
+                name: "image.png".into(),
+                staged_path: None,
+            }],
+            timeout_ms: None,
+        })
+        .unwrap();
+        assert_eq!(value["ref"], "@e3");
+        assert!(value["files"][0].get("staged_path").is_none());
+    }
+
+    #[test]
+    fn download_agent_shape_omits_daemon_path() {
+        let value = serde_json::to_value(DownloadParams {
+            session_id: "s1".into(),
+            ref_: None,
+            selector: Some("#export".into()),
+            tab_id: None,
+            timeout_ms: None,
+            browser_relative_dir: None,
+            max_byte_size: None,
+        })
+        .unwrap();
+        assert!(value.get("browser_relative_dir").is_none());
+        assert!(value.get("max_byte_size").is_none());
+    }
+}

crates/bsk-protocol/src/tools/interaction.rs

@@ -1,5 +1,5 @@
-//! DOM interaction tools (`tool.click`, `tool.fill`, `tool.type`,
-//! `tool.press`, `tool.select`).
+//! DOM interaction tools (`tool.click`, `tool.fill`, `tool.press`,
+//! `tool.select`).
 //!
 //! Element-targeted tools accept either a snapshot `ref` (`@e<N>` form,
 //! normalised against the session's RefStore) **or** a CSS selector
@@ -67,15 +67,6 @@ pub struct ClickParams {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     #[schemars(range(min = 1))]
     pub timeout_ms: Option<u32>,
-    /// Short-lived capture id returned by a visual Surface screenshot.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub capture_id: Option<String>,
-    /// X coordinate in the capture image's pixel coordinate space.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_x: Option<f64>,
-    /// Y coordinate in the capture image's pixel coordinate space.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_y: Option<f64>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -89,12 +80,6 @@ pub struct ClickResult {
     /// agents can correlate with a follow-up `tool.screenshot`.
     pub x: f64,
     pub y: f64,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub capture_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_x: Option<f64>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_y: Option<f64>,
     /// Native JS dialogs observed and auto-handled during this call.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub dialogs: Vec<JavaScriptDialogInfo>,
@@ -188,60 +173,6 @@ pub struct FillResult {
     pub dialogs: Vec<JavaScriptDialogInfo>,
 }
 
-// ---------------------------------------------------------------------------
-// type
-// ---------------------------------------------------------------------------
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct TypeParams {
-    pub session_id: String,
-    /// Text to dispatch to the live editing session. Unlike `fill`, `type`
-    /// does not require the focused DOM editable to retain this text.
-    pub text: String,
-    /// Target to focus before dispatching text. Exactly one targeting mode
-    /// must be selected: `ref` / `selector`, or `focused=true`.
-    #[serde(
-        rename = "ref",
-        alias = "ref_",
-        default,
-        skip_serializing_if = "Option::is_none"
-    )]
-    pub ref_: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub selector: Option<String>,
-    /// Explicitly dispatch to the unique focused text-entry target instead
-    /// of focusing a ref or selector.
-    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
-    pub focused: bool,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub tab_id: Option<i64>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    #[schemars(range(min = 1))]
-    pub timeout_ms: Option<u32>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
-#[serde(rename_all = "snake_case")]
-pub enum TypeVerification {
-    /// Chromium accepted the complete keyboard/IME dispatch transaction.
-    /// The caller must observe the application output to verify business state.
-    Dispatched,
-}
-
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct TypeResult {
-    pub tab_id: i64,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub used_ref: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub used_selector: Option<String>,
-    /// UTF-16 code-unit length of text accepted for dispatch.
-    pub text_length: u32,
-    pub verification: TypeVerification,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub dialogs: Vec<JavaScriptDialogInfo>,
-}
-
 // ---------------------------------------------------------------------------
 // press
 // ---------------------------------------------------------------------------
@@ -357,9 +288,6 @@ mod tests {
             click_count: Some(1),
             modifiers: Some(vec![KeyModifier::Ctrl]),
             timeout_ms: Some(5_000),
-            capture_id: Some("sc_test".into()),
-            image_x: Some(160.0),
-            image_y: Some(90.0),
         };
         let v = serde_json::to_value(&p).unwrap();
         assert_eq!(v.get("ref").and_then(|v| v.as_str()), Some("@e3"));
@@ -405,50 +333,6 @@ mod tests {
         assert_eq!(v, json!("meta"));
     }
 
-    #[test]
-    fn type_payloads_distinguish_dispatch_from_value_verification() {
-        let params = TypeParams {
-            session_id: "abcd".into(),
-            text: "测试".into(),
-            ref_: Some("@e3".into()),
-            selector: None,
-            focused: false,
-            tab_id: Some(4),
-            timeout_ms: Some(5_000),
-        };
-        let encoded = serde_json::to_value(&params).unwrap();
-        assert_eq!(encoded["ref"], json!("@e3"));
-        assert_eq!(encoded["text"], json!("测试"));
-        assert!(encoded.get("focused").is_none());
-
-        let focused = TypeParams {
-            session_id: "abcd".into(),
-            text: "hello".into(),
-            ref_: None,
-            selector: None,
-            focused: true,
-            tab_id: None,
-            timeout_ms: None,
-        };
-        assert_eq!(
-            serde_json::to_value(focused).unwrap()["focused"],
-            json!(true)
-        );
-
-        let result = TypeResult {
-            tab_id: 4,
-            used_ref: Some("e3".into()),
-            used_selector: None,
-            text_length: 2,
-            verification: TypeVerification::Dispatched,
-            dialogs: vec![],
-        };
-        assert_eq!(
-            serde_json::to_value(result).unwrap()["verification"],
-            json!("dispatched")
-        );
-    }
-
     #[test]
     fn press_result_round_trips() {
         let r = PressResult {

crates/bsk-protocol/src/tools/mod.rs

@@ -3,6 +3,7 @@
 pub mod console;
 pub mod dialog;
 pub mod emulate;
+pub mod file_transfer;
 pub mod human_loop;
 pub mod interaction;
 pub mod navigation;
@@ -21,6 +22,7 @@ pub mod window;
 pub use console::*;
 pub use dialog::*;
 pub use emulate::*;
+pub use file_transfer::*;
 pub use human_loop::*;
 pub use interaction::*;
 pub use navigation::*;

crates/bsk-protocol/src/tools/observation.rs

@@ -33,8 +33,8 @@ pub struct SnapshotParams {
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct SnapshotResult {
     /// Indented aria-snapshot text. Refs are rendered as `@e<N>` so the
-    /// agent can copy them into subsequent `tool.click` / `tool.fill` /
-    /// `tool.type` targets.
+    /// agent can copy them into subsequent `tool.click` / `tool.fill`
+    /// selectors.
     pub text: String,
     /// Number of `@e<N>` refs registered for this session by this
     /// snapshot. Equivalent to the size of the new ref-store map.
@@ -58,8 +58,9 @@ pub struct SnapshotResult {
 /// for one tab plus a fresh `@e<N>` ref-store on the extension side.
 ///
 /// Unlike `tool.snapshot`, this path may run bounded perception probes
-/// such as hover-surface discovery. It must not submit input, click,
-/// navigate, or otherwise commit page state.
+/// such as hover-surface discovery, but only when `probe_hover` asks for
+/// them. It must not submit input, click, navigate, or otherwise commit
+/// page state.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct ObserveParams {
     pub session_id: String,
@@ -77,6 +78,16 @@ pub struct ObserveParams {
     /// Include implementation diagnostics for conditional surface probes.
     #[serde(default)]
     pub debug_surfaces: bool,
+    /// Opt in to active hover probing: the extension moves the real cursor
+    /// over a bounded set of controls to discover hover-only menus and
+    /// tooltips.
+    ///
+    /// Off by default. Probing costs seconds of wall clock, mutates the live
+    /// page, and pays off only on pages whose content is genuinely hidden
+    /// behind hover. Request it when a static observation looks like it is
+    /// missing hover-revealed structure.
+    #[serde(default)]
+    pub probe_hover: bool,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -102,6 +113,17 @@ pub struct ObserveDebug {
     pub surface_probes: Vec<SurfaceProbeDebug>,
 }
 
+/// Reports what active hover probing did during an observation, so the agent
+/// can judge how far the live page may have drifted from the returned text.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct HoverProbeReport {
+    /// The real cursor was moved over page content during this observation.
+    pub performed: bool,
+    /// Hovering surfaced content the static tree does not contain, so the page
+    /// reacts to the cursor and may not have fully reverted.
+    pub revealed_content: bool,
+}
+
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct ObserveResult {
     /// Semantic VOM observation text. Refs are rendered as `@e<N>` so
@@ -118,6 +140,9 @@ pub struct ObserveResult {
     pub truncated: bool,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub dialogs: Vec<JavaScriptDialogInfo>,
+    /// Present only when `probe_hover` was requested and probing actually ran.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hover_probe: Option<HoverProbeReport>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub debug: Option<ObserveDebug>,
 }
@@ -208,20 +233,10 @@ pub struct ScreenshotResult {
     /// Always `"png"` in v0.1; reserved for future JPEG / WebP support.
     pub format: String,
     pub tab_id: i64,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub capture: Option<SurfaceCaptureInfo>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub dialogs: Vec<JavaScriptDialogInfo>,
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct SurfaceCaptureInfo {
-    pub id: String,
-    pub surface_ref: String,
-    pub coordinate_space: String,
-    pub expires_at: u64,
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -303,12 +318,6 @@ mod tests {
             height: 600,
             format: "png".into(),
             tab_id: 7,
-            capture: Some(SurfaceCaptureInfo {
-                id: "sc_test".into(),
-                surface_ref: "@e3".into(),
-                coordinate_space: "capture-image-pixel".into(),
-                expires_at: 1_700_000_030_000,
-            }),
             dialogs: vec![],
         };
         let v = serde_json::to_value(&r).unwrap();
@@ -324,6 +333,7 @@ mod tests {
             tab_id: 42,
             truncated: false,
             dialogs: Vec::new(),
+            hover_probe: None,
             debug: None,
         };
         let v = serde_json::to_value(&r).unwrap();
@@ -331,4 +341,30 @@ mod tests {
         let round: ObserveResult = serde_json::from_value(v).unwrap();
         assert_eq!(round, r);
     }
+
+    #[test]
+    fn observe_params_default_to_no_hover_probing() {
+        let params: ObserveParams =
+            serde_json::from_value(serde_json::json!({ "session_id": "s1" })).unwrap();
+        assert!(!params.probe_hover);
+    }
+
+    #[test]
+    fn observe_result_round_trips_with_hover_probe_report() {
+        let r = ObserveResult {
+            text: "@vom 1\n".into(),
+            ref_count: 0,
+            tab_id: 42,
+            truncated: false,
+            dialogs: Vec::new(),
+            hover_probe: Some(HoverProbeReport {
+                performed: true,
+                revealed_content: true,
+            }),
+            debug: None,
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        let round: ObserveResult = serde_json::from_value(v).unwrap();
+        assert_eq!(round, r);
+    }
 }

docs/architecture.md

@@ -143,6 +143,15 @@ flowchart LR
 - No credential storage in bsk — cookies stay in the user's browser profile.
 - `evaluate` restricted to Agent Window tabs in sandbox mode.
 
+### File-transfer boundary
+
+- The invoking agent/harness decides whether a transfer is authorized and supplies the task-local source or destination path.
+- The CLI is the only component that reads an upload source or writes the final download destination. Before browser dispatch it owns rollback of partially staged uploads; after dispatch, ownership moves to the session because a transport timeout cannot prove that Chrome did not attach the file. Download output becomes visible through one atomic commit, and replacement is opt-in without a pre-delete window. The extension never receives either agent-facing path.
+- The daemon is the authority for storage capabilities and limits. It issues opaque session-scoped transfer IDs, stages bounded chunks in a private runtime directory, and injects only private staged upload paths. For download it mints one relative Chrome directory capability. Only after validating the reported path, file type, symlink boundary, and authoritative byte limit does it take ownership of browser-file cleanup and import the bytes.
+- The extension owns only the browser transaction. Both tools resolve one `ResolvedActionTarget` and use that same target for protocol setup and the triggering click. Upload arms Chrome's chooser interception before clicking, then accepts either an exact `Page.fileChooserOpened` input node or an independent probe anchored in the trigger node's own document; one verified input is committed with `DOM.setFileInputFiles`. A non-input picker is rejected immediately as unsupported. Download correlates exact-target CDP intent and `chrome.downloads` filename candidates in either arrival order, claims only one unique match, and never cancels an unclaimed candidate.
+- Browser-side operations report `effect_state` (`none`, `committed`, or `unknown`), `phase`, and `cleanup_state`. Confirmed success wins over a late cancel; an unknown effect is preserved across timeout or transport loss and must not be retried blindly. A transfer deadline sends cancellation to the extension and keeps the session queue occupied for bounded compensation rather than abandoning an in-flight browser effect.
+- Download staging is released after CLI commit. Upload staging remains until session teardown because the page may read an attached file only on a later form submission. Remaining staging is released on session stop/browser disconnect and on daemon startup after a crash. BrowserSkill does not inspect content or decide whether a transfer is appropriate.
+
 ## Repository layout
 
 ```

packages/dsh-plugin-browserskill/skill/SKILL.md

@@ -5,142 +5,99 @@ description: Browser automation through six injected domain tools.
 
 # browser-skill for DeepSeek Harness
 
-Drive the user's real Chromium browser through the six structured domain tools provided by this
-plugin. The browser keeps the user's existing logins and cookies while isolating automation in an
-Agent Window. Every call must include the tool's `action` field; other fields depend on that action.
+Drive the user's logged-in Chromium through this plugin's structured browser tools. Automation is
+isolated in an Agent Window; user-window tabs remain protected unless explicitly borrowed.
 
-## Tool availability
+Loading this skill reveals six tools for the rest of the conversation:
 
-Loading this skill reveals the browser tools for the rest of the conversation. All browser work
-must use the injected tools directly. Do not invoke another process to control the browser. Direct
-tool calls preserve session ownership, the live observation window, cancellation, attachments, and
-cleanup.
+- `browser_session` owns session lifecycle.
+- `browser_page` handles navigation and lifecycle waits.
+- `browser_inspect` reads semantic, visual, console, and network state.
+- `browser_interact` performs normal page interactions.
+- `browser_tabs` manages Agent Window tabs and temporary user-tab borrowing.
+- `browser_assist` handles human help, window size, and device emulation.
 
-The six tools are:
-
-- `browser_session`: start, stop, or list plugin-owned sessions.
-- `browser_page`: navigate, back, forward, reload, or wait for navigation.
-- `browser_inspect`: observe, snapshot, html, screenshot, console, or network.
-- `browser_interact`: click, hover, fill, select, or press.
-- `browser_tabs`: list, create, select, close, borrow, or return tabs.
-- `browser_assist`: resize the Agent Window, emulate a device, or request help from the user.
+Every call includes an `action`. Treat each loaded tool schema as authoritative for its actions and
+parameters; do not guess fields. All browser work must use the injected tools directly so session
+ownership, cancellation, attachments, observation UI, and cleanup remain intact. Do not invoke
+another process to control the browser.
 
 ## Mandatory workflow
 
-Every browser task follows this lifecycle:
-
-1. Call `browser_session` with `action: "start"` and retain its returned `sessionId`.
-2. Use that session for every later call. Pass `session` explicitly when more than one exists.
-3. Call `browser_session` with `action: "stop"` when the goal is reached or an error ends the task.
-   Treat cleanup like a finally path unless the user explicitly asks to keep the session open.
-
-Conceptual sequence:
+Every task owns a bounded plugin session:
 
 ```text
-browser_session({ action: "start", url: "https://example.com" })
-browser_inspect({ action: "observe", session: sessionId })
-browser_interact({ action: "click", session: sessionId, target: "@e4" })
-browser_inspect({ action: "observe", session: sessionId })
+browser_session({ action: "start", ... })
+... use the returned sessionId for browser work ...
 browser_session({ action: "stop", session: sessionId })
 ```
 
-The plugin owns only sessions it starts. Never guess or reuse a session id from another program.
-When `session` is omitted, most actions use the current owned session, but explicit ids are safer.
+Pass the session explicitly when more than one exists. Never guess or reuse an id owned by another
+program. Stop in a finally-style path on success and failure unless the user explicitly asks to keep
+the session open. Stopping also returns borrowed tabs.
 
-## Stop when the goal is met
+## Work toward one observable goal
 
-Browser work is bounded. Define an observable success condition, take the shortest path, and stop
-as soon as success is visible. Do not refresh or click after success. If an action fails twice
-without progress, pause instead of brute-forcing. If state is ambiguous, make at most one fresh
-observation and then ask the user.
+- Derive a concrete success condition from the user's request.
+- Take the shortest purposeful path: observe, act, then make at most one observation to confirm an
+  ambiguous result.
+- Once success is visible, do not click, refresh, navigate, switch tabs, or perform extra checks.
+- If a human-only step appears or two attempts make no progress, request help instead of
+  brute-forcing.
 
-## Observe and interact
+## Observe, act, observe
 
-Use `browser_inspect` with `action: "observe"` as the primary semantic page view. It returns roles,
-states, text, and `@eN` refs. Use `action: "snapshot"` when a static accessibility tree is more useful.
-Prefer a fresh ref over a raw CSS selector for interactions.
+Use `browser_inspect` action `observe` as the primary semantic page view. It returns roles, states,
+text, and `@eN` refs. Prefer fresh refs over raw selectors. Refs invalidate after navigation and may
+also become stale after large DOM changes, so observe again before the next interaction.
 
-Refs invalidate after navigation and may become stale after large DOM changes. Observe again after
-navigation or a meaningful DOM update before using another ref. If an observation identifies a
-hover-triggered surface, hover the trigger, observe again, then interact with the revealed control.
+Use `browser_interact` for click, hover, fill, select, and key actions. An observation marks a
+hover-only surface as `@e1 button "Products" [hover first: Shoes | Bags]`. The listed items are
+labels, not usable refs: hover the trigger, observe again, then act on the revealed item's own ref.
+Do not click the trigger itself unless the user wants the trigger's action.
 
-Use `browser_interact` as follows:
+Escalate reading only as needed:
 
-- `action: "click"`: requires `target`; optionally accepts `button` and `clickCount`.
-- `action: "hover"`: requires `target`; optionally accepts `modifiers`, `settleMs`, and `timeoutMs`.
-- `action: "fill"`: requires `target` and `value`; `noClear` appends instead of replacing.
-- `action: "select"`: requires `target` and a non-empty `values` array. Values are option value
-  attributes, not necessarily the visible labels.
-- `action: "press"`: requires `key`; optionally focus `target` first and set `holdMs`.
+1. `observe` for normal understanding and interaction refs.
+2. `snapshot` when a stricter static accessibility tree is more useful.
+3. `html` for exact markup or hidden metadata that semantic views cannot provide.
+4. `screenshot` for layout, styling, canvas, images, or requested visual evidence.
 
-## Navigate and wait
+Do not start with raw HTML or screenshots merely to discover ordinary controls. When interaction is
+needed, obtain a fresh observation before acting on screenshot or HTML findings.
 
-Use `browser_page` with these actions:
+Use `browser_page` for purposeful navigation, history, reload, or a lifecycle wait. Avoid speculative
+waits when no navigation is expected. After any page change, discard old refs and observe again.
 
-- `navigate` requires `url` and optionally accepts `waitUntil` and `timeoutMs`.
-- `back` and `forward` move one history entry and optionally accept lifecycle wait fields.
-- `reload` refreshes the current tab; set `hard: true` only when bypassing cache is necessary.
-- `wait` waits for an expected navigation after an interaction that did not already wait.
+## Respect the Agent Window boundary
 
-Avoid speculative waits when no navigation is expected. After any page change, discard old refs and
-observe again.
+Use `browser_tabs` to list returned tab ids before selecting, closing, borrowing, or returning tabs.
+Borrow a user tab only for the immediate task, and return it as soon as that step is complete. Never
+invent a tab id or keep a personal tab borrowed across unrelated work.
 
-## Reading priority
+## Ask the human when needed
 
-Escalate page reading only as needed:
+Use `browser_assist` action `request-help` for login, captcha, OTP, payment confirmation, consent, or
+another step the user must complete. Give a precise prompt and highlight fresh targets when concrete
+controls are involved. Use completion criteria only for a clear stable success signal.
 
-1. `browser_inspect` with `action: "observe"` for normal understanding and refs.
-2. The same tool with `action: "snapshot"` for a stricter static tree.
-3. `action: "html"` for exact markup that semantic views cannot provide; keep `maxBytes` bounded and
-   use only a fresh ref when scoping a subtree.
-4. `action: "screenshot"` for layout, styling, canvas, or genuinely visual evidence. A fresh `ref`
-   crops to an element; omit it for the visible tab.
+Resume only after the user continues or the criteria complete. Treat cancellation as rejection and
+timeout as a blocker rather than retrying. Observe again after control returns before reasoning about
+the new state or using refs.
 
-Do not start with raw HTML or a screenshot merely to discover ordinary controls.
+The same tool can resize the Agent Window or emulate a device when the task requires visual or
+responsive testing. Emulation is scoped to one tab.
 
-## Tabs and the Agent Window boundary
+## Debug and recover without wandering
 
-Use `browser_tabs` with these actions:
+Use `browser_inspect` console or network actions only for relevant, bounded, read-only diagnostics.
+Continue from returned sequence cursors instead of rereading the same buffer.
 
-- `list` returns visible tabs; `scope: "user"` finds a user tab before borrowing.
-- `create` makes an Agent Window tab and optionally accepts `url`, `active`, and `index`.
-- `select` focuses an Agent Window tab and requires a returned `tabId`.
-- `close` closes an Agent Window tab and requires a returned `tabId`.
-- `borrow` moves a user tab into the Agent Window and requires a listed user `tabId`.
-- `return` restores a borrowed tab and requires that borrowed `tabId`.
+- Stale ref: observe again and retry the intended action once.
+- Unknown tab: list tabs instead of guessing.
+- Unknown session: list owned sessions or start one; never try foreign ids.
+- Timeout: inspect current state before deciding whether one longer purposeful wait is useful.
+- Unrecoverable failure: report the blocker and stop the owned session.
 
-Return borrowed tabs as soon as the immediate task finishes. Stopping the session is only fallback
-cleanup. Never invent a tab id.
-
-## Human help and display controls
-
-Use `browser_assist` with `action: "request-help"` for login, captcha, OTP, payment confirmation,
-consent, or another human-only step. `prompt` is required. Optional `targets` highlight fresh refs or
-selectors. `completionCriteria` can detect explicit stable success through URL, selector, or text
-conditions. After the user continues or criteria complete, observe again before reasoning about the
-new state.
-
-Use `action: "resize"` with `width` and `height` to resize the outer Agent Window. Use
-`action: "emulate"` with a device preset or explicit width and height; `mobile: true` also requires
-dimensions. Use `off: true` alone to clear emulation. Emulation is per tab.
-
-## Read-only diagnostics
-
-Use `browser_inspect` with `action: "console"` for buffered logs and exceptions, and
-`action: "network"` for response and failure metadata. Both accept `tabId`, `since`, `limit`, and
-`maxTextChars`; continue with the returned sequence cursor rather than rereading the same entries.
-Console additionally accepts `includeStack`.
-
-Arbitrary page script evaluation and interaction recording are intentionally unsupported. Do not
-invent tool names or route around that limitation.
-
-## Error handling and final checklist
-
-On a stale ref, observe again and retry once. On an unknown tab, list tabs instead of guessing. On
-an unknown session, list owned sessions or start one; never try foreign ids. On timeout, decide
-whether one longer purposeful wait is justified, and never immediately repeat a failed history
-action without first checking page state.
-
-Before finishing, verify that the observable goal is met or the blocker is clear, borrowed tabs are
-returned when practical, the owned session is stopped, and no extra page action occurs after
-success.
+Arbitrary page-script evaluation and interaction recording are intentionally unsupported. Do not
+invent tools or route around those limits.

packages/dsh-plugin-browserskill/src/client/ObservationOverlay.tsx

@@ -15,6 +15,7 @@ import {
   RiArrowDownSLine,
   RiCheckLine,
   RiCloseCircleLine,
+  RiCloseLine,
   RiErrorWarningLine,
   RiPictureInPicture2Line,
   RiPushpinFill,
@@ -28,6 +29,7 @@ const asIcon = (component: unknown): IconComponent => component as IconComponent
 const IconStop = asIcon(RiStopCircleLine);
 const IconPip = asIcon(RiPictureInPicture2Line);
 const IconDown = asIcon(RiArrowDownSLine);
+const IconClose = asIcon(RiCloseLine);
 const IconWarn = asIcon(RiErrorWarningLine);
 const IconPin = asIcon(RiPushpinFill);
 const IconCloseSession = asIcon(RiCloseCircleLine);
@@ -320,6 +322,7 @@ export function OverlayBody(props: {
   now: number;
   onPopOut?: (() => void) | undefined;
   onCollapse?: (() => void) | undefined;
+  onClosePip?: (() => void) | undefined;
   inPip: boolean;
   onHeaderPointerDown?: (event: ReactPointerEvent<HTMLDivElement>) => void;
 }) {
@@ -333,6 +336,7 @@ export function OverlayBody(props: {
     now,
     onPopOut,
     onCollapse,
+    onClosePip,
     inPip,
     onHeaderPointerDown,
   } = props;
@@ -389,6 +393,16 @@ export function OverlayBody(props: {
             <IconDown size={14} />
           </button>
         ) : null}
+        {onClosePip !== undefined ? (
+          <button
+            type="button"
+            className={css["icon-button"]}
+            aria-label="Close mini window"
+            onClick={onClosePip}
+          >
+            <IconClose size={14} />
+          </button>
+        ) : null}
       </div>
       <div className={css.stage}>
         {displayUrl !== undefined ? (
@@ -572,6 +586,7 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
           : undefined
       }
       onCollapse={pipWindow === null ? () => setCollapsed(true) : undefined}
+      onClosePip={pipWindow !== null ? () => pipWindow.close() : undefined}
       onHeaderPointerDown={pipWindow === null ? beginMove : undefined}
     />
   );

packages/dsh-plugin-browserskill/src/client/observation-sidebar.tsx

@@ -149,6 +149,7 @@ export function ObservationSidebarTab({
       now={now}
       inPip={pipWindow !== null}
       onPopOut={pipWindow === null && pipSupported ? () => popOut() : undefined}
+      onClosePip={pipWindow !== null ? () => pipWindow.close() : undefined}
     />
   );
 

packages/dsh-plugin-browserskill/src/image.ts

@@ -42,7 +42,7 @@ interface LlmLike {
  * @param data - first bytes of the capture.
  * @returns the detected media type, or undefined when unrecognized.
  */
-function sniffImageMediaType(data: Uint8Array): string | undefined {
+export function sniffImageMediaType(data: Uint8Array): string | undefined {
   if (data.length >= 4) {
     // PNG signature: 89 50 4E 47 (0D 0A 1A 0A)
     if (data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47) {

packages/dsh-plugin-browserskill/src/observation.ts

@@ -17,6 +17,7 @@ import { readFile, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
+import { sniffImageMediaType } from "./image";
 import type { KeyedExecutor } from "./queue";
 import { BskError, type BskRunner, parseBskJson, runWithSessionBusyRetry } from "./runner";
 import type { SessionRegistry } from "./sessions";
@@ -467,7 +468,7 @@ export class ObservationService {
     const seq = (this.seqs.get(sessionId) ?? 0) + 1;
     this.seqs.set(sessionId, seq);
     const id = `obs-${sessionId}-${seq}`;
-    this.frames.set(id, { data, mediaType: "image/png" });
+    this.frames.set(id, { data, mediaType: sniffImageMediaType(data) ?? "image/png" });
     this.hashes.set(sessionId, hash);
     const ring = this.rings.get(sessionId) ?? [];
     ring.push(id);

packages/dsh-plugin-browserskill/src/tools.ts

@@ -563,8 +563,7 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       name: "interact.click",
       description:
         "Click an element in the session's active tab. Target is a snapshot ref (@e3) from the " +
-        "last browser_inspect observation, or a CSS selector. A visual Surface requires the " +
-        "captureId and image coordinates returned by browser_inspect action=screenshot.",
+        "last browser_inspect observation, or a CSS selector.",
       parameters: {
         target: {
           type: "string",
@@ -581,24 +580,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
           type: "integer",
           description: "Number of consecutive presses (double-click = 2).",
         },
-        modifiers: {
-          type: "array",
-          items: { type: "string", enum: ["alt", "ctrl", "meta", "shift"] },
-          description: "Keyboard modifiers held during the click.",
-        },
-        captureId: {
-          type: "string",
-          description:
-            "Short-lived Surface capture id returned by browser_inspect action=screenshot.",
-        },
-        imageX: {
-          type: "number",
-          description: "X coordinate in capture-image pixels; requires captureId and imageY.",
-        },
-        imageY: {
-          type: "number",
-          description: "Y coordinate in capture-image pixels; requires captureId and imageX.",
-        },
       },
       output: {
         schema: {
@@ -609,7 +590,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             tabId: { type: "integer", required: true },
             x: { type: "number", required: true },
             y: { type: "number", required: true },
-            captureId: { type: "string" },
           },
         },
         render: (_args, value) => [
@@ -621,44 +601,17 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       },
       async execute(args, exec) {
         if (args.target.trim().length === 0) throw new Error("target must be a non-empty string");
-        const pointArgCount =
-          Number(args.captureId !== undefined) +
-          Number(args.imageX !== undefined) +
-          Number(args.imageY !== undefined);
-        if (pointArgCount !== 0 && pointArgCount !== 3) {
-          throw new Error("captureId, imageX, and imageY must be given together");
-        }
         const sessionId = registry.resolve(args.session, "browser_interact(action=click)");
         const cmdArgs = ["click", "--session", sessionId];
         if (args.button !== undefined) cmdArgs.push("--button", args.button);
         if (args.clickCount !== undefined) cmdArgs.push("--click-count", String(args.clickCount));
-        if (args.modifiers !== undefined && args.modifiers.length > 0) {
-          cmdArgs.push("--modifiers", args.modifiers.join(","));
-        }
-        if (args.captureId !== undefined) {
-          cmdArgs.push(
-            "--capture",
-            args.captureId,
-            "--image-x",
-            String(args.imageX),
-            "--image-y",
-            String(args.imageY),
-          );
-        }
         cmdArgs.push(args.target);
         const reply = (await runBsk(deps, exec, cmdArgs, "click", sessionId)) as {
           tab_id: number;
           x: number;
           y: number;
-          capture_id?: string;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          x: reply.x,
-          y: reply.y,
-          ...(reply.capture_id !== undefined ? { captureId: reply.capture_id } : {}),
         };
+        return { session: sessionId, tabId: reply.tab_id, x: reply.x, y: reply.y };
       },
       presentCall: (args) => ({
         card: "terminal",
@@ -825,8 +778,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             width: { type: "integer", required: true },
             height: { type: "integer", required: true },
             byteSize: { type: "integer", required: true },
-            captureId: { type: "string" },
-            captureExpiresAt: { type: "integer" },
             image: {
               type: "object",
               additionalProperties: false,
@@ -850,11 +801,7 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             value.image !== undefined
               ? `[session ${value.session}] screenshot of tab ${value.tabId} (${value.width}x${value.height}px)`
               : `[session ${value.session}] screenshot saved to ${value.path} (${value.width}x${value.height}px, ${value.byteSize} bytes) — this deployment cannot inline images; read the file to view it`;
-          const captureText =
-            value.captureId !== undefined
-              ? ` Surface capture ${value.captureId} uses capture-image-pixel coordinates and expires at ${value.captureExpiresAt}.`
-              : "";
-          const blocks: ContentBlock[] = [{ type: "text", text: text + captureText }];
+          const blocks: ContentBlock[] = [{ type: "text", text }];
           if (value.image !== undefined) {
             blocks.push({
               type: "image",
@@ -893,7 +840,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             height: number;
             path: string;
             byte_size: number;
-            capture?: { id: string; expires_at: number };
           };
           writtenPath = reply.path;
           const data = await readFile(reply.path);
@@ -907,9 +853,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             width: reply.width,
             height: reply.height,
             byteSize: reply.byte_size,
-            ...(reply.capture !== undefined
-              ? { captureId: reply.capture.id, captureExpiresAt: reply.capture.expires_at }
-              : {}),
             ...(ref !== undefined
               ? {
                   image: {

packages/dsh-plugin-browserskill/tests/client/observation-overlay.test.tsx

@@ -298,6 +298,33 @@ describe("ObservationOverlay", () => {
     expect(close).toHaveBeenCalledTimes(1);
   });
 
+  it("shows a close button inside the PiP window that closes it", async () => {
+    const h = makeHarness([BUSY]);
+    const pipDoc = document.implementation.createHTMLDocument("pip");
+    const close = vi.fn();
+    const listeners = new Map<string, (() => void)[]>();
+    const requestWindow = vi.fn(async () => {
+      return {
+        document: pipDoc,
+        addEventListener: (name: string, fn: () => void) => {
+          listeners.set(name, [...(listeners.get(name) ?? []), fn]);
+        },
+        close,
+      } as unknown as Window;
+    });
+    (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
+    render(<ObservationOverlay store={h.store} />);
+    const popout = await screen.findByRole("button", { name: /Pop out/ });
+    fireEvent.click(popout);
+    await waitFor(() => expect(pipDoc.body.textContent).toContain("s1"));
+    const closeBtn = pipDoc.body.querySelector<HTMLButtonElement>(
+      'button[aria-label="Close mini window"]',
+    );
+    expect(closeBtn).not.toBeNull();
+    closeBtn!.click();
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
   it("renders the strip for two sessions and pins focus on click", async () => {
     const older: SessionObservation = {
       sessionId: "s1",

packages/dsh-plugin-browserskill/tests/observation.test.ts

@@ -335,6 +335,18 @@ describe("thumbnail cadence", () => {
     await waitFor(() => service.getState()[0]?.thumbnailAttachmentId === "obs-s1-1");
     expect((await service.readThumbnail("obs-s1-1"))?.mediaType).toBe("image/png");
   });
+
+  it("detects JPEG thumbnail bytes instead of hardcoding image/png", async () => {
+    const scheduler = fakeScheduler();
+    const runner = fakeRunner({
+      screenshotBytes: () => new Uint8Array([0xff, 0xd8, 0xff, 0xdb, 0x00, 0x01]),
+    });
+    const { service } = setup({ runner, scheduler });
+    service.addSession("s1");
+    scheduler.runNext();
+    await waitFor(() => service.getState()[0]?.thumbnailAttachmentId === "obs-s1-1");
+    expect((await service.readThumbnail("obs-s1-1"))?.mediaType).toBe("image/jpeg");
+  });
 });
 
 describe("observation traffic isolation", () => {