fix(bsk): download bug fix

Cargo.lock

@@ -134,9 +134,10 @@ dependencies = [
 
 [[package]]
 name = "bsk"
-version = "0.1.11"
+version = "0.1.10"
 dependencies = [
  "anyhow",
+ "base64",
  "bsk-protocol",
  "clap",
  "console",
@@ -168,7 +169,7 @@ dependencies = [
 
 [[package]]
 name = "bsk-protocol"
-version = "0.1.11"
+version = "0.1.10"
 dependencies = [
  "schemars",
  "semver",

Cargo.toml

@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 
 [workspace.package]
-version = "0.1.11"
+version = "0.1.10"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browser-skill/extension",
-  "version": "0.1.7",
+  "version": "0.1.6",
   "private": true,
   "type": "module",
   "scripts": {

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__/file-transfer.test.ts

@@ -0,0 +1,708 @@
+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("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("reconciles a download that completes while cancellation is being requested", 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: 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 () => {
+        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__/observation.test.ts

@@ -1656,7 +1656,7 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "button", name: "close", cursor: "pointer" }),
+      expect.objectContaining({ id: 20, role: "generic", cursor: "pointer" }),
     );
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "close"');
@@ -1732,7 +1732,7 @@ describe("buildVomScene", () => {
     };
 
     const scene = buildVomScene(axNodes, captured);
-    expect(scene.nodes.find((n) => n.id === 20)).toBeUndefined();
+    expect(scene.nodes.find((n) => n.id === 20)?.role).toBe("generic");
     expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("link");
   });
 
@@ -1801,9 +1801,9 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "button", attrs: { "aria-label": "收藏" } }),
+      expect.objectContaining({ id: 20, role: "generic", attrs: { "aria-label": "收藏" } }),
     );
-    expect(scene.nodes.find((n) => n.id === 30)).toBeUndefined();
+    expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("generic");
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "收藏"');
     expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
@@ -2131,7 +2131,7 @@ describe("buildVomScene", () => {
     });
 
     expect(scene.surfaces).toEqual([
-      { triggerId: 20, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
+      { triggerId: 21, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
     ]);
     expect(renderVom(scene).text).toContain(
       '@e1 button "image" [hover first: My profile | Sign out]',
@@ -3155,98 +3155,6 @@ describe("handleSnapshot", () => {
     });
   });
 
-  it("decorates live observations with active controlled content", async () => {
-    const strings = [
-      "html",
-      "body",
-      "button",
-      "div",
-      "#text",
-      "role",
-      "tab",
-      "aria-selected",
-      "true",
-      "aria-controls",
-      "reviews-panel",
-      "id",
-      "static",
-      "auto",
-      "visible",
-      "1",
-      "A detailed review",
-    ];
-    const index = (value: string) => strings.indexOf(value);
-    const style = [index("static"), index("auto"), index("auto"), index("visible"), index("1")];
-    const snapshot = {
-      strings,
-      documents: [
-        {
-          nodes: {
-            parentIndex: [-1, 0, 1, 1, 3],
-            nodeName: [index("html"), index("body"), index("button"), index("div"), index("#text")],
-            backendNodeId: [10, 11, 12, 13, 14],
-            attributes: [
-              [],
-              [],
-              [
-                index("role"),
-                index("tab"),
-                index("aria-selected"),
-                index("true"),
-                index("aria-controls"),
-                index("reviews-panel"),
-              ],
-              [index("id"), index("reviews-panel")],
-              [],
-            ],
-            nodeValue: [-1, -1, -1, -1, index("A detailed review")],
-          },
-          layout: {
-            nodeIndex: [0, 1, 2, 3, 4],
-            styles: [style, style, style, style, style],
-            bounds: [
-              [0, 0, 1000, 800],
-              [0, 0, 1000, 800],
-              [20, 20, 120, 40],
-              [20, 80, 500, 200],
-              [20, 80, 200, 20],
-            ],
-            paintOrders: [0, 0, 1, 1, 1],
-          },
-        },
-      ],
-    };
-    const ax: CdpAxNode[] = [
-      {
-        nodeId: "root",
-        backendDOMNodeId: 11,
-        role: { type: "role", value: "RootWebArea" },
-        childIds: ["reviews"],
-      },
-      {
-        nodeId: "reviews",
-        parentId: "root",
-        backendDOMNodeId: 12,
-        role: { type: "role", value: "tab" },
-        name: { type: "computedString", value: "Reviews" },
-        properties: [
-          { name: "selected", value: { value: true } },
-          { name: "controls", value: { value: "reviews-panel" } },
-        ],
-      },
-    ];
-
-    const result = await captureVomObservation(
-      makeOverlayDeps(ax, snapshot, VP_METRICS).cdp,
-      4,
-      "https://example.com",
-    );
-
-    expect(result.text).toContain('@e1 tab "Reviews"');
-    expect(result.text).toContain("[§ active: Reviews]");
-    expect(result.text).toContain("A detailed review");
-  });
-
   it("does not leak form secrets through the record-safe observation payload", async () => {
     const secrets = {
       email: "user@example.com",

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,10 +29,12 @@ import type {
   ScreenshotParams,
   SelectParams,
   SnapshotParams,
+  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";
@@ -79,6 +82,7 @@ import {
   type TabReturnParams,
   type TabSelectParams,
 } from "./tabs";
+import { handleUpload } from "./upload";
 import { handleWaitForNavigation } from "./waits";
 import { handleWindowResize, type WindowResizeParams } from "./window";
 
@@ -513,6 +517,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,
@@ -719,6 +757,8 @@ function sessionIdForBrowserControlMethod(req: RequestFrame): string | null {
     case "tool.fill":
     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,364 @@
+// 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 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];
+  const item = await lookup();
+  if (!item || item.state === "interrupted") return;
+  if (item.state === "complete") {
+    await downloads.removeFile(downloadId);
+    return;
+  }
+
+  try {
+    await downloads.cancel(downloadId);
+  } catch (cancelError) {
+    // Completion can win the race after the lookup but before cancellation.
+    // Reconcile against Chrome's authoritative state before declaring cleanup
+    // failed so every terminal state has one explicit cleanup path.
+    const reconciled = await lookup();
+    if (!reconciled || reconciled.state === "interrupted") return;
+    if (reconciled.state === "complete") {
+      await downloads.removeFile(downloadId);
+      return;
+    }
+    throw cancelError;
+  }
+}
+
+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/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,484 @@
+// 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 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>(
+  promise: 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 {
+    return await Promise.race([promise, 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",
+  );
+}
+
+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 interceptionArmed = false;
+  let probeArmed = false;
+  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 {
+      await waitBounded(
+        sendToCdpTarget(options.cdp, target, "Page.setInterceptFileChooserDialog", {
+          enabled: true,
+        }),
+        deadline,
+        options.signal,
+        "arming native file chooser interception timed out",
+      );
+      interceptionArmed = true;
+    } catch (err) {
+      outcome = transferFailure(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "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");
+
+      const armed = await waitBounded(
+        callOnTrigger<RuntimeReply>(
+          options,
+          triggerObjectId,
+          `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");
+      }
+      probeArmed = true;
+    } catch (err) {
+      outcome = transferFailure(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "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(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "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 callOnTrigger<RuntimeReply>(
+          options,
+          triggerObjectId,
+          `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,
+        );
+        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 callOnTrigger<RuntimeReply>(
+          options,
+          triggerObjectId,
+          `function(key) { return this.ownerDocument.defaultView?.[key]?.inputs[0]; }`,
+          [stateKey],
+          false,
+        );
+        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 sendToCdpTarget<{ node?: { backendNodeId?: number } }>(
+          options.cdp,
+          target,
+          "DOM.describeNode",
+          { objectId: input.result.objectId },
+        );
+        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(
+          err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+          "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(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "resolve_input",
+      );
+      return outcome;
+    }
+  } finally {
+    chooserSubscription?.dispose();
+    let cleanupFailed = false;
+    if (probeArmed && triggerObjectId) {
+      try {
+        await waitBounded(
+          callOnTrigger(
+            options,
+            triggerObjectId,
+            `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,
+          ),
+          Date.now() + CLEANUP_TIMEOUT_MS,
+          undefined,
+          "cleaning file input probe timed out",
+        );
+      } catch {
+        cleanupFailed = true;
+      }
+    }
+    if (interceptionArmed) {
+      try {
+        await waitBounded(
+          sendToCdpTarget(options.cdp, target, "Page.setInterceptFileChooserDialog", {
+            enabled: false,
+            cancel: true,
+          }),
+          Date.now() + CLEANUP_TIMEOUT_MS,
+          undefined,
+          "disabling file chooser interception timed out",
+        );
+      } catch {
+        cleanupFailed = true;
+      }
+    }
+    try {
+      await waitBounded(
+        sendToCdpTarget(options.cdp, target, "Runtime.releaseObjectGroup", { objectGroup }),
+        Date.now() + CLEANUP_TIMEOUT_MS,
+        undefined,
+        "releasing upload object group timed out",
+      );
+    } catch {
+      cleanupFailed = true;
+    }
+
+    const effect = isRpcError(outcome)
+      ? (outcome.data?.effect_state as TransferEffectState | undefined)
+      : "committed";
+    if (effect === "unknown" || cleanupFailed) {
+      await options.cdp.detach?.(target.tabId);
+    }
+    if (cleanupFailed && isRpcError(outcome)) {
+      outcome.data = { ...outcome.data, cleanup_state: "failed" };
+    }
+  }
+}

apps/extension/src/tools/interaction.ts

@@ -40,6 +40,7 @@ import {
   enforceAgentWindow,
   isRpcError,
   lookupSession,
+  type ResolvedTargetTab,
   resolveTargetTab,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
@@ -56,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;
 
@@ -128,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 },
@@ -215,6 +225,17 @@ async function resolveBackendNode(
   }
 }
 
+export async function resolveActionTarget(
+  cdp: CdpRunner,
+  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
 // ---------------------------------------------------------------------------
@@ -233,10 +254,19 @@ 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 node = await resolveBackendNode(deps.cdp, ctx, target, params, "click");
-  if (isRpcError(node)) return node;
+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" };
@@ -247,9 +277,9 @@ export async function handleClick(
     deps.cdp,
     target.tabId,
     {
-      target: node.cdpTarget,
-      backendNodeId: node.backendNodeId,
-      ...(node.frameId ? { frameId: node.frameId } : {}),
+      target: resolved.cdpTarget,
+      backendNodeId: resolved.backendNodeId,
+      ...(resolved.frameId ? { frameId: resolved.frameId } : {}),
     },
     { scrollIntoView: true },
   );
@@ -337,8 +367,8 @@ export async function handleClick(
 
   return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
     tab_id: target.tabId,
-    used_ref: node.usedRef,
-    used_selector: node.usedSelector,
+    used_ref: resolved.usedRef,
+    used_selector: resolved.usedSelector,
     x: centre.x,
     y: centre.y,
   });

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/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

@@ -36,7 +36,7 @@ function fakeSnapshotReply() {
         },
         layout: {
           nodeIndex: [1, 2, 3],
-          // Legacy fixture: omitted style columns fall back to visible defaults.
+          // styles columns follow requested computedStyles order: [position, pointer-events]
           styles: [
             [i("static"), i("auto")],
             [i("fixed"), i("auto")],
@@ -682,46 +682,6 @@ describe("captureViewModel", () => {
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
 
-  it("captures painted visibility as DOM fallback evidence", async () => {
-    const S = ["html", "body", "button", "static", "auto", "visible", "hidden", "1", "0"];
-    const i = (value: string) => S.indexOf(value);
-    const snapshot = {
-      strings: S,
-      documents: [
-        {
-          nodes: {
-            parentIndex: [-1, 0, 1, 1, 1],
-            nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
-            backendNodeId: [10, 11, 12, 13, 14],
-            attributes: [[], [], [], [], []],
-          },
-          layout: {
-            nodeIndex: [1, 2, 3, 4],
-            styles: [
-              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
-              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
-              [i("static"), i("auto"), i("auto"), i("hidden"), i("1")],
-              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
-            ],
-            bounds: [
-              [0, 0, 1000, 800],
-              [10, 10, 100, 30],
-              [10, 50, 100, 30],
-              [10, 90, 100, 30],
-            ],
-            paintOrders: [0, 1, 2, 3],
-          },
-        },
-      ],
-    };
-
-    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
-
-    expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
-    expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
-    expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
-  });
-
   it("subtracts scroll offset to make rects viewport-relative", async () => {
     const cdp = {
       send: vi.fn(async (_t: number, method: string) => {

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

@@ -132,67 +132,4 @@ describe("captureFrameData", () => {
       ]),
     );
   });
-
-  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
-    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
-    const captured: CapturedViewModel = {
-      nodes: [owner],
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      frameNodes: new Map([["main", [owner]]]),
-      rootFrameId: "main",
-      excludedBackendNodeIds: new Set(),
-    };
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method) => {
-        if (method === "Accessibility.enable") return {};
-        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-        }
-        throw new Error(`unexpected root ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
-        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
-        if (method === "Accessibility.getFullAXTree") {
-          return {
-            nodes: [
-              {
-                nodeId: "button",
-                backendDOMNodeId: 101,
-                role: { type: "role", value: "button" },
-                name: { type: "computedString", value: "Continue" },
-              },
-            ],
-          };
-        }
-        throw new Error(`unexpected ${method}`);
-      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
-      getFrameGraph: vi.fn(async () => ({
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "child",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4, sessionId: "child-session" },
-          },
-        ],
-      })),
-    };
-
-    const documents = await captureFrameData(cdp, 4, captured);
-    const childDocument = documents.find((document) => document.frameId === "child");
-
-    expect(childDocument?.axNodes).toEqual([
-      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
-    ]);
-    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
-      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
-    );
-  });
 });

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

@@ -1,183 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { CdpTarget } from "@/browser-driver/frame-graph";
-import type { CdpRunner } from "../../shared";
-import type { CapturedNode } from "../capture";
-import type { FrameDocument, FrameOwnedAxNode } from "../frame-document";
-import { probeTooltipNames } from "../name-enrichment";
-import { buildSemanticGraph, resolveSemanticGraph } from "../semantic-graph";
-import { stableIdentifierName } from "../semantic-graph/name-evidence";
-import { frameBackendKey } from "../semantic-graph/types";
-
-function document(
-  target: CdpTarget,
-  backendNodeId: number,
-  accessibleName?: string,
-  frameId = "child",
-  x = 10,
-): FrameDocument<FrameOwnedAxNode> {
-  const node: CapturedNode = {
-    backendNodeId,
-    parentBackendNodeId: null,
-    frameId,
-    tag: "button",
-    attrs: {
-      id: "toolInsertRecord",
-      "data-test-id": "toolInsertRecord",
-      ...(accessibleName ? { "aria-label": accessibleName } : {}),
-    },
-    rect: { x, y: 20, w: 40, h: 30 },
-    localRect: { x: 2, y: 3, w: 40, h: 30 },
-    paintOrder: 1,
-    position: "static",
-    pointerEvents: "auto",
-    cursor: "pointer",
-  };
-  return {
-    frameId,
-    parentFrameId: "main",
-    contextScopeId: "child",
-    target,
-    axNodes: [],
-    domNodes: [node],
-    url: "https://example.com/frame",
-  };
-}
-
-function semantics(documents: FrameDocument<FrameOwnedAxNode>[]) {
-  return resolveSemanticGraph(
-    buildSemanticGraph({
-      documents,
-      viewport: { width: 800, height: 600 },
-      rootFrameId: documents[0]?.frameId,
-    }),
-    { identifierFallback: false },
-  );
-}
-
-describe("tooltip name enrichment", () => {
-  it("uses the owning frame target and upgrades an identifier name from a tooltip", async () => {
-    const target = { tabId: 7, sessionId: "oopif-session" };
-    let hovered = false;
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method, params) => {
-        if (method === "Input.dispatchMouseEvent") {
-          hovered = (params as { x?: number }).x === 30;
-        }
-        return {};
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "Page.createIsolatedWorld") return { executionContextId: 11 };
-        if (method === "DOM.resolveNode") return { object: { objectId: "button-501" } };
-        if (method === "Runtime.callFunctionOn") {
-          return { result: { value: hovered ? ["插入行"] : [] } };
-        }
-        return {};
-      }) as CdpRunner["sendToTarget"],
-    };
-
-    const documents = [document(target, 501)];
-    const graph = semantics(documents);
-    const names = await probeTooltipNames(cdp, 7, documents, graph);
-
-    expect(names.get(frameBackendKey("child", 501))).toBe("插入行");
-    expect(cdp.sendToTarget).toHaveBeenCalledWith(
-      target,
-      "Page.createIsolatedWorld",
-      expect.objectContaining({ frameId: "child" }),
-    );
-
-    const sendsBeforeCache = vi.mocked(cdp.send).mock.calls.length;
-    const targetSendsBeforeCache = vi.mocked(
-      cdp.sendToTarget as NonNullable<CdpRunner["sendToTarget"]>,
-    ).mock.calls.length;
-    const cached = await probeTooltipNames(cdp, 7, documents, graph);
-    expect(cached.get(frameBackendKey("child", 501))).toBe("插入行");
-    expect(cdp.send).toHaveBeenCalledTimes(sendsBeforeCache);
-    expect(cdp.sendToTarget).toHaveBeenCalledTimes(targetSendsBeforeCache);
-  });
-
-  it("does not probe controls that already have a higher-confidence name", async () => {
-    const cdp: CdpRunner = {
-      send: vi.fn(async () => ({})) as CdpRunner["send"],
-      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
-    };
-
-    const documents = [document({ tabId: 8 }, 601, "Add a new record")];
-    const names = await probeTooltipNames(cdp, 8, documents, semantics(documents));
-
-    expect(names.size).toBe(0);
-    expect(cdp.send).not.toHaveBeenCalled();
-    expect(cdp.sendToTarget).not.toHaveBeenCalled();
-  });
-
-  it("does not collect supplemental names from form controls", async () => {
-    const cdp: CdpRunner = {
-      send: vi.fn(async () => ({})) as CdpRunner["send"],
-      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
-    };
-    const inputDocument = document({ tabId: 8 }, 602);
-    inputDocument.domNodes[0] = {
-      ...inputDocument.domNodes[0],
-      tag: "input",
-      attrs: { type: "email" },
-      formValue: "user@example.com",
-      formDefaultValue: "",
-      formState: "filled",
-    };
-
-    const names = await probeTooltipNames(cdp, 8, [inputDocument], semantics([inputDocument]));
-
-    expect(names.size).toBe(0);
-    expect(cdp.send).not.toHaveBeenCalled();
-    expect(cdp.sendToTarget).not.toHaveBeenCalled();
-  });
-
-  it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
-    let hoveredX = -10;
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method, params) => {
-        if (method === "Input.dispatchMouseEvent") {
-          hoveredX = (params as { x: number }).x;
-        }
-        return {};
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (target, method, params) => {
-        if (method === "Page.createIsolatedWorld") {
-          return { executionContextId: target.sessionId === "left-session" ? 21 : 22 };
-        }
-        if (method === "DOM.resolveNode") {
-          return { object: { objectId: target.sessionId === "left-session" ? "left" : "right" } };
-        }
-        if (method === "Runtime.callFunctionOn") {
-          const objectId = (params as { objectId: string }).objectId;
-          const value =
-            objectId === "left" && hoveredX === 30
-              ? ["Left action"]
-              : objectId === "right" && hoveredX === 130
-                ? ["Right action"]
-                : [];
-          return { result: { value } };
-        }
-        return {};
-      }) as CdpRunner["sendToTarget"],
-    };
-    const documents = [
-      document({ tabId: 9, sessionId: "left-session" }, 701, undefined, "left", 10),
-      document({ tabId: 9, sessionId: "right-session" }, 701, undefined, "right", 110),
-    ];
-
-    const names = await probeTooltipNames(cdp, 9, documents, semantics(documents));
-
-    expect(names.get(frameBackendKey("left", 701))).toBe("Left action");
-    expect(names.get(frameBackendKey("right", 701))).toBe("Right action");
-  });
-});
-
-describe("stable identifier evidence", () => {
-  it("accepts readable action identifiers and rejects framework-generated ids", () => {
-    expect(stableIdentifierName({ id: "toolInsertRecord" })).toBe("Insert record");
-    expect(stableIdentifierName({ id: "reactivateAccount" })).toBe("Reactivate account");
-    expect(stableIdentifierName({ id: "headlessui-menu-button-r1" })).toBeUndefined();
-    expect(stableIdentifierName({ id: "7f15a3bc91" })).toBeUndefined();
-  });
-});

apps/extension/src/tools/vom/__tests__/semantic-graph.test.ts

@@ -1,782 +0,0 @@
-import { isVomReferenceNode, renderVom } from "@browser-skill/vom";
-import { describe, expect, it } from "vitest";
-import type { CapturedNode } from "../capture";
-import type { FrameDocument } from "../frame-document";
-import { buildSemanticVomScene, type SemanticAxNode } from "../semantic-graph";
-
-function dom(
-  backendNodeId: number,
-  parentBackendNodeId: number | null,
-  tag: string,
-  attrs: Record<string, string> = {},
-  textContent?: string,
-): CapturedNode {
-  return {
-    backendNodeId,
-    parentBackendNodeId,
-    tag,
-    attrs,
-    rect: { x: 0, y: 0, w: 100, h: 30 },
-    paintOrder: backendNodeId,
-    position: "static",
-    pointerEvents: "auto",
-    ...(textContent ? { textContent } : {}),
-  };
-}
-
-function document(
-  frameId: string,
-  axNodes: SemanticAxNode[],
-  domNodes: CapturedNode[],
-  frame?: Pick<FrameDocument<SemanticAxNode>, "parentFrameId" | "ownerBackendNodeId">,
-): FrameDocument<SemanticAxNode> {
-  return {
-    frameId,
-    contextScopeId: frameId,
-    target: { tabId: 1 },
-    axNodes,
-    domNodes,
-    ...frame,
-  };
-}
-
-describe("semantic VOM graph", () => {
-  it("preserves backend-less AX structure without making it referenceable", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["toolbar"],
-            },
-            {
-              nodeId: "toolbar",
-              parentId: "root",
-              role: { type: "role", value: "toolbar" },
-              name: { type: "computedString", value: "Formatting" },
-              childIds: ["bold", "italic"],
-            },
-            {
-              nodeId: "bold",
-              parentId: "toolbar",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Bold" },
-            },
-            {
-              nodeId: "italic",
-              parentId: "toolbar",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Italic" },
-            },
-          ],
-          [dom(1, null, "body"), dom(2, 1, "button"), dom(3, 1, "button")],
-        ),
-      ],
-    });
-
-    const toolbar = scene.nodes.find((node) => node.role === "toolbar");
-    const buttons = scene.nodes.filter((node) => node.role === "button");
-    expect(toolbar).toEqual(expect.objectContaining({ name: "Formatting", referenceable: false }));
-    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
-    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
-    expect(renderVom(scene).refs.map((ref) => ref.backendNodeId)).toEqual([2, 3]);
-  });
-
-  it("resolves missing AX names through one DOM naming pipeline", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["labelled", "titled", "text"],
-            },
-            {
-              nodeId: "labelled",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "button" },
-            },
-            {
-              nodeId: "titled",
-              parentId: "root",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "button" },
-            },
-            {
-              nodeId: "text",
-              parentId: "root",
-              backendDOMNodeId: 4,
-              role: { type: "role", value: "button" },
-            },
-          ],
-          [
-            dom(1, null, "body"),
-            dom(2, 1, "button", { "aria-label": "Add row" }),
-            dom(3, 1, "button", { title: "Settings" }),
-            dom(4, 1, "button"),
-            dom(5, 4, "span", {}, "Save"),
-          ],
-        ),
-      ],
-    });
-
-    expect(scene.nodes.filter((node) => node.role === "button").map((node) => node.name)).toEqual([
-      "Add row",
-      "Settings",
-      "Save",
-    ]);
-  });
-
-  it("aggregates AX text at the semantic text frontier", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["covered", "inline-only", "repeated", "labelled"],
-            },
-            {
-              nodeId: "covered",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "paragraph" },
-              childIds: ["covered-static"],
-            },
-            {
-              nodeId: "covered-static",
-              parentId: "covered",
-              role: { type: "role", value: "StaticText" },
-              name: { type: "computedString", value: "Covered text" },
-              childIds: ["covered-inline"],
-            },
-            {
-              nodeId: "covered-inline",
-              parentId: "covered-static",
-              role: { type: "role", value: "InlineTextBox" },
-              name: { type: "computedString", value: "Covered text" },
-            },
-            {
-              nodeId: "inline-only",
-              parentId: "root",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "paragraph" },
-              childIds: ["inline-leaf"],
-            },
-            {
-              nodeId: "inline-leaf",
-              parentId: "inline-only",
-              role: { type: "role", value: "InlineTextBox" },
-              name: { type: "computedString", value: "Inline fallback" },
-            },
-            {
-              nodeId: "repeated",
-              parentId: "root",
-              backendDOMNodeId: 4,
-              role: { type: "role", value: "paragraph" },
-              childIds: ["first-go", "second-go"],
-            },
-            {
-              nodeId: "first-go",
-              parentId: "repeated",
-              role: { type: "role", value: "StaticText" },
-              name: { type: "computedString", value: "Go" },
-            },
-            {
-              nodeId: "second-go",
-              parentId: "repeated",
-              role: { type: "role", value: "StaticText" },
-              name: { type: "computedString", value: "Go" },
-            },
-            {
-              nodeId: "labelled",
-              parentId: "root",
-              backendDOMNodeId: 5,
-              role: { type: "role", value: "button" },
-              childIds: ["visible-label"],
-            },
-            {
-              nodeId: "visible-label",
-              parentId: "labelled",
-              role: { type: "role", value: "StaticText" },
-              name: { type: "computedString", value: "Visible text" },
-            },
-          ],
-          [
-            dom(1, null, "body"),
-            dom(2, 1, "p"),
-            dom(3, 1, "p"),
-            dom(4, 1, "p"),
-            dom(5, 1, "button", { "aria-label": "Explicit action" }),
-          ],
-        ),
-      ],
-    });
-
-    expect(scene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Covered text");
-    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Inline fallback");
-    expect(scene.nodes.find((node) => node.backendNodeId === 4)?.name).toBe("Go Go");
-    expect(scene.nodes.find((node) => node.backendNodeId === 5)?.name).toBe("Explicit action");
-    expect(renderVom(scene).text).not.toContain("Covered text Covered text");
-  });
-
-  it("uses stable identifiers only as a final name fallback", () => {
-    const base = document(
-      "main",
-      [
-        {
-          nodeId: "root",
-          backendDOMNodeId: 1,
-          role: { type: "role", value: "RootWebArea" },
-          childIds: ["fallback", "labelled", "container"],
-        },
-        {
-          nodeId: "fallback",
-          parentId: "root",
-          backendDOMNodeId: 2,
-          role: { type: "role", value: "button" },
-        },
-        {
-          nodeId: "labelled",
-          parentId: "root",
-          backendDOMNodeId: 3,
-          role: { type: "role", value: "button" },
-          name: { type: "computedString", value: "Localized name" },
-        },
-        {
-          nodeId: "container",
-          parentId: "root",
-          backendDOMNodeId: 4,
-          role: { type: "role", value: "generic" },
-        },
-      ],
-      [
-        dom(1, null, "body"),
-        dom(2, 1, "button", { "data-test-id": "toolInsertRecord" }),
-        dom(3, 1, "button", { id: "toolIgnoredFallback" }),
-        dom(4, 1, "div", { id: "toolbarContainer" }),
-      ],
-    );
-    const staticScene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [base],
-    });
-    const enrichedScene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [base],
-      supplementalNames: new Map([["main\u00002", "插入行"]]),
-    });
-
-    expect(staticScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Insert record");
-    expect(staticScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Localized name");
-    expect(staticScene.nodes.find((node) => node.backendNodeId === 4)?.name).toBeUndefined();
-    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("插入行");
-    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe(
-      "Localized name",
-    );
-  });
-
-  it("isolates equal backend node ids in sibling frames", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 1000, height: 800 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["owner-a", "owner-b"],
-            },
-            {
-              nodeId: "owner-a",
-              parentId: "root",
-              backendDOMNodeId: 10,
-              role: { type: "role", value: "Iframe" },
-            },
-            {
-              nodeId: "owner-b",
-              parentId: "root",
-              backendDOMNodeId: 20,
-              role: { type: "role", value: "Iframe" },
-            },
-          ],
-          [dom(1, null, "body"), dom(10, 1, "iframe"), dom(20, 1, "iframe")],
-        ),
-        document(
-          "frame-a",
-          [
-            {
-              nodeId: "button-a",
-              backendDOMNodeId: 5,
-              role: { type: "role", value: "button" },
-              childIds: ["text-a"],
-            },
-            {
-              nodeId: "text-a",
-              parentId: "button-a",
-              role: { type: "role", value: "StaticText" },
-              name: { type: "computedString", value: "Accept" },
-              childIds: ["inline-a"],
-            },
-            {
-              nodeId: "inline-a",
-              parentId: "text-a",
-              role: { type: "role", value: "InlineTextBox" },
-              name: { type: "computedString", value: "Accept" },
-            },
-          ],
-          [dom(5, null, "button")],
-          { parentFrameId: "main", ownerBackendNodeId: 10 },
-        ),
-        document(
-          "frame-b",
-          [
-            {
-              nodeId: "button-b",
-              backendDOMNodeId: 5,
-              role: { type: "role", value: "button" },
-              childIds: ["text-b"],
-            },
-            {
-              nodeId: "text-b",
-              parentId: "button-b",
-              role: { type: "role", value: "StaticText" },
-              name: { type: "computedString", value: "Decline" },
-              childIds: ["inline-b"],
-            },
-            {
-              nodeId: "inline-b",
-              parentId: "text-b",
-              role: { type: "role", value: "InlineTextBox" },
-              name: { type: "computedString", value: "Decline" },
-            },
-          ],
-          [dom(5, null, "button")],
-          { parentFrameId: "main", ownerBackendNodeId: 20 },
-        ),
-      ],
-    });
-
-    const frameButtons = scene.nodes.filter((node) => node.backendNodeId === 5);
-    const owners = new Map(
-      scene.nodes
-        .filter((node) => node.backendNodeId === 10 || node.backendNodeId === 20)
-        .map((node) => [node.backendNodeId, node.id]),
-    );
-    expect(frameButtons.map((node) => node.frameId)).toEqual(["frame-a", "frame-b"]);
-    expect(frameButtons.map((node) => node.name)).toEqual(["Accept", "Decline"]);
-    expect(frameButtons.map((node) => node.parentId)).toEqual([owners.get(10), owners.get(20)]);
-    expect(renderVom(scene).refs.map((ref) => [ref.frameId, ref.backendNodeId])).toEqual([
-      ["frame-a", 5],
-      ["frame-b", 5],
-    ]);
-  });
-
-  it("requires render evidence before promoting DOM fallback semantics", () => {
-    const hiddenOwner = {
-      ...dom(10, 1, "iframe", { hidden: "" }),
-      rect: null,
-      localRect: null,
-      rendered: false,
-    };
-    const hiddenButton = {
-      ...dom(2, 1, "button", { "aria-label": "Hidden action" }),
-      rendered: false,
-    };
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-            },
-          ],
-          [dom(1, null, "body"), hiddenButton, hiddenOwner],
-        ),
-        document("hidden-frame", [], [dom(20, null, "button", {}, "Frame action")], {
-          parentFrameId: "main",
-          ownerBackendNodeId: 10,
-        }),
-      ],
-    });
-
-    expect(scene.nodes.some((node) => node.backendNodeId === 2)).toBe(false);
-    expect(scene.nodes.some((node) => node.backendNodeId === 10)).toBe(false);
-    expect(scene.nodes.some((node) => node.frameId === "hidden-frame")).toBe(false);
-    expect(renderVom(scene).refs).toEqual([]);
-  });
-
-  it("retains rendered DOM fallback controls when AX semantics are unavailable", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [],
-          [dom(1, null, "body"), { ...dom(2, 1, "button", {}, "Save"), rendered: true }],
-        ),
-      ],
-    });
-
-    expect(renderVom(scene).refs).toEqual([
-      expect.objectContaining({ backendNodeId: 2, role: "button", name: "Save" }),
-    ]);
-  });
-
-  it("lets explicit DOM structure override ignored AX metadata", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["toolbar"],
-            },
-            {
-              nodeId: "toolbar",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              ignored: true,
-              role: { type: "role", value: "generic" },
-              childIds: ["wrapper"],
-            },
-            {
-              nodeId: "wrapper",
-              parentId: "toolbar",
-              backendDOMNodeId: 5,
-              role: { type: "role", value: "generic" },
-              childIds: ["bold", "italic"],
-            },
-            {
-              nodeId: "bold",
-              parentId: "wrapper",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Bold" },
-            },
-            {
-              nodeId: "italic",
-              parentId: "wrapper",
-              backendDOMNodeId: 4,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Italic" },
-            },
-          ],
-          [
-            dom(1, null, "body"),
-            dom(2, 1, "div", { role: "toolbar" }),
-            dom(5, 2, "div"),
-            dom(3, 5, "button"),
-            dom(4, 5, "button"),
-          ],
-        ),
-      ],
-    });
-
-    const toolbar = scene.nodes.find((node) => node.backendNodeId === 2);
-    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
-    expect(toolbar).toEqual(expect.objectContaining({ role: "toolbar" }));
-    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
-    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
-    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
-  });
-
-  it("infers an unnamed group only from independent interaction branches", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["wrapper"],
-            },
-            {
-              nodeId: "wrapper",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "generic" },
-              childIds: ["first", "second"],
-            },
-            {
-              nodeId: "first",
-              parentId: "wrapper",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "First" },
-            },
-            {
-              nodeId: "second",
-              parentId: "wrapper",
-              backendDOMNodeId: 4,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Second" },
-            },
-          ],
-          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button"), dom(4, 2, "button")],
-        ),
-      ],
-    });
-
-    const group = scene.nodes.find((node) => node.backendNodeId === 2);
-    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
-    expect(group).toEqual(expect.objectContaining({ role: "group" }));
-    expect(group?.name).toBeUndefined();
-    expect(group && isVomReferenceNode(group)).toBe(false);
-    expect(buttons.map((node) => node.parentId)).toEqual([group?.id, group?.id]);
-
-    const rendered = renderVom(scene);
-    const lines = rendered.text.split("\n");
-    const groupLine = lines.findIndex((line) => line.trim() === "group");
-    expect(groupLine).toBeGreaterThanOrEqual(0);
-    for (const ref of rendered.refs) {
-      expect(ref.line).toBeGreaterThan(groupLine);
-      expect(lines[ref.line]).toMatch(/^\s+@e\d+ button/);
-    }
-  });
-
-  it("never promotes a form value into its semantic name through supplemental evidence", () => {
-    const secret = "user@example.com";
-    const input = {
-      ...dom(2, 1, "input", { type: "email" }),
-      formValue: secret,
-      formDefaultValue: "",
-      formState: "filled" as const,
-    };
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      supplementalNames: new Map([["main\u00002", secret]]),
-      identifierFallback: false,
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["email"],
-            },
-            {
-              nodeId: "email",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "textbox" },
-              value: { value: secret },
-            },
-          ],
-          [dom(1, null, "body"), input],
-        ),
-      ],
-    });
-
-    const field = scene.nodes.find((node) => node.backendNodeId === 2);
-    expect(field?.name).toBeUndefined();
-    const rendered = renderVom(scene, { redactValues: true });
-    expect(rendered.text).toContain("•••");
-    expect(JSON.stringify(rendered)).not.toContain(secret);
-  });
-
-  it("keeps uncertain single-branch wrappers flat", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["wrapper"],
-            },
-            {
-              nodeId: "wrapper",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "generic" },
-              childIds: ["button"],
-            },
-            {
-              nodeId: "button",
-              parentId: "wrapper",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Only action" },
-            },
-          ],
-          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button")],
-        ),
-      ],
-    });
-
-    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
-    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.parentId).toBe(
-      scene.nodes.find((node) => node.backendNodeId === 1)?.id,
-    );
-  });
-
-  it("does not infer across mixed content boundaries", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["wrapper"],
-            },
-            {
-              nodeId: "wrapper",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "generic" },
-              childIds: ["first", "second", "paragraph"],
-            },
-            {
-              nodeId: "first",
-              parentId: "wrapper",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "First" },
-            },
-            {
-              nodeId: "second",
-              parentId: "wrapper",
-              backendDOMNodeId: 4,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Second" },
-            },
-            {
-              nodeId: "paragraph",
-              parentId: "wrapper",
-              backendDOMNodeId: 5,
-              role: { type: "role", value: "paragraph" },
-            },
-          ],
-          [
-            dom(1, null, "body"),
-            dom(2, 1, "div"),
-            dom(3, 2, "button"),
-            dom(4, 2, "button"),
-            dom(5, 2, "p", {}, "Description"),
-          ],
-        ),
-      ],
-    });
-
-    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
-  });
-
-  it("keeps only the innermost reliable inferred group", () => {
-    const scene = buildSemanticVomScene({
-      viewport: { width: 800, height: 600 },
-      rootFrameId: "main",
-      documents: [
-        document(
-          "main",
-          [
-            {
-              nodeId: "root",
-              backendDOMNodeId: 1,
-              role: { type: "role", value: "RootWebArea" },
-              childIds: ["outer"],
-            },
-            {
-              nodeId: "outer",
-              parentId: "root",
-              backendDOMNodeId: 2,
-              role: { type: "role", value: "generic" },
-              childIds: ["inner", "third"],
-            },
-            {
-              nodeId: "inner",
-              parentId: "outer",
-              backendDOMNodeId: 3,
-              role: { type: "role", value: "generic" },
-              childIds: ["first", "second"],
-            },
-            {
-              nodeId: "first",
-              parentId: "inner",
-              backendDOMNodeId: 4,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "First" },
-            },
-            {
-              nodeId: "second",
-              parentId: "inner",
-              backendDOMNodeId: 5,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Second" },
-            },
-            {
-              nodeId: "third",
-              parentId: "outer",
-              backendDOMNodeId: 6,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: "Third" },
-            },
-          ],
-          [
-            dom(1, null, "body"),
-            dom(2, 1, "div"),
-            dom(3, 2, "div"),
-            dom(4, 3, "button"),
-            dom(5, 3, "button"),
-            dom(6, 2, "button"),
-          ],
-        ),
-      ],
-    });
-
-    const groups = scene.nodes.filter((node) => node.role === "group");
-    expect(groups.map((node) => node.backendNodeId)).toEqual([3]);
-    expect(scene.nodes.find((node) => node.backendNodeId === 6)?.parentId).not.toBe(groups[0]?.id);
-  });
-});

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

@@ -1,17 +1,16 @@
 // CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
 // → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
 // raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
-// shared string table); requested computed styles are decoded through
-// STYLE_COL so capture and visibility policy share one explicit contract.
+// shared string table); we request exactly three computed styles so the
+// `styles` columns are [position, pointer-events, cursor] in that order.
 
 import type { Rect, Viewport } from "@browser-skill/vom";
 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";
 
-const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
+const REQUESTED_STYLES = ["position", "pointer-events", "cursor"] as const;
 const STYLE_COL = Object.fromEntries(
   REQUESTED_STYLES.map((name, index) => [name, index]),
 ) as Record<(typeof REQUESTED_STYLES)[number], number>;
@@ -39,12 +38,6 @@ export interface CapturedNode {
    * `textContent`: the live parser always sets it, hand-built fixtures may not.
    */
   cursor?: string;
-  /**
-   * Whether the live DOM snapshot provides a painted, non-hidden box for this
-   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
-   * nodes remain authoritative even when they are outside the viewport.
-   */
-  rendered?: boolean;
   textContent?: string;
   formState?: "empty" | "filled" | "default";
   formValue?: string;
@@ -467,6 +460,36 @@ function hoverStateExpression(): string {
   })()`;
 }
 
+async function wait(ms: number, signal?: AbortSignal): Promise<void> {
+  throwIfAborted(signal);
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(captureAbortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
+  await cdp
+    .send(tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: -10,
+      y: -10,
+    })
+    .catch(() =>
+      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
+        // best effort
+      }),
+    );
+}
+
 function capturedText(node: CapturedNode): string | undefined {
   const value =
     node.attrs["aria-label"] ?? node.attrs.title ?? node.attrs.alt ?? node.textContent ?? "";
@@ -646,7 +669,7 @@ async function probeHoverSurfaces(
         try {
           await clearHover(cdp, tabId);
           throwIfAborted(options.signal);
-          await waitForHover(HOVER_SETTLE_MS, options.signal);
+          await wait(HOVER_SETTLE_MS, options.signal);
           const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -661,7 +684,7 @@ async function probeHoverSurfaces(
             y: candidate.y,
           });
           throwIfAborted(options.signal);
-          await waitForHover(HOVER_SETTLE_MS, options.signal);
+          await wait(HOVER_SETTLE_MS, options.signal);
           const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -794,8 +817,6 @@ function parseDocumentNodes(
   const posCol = STYLE_COL.position;
   const peCol = STYLE_COL["pointer-events"];
   const cursorCol = STYLE_COL.cursor;
-  const visibilityCol = STYLE_COL.visibility;
-  const opacityCol = STYLE_COL.opacity;
   const inputValues = sparseIndexMap(dn.inputValue);
   const textValues = sparseIndexMap(dn.textValue);
   const checkedInputs = new Set(dn.inputChecked?.index ?? []);
@@ -840,7 +861,6 @@ function parseDocumentNodes(
     let position = "static";
     let pointerEvents = "auto";
     let cursor = "auto";
-    let rendered = false;
     const li = layoutByNode.get(n);
     if (li !== undefined) {
       const b = dl?.bounds?.[li];
@@ -861,13 +881,6 @@ function parseDocumentNodes(
       position = str(strings, styleRow[posCol]) || "static";
       pointerEvents = str(strings, styleRow[peCol]) || "auto";
       cursor = str(strings, styleRow[cursorCol]) || "auto";
-      const visibility = str(strings, styleRow[visibilityCol]) || "visible";
-      const opacity = str(strings, styleRow[opacityCol]) || "1";
-      rendered =
-        localRect !== null &&
-        visibility !== "hidden" &&
-        visibility !== "collapse" &&
-        (Number.parseFloat(opacity) || 0) > 0;
     }
 
     // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
@@ -903,7 +916,6 @@ function parseDocumentNodes(
       position,
       pointerEvents,
       cursor,
-      rendered,
       textContent,
       ...(formValue !== undefined ? { formValue } : {}),
       ...(tag === "input" || tag === "textarea"
@@ -1008,13 +1020,7 @@ export async function captureViewModel(
   options: CaptureViewModelOptions = {},
 ): Promise<CapturedViewModel> {
   throwIfAborted(options.signal);
-  let metrics: LayoutMetricsReply = {};
-  try {
-    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    console.debug("[bsk capture] layout metrics unavailable", error);
-  }
+  const metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
   throwIfAborted(options.signal);
   const dpr = devicePixelRatio(metrics);
   const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};

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

@@ -33,19 +33,25 @@ async function discoverFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFra
 
 function transformFrameNodes(
   nodes: CapturedNode[],
-  projection: GeometryProjection | null,
+  projection: GeometryProjection,
 ): CapturedNode[] {
   return nodes.map((node) => ({
     ...node,
-    rect: projection
-      ? (() => {
-          const bounds = projectRectToViewport(node.rect, projection);
-          return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
-        })()
-      : null,
+    rect: (() => {
+      const bounds = projectRectToViewport(node.rect, projection);
+      return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
+    })(),
   }));
 }
 
+function frameOwnerNode(captured: CapturedViewModel, frame: CdpFrame): CapturedNode | undefined {
+  if (frame.ownerBackendNodeId === undefined) return undefined;
+  const parentNodes = frame.parentFrameId
+    ? captured.frameNodes?.get(frame.parentFrameId)
+    : captured.nodes;
+  return parentNodes?.find((node) => node.backendNodeId === frame.ownerBackendNodeId);
+}
+
 async function captureMissingFrameDocuments(
   cdp: CdpRunner,
   tabId: number,
@@ -59,20 +65,14 @@ async function captureMissingFrameDocuments(
 
   for (const frame of graph.frames) {
     if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
+    const owner = frameOwnerNode(captured, frame);
+    if (!owner?.rect || frame.ownerBackendNodeId === undefined) continue;
     try {
       const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
         signal,
       });
-      let projection: GeometryProjection | null = null;
-      try {
-        projection = await resolveFrameProjection(cdp, graph, frame.frameId);
-      } catch (err) {
-        if (isAbortError(err)) throw err;
-        console.debug("[bsk observation] child frame geometry projection failed", {
-          frameId: frame.frameId,
-          err,
-        });
-      }
+      const projection = await resolveFrameProjection(cdp, graph, frame.frameId);
+      if (!projection) continue;
       const rootFrameId = child.rootFrameId ?? frame.frameId;
       const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
       if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
@@ -85,13 +85,11 @@ async function captureMissingFrameDocuments(
       for (const [childFrameId, nodes] of childFrames) {
         captured.frameNodes.set(childFrameId, transformFrameNodes(nodes, projection));
       }
-      if (frame.ownerBackendNodeId !== undefined) {
-        captured.iframeNodes.set(
-          frame.ownerBackendNodeId,
-          captured.frameNodes.get(frame.frameId) ?? [],
-        );
-        captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
-      }
+      captured.iframeNodes.set(
+        frame.ownerBackendNodeId,
+        captured.frameNodes.get(frame.frameId) ?? [],
+      );
+      captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
       if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
       for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
         captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);

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

@@ -1,37 +0,0 @@
-import type { CdpRunner } from "../shared";
-
-function abortError(): Error {
-  const error = new Error("hover perception aborted");
-  error.name = "AbortError";
-  return error;
-}
-
-export async function waitForHover(ms: number, signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted) throw abortError();
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      reject(abortError());
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-export async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
-  await cdp
-    .send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseMoved",
-      x: -10,
-      y: -10,
-    })
-    .catch(() =>
-      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
-        // Best effort cleanup.
-      }),
-    );
-}

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

@@ -1,296 +0,0 @@
-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 { stableIdentifierName } from "./semantic-graph/name-evidence";
-import { frameBackendKey, type ResolvedSemanticGraph } from "./semantic-graph/types";
-
-const MAX_TOOLTIP_CANDIDATES = 8;
-const MAX_TOOLTIP_PROBE_MS = 2_400;
-const TOOLTIP_SETTLE_MS = 250;
-const CACHE_TTL_MS = 5 * 60_000;
-const MAX_CACHE_ENTRIES = 500;
-const FORM_CONTROL_TAGS = new Set(["input", "select", "textarea"]);
-
-interface TooltipCacheEntry {
-  name: string;
-  expiresAt: number;
-}
-
-interface TooltipCandidate<T extends FrameOwnedAxNode> {
-  document: FrameDocument<T>;
-  backendNodeId: number;
-  x: number;
-  y: number;
-  stableIdentifier: boolean;
-}
-
-export interface TooltipNameProbeOptions {
-  signal?: AbortSignal;
-  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
-}
-
-const tooltipCache = new Map<string, TooltipCacheEntry>();
-
-function cacheKey<T extends FrameOwnedAxNode>(
-  document: FrameDocument<T>,
-  backendNodeId: number,
-): string {
-  return `${document.target.tabId}\u0000${document.frameId}\u0000${document.url ?? ""}\u0000${backendNodeId}`;
-}
-
-function cachedName<T extends FrameOwnedAxNode>(
-  document: FrameDocument<T>,
-  backendNodeId: number,
-): string | undefined {
-  const key = cacheKey(document, backendNodeId);
-  const entry = tooltipCache.get(key);
-  if (!entry) return undefined;
-  if (entry.expiresAt <= Date.now()) {
-    tooltipCache.delete(key);
-    return undefined;
-  }
-  return entry.name;
-}
-
-function storeName<T extends FrameOwnedAxNode>(
-  document: FrameDocument<T>,
-  backendNodeId: number,
-  name: string,
-): void {
-  if (tooltipCache.size >= MAX_CACHE_ENTRIES) {
-    const oldest = tooltipCache.keys().next().value;
-    if (oldest !== undefined) tooltipCache.delete(oldest);
-  }
-  tooltipCache.set(cacheKey(document, backendNodeId), {
-    name,
-    expiresAt: Date.now() + CACHE_TTL_MS,
-  });
-}
-
-function tooltipCollectorFunction(): string {
-  return `function() {
-    const ownRoot = this && typeof this.getRootNode === "function" ? this.getRootNode() : null;
-    const roots = ownRoot && ownRoot !== document ? [ownRoot, document] : [document];
-    const items = [];
-    const seen = new Set();
-    for (const root of roots) {
-      for (const el of Array.from(root.querySelectorAll("[role='tooltip']"))) {
-        const style = getComputedStyle(el);
-        const rect = el.getBoundingClientRect();
-        if (rect.width <= 0 || rect.height <= 0) continue;
-        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") continue;
-        const text = String(el.getAttribute("aria-label") || el.getAttribute("title") || el.textContent || "")
-          .replace(/\\s+/g, " ")
-          .trim();
-        if (!text || text.length > 160 || seen.has(text)) continue;
-        seen.add(text);
-        items.push(text);
-      }
-    }
-    return items.slice(0, 20);
-  }`;
-}
-
-function cleanTooltipDiff(before: string[], after: string[]): string | undefined {
-  const existing = new Set(before.map((value) => value.toLowerCase()));
-  const added = [...new Set(after.map((value) => value.replace(/\s+/g, " ").trim()))].filter(
-    (value) => value && !existing.has(value.toLowerCase()),
-  );
-  return added.length === 1 ? added[0] : undefined;
-}
-
-function candidates<T extends FrameOwnedAxNode>(
-  documents: FrameDocument<T>[],
-  graph: ResolvedSemanticGraph,
-): TooltipCandidate<T>[] {
-  const documentByFrame = new Map(documents.map((document) => [document.frameId, document]));
-  const byFrame = new Map<string, TooltipCandidate<T>[]>();
-  for (const node of graph.nodes.values()) {
-    if (
-      node.vom.name ||
-      FORM_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "") ||
-      !node.referenceable ||
-      node.backendNodeId === undefined ||
-      !isVomReferenceNode({
-        ...node.vom,
-        id: 0,
-        parentId: null,
-        backendNodeId: node.backendNodeId,
-        frameId: node.frameId,
-        referenceable: true,
-      })
-    ) {
-      continue;
-    }
-    const document = documentByFrame.get(node.frameId);
-    const rect = node.dom?.rect;
-    if (!document || !rect || rect.w <= 0 || rect.h <= 0) continue;
-    if (
-      rect.x + rect.w <= 0 ||
-      rect.y + rect.h <= 0 ||
-      rect.x >= graph.viewport.width ||
-      rect.y >= graph.viewport.height
-    ) {
-      continue;
-    }
-    if (
-      node.vom.disabled ||
-      node.vom.inert ||
-      node.vom.pointerEvents === "none" ||
-      node.vom.sensitive
-    ) {
-      continue;
-    }
-    const frameCandidates = byFrame.get(node.frameId) ?? [];
-    frameCandidates.push({
-      document,
-      backendNodeId: node.backendNodeId,
-      x: (Math.max(0, rect.x) + Math.min(graph.viewport.width, rect.x + rect.w)) / 2,
-      y: (Math.max(0, rect.y) + Math.min(graph.viewport.height, rect.y + rect.h)) / 2,
-      stableIdentifier: stableIdentifierName(node.dom?.attrs ?? {}) !== undefined,
-    });
-    byFrame.set(node.frameId, frameCandidates);
-  }
-
-  const out: TooltipCandidate<T>[] = [];
-  for (const stableIdentifier of [true, false]) {
-    const queues = documents.map((document) =>
-      (byFrame.get(document.frameId) ?? []).filter(
-        (candidate) => candidate.stableIdentifier === stableIdentifier,
-      ),
-    );
-    for (let index = 0; queues.some((queue) => index < queue.length); index += 1) {
-      for (const queue of queues) {
-        const candidate = queue[index];
-        if (candidate) out.push(candidate);
-      }
-    }
-  }
-  return out;
-}
-
-async function executionContextId<T extends FrameOwnedAxNode>(
-  cdp: CdpRunner,
-  document: FrameDocument<T>,
-): Promise<number | undefined> {
-  const result = await sendToCdpTarget<{ executionContextId?: number }>(
-    cdp,
-    document.target,
-    "Page.createIsolatedWorld",
-    {
-      frameId: document.frameId,
-      worldName: "bsk-vom-tooltip",
-      grantUniveralAccess: false,
-    },
-  );
-  return result.executionContextId;
-}
-
-async function resolvedObjectId<T extends FrameOwnedAxNode>(
-  cdp: CdpRunner,
-  document: FrameDocument<T>,
-  contextId: number,
-  backendNodeId: number,
-): Promise<string | undefined> {
-  const result = await sendToCdpTarget<{
-    object?: { objectId?: string };
-  }>(cdp, document.target, "DOM.resolveNode", {
-    backendNodeId,
-    executionContextId: contextId,
-  });
-  return result.object?.objectId;
-}
-
-async function tooltipTexts<T extends FrameOwnedAxNode>(
-  cdp: CdpRunner,
-  document: FrameDocument<T>,
-  objectId: string,
-): Promise<string[]> {
-  const result = await sendToCdpTarget<{
-    result?: { value?: string[] };
-  }>(cdp, document.target, "Runtime.callFunctionOn", {
-    functionDeclaration: tooltipCollectorFunction(),
-    objectId,
-    returnByValue: true,
-  });
-  return result.result?.value ?? [];
-}
-
-async function releaseObject<T extends FrameOwnedAxNode>(
-  cdp: CdpRunner,
-  document: FrameDocument<T>,
-  objectId: string,
-): Promise<void> {
-  await sendToCdpTarget(cdp, document.target, "Runtime.releaseObject", { objectId }).catch(
-    () => undefined,
-  );
-}
-
-export async function probeTooltipNames<T extends FrameOwnedAxNode>(
-  cdp: CdpRunner,
-  tabId: number,
-  documents: FrameDocument<T>[],
-  graph: ResolvedSemanticGraph,
-  options: TooltipNameProbeOptions = {},
-): Promise<Map<string, string>> {
-  const names = new Map<string, string>();
-  const pending: TooltipCandidate<T>[] = [];
-  for (const candidate of candidates(documents, graph)) {
-    const cached = cachedName(candidate.document, candidate.backendNodeId);
-    if (cached) {
-      names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), cached);
-    } else if (pending.length < MAX_TOOLTIP_CANDIDATES) {
-      pending.push(candidate);
-    }
-  }
-  if (pending.length === 0) return names;
-
-  const started = Date.now();
-  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;
-      let objectId: string | undefined;
-      try {
-        let contextId = contexts.get(candidate.document.frameId);
-        if (contextId === undefined) {
-          contextId = await executionContextId(cdp, candidate.document);
-          if (contextId === undefined) continue;
-          contexts.set(candidate.document.frameId, contextId);
-        }
-        objectId = await resolvedObjectId(
-          cdp,
-          candidate.document,
-          contextId,
-          candidate.backendNodeId,
-        );
-        if (!objectId) continue;
-        await clearHover(cdp, tabId);
-        const before = await tooltipTexts(cdp, candidate.document, objectId);
-        await cdp.send(tabId, "Input.dispatchMouseEvent", {
-          type: "mouseMoved",
-          x: candidate.x,
-          y: candidate.y,
-        });
-        await waitForHover(TOOLTIP_SETTLE_MS, options.signal);
-        const after = await tooltipTexts(cdp, candidate.document, objectId);
-        const name = cleanTooltipDiff(before, after);
-        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 {
-        if (objectId) await releaseObject(cdp, candidate.document, objectId);
-        await clearHover(cdp, tabId);
-      }
-    }
-  } finally {
-    await clearHover(cdp, tabId);
-    await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
-  }
-  return names;
-}

apps/extension/src/tools/vom/semantic-graph/build.ts

@@ -1,154 +0,0 @@
-import type { Viewport } from "@browser-skill/vom";
-import type { FrameDocument } from "../frame-document";
-import {
-  frameAxKey,
-  frameBackendKey,
-  type SemanticAxNode,
-  type SemanticFrame,
-  type SemanticGraph,
-  type SemanticGraphNode,
-  type SemanticNodeId,
-} from "./types";
-
-export interface BuildSemanticGraphInput {
-  documents: FrameDocument<SemanticAxNode>[];
-  viewport: Viewport;
-  rootFrameId?: string;
-  excludedBackendNodeIds?: ReadonlySet<number>;
-}
-
-function domNodeId(frameId: string, backendNodeId: number): SemanticNodeId {
-  return JSON.stringify([frameId, "dom", backendNodeId]);
-}
-
-function axNodeId(frameId: string, nodeId: string): SemanticNodeId {
-  return JSON.stringify([frameId, "ax", nodeId]);
-}
-
-export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGraph {
-  const rootFrameId =
-    input.rootFrameId ??
-    input.documents.find((document) => !document.parentFrameId)?.frameId ??
-    input.documents[0]?.frameId ??
-    "root";
-  const frames = new Map<string, SemanticFrame>();
-  const nodes = new Map<SemanticNodeId, SemanticGraphNode>();
-  const nodeIdsByFrame = new Map<string, SemanticNodeId[]>();
-  const nodeByFrameBackend = new Map<string, SemanticNodeId>();
-  const nodeByFrameAx = new Map<string, SemanticNodeId>();
-
-  for (const [frameOrder, document] of input.documents.entries()) {
-    frames.set(document.frameId, {
-      frameId: document.frameId,
-      ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
-      ...(document.ownerBackendNodeId !== undefined
-        ? { ownerBackendNodeId: document.ownerBackendNodeId }
-        : {}),
-      contextScopeId: document.contextScopeId,
-      target: document.target,
-      ...(document.url ? { url: document.url } : {}),
-      order: frameOrder,
-    });
-
-    const frameNodeIds: SemanticNodeId[] = [];
-    nodeIdsByFrame.set(document.frameId, frameNodeIds);
-    for (const [index, dom] of document.domNodes.entries()) {
-      const id = domNodeId(document.frameId, dom.backendNodeId);
-      const node: SemanticGraphNode = {
-        id,
-        frameId: document.frameId,
-        backendNodeId: dom.backendNodeId,
-        dom,
-        sourceOrder: index,
-        excluded:
-          document.frameId === rootFrameId &&
-          input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
-      };
-      nodes.set(id, node);
-      frameNodeIds.push(id);
-      nodeByFrameBackend.set(frameBackendKey(document.frameId, dom.backendNodeId), id);
-    }
-
-    for (const [index, ax] of document.axNodes.entries()) {
-      const joinedId =
-        typeof ax.backendDOMNodeId === "number"
-          ? nodeByFrameBackend.get(frameBackendKey(document.frameId, ax.backendDOMNodeId))
-          : undefined;
-      const id = joinedId ?? axNodeId(document.frameId, ax.nodeId);
-      const existing = nodes.get(id);
-      if (existing) {
-        existing.ax = ax;
-        existing.axNodeId = ax.nodeId;
-      } else {
-        nodes.set(id, {
-          id,
-          frameId: document.frameId,
-          ...(typeof ax.backendDOMNodeId === "number"
-            ? { backendNodeId: ax.backendDOMNodeId }
-            : {}),
-          axNodeId: ax.nodeId,
-          ax,
-          sourceOrder: document.domNodes.length + index,
-          excluded:
-            document.frameId === rootFrameId &&
-            typeof ax.backendDOMNodeId === "number" &&
-            input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
-        });
-        frameNodeIds.push(id);
-      }
-      nodeByFrameAx.set(frameAxKey(document.frameId, ax.nodeId), id);
-    }
-  }
-
-  for (const document of input.documents) {
-    for (const dom of document.domNodes) {
-      const id = nodeByFrameBackend.get(frameBackendKey(document.frameId, dom.backendNodeId));
-      const node = id ? nodes.get(id) : undefined;
-      if (!node || dom.parentBackendNodeId === null) continue;
-      node.domParentId = nodeByFrameBackend.get(
-        frameBackendKey(document.frameId, dom.parentBackendNodeId),
-      );
-    }
-    for (const ax of document.axNodes) {
-      const id = nodeByFrameAx.get(frameAxKey(document.frameId, ax.nodeId));
-      const node = id ? nodes.get(id) : undefined;
-      if (!node || !ax.parentId) continue;
-      node.axParentId = nodeByFrameAx.get(frameAxKey(document.frameId, ax.parentId));
-    }
-  }
-
-  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
-  const excludedQueue: SemanticNodeId[] = [];
-  for (const node of nodes.values()) {
-    if (node.axParentId) {
-      const children = axChildren.get(node.axParentId) ?? [];
-      children.push(node.id);
-      axChildren.set(node.axParentId, children);
-    }
-    if (node.excluded) excludedQueue.push(node.id);
-  }
-  for (let index = 0; index < excludedQueue.length; index += 1) {
-    for (const childId of axChildren.get(excludedQueue[index]) ?? []) {
-      const child = nodes.get(childId);
-      if (!child || child.excluded) continue;
-      child.excluded = true;
-      excludedQueue.push(childId);
-    }
-  }
-
-  for (const frame of frames.values()) {
-    if (!frame.parentFrameId || frame.ownerBackendNodeId === undefined) continue;
-    frame.ownerNodeId = nodeByFrameBackend.get(
-      frameBackendKey(frame.parentFrameId, frame.ownerBackendNodeId),
-    );
-  }
-
-  return {
-    viewport: input.viewport,
-    rootFrameId,
-    frames,
-    nodes,
-    nodeIdsByFrame,
-    nodeByFrameBackend,
-  };
-}

apps/extension/src/tools/vom/semantic-graph/index.ts

@@ -1,59 +0,0 @@
-import type { Viewport, VomScene } from "@browser-skill/vom";
-import type { FrameDocument } from "../frame-document";
-import { buildSemanticGraph as buildGraph } from "./build";
-import { projectSemanticGraph as projectGraph } from "./project";
-import { resolveSemanticGraph as resolveGraph } from "./resolve";
-import { normalizeSemanticStructure as normalizeStructure } from "./structure";
-import type {
-  ResolvedSemanticGraph,
-  SemanticAxNode,
-  SemanticGraph,
-  StructuredSemanticGraph,
-} from "./types";
-
-export type { SemanticAxNode } from "./types";
-
-export interface SemanticVomInput {
-  documents: FrameDocument<SemanticAxNode>[];
-  viewport: Viewport;
-  rootFrameId?: string;
-  excludedBackendNodeIds?: ReadonlySet<number>;
-}
-
-export function buildSemanticGraph(input: SemanticVomInput): SemanticGraph {
-  return buildGraph(input);
-}
-
-export function resolveSemanticGraph(
-  graph: SemanticGraph,
-  options: {
-    supplementalNames?: ReadonlyMap<string, string>;
-    identifierFallback?: boolean;
-  } = {},
-): ResolvedSemanticGraph {
-  return resolveGraph(graph, options);
-}
-
-export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
-  return normalizeStructure(graph);
-}
-
-export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
-  return projectGraph(graph);
-}
-
-export function buildSemanticVomScene(
-  input: SemanticVomInput & {
-    supplementalNames?: ReadonlyMap<string, string>;
-    identifierFallback?: boolean;
-  },
-): VomScene {
-  return projectSemanticGraph(
-    normalizeSemanticStructure(
-      resolveSemanticGraph(buildSemanticGraph(input), {
-        supplementalNames: input.supplementalNames,
-        identifierFallback: input.identifierFallback,
-      }),
-    ),
-  );
-}

apps/extension/src/tools/vom/semantic-graph/name-evidence.ts

@@ -1,34 +0,0 @@
-const IDENTIFIER_ATTRS = ["data-testid", "data-test-id", "id"] as const;
-const GENERIC_TOKENS = new Set(["btn", "button", "control", "icon", "item", "test", "tool"]);
-const GENERATED_PREFIXES = new Set(["ember", "headlessui", "mui", "radix", "react", "rc"]);
-
-function identifierTokens(value: string): string[] {
-  return value
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .split(/[^a-zA-Z0-9]+/)
-    .map((token) => token.toLowerCase())
-    .filter(Boolean);
-}
-
-function readableIdentifier(value: string | undefined): string | undefined {
-  const raw = value?.trim();
-  if (!raw || raw.length < 3 || raw.length > 80) return undefined;
-  if (/^[a-f0-9]{8,}$/i.test(raw)) return undefined;
-
-  const tokens = identifierTokens(raw);
-  if (GENERATED_PREFIXES.has(tokens[0])) return undefined;
-  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[0])) tokens.shift();
-  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[tokens.length - 1])) tokens.pop();
-  if (tokens.length === 0 || !tokens.some((token) => /[a-z]{3,}/.test(token))) return undefined;
-  return tokens
-    .map((token, index) => (index === 0 ? `${token[0].toUpperCase()}${token.slice(1)}` : token))
-    .join(" ");
-}
-
-export function stableIdentifierName(attrs: Readonly<Record<string, string>>): string | undefined {
-  for (const name of IDENTIFIER_ATTRS) {
-    const label = readableIdentifier(attrs[name]);
-    if (label) return label;
-  }
-  return undefined;
-}

apps/extension/src/tools/vom/semantic-graph/project.ts

@@ -1,85 +0,0 @@
-import type { VomNode, VomScene } from "@browser-skill/vom";
-import type { SemanticNodeId, StructuredSemanticGraph, StructuredSemanticNode } from "./types";
-
-function retained(node: StructuredSemanticNode): boolean {
-  return node.structure.kind === "keep" || node.structure.kind === "inferred-group";
-}
-
-function connectedFrameIds(graph: StructuredSemanticGraph): Set<string> {
-  const connected = new Set<string>([graph.rootFrameId]);
-  const childrenByParent = new Map<string, string[]>();
-  for (const frame of graph.frames.values()) {
-    if (!frame.parentFrameId) continue;
-    const children = childrenByParent.get(frame.parentFrameId) ?? [];
-    children.push(frame.frameId);
-    childrenByParent.set(frame.parentFrameId, children);
-  }
-  const queue = [graph.rootFrameId];
-  for (let index = 0; index < queue.length; index += 1) {
-    for (const frameId of childrenByParent.get(queue[index]) ?? []) {
-      if (connected.has(frameId)) continue;
-      const frame = graph.frames.get(frameId);
-      if (!frame?.ownerNodeId) continue;
-      const owner = graph.nodes.get(frame.ownerNodeId);
-      if (!owner || !retained(owner)) continue;
-      connected.add(frame.frameId);
-      queue.push(frame.frameId);
-    }
-  }
-  return connected;
-}
-
-function domAncestors(
-  graph: StructuredSemanticGraph,
-  node: StructuredSemanticNode,
-  numericId: ReadonlyMap<SemanticNodeId, number>,
-): number[] {
-  const ancestors: number[] = [];
-  const seen = new Set<SemanticNodeId>();
-  let current = node.domParentId;
-  while (current && !seen.has(current)) {
-    seen.add(current);
-    const id = numericId.get(current);
-    if (id !== undefined) ancestors.push(id);
-    current = graph.nodes.get(current)?.domParentId;
-  }
-  return ancestors;
-}
-
-export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
-  const connectedFrames = connectedFrameIds(graph);
-  const orderedNodes = [...graph.frames.values()]
-    .filter((frame) => connectedFrames.has(frame.frameId))
-    .sort((a, b) => a.order - b.order)
-    .flatMap((frame) =>
-      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
-        .map((id) => graph.nodes.get(id))
-        .filter((node): node is StructuredSemanticNode => node !== undefined && retained(node))
-        .sort((a, b) => a.sourceOrder - b.sourceOrder),
-    );
-
-  const numericId = new Map<SemanticNodeId, number>();
-  orderedNodes.forEach((node, index) => numericId.set(node.id, index + 1));
-  const nodes: VomNode[] = orderedNodes.map((node) => ({
-    ...node.vom,
-    id: numericId.get(node.id) as number,
-    parentId: node.semanticParentId ? (numericId.get(node.semanticParentId) ?? null) : null,
-    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
-    frameId: node.frameId,
-    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
-    referenceable: node.referenceable,
-    ...(node.dom
-      ? {
-          domParentId:
-            node.domParentId === undefined ? null : (numericId.get(node.domParentId) ?? null),
-          domAncestorIds: domAncestors(graph, node, numericId),
-        }
-      : {}),
-  }));
-
-  return {
-    viewport: graph.viewport,
-    nodes,
-    rootFrameId: graph.rootFrameId,
-  };
-}

apps/extension/src/tools/vom/semantic-graph/resolve.ts

@@ -1,521 +0,0 @@
-import type { VomNode } from "@browser-skill/vom";
-import { stableIdentifierName } from "./name-evidence";
-import type {
-  ResolvedSemanticGraph,
-  ResolvedSemanticNode,
-  SemanticAxNode,
-  SemanticGraph,
-  SemanticGraphNode,
-  SemanticNodeId,
-} from "./types";
-import { frameBackendKey } from "./types";
-
-const FORM_TAGS = new Set(["input", "textarea", "select"]);
-const NATIVE_CONTROL_TAGS = new Set(["button", "input", "select", "textarea"]);
-const TEXT_AX_ROLES = new Set(["statictext", "inlinetextbox", "labeltext", "text"]);
-const INTERACTIVE_ROLES = new Set([
-  "button",
-  "checkbox",
-  "combobox",
-  "link",
-  "listbox",
-  "menuitem",
-  "menuitemcheckbox",
-  "menuitemradio",
-  "option",
-  "radio",
-  "searchbox",
-  "slider",
-  "spinbutton",
-  "switch",
-  "tab",
-  "textbox",
-  "treeitem",
-]);
-const SENSITIVE_INPUT_TYPES = new Set([
-  "password",
-  "credit-card",
-  "one-time-code",
-  "current-password",
-  "new-password",
-]);
-
-function clean(value: string | undefined): string | undefined {
-  const normalized = value?.replace(/\s+/g, " ").trim();
-  return normalized || undefined;
-}
-
-function axValue(field?: { value?: string | number | boolean }): string | undefined {
-  return field?.value === undefined ? undefined : clean(String(field.value));
-}
-
-function axProperty(node: SemanticAxNode | undefined, name: string): string | undefined {
-  return axValue(node?.properties?.find((property) => property.name === name)?.value);
-}
-
-function normalizeRole(value: string | undefined): string | undefined {
-  const role = clean(value)?.toLowerCase();
-  return role || undefined;
-}
-
-function nativeRole(tag: string, attrs: Record<string, string>): string | undefined {
-  if (tag === "button") return "button";
-  if (tag === "textarea") return "textbox";
-  if (tag === "select") return attrs.multiple === undefined ? "combobox" : "listbox";
-  if (tag === "a" && attrs.href) return "link";
-  if (tag === "iframe") return "Iframe";
-  if (tag === "dialog") return "dialog";
-  if (tag === "img") return "img";
-  if (tag === "table") return "table";
-  if (tag === "tr") return "row";
-  if (tag === "th") return "columnheader";
-  if (tag === "td") return "cell";
-  if (tag === "ul" || tag === "ol") return "list";
-  if (tag === "li") return "listitem";
-  if (/^h[1-6]$/.test(tag)) return "heading";
-  if (tag === "nav") return "navigation";
-  if (tag === "main") return "main";
-  if (tag === "form") return "form";
-  if (tag === "input") {
-    const type = (attrs.type ?? "text").toLowerCase();
-    if (type === "hidden") return undefined;
-    if (type === "checkbox") return "checkbox";
-    if (type === "radio") return "radio";
-    if (type === "range") return "slider";
-    if (type === "number") return "spinbutton";
-    if (type === "search") return "searchbox";
-    if (["button", "submit", "reset", "image"].includes(type)) return "button";
-    return "textbox";
-  }
-  return undefined;
-}
-
-function domRole(tag: string, attrs: Record<string, string>): string | undefined {
-  return normalizeRole(attrs.role) ?? nativeRole(tag, attrs);
-}
-
-function resolvedRole(node: SemanticGraphNode): {
-  value?: string;
-  source: ResolvedSemanticNode["roleSource"];
-} {
-  const rawAxRole = clean(axValue(node.ax?.role));
-  const axRole = normalizeRole(rawAxRole);
-  const attrs = node.dom?.attrs ?? {};
-  const explicitDomRole = normalizeRole(attrs.role);
-  const nativeDomRole = nativeRole(node.dom?.tag.toLowerCase() ?? "", attrs);
-  const usableAxRole = node.ax?.ignored !== true;
-  if (usableAxRole && axRole && !["generic", "none", "presentation"].includes(axRole)) {
-    return { value: rawAxRole, source: "ax" };
-  }
-  if (explicitDomRole) return { value: explicitDomRole, source: "dom-explicit" };
-  if (nativeDomRole) return { value: nativeDomRole, source: "dom-native" };
-  if (rawAxRole) {
-    return { value: rawAxRole, source: usableAxRole ? "ax" : "ax-ignored" };
-  }
-  return { source: "none" };
-}
-
-function sensitive(node: SemanticGraphNode): boolean {
-  const attrs = node.dom?.attrs ?? {};
-  const type = (attrs.type ?? "").toLowerCase();
-  const autocomplete = (attrs.autocomplete ?? "").toLowerCase();
-  return (
-    type === "password" ||
-    autocomplete.startsWith("cc-") ||
-    SENSITIVE_INPUT_TYPES.has(autocomplete) ||
-    SENSITIVE_INPUT_TYPES.has(axProperty(node.ax, "inputType") ?? "")
-  );
-}
-
-function inputState(
-  node: SemanticGraphNode,
-  role: string | undefined,
-  value: string | undefined,
-  isSensitive: boolean,
-): VomNode["inputState"] {
-  if (node.dom?.formState) return node.dom.formState;
-  const tag = node.dom?.tag.toLowerCase() ?? "";
-  if (!FORM_TAGS.has(tag) && !["textbox", "searchbox"].includes(role ?? "")) return undefined;
-  if (isSensitive) return value ? "filled" : "empty";
-  if (node.dom?.formValue !== undefined) {
-    if (node.dom.formValue === "") return "empty";
-    return node.dom.formValue === (node.dom.formDefaultValue ?? "") ? "default" : "filled";
-  }
-  return value ? "filled" : "empty";
-}
-
-function externalHrefHost(
-  href: string | undefined,
-  pageUrl: string | undefined,
-): string | undefined {
-  if (!href || !pageUrl) return undefined;
-  try {
-    const page = new URL(pageUrl);
-    const target = new URL(href, page);
-    return target.origin === page.origin ? undefined : target.hostname;
-  } catch {
-    return undefined;
-  }
-}
-
-interface ResolveIndexes {
-  domChildren: Map<SemanticNodeId, SemanticNodeId[]>;
-  axChildren: Map<SemanticNodeId, SemanticNodeId[]>;
-  domIdIndex: Map<string, SemanticNodeId>;
-  labelForIndex: Map<string, SemanticNodeId[]>;
-  domText: (nodeId: SemanticNodeId) => string | undefined;
-  axText: (nodeId: SemanticNodeId) => string | undefined;
-  hasNativeDescendant: (nodeId: SemanticNodeId) => boolean;
-}
-
-function buildIndexes(graph: SemanticGraph): ResolveIndexes {
-  const domChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
-  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
-  const domIdIndex = new Map<string, SemanticNodeId>();
-  const labelForIndex = new Map<string, SemanticNodeId[]>();
-  for (const node of graph.nodes.values()) {
-    if (node.domParentId) {
-      const children = domChildren.get(node.domParentId) ?? [];
-      children.push(node.id);
-      domChildren.set(node.domParentId, children);
-    }
-    if (node.axParentId) {
-      const children = axChildren.get(node.axParentId) ?? [];
-      children.push(node.id);
-      axChildren.set(node.axParentId, children);
-    }
-    const id = clean(node.dom?.attrs.id);
-    if (id) domIdIndex.set(`${node.frameId}\u0000${id}`, node.id);
-    const targetId = clean(node.dom?.attrs.for);
-    if (node.dom?.tag.toLowerCase() === "label" && targetId) {
-      const key = `${node.frameId}\u0000${targetId}`;
-      const labels = labelForIndex.get(key) ?? [];
-      labels.push(node.id);
-      labelForIndex.set(key, labels);
-    }
-  }
-
-  for (const [parentId, children] of axChildren) {
-    const order = graph.nodes.get(parentId)?.ax?.childIds ?? [];
-    const orderByAxId = new Map(order.map((nodeId, index) => [nodeId, index]));
-    children.sort((a, b) => {
-      const aIndex = orderByAxId.get(graph.nodes.get(a)?.axNodeId ?? "") ?? -1;
-      const bIndex = orderByAxId.get(graph.nodes.get(b)?.axNodeId ?? "") ?? -1;
-      return (
-        (aIndex < 0 ? Number.MAX_SAFE_INTEGER : aIndex) -
-        (bIndex < 0 ? Number.MAX_SAFE_INTEGER : bIndex)
-      );
-    });
-  }
-
-  const textMemo = new Map<SemanticNodeId, string | undefined>();
-  const resolvingText = new Set<SemanticNodeId>();
-  const domText = (nodeId: SemanticNodeId): string | undefined => {
-    if (textMemo.has(nodeId)) return textMemo.get(nodeId);
-    if (resolvingText.has(nodeId)) return undefined;
-    resolvingText.add(nodeId);
-    const node = graph.nodes.get(nodeId);
-    const parts: string[] = [];
-    const own = clean(node?.dom?.textContent);
-    if (own) parts.push(own);
-    for (const childId of domChildren.get(nodeId) ?? []) {
-      const child = graph.nodes.get(childId);
-      const childRole = child
-        ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
-        : undefined;
-      if (childRole && INTERACTIVE_ROLES.has(childRole.toLowerCase())) continue;
-      const childText = domText(childId);
-      if (childText) parts.push(childText);
-      if (parts.join(" ").length >= 240) break;
-    }
-    resolvingText.delete(nodeId);
-    const result = clean(parts.join(" ").slice(0, 240));
-    textMemo.set(nodeId, result);
-    return result;
-  };
-
-  const axTextMemo = new Map<SemanticNodeId, string | undefined>();
-  const resolvingAxText = new Set<SemanticNodeId>();
-  const axText = (nodeId: SemanticNodeId): string | undefined => {
-    if (axTextMemo.has(nodeId)) return axTextMemo.get(nodeId);
-    if (resolvingAxText.has(nodeId)) return undefined;
-    resolvingAxText.add(nodeId);
-    const complete = (value: string | undefined): string | undefined => {
-      resolvingAxText.delete(nodeId);
-      axTextMemo.set(nodeId, value);
-      return value;
-    };
-    const node = graph.nodes.get(nodeId);
-    const role = normalizeRole(axValue(node?.ax?.role)) ?? "";
-    if (TEXT_AX_ROLES.has(role)) {
-      const own = clean(axValue(node?.ax?.name) ?? axValue(node?.ax?.value));
-      if (own) return complete(own);
-    }
-    const parts: string[] = [];
-    for (const childId of axChildren.get(nodeId) ?? []) {
-      const child = graph.nodes.get(childId);
-      const childRole = normalizeRole(axValue(child?.ax?.role)) ?? "";
-      if (INTERACTIVE_ROLES.has(childRole)) continue;
-      const childText = axText(childId);
-      if (childText) parts.push(childText);
-      if (parts.join(" ").length >= 240) break;
-    }
-    return complete(clean(parts.join(" ").slice(0, 240)));
-  };
-
-  const nativeMemo = new Map<SemanticNodeId, boolean>();
-  const hasNativeDescendant = (nodeId: SemanticNodeId): boolean => {
-    const cached = nativeMemo.get(nodeId);
-    if (cached !== undefined) return cached;
-    nativeMemo.set(nodeId, false);
-    for (const childId of domChildren.get(nodeId) ?? []) {
-      const child = graph.nodes.get(childId);
-      const childRole =
-        (child?.ax?.ignored === true ? undefined : normalizeRole(axValue(child?.ax?.role))) ??
-        (child ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {}) : undefined);
-      if (
-        (child?.dom && NATIVE_CONTROL_TAGS.has(child.dom.tag.toLowerCase())) ||
-        INTERACTIVE_ROLES.has(childRole ?? "") ||
-        hasNativeDescendant(childId)
-      ) {
-        nativeMemo.set(nodeId, true);
-        return true;
-      }
-    }
-    return false;
-  };
-
-  return {
-    domChildren,
-    axChildren,
-    domIdIndex,
-    labelForIndex,
-    domText,
-    axText,
-    hasNativeDescendant,
-  };
-}
-
-function ariaLabelledText(node: SemanticGraphNode, indexes: ResolveIndexes): string | undefined {
-  const ids = (node.dom?.attrs["aria-labelledby"] ?? "").split(/\s+/).filter(Boolean);
-  const parts = ids.flatMap((id) => {
-    const target = indexes.domIdIndex.get(`${node.frameId}\u0000${id}`);
-    return target ? (indexes.domText(target) ?? []) : [];
-  });
-  return clean(parts.join(" "));
-}
-
-function nativeLabelText(
-  node: SemanticGraphNode,
-  graph: SemanticGraph,
-  indexes: ResolveIndexes,
-): string | undefined {
-  const id = clean(node.dom?.attrs.id);
-  if (id) {
-    const labels = indexes.labelForIndex.get(`${node.frameId}\u0000${id}`) ?? [];
-    const explicit = clean(
-      labels
-        .map((labelId) => indexes.domText(labelId))
-        .filter(Boolean)
-        .join(" "),
-    );
-    if (explicit) return explicit;
-  }
-  let parentId = node.domParentId;
-  let guard = 0;
-  while (parentId && guard <= graph.nodes.size) {
-    const parent = graph.nodes.get(parentId);
-    if (!parent) break;
-    if (parent.dom?.tag.toLowerCase() === "label") return indexes.domText(parentId);
-    parentId = parent.domParentId;
-    guard += 1;
-  }
-  return undefined;
-}
-
-function precedingAxText(
-  node: SemanticGraphNode,
-  graph: SemanticGraph,
-  indexes: ResolveIndexes,
-): string | undefined {
-  if (!node.axParentId) return undefined;
-  const siblings = indexes.axChildren.get(node.axParentId) ?? [];
-  const index = siblings.indexOf(node.id);
-  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
-    const sibling = graph.nodes.get(siblings[index - offset]);
-    const role = normalizeRole(axValue(sibling?.ax?.role)) ?? "";
-    if (INTERACTIVE_ROLES.has(role)) break;
-    if (!TEXT_AX_ROLES.has(role) && role !== "generic") continue;
-    const text = clean(axValue(sibling?.ax?.name) ?? axValue(sibling?.ax?.value))?.replace(
-      /[：:]\s*$/,
-      "",
-    );
-    if (text && text.length <= 80) return text;
-  }
-  return undefined;
-}
-
-function precedingDomText(
-  node: SemanticGraphNode,
-  graph: SemanticGraph,
-  indexes: ResolveIndexes,
-): string | undefined {
-  if (!node.domParentId) return undefined;
-  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
-  const index = siblings.indexOf(node.id);
-  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
-    const sibling = graph.nodes.get(siblings[index - offset]);
-    const siblingRole = sibling
-      ? domRole(sibling.dom?.tag.toLowerCase() ?? "", sibling.dom?.attrs ?? {})
-      : undefined;
-    if (siblingRole && INTERACTIVE_ROLES.has(siblingRole.toLowerCase())) break;
-    const text = indexes.domText(siblings[index - offset])?.replace(/[：:]\s*$/, "");
-    if (text && text.length <= 80) return text;
-  }
-  return undefined;
-}
-
-function resolvedName(
-  node: SemanticGraphNode,
-  role: string | undefined,
-  graph: SemanticGraph,
-  indexes: ResolveIndexes,
-  supplementalNames: ReadonlyMap<string, string>,
-  identifierFallback: boolean,
-): string | undefined {
-  const attrs = node.dom?.attrs ?? {};
-  const formControl = FORM_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
-  const descendantText = indexes.domText(node.id);
-  const interactive =
-    INTERACTIVE_ROLES.has(role?.toLowerCase() ?? "") ||
-    NATIVE_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
-  const candidates = [
-    node.ax?.ignored === true ? undefined : axValue(node.ax?.name),
-    ariaLabelledText(node, indexes),
-    clean(attrs["aria-label"]),
-    nativeLabelText(node, graph, indexes),
-    clean(attrs.title),
-    clean(attrs.alt),
-    node.ax?.ignored === true ? undefined : indexes.axText(node.id),
-    descendantText,
-    formControl ? precedingAxText(node, graph, indexes) : undefined,
-    formControl ? precedingDomText(node, graph, indexes) : undefined,
-    formControl ? clean(node.dom?.formPlaceholder ?? attrs.placeholder) : undefined,
-    formControl || !interactive || node.backendNodeId === undefined
-      ? undefined
-      : clean(supplementalNames.get(frameBackendKey(node.frameId, node.backendNodeId))),
-    identifierFallback && interactive ? stableIdentifierName(attrs) : undefined,
-  ];
-  let name = candidates.find((candidate) => candidate !== undefined);
-  const hasPopup = axProperty(node.ax, "hasPopup");
-  if (name && hasPopup && hasPopup !== "false") {
-    name =
-      axProperty(node.ax, "expanded") === "true" ? `${name} [expanded]` : `${name} [has-submenu]`;
-  }
-  if (!name && role?.toLowerCase() === "iframe") return clean(attrs.id);
-  return name;
-}
-
-function insideNative(node: SemanticGraphNode, graph: SemanticGraph): boolean {
-  let parentId = node.domParentId;
-  let guard = 0;
-  while (parentId && guard <= graph.nodes.size) {
-    const parent = graph.nodes.get(parentId);
-    if (!parent) break;
-    if (parent.dom && NATIVE_CONTROL_TAGS.has(parent.dom.tag.toLowerCase())) return true;
-    parentId = parent.domParentId;
-    guard += 1;
-  }
-  return false;
-}
-
-function nearbyText(
-  node: SemanticGraphNode,
-  graph: SemanticGraph,
-  indexes: ResolveIndexes,
-): string | undefined {
-  if (!node.domParentId) return undefined;
-  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
-  const index = siblings.indexOf(node.id);
-  if (index < 0) return undefined;
-  const texts = siblings
-    .slice(Math.max(0, index - 3), index + 4)
-    .filter((id) => id !== node.id)
-    .flatMap((id) => indexes.domText(id) ?? [])
-    .slice(0, 3);
-  return clean(texts.join(" "));
-}
-
-export function resolveSemanticGraph(
-  graph: SemanticGraph,
-  options: {
-    supplementalNames?: ReadonlyMap<string, string>;
-    identifierFallback?: boolean;
-  } = {},
-): ResolvedSemanticGraph {
-  const indexes = buildIndexes(graph);
-  const supplementalNames = options.supplementalNames ?? new Map<string, string>();
-  const identifierFallback = options.identifierFallback ?? true;
-  const nodes = new Map<SemanticNodeId, ResolvedSemanticNode>();
-  for (const node of graph.nodes.values()) {
-    const roleResolution = resolvedRole(node);
-    const role = roleResolution.value;
-    const name = resolvedName(node, role, graph, indexes, supplementalNames, identifierFallback);
-    const isSensitive = sensitive(node);
-    const sourceValue = node.dom?.formValue ?? axValue(node.ax?.value);
-    const value = isSensitive ? undefined : sourceValue;
-    const attrs = { ...(node.dom?.attrs ?? {}) };
-    if (isSensitive) delete attrs.value;
-    const frame = graph.frames.get(node.frameId);
-    const tag = node.dom?.tag.toLowerCase() ?? "";
-    const vom: ResolvedSemanticNode["vom"] = {
-      tag,
-      rect: node.dom?.rect ?? null,
-      paintOrder: node.dom?.paintOrder ?? 0,
-      position: node.dom?.position || "static",
-      pointerEvents: node.dom?.pointerEvents || "auto",
-      ...(node.dom?.cursor ? { cursor: node.dom.cursor } : {}),
-      ...(role ? { role } : {}),
-      ...(name ? { name } : {}),
-      ...(value !== undefined ? { value } : {}),
-      ...(clean(node.dom?.formPlaceholder ?? attrs.placeholder)
-        ? { placeholder: clean(node.dom?.formPlaceholder ?? attrs.placeholder) }
-        : {}),
-      attrs,
-      ...(clean(node.dom?.textContent) ? { text: clean(node.dom?.textContent) } : {}),
-      ...(nearbyText(node, graph, indexes) ? { nearbyText: nearbyText(node, graph, indexes) } : {}),
-      inputState: inputState(node, role, sourceValue, isSensitive),
-      sensitive: isSensitive,
-      modal:
-        ["dialog", "alertdialog"].includes(role?.toLowerCase() ?? "") ||
-        tag === "dialog" ||
-        (attrs["aria-modal"] ?? "").toLowerCase() === "true",
-      disabled:
-        Object.prototype.hasOwnProperty.call(attrs, "disabled") ||
-        (attrs["aria-disabled"] ?? "").toLowerCase() === "true",
-      inert: Object.prototype.hasOwnProperty.call(attrs, "inert"),
-      hasNativeDescendant: indexes.hasNativeDescendant(node.id),
-      insideNative: insideNative(node, graph),
-      ...(role?.toLowerCase() === "link" ? { href: externalHrefHost(attrs.href, frame?.url) } : {}),
-    };
-    const selected = node.ax?.ignored === true ? undefined : axProperty(node.ax, "selected");
-    const expanded = node.ax?.ignored === true ? undefined : axProperty(node.ax, "expanded");
-    const controls = node.ax?.ignored === true ? undefined : axProperty(node.ax, "controls");
-    if (selected === "true" && !vom.attrs?.["aria-selected"]) {
-      vom.attrs = { ...(vom.attrs ?? {}), "aria-selected": "true" };
-    }
-    if (expanded === "true" && !vom.attrs?.["aria-expanded"]) {
-      vom.attrs = { ...(vom.attrs ?? {}), "aria-expanded": "true" };
-    }
-    if (controls && !vom.attrs?.["aria-controls"]) {
-      vom.attrs = { ...(vom.attrs ?? {}), "aria-controls": controls };
-    }
-    nodes.set(node.id, {
-      ...node,
-      vom,
-      referenceable: node.backendNodeId !== undefined,
-      roleSource: roleResolution.source,
-    });
-  }
-  return { ...graph, nodes };
-}

apps/extension/src/tools/vom/semantic-graph/structure.ts

@@ -1,456 +0,0 @@
-import {
-  applyVomInteractionRecovery,
-  isVomReferenceNode,
-  isVomStructuralRole,
-  type VomNode,
-} from "@browser-skill/vom";
-import type {
-  ResolvedSemanticGraph,
-  ResolvedSemanticNode,
-  SemanticNodeId,
-  StructureDecision,
-  StructuredSemanticGraph,
-  StructuredSemanticNode,
-} from "./types";
-
-const TRANSPARENT_ROLES = new Set(["", "generic", "none", "presentation", "inlinetextbox"]);
-const ROOT_ROLES = new Set(["rootwebarea", "webarea"]);
-const CONTENT_BOUNDARY_ROLES = new Set([
-  "article",
-  "dialog",
-  "document",
-  "feed",
-  "form",
-  "grid",
-  "heading",
-  "iframe",
-  "list",
-  "main",
-  "navigation",
-  "paragraph",
-  "region",
-  "section",
-  "table",
-  "tree",
-]);
-
-function hasMeaningfulRelations(node: ResolvedSemanticNode): boolean {
-  const attrs = node.vom.attrs ?? {};
-  return ["aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"].some((name) =>
-    attrs[name]?.trim(),
-  );
-}
-
-function explicitStructural(node: ResolvedSemanticNode): boolean {
-  return (
-    isVomStructuralRole(node.vom.role) &&
-    node.roleSource !== "none" &&
-    node.roleSource !== "ax-ignored"
-  );
-}
-
-function hasUsableAxSemantics(node: ResolvedSemanticNode): boolean {
-  return node.ax !== undefined && node.ax.ignored !== true;
-}
-
-function isRenderedDomFallback(node: ResolvedSemanticNode): boolean {
-  if (!node.dom) return false;
-  const attrs = node.dom.attrs;
-  if (
-    Object.prototype.hasOwnProperty.call(attrs, "hidden") ||
-    Object.prototype.hasOwnProperty.call(attrs, "inert") ||
-    (attrs["aria-hidden"] ?? "").toLowerCase() === "true"
-  ) {
-    return false;
-  }
-  return node.dom.rendered ?? (node.dom.localRect != null || node.dom.rect != null);
-}
-
-function initialParentId(
-  graph: ResolvedSemanticGraph,
-  node: ResolvedSemanticNode,
-): SemanticNodeId | undefined {
-  let parentId = node.axParentId ?? node.domParentId;
-  if (node.axParentId && node.domParentId && node.axParentId !== node.domParentId) {
-    const axParent = graph.nodes.get(node.axParentId);
-    const axRole = axParent?.vom.role?.toLowerCase() ?? "";
-    const meaningfulAxParent =
-      axParent !== undefined &&
-      !ROOT_ROLES.has(axRole) &&
-      (explicitStructural(axParent) ||
-        !TRANSPARENT_ROLES.has(axRole) ||
-        Boolean(axParent.vom.name || axParent.vom.text || hasMeaningfulRelations(axParent)));
-    parentId = meaningfulAxParent ? node.axParentId : node.domParentId;
-  }
-  if (parentId) return parentId;
-  if (node.frameId === graph.rootFrameId) return undefined;
-  return graph.frames.get(node.frameId)?.ownerNodeId;
-}
-
-function orderedNodes(graph: ResolvedSemanticGraph): ResolvedSemanticNode[] {
-  return [...graph.frames.values()]
-    .sort((a, b) => a.order - b.order)
-    .flatMap((frame) =>
-      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
-        .map((id) => graph.nodes.get(id))
-        .filter((node): node is ResolvedSemanticNode => node !== undefined)
-        .sort((a, b) => a.sourceOrder - b.sourceOrder),
-    );
-}
-
-function recoveredNodes(
-  graph: ResolvedSemanticGraph,
-  nodes: ResolvedSemanticNode[],
-): Map<SemanticNodeId, VomNode> {
-  const numericId = new Map(nodes.map((node, index) => [node.id, index + 1]));
-  const semanticId = new Map([...numericId].map(([id, numeric]) => [numeric, id]));
-  const provisional = nodes.map((node) => ({
-    ...node.vom,
-    id: numericId.get(node.id) as number,
-    parentId: (() => {
-      const parent = initialParentId(graph, node);
-      return parent ? (numericId.get(parent) ?? null) : null;
-    })(),
-    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
-    frameId: node.frameId,
-    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
-    referenceable: node.referenceable,
-  }));
-  return new Map(
-    applyVomInteractionRecovery(provisional).flatMap((node) => {
-      const id = semanticId.get(node.id);
-      return id ? [[id, node] as const] : [];
-    }),
-  );
-}
-
-function redundantSourceNodes(
-  graph: ResolvedSemanticGraph,
-  nodes: ResolvedSemanticNode[],
-  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
-): Set<SemanticNodeId> {
-  const byKey = new Map<string, ResolvedSemanticNode[]>();
-  for (const node of nodes) {
-    const output = recovered.get(node.id) as VomNode;
-    const name = output.name?.trim().toLowerCase() ?? "";
-    if (!name || !isVomReferenceNode({ ...output, referenceable: true })) continue;
-    const key = `${node.frameId}\u0000${initialParentId(graph, node) ?? ""}\u0000${output.role?.toLowerCase() ?? ""}\u0000${name}\u0000${output.sensitive === true}`;
-    const matches = byKey.get(key) ?? [];
-    matches.push(node);
-    byKey.set(key, matches);
-  }
-  const redundant = new Set<SemanticNodeId>();
-  for (const matches of byKey.values()) {
-    const axOnly = matches.filter((node) => node.ax && !node.dom);
-    const domOnly = matches.filter((node) => node.dom && !node.ax);
-    if (matches.length === 2 && axOnly.length === 1 && domOnly.length === 1) {
-      redundant.add(domOnly[0].id);
-    }
-  }
-  return redundant;
-}
-
-function baseDecision(
-  graph: ResolvedSemanticGraph,
-  node: ResolvedSemanticNode,
-  output: VomNode,
-  frameOwnerIds: ReadonlySet<SemanticNodeId>,
-  redundant: ReadonlySet<SemanticNodeId>,
-): StructureDecision {
-  if (node.excluded) return { kind: "excluded", reason: "excluded" };
-  if (redundant.has(node.id)) return { kind: "excluded", reason: "redundant-source" };
-  if (!hasUsableAxSemantics(node) && !isRenderedDomFallback(node)) {
-    return { kind: "excluded", reason: "non-rendered-dom-fallback" };
-  }
-  if (frameOwnerIds.has(node.id)) return { kind: "keep", reason: "frame-owner" };
-  if (node.frameId !== graph.rootFrameId && ROOT_ROLES.has(output.role?.toLowerCase() ?? "")) {
-    return { kind: "transparent", reason: "child-document-root" };
-  }
-  if (node.ax?.ignored === true && !node.dom) {
-    return { kind: "transparent", reason: "ax-ignored" };
-  }
-  const role = output.role?.toLowerCase() ?? "";
-  if (!TRANSPARENT_ROLES.has(role)) return { kind: "keep", reason: "semantic" };
-  if (
-    output.name ||
-    output.text ||
-    output.value ||
-    output.placeholder ||
-    hasMeaningfulRelations(node) ||
-    (output.rect && ["fixed", "sticky"].includes(output.position))
-  ) {
-    return { kind: "keep", reason: "semantic" };
-  }
-  return { kind: "transparent", reason: "wrapper" };
-}
-
-function buildChildren(
-  nodes: ResolvedSemanticNode[],
-  relation: "axParentId" | "domParentId",
-): Map<SemanticNodeId, SemanticNodeId[]> {
-  const children = new Map<SemanticNodeId, SemanticNodeId[]>();
-  for (const node of nodes) {
-    const parentId = node[relation];
-    if (!parentId) continue;
-    const siblings = children.get(parentId) ?? [];
-    siblings.push(node.id);
-    children.set(parentId, siblings);
-  }
-  return children;
-}
-
-function explicitDomAncestors(
-  graph: ResolvedSemanticGraph,
-  nodes: ResolvedSemanticNode[],
-  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
-): Set<SemanticNodeId> {
-  const inside = new Set<SemanticNodeId>();
-  const roots = nodes.filter((node) => !node.domParentId);
-  const queue = roots.map((node) => node.id);
-  for (let index = 0; index < queue.length; index += 1) {
-    const parentId = queue[index];
-    const parent = graph.nodes.get(parentId);
-    const parentIsBoundary =
-      parent !== undefined &&
-      explicitStructural(parent) &&
-      !ROOT_ROLES.has(parent.vom.role?.toLowerCase() ?? "");
-    for (const childId of domChildren.get(parentId) ?? []) {
-      if (inside.has(parentId) || parentIsBoundary) inside.add(childId);
-      queue.push(childId);
-    }
-  }
-  return inside;
-}
-
-function reliableGroupCandidates(
-  graph: ResolvedSemanticGraph,
-  nodes: ResolvedSemanticNode[],
-  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
-  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
-  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
-): Set<SemanticNodeId> {
-  const insideExplicitStructure = explicitDomAncestors(graph, nodes, domChildren);
-  const remainingChildren = new Map(
-    nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]),
-  );
-  const summaries = new Map<SemanticNodeId, { blocked: boolean; interactions: number }>();
-  const queue = nodes
-    .filter((node) => (remainingChildren.get(node.id) ?? 0) === 0)
-    .map((node) => node.id);
-  for (let index = 0; index < queue.length; index += 1) {
-    const nodeId = queue[index];
-    const node = graph.nodes.get(nodeId);
-    const output = recovered.get(nodeId);
-    if (!node || !output) continue;
-    const role = output.role?.toLowerCase() ?? "";
-    const excluded = decisions.get(nodeId)?.kind === "excluded";
-    const blocked = excluded || explicitStructural(node) || CONTENT_BOUNDARY_ROLES.has(role);
-    const summary = excluded
-      ? { blocked: true, interactions: 0 }
-      : isVomReferenceNode(output)
-        ? { blocked: false, interactions: 1 }
-        : blocked
-          ? { blocked: true, interactions: 0 }
-          : (domChildren.get(nodeId) ?? []).reduce(
-              (combined, childId) => {
-                const child = summaries.get(childId);
-                return {
-                  blocked: combined.blocked || !child || child.blocked,
-                  interactions: Math.min(2, combined.interactions + (child?.interactions ?? 0)),
-                };
-              },
-              { blocked: false, interactions: 0 },
-            );
-    summaries.set(nodeId, summary);
-    const parentId = node.domParentId;
-    if (!parentId) continue;
-    const remaining = (remainingChildren.get(parentId) ?? 1) - 1;
-    remainingChildren.set(parentId, remaining);
-    if (remaining === 0) queue.push(parentId);
-  }
-
-  const candidates = new Set<SemanticNodeId>();
-  for (const node of nodes) {
-    const output = recovered.get(node.id) as VomNode;
-    const role = output.role?.toLowerCase() ?? "";
-    if (
-      !node.dom ||
-      node.dom.tag.toLowerCase() !== "div" ||
-      !TRANSPARENT_ROLES.has(role) ||
-      insideExplicitStructure.has(node.id) ||
-      decisions.get(node.id)?.kind === "excluded" ||
-      node.dom.attrs.hidden !== undefined ||
-      (node.dom.attrs["aria-hidden"] ?? "").toLowerCase() === "true" ||
-      node.dom.attrs.inert !== undefined
-    ) {
-      continue;
-    }
-
-    const branches = (domChildren.get(node.id) ?? []).map((id) => summaries.get(id));
-    const blocked = branches.some((summary) => !summary || summary.blocked);
-    const contributingBranches = branches.filter(
-      (summary) => (summary?.interactions ?? 0) > 0,
-    ).length;
-    const interactions = branches.reduce(
-      (count, summary) => Math.min(2, count + (summary?.interactions ?? 0)),
-      0,
-    );
-    if (!blocked && contributingBranches >= 2 && interactions >= 2) {
-      candidates.add(node.id);
-    }
-  }
-  return candidates;
-}
-
-function leafCandidates(
-  nodes: ResolvedSemanticNode[],
-  candidates: ReadonlySet<SemanticNodeId>,
-  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
-): Set<SemanticNodeId> {
-  const parentById = new Map(
-    nodes.flatMap((node) => (node.domParentId ? ([[node.id, node.domParentId]] as const) : [])),
-  );
-  const childCount = new Map(nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]));
-  const containsCandidate = new Set<SemanticNodeId>();
-  const queue = nodes.filter((node) => (childCount.get(node.id) ?? 0) === 0).map((node) => node.id);
-  const selected = new Set<SemanticNodeId>();
-  for (let index = 0; index < queue.length; index += 1) {
-    const nodeId = queue[index];
-    if (candidates.has(nodeId) && !containsCandidate.has(nodeId)) selected.add(nodeId);
-    const parentId = parentById.get(nodeId);
-    if (!parentId) continue;
-    if (candidates.has(nodeId) || containsCandidate.has(nodeId)) containsCandidate.add(parentId);
-    const remaining = (childCount.get(parentId) ?? 1) - 1;
-    childCount.set(parentId, remaining);
-    if (remaining === 0) queue.push(parentId);
-  }
-  return selected;
-}
-
-function nearestKept(
-  graph: ResolvedSemanticGraph,
-  startId: SemanticNodeId | undefined,
-  relation: "axParentId" | "domParentId",
-  kept: ReadonlySet<SemanticNodeId>,
-  memo: Map<SemanticNodeId, SemanticNodeId | undefined>,
-): SemanticNodeId | undefined {
-  let currentId = startId;
-  const path: SemanticNodeId[] = [];
-  const seen = new Set<SemanticNodeId>();
-  let result: SemanticNodeId | undefined;
-  while (currentId && !seen.has(currentId)) {
-    if (kept.has(currentId)) {
-      result = currentId;
-      break;
-    }
-    if (memo.has(currentId)) {
-      result = memo.get(currentId);
-      break;
-    }
-    seen.add(currentId);
-    path.push(currentId);
-    currentId = graph.nodes.get(currentId)?.[relation];
-  }
-  for (const id of path) memo.set(id, result);
-  return result;
-}
-
-function finalParentId(
-  graph: ResolvedSemanticGraph,
-  node: ResolvedSemanticNode,
-  kept: ReadonlySet<SemanticNodeId>,
-  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
-  axParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
-  domParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
-): SemanticNodeId | undefined {
-  const axParent = nearestKept(graph, node.axParentId, "axParentId", kept, axParentMemo);
-  const domParent = nearestKept(graph, node.domParentId, "domParentId", kept, domParentMemo);
-  const axNode = axParent ? graph.nodes.get(axParent) : undefined;
-  const domNode = domParent ? graph.nodes.get(domParent) : undefined;
-  const axIsRoot = ROOT_ROLES.has(axNode?.vom.role?.toLowerCase() ?? "");
-  const axIsExplicit = axNode ? explicitStructural(axNode) && !axIsRoot : false;
-  const domIsStructural =
-    domNode !== undefined &&
-    (explicitStructural(domNode) || decisions.get(domNode.id)?.kind === "inferred-group");
-  if (axIsExplicit) return axParent;
-  if (domIsStructural) return domParent;
-  if (axParent && !axIsRoot) return axParent;
-  if (domParent) return domParent;
-  if (axParent) return axParent;
-  if (node.frameId === graph.rootFrameId) return undefined;
-  return graph.frames.get(node.frameId)?.ownerNodeId;
-}
-
-function recoveredVom(node: VomNode, inferredGroup: boolean): ResolvedSemanticNode["vom"] {
-  const {
-    id: _id,
-    parentId: _parentId,
-    backendNodeId: _backendNodeId,
-    frameId: _frameId,
-    contextScopeId: _contextScopeId,
-    referenceable: _referenceable,
-    ...vom
-  } = node;
-  if (!inferredGroup) return vom;
-  const { name: _name, text: _text, nearbyText: _nearbyText, ...groupVom } = vom;
-  return { ...groupVom, role: "group" };
-}
-
-export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
-  const nodes = orderedNodes(graph);
-  const recovered = recoveredNodes(graph, nodes);
-  const redundant = redundantSourceNodes(graph, nodes, recovered);
-  const frameOwnerIds = new Set(
-    [...graph.frames.values()].flatMap((frame) => frame.ownerNodeId ?? []),
-  );
-  const decisions = new Map<SemanticNodeId, StructureDecision>();
-  for (const node of nodes) {
-    decisions.set(
-      node.id,
-      baseDecision(graph, node, recovered.get(node.id) as VomNode, frameOwnerIds, redundant),
-    );
-  }
-
-  const domChildren = buildChildren(nodes, "domParentId");
-  const candidates = reliableGroupCandidates(graph, nodes, recovered, decisions, domChildren);
-  for (const nodeId of leafCandidates(nodes, candidates, domChildren)) {
-    decisions.set(nodeId, {
-      kind: "inferred-group",
-      reason: "independent-interaction-branches",
-    });
-  }
-
-  const kept = new Set(
-    nodes
-      .filter((node) => {
-        const kind = decisions.get(node.id)?.kind;
-        return kind === "keep" || kind === "inferred-group";
-      })
-      .map((node) => node.id),
-  );
-  const axParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
-  const domParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
-  const structuredNodes = new Map<SemanticNodeId, StructuredSemanticNode>();
-  for (const node of nodes) {
-    const structure = decisions.get(node.id) as StructureDecision;
-    const inferredGroup = structure.kind === "inferred-group";
-    structuredNodes.set(node.id, {
-      ...node,
-      vom: recoveredVom(recovered.get(node.id) as VomNode, inferredGroup),
-      structure,
-      ...(kept.has(node.id)
-        ? {
-            semanticParentId: finalParentId(
-              graph,
-              node,
-              kept,
-              decisions,
-              axParentMemo,
-              domParentMemo,
-            ),
-          }
-        : {}),
-    });
-  }
-  return { ...graph, nodes: structuredNodes };
-}

apps/extension/src/tools/vom/semantic-graph/types.ts

@@ -1,88 +0,0 @@
-import type { Viewport, VomNode } from "@browser-skill/vom";
-import type { CdpTarget } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "../capture";
-
-export interface SemanticAxNode {
-  nodeId: string;
-  frameId?: string;
-  parentId?: string;
-  backendDOMNodeId?: number;
-  ignored?: boolean;
-  role?: { type: string; value?: string };
-  name?: { type: string; value?: string };
-  description?: { value?: string };
-  value?: { value?: string | number | boolean };
-  properties?: Array<{ name?: string; value?: { value?: string | number | boolean } }>;
-  childIds?: string[];
-}
-
-export type SemanticNodeId = string;
-
-export interface SemanticFrame {
-  frameId: string;
-  parentFrameId?: string;
-  ownerBackendNodeId?: number;
-  ownerNodeId?: SemanticNodeId;
-  contextScopeId: string;
-  target: CdpTarget;
-  url?: string;
-  order: number;
-}
-
-export interface SemanticGraphNode {
-  id: SemanticNodeId;
-  frameId: string;
-  backendNodeId?: number;
-  axNodeId?: string;
-  ax?: SemanticAxNode;
-  dom?: CapturedNode;
-  axParentId?: SemanticNodeId;
-  domParentId?: SemanticNodeId;
-  sourceOrder: number;
-  excluded: boolean;
-}
-
-export interface SemanticGraph {
-  viewport: Viewport;
-  rootFrameId: string;
-  frames: Map<string, SemanticFrame>;
-  nodes: Map<SemanticNodeId, SemanticGraphNode>;
-  nodeIdsByFrame: Map<string, SemanticNodeId[]>;
-  nodeByFrameBackend: Map<string, SemanticNodeId>;
-}
-
-export interface ResolvedSemanticNode extends SemanticGraphNode {
-  vom: Omit<VomNode, "id" | "parentId" | "backendNodeId" | "frameId" | "contextScopeId">;
-  referenceable: boolean;
-  roleSource: "ax" | "ax-ignored" | "dom-explicit" | "dom-native" | "none";
-}
-
-export interface ResolvedSemanticGraph extends Omit<SemanticGraph, "nodes"> {
-  nodes: Map<SemanticNodeId, ResolvedSemanticNode>;
-}
-
-export type StructureDecision =
-  | { kind: "keep"; reason: "semantic" | "frame-owner" }
-  | { kind: "inferred-group"; reason: "independent-interaction-branches" }
-  | { kind: "transparent"; reason: "wrapper" | "child-document-root" | "ax-ignored" }
-  | {
-      kind: "excluded";
-      reason: "excluded" | "redundant-source" | "non-rendered-dom-fallback";
-    };
-
-export interface StructuredSemanticNode extends ResolvedSemanticNode {
-  structure: StructureDecision;
-  semanticParentId?: SemanticNodeId;
-}
-
-export interface StructuredSemanticGraph extends Omit<ResolvedSemanticGraph, "nodes"> {
-  nodes: Map<SemanticNodeId, StructuredSemanticNode>;
-}
-
-export function frameBackendKey(frameId: string, backendNodeId: number): string {
-  return `${frameId}\u0000${backendNodeId}`;
-}
-
-export function frameAxKey(frameId: string, axNodeId: string): string {
-  return `${frameId}\u0000${axNodeId}`;
-}

apps/extension/src/transport/types.ts

@@ -33,10 +33,22 @@ export type RpcErrorReason =
   | "restricted_tab_url"
   | "borrow_conflict"
   | "screenshot_capture_failed"
+  | "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;
 }
 
@@ -500,6 +512,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/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

@@ -206,6 +206,29 @@ Both capture from the moment the tab is attached and read a bounded per-tab buff
 | `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 |

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

@@ -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>,

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,6 +41,7 @@ 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;
@@ -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;
 
@@ -177,6 +182,12 @@ pub enum Command {
     /// 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/render_error.rs

@@ -49,6 +49,12 @@ pub mod reason {
     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 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";
 }
@@ -197,6 +203,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(
@@ -280,6 +300,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,
     }
 }
@@ -419,6 +469,38 @@ mod tests {
         assert_eq!(info.exit_code, 3);
     }
 
+    #[test]
+    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,
+            "the upload trigger did not activate a file input"
+        );
+        assert!(info.hint.unwrap().contains("exact original local path"));
+
+        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]
     fn ref_not_found_overrides_not_found_copy() {
         let data = serde_json::json!({ "reason": reason::REF_NOT_FOUND });

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
@@ -246,6 +256,8 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
                 | Method::ToolFill
                 | Method::ToolPress
                 | Method::ToolSelect
+                | Method::ToolUpload
+                | Method::ToolDownload
                 | Method::ToolEvaluate
                 | Method::ToolWaitForNavigation
                 | Method::ToolRequestHelp
@@ -324,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),
     };
@@ -338,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,
     }
 }
 
@@ -533,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
@@ -798,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(),
@@ -897,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);
@@ -1329,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

@@ -97,6 +97,8 @@ fn dispatch(cli: Cli, format: Format) -> Result<(), CliError> {
         Command::Fill(args) => cli::interaction::dispatch_fill(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

@@ -213,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-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_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

@@ -85,6 +85,10 @@ fn main() {
     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

@@ -78,6 +78,10 @@ pub enum Method {
     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")]
@@ -105,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,6 +171,8 @@ impl Method {
             | Method::ToolFill
             | 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.
@@ -194,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,
         }
     }

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/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::*;

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/src/archive-cleanup.ts

@@ -1,108 +0,0 @@
-/**
- * Archive-triggered bsk session cleanup. DSH conversation archival writes
- * the workspace registry's durable global state, which the storage domain
- * broadcasts as `domain/changed` ({domain: 'workspace', table: ''}) with
- * the new `archivedSessionIds`. The watcher diffs that set and stops every
- * bsk session owned by a freshly archived conversation — archived sessions
- * are hidden from every surface, so their Agent Windows would otherwise
- * linger with no way back to them.
- *
- * Ownership lineage: browser_session_start records the calling agent's
- * session id PLUS every ancestor along `header.parentSession` (a subagent's
- * browsers are reaped when any ancestor is archived, the root conversation
- * included). Lineage is resolved through the host session store; an
- * unloaded ancestor simply ends the walk.
- */
-
-import type { Context } from "@deepseek-ai/cordis";
-import type { ObservationService } from "./observation";
-import type { SessionRegistry } from "./sessions";
-
-/** The wire shape of a `domain/changed` frame (see dsh-storage-domain). */
-interface DomainChange {
-  domain?: string;
-  table?: string;
-  value?: unknown;
-}
-
-/** The workspace registry's durable global singleton slice we read. */
-interface WorkspaceGlobal {
-  archivedSessionIds?: unknown;
-}
-
-/** Structural host session store face: only the lineage read is needed. */
-interface SessionStoreLike {
-  get(id: string): { header: { parentSession?: string } } | undefined;
-}
-
-/** Cap on lineage walks — defensive against a malformed parent chain. */
-const MAX_LINEAGE_DEPTH = 16;
-
-/**
- * The DSH session ids that own a tool call's browser sessions: the calling
- * agent's own session plus every ancestor along the seed lineage. Empty
- * when the call carried no agent identity (those sessions outlive any
- * archive cleanup by design — nothing can name their owner).
- */
-export function ownerSessionIds(ctx: Context, agentId: string | undefined): string[] {
-  if (agentId === undefined) return [];
-  const store = ctx.get("sessions") as SessionStoreLike | undefined;
-  const ids: string[] = [];
-  let current: string | undefined = agentId;
-  for (let depth = 0; current !== undefined && depth < MAX_LINEAGE_DEPTH; depth += 1) {
-    if (ids.includes(current)) break; // a cycle in stored headers must not loop
-    ids.push(current);
-    current = store?.get(current)?.header.parentSession;
-  }
-  return ids;
-}
-
-/**
- * Watch conversation archival and stop the bsk sessions it opened. Returns
- * the disposer (plugin unload). In compositions without the workspace
- * domain (headless), the event simply never fires — and a context without
- * the events mixin degrades to a no-op like the other optional seams.
- */
-export function armArchiveCleanup(
-  ctx: Context,
-  registry: SessionRegistry,
-  observation: ObservationService,
-): () => void {
-  // 'domain/changed' lives outside the vendored Events type map, so the
-  // listener goes through a structural view of the events mixin.
-  const on = (
-    ctx as { on?: (event: string, listener: (change: DomainChange) => void) => () => void }
-  ).on;
-  if (typeof on !== "function") return () => {};
-
-  /** Archived ids already accounted for; lazily seeded from the registry. */
-  let seen: Set<string> | undefined;
-  const initialize = (): Set<string> => {
-    if (seen === undefined) {
-      const registryService = ctx.get("workspaceRegistry") as
-        | { archivedSessionIds?: readonly string[] }
-        | undefined;
-      seen = new Set(registryService?.archivedSessionIds ?? []);
-    }
-    return seen;
-  };
-
-  return on.call(ctx, "domain/changed", (change: DomainChange) => {
-    if (change?.domain !== "workspace" || change?.table !== "") return;
-    const archived = (change.value as WorkspaceGlobal | undefined)?.archivedSessionIds;
-    if (!Array.isArray(archived)) return;
-    const previous = initialize();
-    const fresh = archived.filter(
-      (id): id is string => typeof id === "string" && !previous.has(id),
-    );
-    seen = new Set(archived.filter((id): id is string => typeof id === "string"));
-    for (const dshSessionId of fresh) {
-      for (const sessionId of registry.ownedByDsh(dshSessionId)) {
-        // stopSession owns the full teardown (kill in-flight tools, queue
-        // the daemon stop, drop registry + observation entries); a failure
-        // just leaves the session for idle timeout or unload cleanup.
-        void observation.stopSession(sessionId).catch(() => {});
-      }
-    }
-  });
-}

packages/dsh-plugin-browserskill/src/client/ObservationOverlay.module.css

@@ -30,51 +30,17 @@
   color: var(--card-foreground);
 }
 
-/* Sidebar carrier: fill the better-sidebar tab area and let the body flex
-   (the tab content container owns the outer sizing). */
-.sidebar-tab {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  min-height: 0;
-}
-
-.sidebar-tab > * {
-  flex: 1;
-  min-height: 0;
-}
-
-/* The BSK product mark in the sidebar tab strip (the source artwork already
-   carries rounded corners — just soften the square to match). */
-.brand-icon {
-  display: block;
-  border-radius: 22%;
-}
-
 .header {
   display: flex;
   align-items: center;
   gap: 6px;
   padding: 6px 8px;
+  cursor: move;
   user-select: none;
   touch-action: none;
   border-bottom: 1px solid var(--border);
 }
 
-/* Only the floating card drags by its header — the sidebar tab does not. */
-.header[data-draggable] {
-  cursor: move;
-}
-
-/* In the sidebar the status row is chrome, not a card edge: drop its bottom
-   border. A fixed-height bordered row can never track the shell header's
-   hairline across the panel boundary (its height varies per window), and
-   the BSK warm border tint clashes with the sidebar's neutral hairlines —
-   borderless, the stage's own background provides the separation. */
-.sidebar-tab .header {
-  border-bottom: none;
-}
-
 .status-text {
   flex: 1;
   min-width: 0;
@@ -165,12 +131,6 @@
   border-top: 1px solid var(--border);
 }
 
-.actions-group {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-}
-
 .tool-wrap {
   position: relative;
   display: inline-flex;
@@ -205,14 +165,8 @@
   color: var(--destructive);
 }
 
-/* Stop session: danger-tinted like interrupt. */
-.tool-stop {
-  color: var(--destructive);
-}
-
-/* Hover the wrap (not just :hover on the button) so the tooltip target
-   lights the icon up too. The corner resize handles sit above this bar, so
-   the outer sliver of the corner-most buttons starts a resize instead. */
+/* Hover the wrap (not just :hover on the button) so the tooltip target and
+   the left-corner resize overlay still light the icon up. */
 .tool-wrap:hover .tool-button:not(:disabled) {
   color: var(--foreground);
   background: var(--accent);
@@ -227,15 +181,6 @@
   background: var(--accent);
 }
 
-/* The armed (confirm) state of the stop button: solid destructive fill so
-   the second click reads as final. Written at the wrap-hover specificity so
-   the hover rules above never wash it out. */
-.tool-button.tool-stop-armed,
-.tool-wrap:hover .tool-button.tool-stop-armed {
-  color: var(--destructive-foreground);
-  background: var(--destructive);
-}
-
 .hint {
   position: absolute;
   bottom: calc(100% + 4px);
@@ -258,16 +203,13 @@
   right: 0;
 }
 
-/* Invisible hit targets — no grip glyph; all four corners resize. Must sit
-   above the bottom .actions bar (z-index 3): it spans the full card width
-   and would otherwise swallow every pointer event aimed at the sw/se
-   corners. The top corners already win because .header is not positioned. */
+/* Invisible hit targets — no grip glyph; all four corners resize. */
 .resize-handle {
   position: absolute;
   width: 16px;
   height: 16px;
   touch-action: none;
-  z-index: 4;
+  z-index: 2;
 }
 
 .resize-handle[data-corner="nw"] {

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

@@ -3,18 +3,13 @@
 // composer's way); collapsed = a status capsule; "pop out" upgrades the same
 // content to a native Document PiP window (user gesture required by the
 // browser). Multi-session renders a meeting-style strip under the focus view.
-// When the dsh-better-sidebar plugin is installed the tracking view moves
-// into a sidebar tab instead (see observation-sidebar.tsx) and this floating
-// card hides itself via the sidebar-mode flag. Visuals follow the
-// BrowserSkill product family: @browser-skill/ui components and oklch tokens
-// on a .bsk-obs scope root, so the card reads as BSK's own surface without
-// leaking styles into (or inheriting themes from) the shell.
+// Visuals follow the BrowserSkill product family: @browser-skill/ui components
+// and oklch tokens on a .bsk-obs scope root, so the card reads as BSK's own
+// surface without leaking styles into (or inheriting themes from) the shell.
 
 import { cn } from "@browser-skill/ui";
 import {
   RiArrowDownSLine,
-  RiCheckLine,
-  RiCloseCircleLine,
   RiErrorWarningLine,
   RiPictureInPicture2Line,
   RiPushpinFill,
@@ -30,8 +25,6 @@ const IconPip = asIcon(RiPictureInPicture2Line);
 const IconDown = asIcon(RiArrowDownSLine);
 const IconWarn = asIcon(RiErrorWarningLine);
 const IconPin = asIcon(RiPushpinFill);
-const IconCloseSession = asIcon(RiCloseCircleLine);
-const IconCheck = asIcon(RiCheckLine);
 
 import {
   type ReactNode,
@@ -46,12 +39,11 @@ import { createPortal } from "react-dom";
 import type { SessionObservation } from "../observation";
 import css from "./ObservationOverlay.module.css";
 import type { ObservationClientStore } from "./observation-store";
-import { focusOf, statusOf, useObservationView, usePip } from "./observation-view";
-import { getSidebarMode, subscribeSidebarMode } from "./sidebar-mode";
 
-// The pure view helpers live in observation-view (shared with the sidebar
-// tab); re-export so existing imports of this module keep working.
-export { focusOf, statusOf };
+/** Minimal Document PiP surface (TS lib.dom lacks it). */
+interface DocumentPip {
+  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
+}
 
 interface Point {
   x: number;
@@ -69,6 +61,11 @@ const EDGE_MARGIN = 16;
 /** Default dock: top-right, just under the shell's top bar (no spacing tokens exist in dsh 0.1). */
 const TOP_OFFSET = 64;
 
+function pipApi(): DocumentPip | undefined {
+  if (typeof window === "undefined") return undefined;
+  return (window as unknown as { documentPictureInPicture?: DocumentPip }).documentPictureInPicture;
+}
+
 function clampSize(size: Size, viewport: Size): Size {
   const maxW = viewport.w * 0.8;
   const maxH = viewport.h * 0.8;
@@ -117,6 +114,23 @@ function formatElapsed(sinceMs: number, nowMs: number): string {
   return `${mm}:${ss}`;
 }
 
+/**
+ * Auto-follow focus: the most recently touched session, but never yank focus
+ * to a session whose latest action failed (errors flag the strip item, they
+ * do not steal the stage) or one already reported dead.
+ */
+export function focusOf(sessions: readonly SessionObservation[]): SessionObservation | undefined {
+  if (sessions.length === 0) return undefined;
+  const byRecency = [...sessions].sort((a, b) => b.since - a.since);
+  const healthy = byRecency.find((s) => s.lastError === undefined && s.dead !== true);
+  return healthy ?? byRecency[0];
+}
+
+export function statusOf(obs: SessionObservation): "active" | "idle" | "error" {
+  if (obs.lastError !== undefined && obs.action === "idle") return "error";
+  return obs.action === "idle" ? "idle" : "active";
+}
+
 /** Compact toolbar icon: no label, hover bubble for the name / semantics. */
 function IconAction(props: {
   label: string;
@@ -152,83 +166,6 @@ function IconAction(props: {
   );
 }
 
-/** How long the stop button stays armed before the confirm click expires. */
-const STOP_ARM_MS = 3000;
-
-/**
- * Stop-session button with a lightweight two-click confirm: the first click
- * arms the button (solid red, check icon, short expiry), the second executes
- * the stop. No dialog, no layout shift — and a stray single click can never
- * close an Agent Window.
- */
-function StopSessionAction(props: {
-  sessionId: string | undefined;
-  onStop: (sessionId: string) => Promise<boolean>;
-}) {
-  const { sessionId, onStop } = props;
-  const [hover, setHover] = useState(false);
-  const [armed, setArmed] = useState(false);
-  const [stopping, setStopping] = useState(false);
-
-  useEffect(() => {
-    if (!armed) return;
-    const timer = setTimeout(() => setArmed(false), STOP_ARM_MS);
-    return () => clearTimeout(timer);
-  }, [armed]);
-
-  // The focused session can vanish mid-arm (stopped elsewhere): disarm.
-  useEffect(() => {
-    if (sessionId === undefined) setArmed(false);
-  }, [sessionId]);
-
-  const disabled = sessionId === undefined || stopping;
-  const label = stopping
-    ? "Stopping session…"
-    : armed
-      ? `Confirm stop session ${sessionId ?? ""}`
-      : `Stop session ${sessionId ?? ""}`;
-  const hint = stopping
-    ? "Closing the Agent Window…"
-    : armed
-      ? `Click again to stop session ${sessionId ?? ""} and close its Agent Window.`
-      : `Stop session ${sessionId ?? ""} and close its Agent Window.`;
-
-  return (
-    <span
-      className={css["tool-wrap"]}
-      onPointerEnter={() => setHover(true)}
-      onPointerLeave={() => setHover(false)}
-    >
-      <button
-        type="button"
-        className={cn(css["tool-button"], css["tool-stop"], armed && css["tool-stop-armed"])}
-        disabled={disabled}
-        aria-label={label}
-        aria-pressed={armed}
-        data-armed={armed || undefined}
-        onClick={() => {
-          if (sessionId === undefined || stopping) return;
-          if (!armed) {
-            setArmed(true);
-            return;
-          }
-          setArmed(false);
-          setStopping(true);
-          const target = sessionId;
-          void onStop(target).finally(() => setStopping(false));
-        }}
-      >
-        {armed ? <IconCheck size={16} /> : <IconCloseSession size={16} />}
-      </button>
-      {hover ? (
-        <span className={css.hint} role="tooltip">
-          {hint}
-        </span>
-      ) : null}
-    </span>
-  );
-}
-
 /** Flat status dot, specced after the BSK popup's ConnectionStatusIndicator. */
 function StatusDot({ state }: { state: "active" | "idle" | "error" | "dead" }) {
   const color =
@@ -309,8 +246,8 @@ function StripItem(props: {
   );
 }
 
-/** The floating card / PiP / sidebar-tab shared content. */
-export function OverlayBody(props: {
+/** The floating card / PiP shared content. */
+function OverlayBody(props: {
   store: ObservationClientStore;
   focus: SessionObservation | undefined;
   sessions: readonly SessionObservation[];
@@ -373,7 +310,6 @@ export function OverlayBody(props: {
       <div
         className={css.header}
         data-testid="obs-header"
-        data-draggable={onHeaderPointerDown !== undefined || undefined}
         onPointerDown={onHeaderPointerDown}
         role="presentation"
       >
@@ -427,21 +363,15 @@ export function OverlayBody(props: {
         </div>
       ) : null}
       <div className={css.actions}>
-        <div className={css["actions-group"]}>
-          <IconAction
-            label={interrupting ? "Interrupting…" : "Interrupt the current browser action"}
-            hint="Stop the current browser action."
-            disabled={!canInterrupt}
-            danger
-            onClick={onInterrupt}
-          >
-            <IconStop size={16} />
-          </IconAction>
-          <StopSessionAction
-            sessionId={focus?.sessionId}
-            onStop={(sessionId) => store.stopSession(sessionId)}
-          />
-        </div>
+        <IconAction
+          label={interrupting ? "Interrupting…" : "Interrupt the current browser action"}
+          hint="Stop the current browser action."
+          disabled={!canInterrupt}
+          danger
+          onClick={onInterrupt}
+        >
+          <IconStop size={16} />
+        </IconAction>
         {onPopOut !== undefined ? (
           <IconAction
             label="Pop out into a mini window"
@@ -457,17 +387,25 @@ export function OverlayBody(props: {
   );
 }
 
+/** Clone the host document's style/link nodes into a PiP window. */
+function cloneStylesInto(pipWindow: Window): void {
+  for (const node of document.querySelectorAll('link[rel="stylesheet"], style')) {
+    pipWindow.document.head.appendChild(node.cloneNode(true));
+  }
+}
+
 export function ObservationOverlay({ store }: { store: ObservationClientStore }) {
-  const { snapshot, focus, pinnedId, onTogglePin, now } = useObservationView(store);
-  // While the better-sidebar plugin carries the tracking view, this floating
-  // card (and its capsule) stays out of the way; an already-open PiP window
-  // keeps its portal until the user closes it.
-  const sidebarMode = useSyncExternalStore(subscribeSidebarMode, getSidebarMode);
+  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot);
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
 
   const [collapsed, setCollapsed] = useState(false);
   const [pos, setPos] = useState<Point | null>(null);
   const [size, setSize] = useState<Size>(DEFAULT_SIZE);
-  const { pipWindow, pipSupported, popOut } = usePip();
+  const [pipWindow, setPipWindow] = useState<Window | null>(null);
+  const [pinnedId, setPinnedId] = useState<string | null>(null);
   const dragRef = useRef<{
     kind: "move" | "resize";
     corner?: ResizeCorner;
@@ -476,6 +414,23 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     base: Point & Size;
   } | null>(null);
 
+  // Elapsed-time ticker: 1s while anything is active.
+  const anyActive = snapshot.sessions.some((s) => s.action !== "idle");
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!anyActive) return;
+    const timer = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(timer);
+  }, [anyActive]);
+
+  // Focus: the pinned session wins while it still exists; otherwise auto-follow.
+  const pinned =
+    pinnedId !== null ? snapshot.sessions.find((s) => s.sessionId === pinnedId) : undefined;
+  const focus = pinned ?? focusOf(snapshot.sessions);
+  const onTogglePin = useCallback((sessionId: string) => {
+    setPinnedId((current) => (current === sessionId ? null : sessionId));
+  }, []);
+
   const viewport = (): Size => ({ w: window.innerWidth, h: window.innerHeight });
 
   const onPointerMove = useCallback((event: PointerEvent) => {
@@ -556,21 +511,34 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     document.addEventListener("pointerup", onPointerUp);
   };
 
+  const popOut = async (): Promise<void> => {
+    const pip = pipApi();
+    if (pip === undefined) return;
+    try {
+      const win = await pip.requestWindow({ width: size.w, height: size.h });
+      cloneStylesInto(win);
+      win.addEventListener("pagehide", () => setPipWindow(null));
+      setPipWindow(win);
+    } catch {
+      // requestWindow rejects without a user gesture (or when the window was
+      // closed mid-request): stay on the in-page card, no state change.
+    }
+  };
+
+  // Hidden while no owned session exists (and no PiP is up).
+  if (snapshot.sessions.length === 0 && pipWindow === null) return null;
+
   const body = (
     <OverlayBody
       store={store}
       focus={focus}
       sessions={snapshot.sessions}
       available={snapshot.available}
-      pinnedId={pinnedId}
+      pinnedId={pinned !== undefined ? pinnedId : null}
       onTogglePin={onTogglePin}
       now={now}
       inPip={pipWindow !== null}
-      onPopOut={
-        pipWindow === null && pipSupported
-          ? () => popOut({ width: size.w, height: size.h })
-          : undefined
-      }
+      onPopOut={pipWindow === null && pipApi() !== undefined ? () => void popOut() : undefined}
       onCollapse={pipWindow === null ? () => setCollapsed(true) : undefined}
       onHeaderPointerDown={pipWindow === null ? beginMove : undefined}
     />
@@ -580,12 +548,6 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     return createPortal(body, pipWindow.document.body);
   }
 
-  // The sidebar tab is the carrier now — no floating card, no capsule.
-  if (sidebarMode) return null;
-
-  // Hidden while no owned session exists (and no PiP is up).
-  if (snapshot.sessions.length === 0) return null;
-
   if (collapsed) {
     const state = focus !== undefined ? statusOf(focus) : "idle";
     return (

packages/dsh-plugin-browserskill/src/client/brand-icon.ts

@@ -1,8 +0,0 @@
-/**
- * The BrowserSkill product mark (apps/extension/assets/logo.png, downscaled
- * to 32px and inlined): the sidebar tab icon, so the tracking view reads as
- * BSK's own surface next to better-sidebar's built-in "browser" tab.
- * Regenerate with: resize the source to 32x32 PNG and replace the payload.
- */
-export const BSK_LOGO_URL =
-  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAJGklEQVR42m2X248c2V3HP79zTlV19/TcPOOZWY+vsdmQFdngTQJswgs3hQ15iCJslAey+8xDAIHgH+CBNxIpj0gkEXnAKyKQWITEJlKWXSssEMfJRmuMHa/W9njHMz3Tl+nprsv5/XiomlugpdN16lR1n9/1e75fAbAbeLlO3Pz2ly4vjO7+sRbF58oiP49FEREOPwaIYQjS3IvUy0fP66kAZoYJIM7SpPVY0uy14cyzXzn9u9+4c+MG/vp1otiNa16uvxr7X/+1L3bK3lcTyU9P80ilR/uKCGYHOxxd6s2kmdaGIVYb1qyY1e8HD63UUblstwirf9J95fW/sRvXvAD0v/6Z6/O68Xf5/pS8kigiTsTkuCfIwfzAxQN37chjaAyt594JIXE4gbKMhog6Nd/qthi7lVe6L3/nG7Jz4/fPJ9u3b4U4WSwiKog/EcsTLh+PSuO3GXYs/D44QnBgyniQs7OV0+8bOxPPM6c9l660VEyF0Nmrlp9/IYT+/S/PUJ4a5C46EW8HnjVhBKjXaHJfz9Xq95xzhMThHZR5xXBrwtPNnP6eRzvzhJWzrF1d5UI759//9iYra5lrt1ycDeXsaOf+n4Y4HX8+r9SciasLS/6P12LHoyF47wipYKpM9gqePpyyvVMxjBn+1DILH17l0rkZlhYcLetT3n/A5FGfTtvTCh4ibjpVI81/J0il62V1rNStLp6j4jowxwiJh2iMevtsbU3pjYQim6Nz9hJLH13i8mrGbJgSxjuUvQfEjT2GOw4Zddh0BakPtFPH/jRKqaCSrwetKi9mKIIYhyFuOg6TurCcF7ae5ty5t48/vcTiz3+Ei+szLC06WnGA7TykfNCnmObk5nAtj+53yDcTZteMwZOChbkMVa3/14DCJBBBFBxyopndUUBqwwxu/XjAJ778Bc4ul+R3fgyj9yg/GDMpFZxHgoe0hQ9QDRzFI48zqHzJeKhcvNKiLAyiQ1BwgsOcqNZ9Xo96rgaVgmqdiBACH740y/1/+j4b7w1x80tUkwLM4VptJAQMcN6o+p7iYQIqhBQmsUIrR7cd0NI12ODAwJnWTpvZoRGqdRrS1CECeR7Z2NzHRBjeecgbX/kut39UUlx5ATe3gFUlAM5Tb/4oHCJl0oadUcFsK8E5sFh7ZaqgEFBr3KyhxAySxDMplDv3BuztlmhhZC6QqONDrXkW28Kbf/1d7A9+i6vPr7N/e5vQDZQ7jvxxUqdPwFRwHaP3sGR1boZYGabWwHdd7MHMMBUMh5mRJp6tnZx33tllJbS53J1jZj6BKpKPpkhZ8e5mj3Nf/FV+8ZOnmNz6Pr6TUvUcxeOAc0cN6xwUoWIyUhZXMqqq6bKmrQ0hWBQzdXX+nGOwV3LnJ30+trjE8mxGUUVG/Qn7owkt7/hpb5fwmat84qXz5P95EwmOqh8oNkKTSkFqICTJYDgpCOppZYGyjIfgdoApQRScCtEgDZ5b93dxuWd3OuWD8T5pqbSLyEyWcHdrh+S3r/Kpz15i/z/eQhIh9hOKjQRTyBYgFhAndSpDW+gNC+ZbGR6jjM3BVsNsXQNqhqpiOPIicuXcLFvdKT7xtNXTG+X0Bopt9Wi9dJUXX7rI5O23kNQRB4F8I0CEzgr0/B7t2YB/2iJOQDrK8HHJ+dkZqqI+JfUAYRXMGc6pM1MBBa2Ubttz5ews51c6XFjr8OJHT5N0HPIbz/Ppz11h/+03IXVUg4T8ccAidFaNp7LHzdd2uXdvj866gQq5L8nHMD+TUJUG0aAyJBqidZQcUfFqeK2vlEo1rYh5iUXl6eMB5eoKv37tOUb/9q+4LBD7gXKj3ry7Ak/iHrdeH/ArC7P07ykPekMWzkFvkNMmkHkgagNoDciogYKzaGg0YgSNYLEJj0ndfiGj6o/Z3i5or5+j2BTKJwlawcwKbMQ9fvK9Ib+QtgitQMg8d384wVYLdocls1mCad1+Fg1TDgeV4UxFTB2ow44NjQ5rwcwZ+MjqmLe/dZOBLOHHCeUUZteED+Ie73xvyHNpmyx1TERozXieW1/mO/+yzWhTWVtsU5aCqKvRT4+GmRDEHGJ6yPPMBHNGeqbCdwqs02X9l14g/a8H3PzWm/zyp1ZZXgn8tDfgnbeGPN/qIEDSyhh7w2OcPZWRsESWCq3EoVFPksZDMuUIps7qLjDUQBxkZ0tcu8KSGdIXPo3OLbOSdfj4YMIPbg6ZXxux9wRmWimFKe0k0J7v8H5vQHchpSoiC536bKhKEDlCJzM7JLJqhqtxoEYoUcEFw/Yduh8Jl38OP7eAlBOm29ssziV87JlluqMOL15ZZWVlhu0yMrfYxQQmZUU3TbCmnog1mRE1xOp9xOoaEwVRI9QnUGOECLoPNlcRlucJ6xeIgx3K/3kX23pINWnRdnBxtYNWkbkkMJ5JSLKEwaSgRFlsJWh1mNBDfsEBzZGaYIiBIgRtImCmmArhlBFOR1Q9xZ3b6OOHWFnifEq1U/84TpXgHL4hUh7hv3t91pY6eCeUpTYs2o6RisYEO6B5hpoSRCWaanNAGP5UVZ+r+YB4dxcbZ4QVx/Q9wSYg/uDYNvKyoorwgyfbtDuBC6c65HmFa5Jsh56f3NgO4iGeYC68n8Ty2WkphAUVv2hoLuggoXgUcJkRh0rVF7wHi3Vw1YxuSMh1zMpcmw8tdynzCmmCL1JjzQG3lpNU37xAdNnjYC79xywUfzbJNboEX214iqeeuN/IrkKw6BAvNUiJ1a2K0HKOT144jQBFoTWRayrc9LhWa1TTUTNqJ038wCf/LO//xZfWWw9u/zCt8uWpSiTixZ3UeJzQPkerdkyq1RryZwVN87CJBALR0ExULMtG4/VnPy4AG3/4m19YGG/9fT7NmZpEhzg5lCNHOo//774u7UYp2WEt1XrSftYMTcF32ynbrfmXz3ztjW86u3bNn/nq69/eaZ/6PUlbm/PB+YSapUozMG2uB0M5fI7WSKoKasjBu6qHczEjwWQ2iJc03XmaLb5y5mtvfNOuNeLUruHlVeK7f/7yxbXBu39U5sXnq7I8L2pH6rwRgCZyUpeKnZSOB5K2EbT1l5hPk0c+zV7bXXzmry7/5T/cvXENf/1V4v8CSYIrURx3kHgAAAAASUVORK5CYII=";

packages/dsh-plugin-browserskill/src/client/index.ts

@@ -1,9 +1,7 @@
 /**
  * dsh-plugin-browserskill browser half: the `browser_screenshot` keyed
- * toolview plus the observation overlay (live thumbnails + interrupt). The
- * default carrier is a floating card on the `shell.overlay` seat; when the
- * dsh-better-sidebar plugin provides its `betterSidebar` service, the view
- * moves into a sidebar tab instead (see observation-sidebar.tsx).
+ * toolview plus the observation overlay (live thumbnails + interrupt) floating
+ * over the shell via the `shell.overlay` seat.
  */
 
 import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
@@ -17,7 +15,6 @@ import { createElement } from "react";
 import "./bsk-tokens.nomodule.css";
 import "./bsk-ui.nomodule.css";
 import { ObservationOverlay } from "./ObservationOverlay";
-import { type BetterSidebarLike, registerObservationSidebar } from "./observation-sidebar";
 import { type EventSourceLike, ObservationClientStore } from "./observation-store";
 import { ScreenshotToolView } from "./ScreenshotToolView";
 
@@ -84,14 +81,4 @@ export function apply(ctx: ClientContext): void {
       createElement(ObservationOverlay, { store }),
     ),
   );
-  // Optional carrier upgrade: when the dsh-better-sidebar plugin is installed,
-  // its service moves the tracking view into a sidebar tab (the floating
-  // overlay hides itself through the sidebar-mode flag). In profiles without
-  // the sidebar plugin this fiber never runs and nothing changes.
-  ctx.inject(["betterSidebar"], (injected) =>
-    registerObservationSidebar(
-      (injected as unknown as { betterSidebar: BetterSidebarLike }).betterSidebar,
-      store,
-    ),
-  );
 }

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

@@ -1,256 +0,0 @@
-// better-sidebar carrier for the observation view. When the
-// dsh-better-sidebar plugin is installed its client publishes a
-// `betterSidebar` cordis service; the client entry then runs the
-// registration below and the tracking view moves from the floating card
-// into a single-instance sidebar tab (Document PiP pop-out stays available
-// from inside the tab). Detection is purely service-based — profiles
-// without the sidebar plugin never start this fiber and keep the floating
-// overlay.
-
-import { createElement, type ReactNode } from "react";
-import { createPortal } from "react-dom";
-import { BSK_LOGO_URL } from "./brand-icon";
-import { OverlayBody } from "./ObservationOverlay";
-import css from "./ObservationOverlay.module.css";
-import type { ObservationClientStore } from "./observation-store";
-import { useObservationView, usePip, visibleToScope } from "./observation-view";
-import { setSidebarMode } from "./sidebar-mode";
-
-/** The tab title — "Browser Skill", distinct from the sidebar's built-in "browser" tab. */
-const TAB_TITLE = "Browser Skill";
-
-/** Tab strip icon: the BrowserSkill product mark at the requested size. */
-function TabIcon({ size }: { size: number }) {
-  return (
-    <img
-      src={BSK_LOGO_URL}
-      width={size}
-      height={size}
-      alt=""
-      aria-hidden
-      className={css["brand-icon"]}
-    />
-  );
-}
-
-/**
- * Structural mirrors of dsh-better-sidebar's client service surface (only
- * the slices this integration touches — see the upstream
- * lib/types/client/service.d.ts). Declared locally so the plugin carries no
- * dependency on the sidebar package; the service contract has been stable
- * since v0.4.0 and newer capabilities arrive behind its `features` list.
- */
-export interface SidebarTabLike {
-  id: string;
-  type: string;
-  title: string;
-}
-
-export interface SidebarLeafLike {
-  kind: "leaf";
-  id: string;
-  tabs: SidebarTabLike[];
-  active: string | null;
-}
-
-export interface SidebarSplitLike {
-  kind: "split";
-  id: string;
-  dir: "row" | "col";
-  sizes: number[];
-  children: SidebarNodeLike[];
-}
-
-export type SidebarNodeLike = SidebarLeafLike | SidebarSplitLike;
-
-export interface SidebarStateLike {
-  splits: SidebarNodeLike;
-  bottomSplits: SidebarNodeLike;
-  /** Whether the right panel is expanded (the merged drawer on narrow screens). */
-  panelOpen?: boolean;
-}
-
-export interface SidebarSnapshotLike {
-  sessionId?: string;
-  state?: SidebarStateLike;
-}
-
-/** Props every tab component receives (the slices we read). */
-export interface TabComponentPropsLike {
-  /** The conversation this sidebar instance belongs to. */
-  scope: { sessionId: string };
-}
-
-export interface TabDescriptorLike {
-  id: string;
-  title: string | (() => string);
-  icon?: ReactNode | ((size: number) => ReactNode);
-  order?: number;
-  /** Single-instance: opening focuses the existing tab instead of duplicating. */
-  single?: boolean;
-  /** Small pill on the tab strip; null/undefined hides it. */
-  badge?: (
-    ctx: unknown,
-    scope: { sessionId: string },
-    state: unknown,
-  ) => string | number | null | undefined;
-  component: (props: TabComponentPropsLike) => ReactNode;
-}
-
-export interface BetterSidebarLike {
-  registerTab(descriptor: TabDescriptorLike): () => void;
-  openTab(seed: {
-    type: string;
-    title?: string;
-    /** Content seed (lands on tab.path); content opens expand the panel. */
-    path?: string;
-  }): void;
-  getSnapshot(): SidebarSnapshotLike;
-  /** Sidebar state feed (v0.12+): session switches, state and prefs changes. */
-  subscribeState?: (listener: () => void) => () => void;
-  isTabEnabled(id: string): boolean;
-}
-
-/** The registered tab type id (also the SidebarTab.type value). */
-export const OBSERVATION_TAB_TYPE = "browserskill:observation";
-
-/**
- * Inert content seed carried on auto-opened tabs: its mere presence makes
- * the sidebar treat the open as a content open (expanding the hosting panel
- * so the tracking view lands in sight). Never read by our component.
- */
-export const OBSERVATION_TAB_PATH = "browser-skill:observation";
-
-/**
- * The observation tab body: the same OverlayBody the floating card renders,
- * minus the card chrome (no drag header, no collapse — the sidebar tab bar
- * owns those), plus the PiP pop-out upgrade. The view is scoped to the
- * sidebar's conversation: only browser sessions started by it (or its
- * descendants) show here — the floating card keeps the global view.
- */
-export function ObservationSidebarTab({
-  store,
-  scopeId,
-}: {
-  store: ObservationClientStore;
-  scopeId: string;
-}) {
-  const { snapshot, focus, pinnedId, onTogglePin, now } = useObservationView(store, scopeId);
-  const { pipWindow, pipSupported, popOut } = usePip();
-
-  const body = (
-    <OverlayBody
-      store={store}
-      focus={focus}
-      sessions={snapshot.sessions}
-      available={snapshot.available}
-      pinnedId={pinnedId}
-      onTogglePin={onTogglePin}
-      now={now}
-      inPip={pipWindow !== null}
-      onPopOut={pipWindow === null && pipSupported ? () => popOut() : undefined}
-    />
-  );
-
-  if (pipWindow !== null) {
-    return createPortal(body, pipWindow.document.body);
-  }
-  return <div className={css["sidebar-tab"]}>{body}</div>;
-}
-
-function* leafNodes(node: SidebarNodeLike): Generator<SidebarLeafLike> {
-  if (node.kind === "leaf") {
-    yield node;
-    return;
-  }
-  for (const child of node.children) yield* leafNodes(child);
-}
-
-/** Whether a tab of our type is already open in either sidebar workbench. */
-export function observationTabOpen(state: SidebarStateLike | undefined): boolean {
-  if (state === undefined) return false;
-  for (const root of [state.splits, state.bottomSplits]) {
-    for (const leaf of leafNodes(root)) {
-      if (leaf.tabs.some((tab) => tab.type === OBSERVATION_TAB_TYPE)) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Register the observation sidebar tab and flip the carrier flag. Returns
- * the disposer the cordis fiber invokes when the sidebar service goes away
- * (plugin unload/HMR): the floating overlay then resumes as the carrier.
- */
-export function registerObservationSidebar(
-  service: BetterSidebarLike,
-  store: ObservationClientStore,
-): () => void {
-  setSidebarMode(true);
-  // Hold the feed for the whole sidebar lifetime so the auto-open watcher
-  // sees new sessions even while the tab itself is closed.
-  store.acquire();
-  const disposeTab = service.registerTab({
-    id: OBSERVATION_TAB_TYPE,
-    title: TAB_TITLE,
-    icon: (size: number) => createElement(TabIcon, { size }),
-    single: true,
-    // The badge counts only sessions visible to the tab strip's own
-    // conversation (global sessions from other conversations stay hidden,
-    // mirroring the tab body's scoped view).
-    badge: (_ctx, scope) => {
-      const count = store
-        .getSnapshot()
-        .sessions.filter((s) => visibleToScope(s, scope.sessionId)).length;
-      return count > 0 ? count : null;
-    },
-    component: (props) =>
-      createElement(ObservationSidebarTab, { store, scopeId: props.scope.sessionId }),
-  });
-
-  // Auto-open the tab when a browser session VISIBLE TO the active
-  // conversation appears (and right away when one is already live). The
-  // evaluation runs on observation publishes AND on sidebar state changes:
-  // the latter covers the sidebar store's async init (its state is
-  // undefined for the first beats after page load) and conversation
-  // switches. The open carries a content seed (`path`): only content opens
-  // land in sight — the sidebar expands the hosting panel for them. While
-  // the panel is OPEN an existing tab is never re-focused — the user may
-  // be reading another page on purpose; while it is collapsed a NEW
-  // session (0→N) nudges the tab back into sight, mirroring how the
-  // floating card used to reappear.
-  const activeVisibleCount = (): number => {
-    const activeId = service.getSnapshot().sessionId;
-    if (activeId === undefined) return 0;
-    return store.getSnapshot().sessions.filter((s) => visibleToScope(s, activeId)).length;
-  };
-  let previousVisible = activeVisibleCount();
-  const evaluate = (): void => {
-    const count = activeVisibleCount();
-    const { state, sessionId } = service.getSnapshot();
-    if (
-      state !== undefined &&
-      sessionId !== undefined &&
-      service.isTabEnabled(OBSERVATION_TAB_TYPE)
-    ) {
-      const open = observationTabOpen(state);
-      if (count > 0 && !open) {
-        service.openTab({ type: OBSERVATION_TAB_TYPE, path: OBSERVATION_TAB_PATH });
-      } else if (previousVisible === 0 && count > 0 && open && state.panelOpen === false) {
-        service.openTab({ type: OBSERVATION_TAB_TYPE, path: OBSERVATION_TAB_PATH });
-      }
-    }
-    previousVisible = count;
-  };
-  evaluate();
-  const unsubscribe = store.subscribe(evaluate);
-  const unsubscribeState = service.subscribeState?.(evaluate);
-
-  return () => {
-    unsubscribe();
-    unsubscribeState?.();
-    disposeTab();
-    store.release();
-    setSidebarMode(false);
-  };
-}

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

@@ -53,7 +53,6 @@ export interface OverlaySnapshot {
 const STATE_URL = "/bsk-observation/state";
 const EVENTS_URL = "/bsk-observation/events";
 const INTERRUPT_URL = "/bsk-observation/interrupt";
-const STOP_URL = "/bsk-observation/stop";
 
 function revoke(url: string | undefined): void {
   if (url !== undefined && typeof URL.revokeObjectURL === "function") {
@@ -79,8 +78,6 @@ export class ObservationClientStore {
   };
   private available = true;
   private started = false;
-  /** Refcount of mounted consumers (overlay card, sidebar tab, sidebar fiber). */
-  private consumers = 0;
 
   constructor(private readonly deps: ObservationClientDeps) {}
 
@@ -192,23 +189,6 @@ export class ObservationClientStore {
     this.publish();
   }
 
-  /**
-   * Hold the feed for one consumer's lifetime: the stream starts with the
-   * first holder and stops with the last release. Several carriers can share
-   * the store (the floating card, the better-sidebar tab, and the sidebar
-   * integration fiber) without one unmount killing the others' updates.
-   */
-  acquire(): void {
-    this.consumers += 1;
-    if (this.consumers === 1) this.start();
-  }
-
-  release(): void {
-    if (this.consumers === 0) return;
-    this.consumers -= 1;
-    if (this.consumers === 0) this.stop();
-  }
-
   /** Forget one session's tracked + held frames, revoking their blob URLs. */
   private dropThumb(sessionId: string): void {
     const attachmentId = this.thumbBySession.get(sessionId);
@@ -312,23 +292,4 @@ export class ObservationClientStore {
       return false;
     }
   }
-
-  /**
-   * Stop one session and close its Agent Window. The session's removal
-   * arrives through the SSE remove event — no local state is touched here.
-   */
-  async stopSession(sessionId: string): Promise<boolean> {
-    try {
-      const res = await this.deps.fetchFn(STOP_URL, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ sessionId }),
-      });
-      if (!res.ok) return false;
-      const body = (await res.json()) as { stopped?: boolean };
-      return body.stopped === true;
-    } catch {
-      return false;
-    }
-  }
 }

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

@@ -1,148 +0,0 @@
-/**
- * Shared view logic for the observation carriers (the floating overlay card
- * and the better-sidebar tab): the store-backed view model (snapshot, focus
- * pinning, elapsed ticker) and the Document PiP pop-out. Extracted from
- * ObservationOverlay so both carriers run the same focus/interrupt behavior
- * without duplicating hooks.
- */
-
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
-import type { SessionObservation } from "../observation";
-import type { ObservationClientStore, OverlaySnapshot } from "./observation-store";
-
-/**
- * Auto-follow focus: the most recently touched session, but never yank focus
- * to a session whose latest action failed (errors flag the strip item, they
- * do not steal the stage) or one already reported dead.
- */
-export function focusOf(sessions: readonly SessionObservation[]): SessionObservation | undefined {
-  if (sessions.length === 0) return undefined;
-  const byRecency = [...sessions].sort((a, b) => b.since - a.since);
-  const healthy = byRecency.find((s) => s.lastError === undefined && s.dead !== true);
-  return healthy ?? byRecency[0];
-}
-
-export function statusOf(obs: SessionObservation): "active" | "idle" | "error" {
-  if (obs.lastError !== undefined && obs.action === "idle") return "error";
-  return obs.action === "idle" ? "idle" : "active";
-}
-
-/** Minimal Document PiP surface (TS lib.dom lacks it). */
-export interface DocumentPip {
-  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
-}
-
-export function pipApi(): DocumentPip | undefined {
-  if (typeof window === "undefined") return undefined;
-  return (window as unknown as { documentPictureInPicture?: DocumentPip }).documentPictureInPicture;
-}
-
-/** Clone the host document's style/link nodes into a PiP window. */
-export function cloneStylesInto(pipWindow: Window): void {
-  for (const node of document.querySelectorAll('link[rel="stylesheet"], style')) {
-    pipWindow.document.head.appendChild(node.cloneNode(true));
-  }
-}
-
-export interface ObservationView {
-  readonly snapshot: OverlaySnapshot;
-  /** Pinned session wins while it still exists; otherwise auto-follow. */
-  readonly focus: SessionObservation | undefined;
-  readonly pinnedId: string | null;
-  readonly onTogglePin: (sessionId: string) => void;
-  /** 1s ticker while anything is active (drives the elapsed readout). */
-  readonly now: number;
-}
-
-/**
- * Whether one session is visible on a surface scoped to one DSH
- * conversation: sessions started by that conversation or its descendants
- * (the lineage ancestors ride along on the entry). Untracked sessions (no
- * owner recorded) are hidden from scoped surfaces but stay in global views.
- */
-export function visibleToScope(obs: SessionObservation, scopeId: string): boolean {
-  return obs.dshSessionIds?.includes(scopeId) === true;
-}
-
-/**
- * The store-backed observation view model. Holds the feed for the component
- * lifetime (refcounted — overlapping carriers never kill each other's
- * stream). `scopeId` narrows the view to one DSH conversation's sessions
- * (the better-sidebar tab); undefined keeps the global view (floating
- * card, PiP).
- */
-export function useObservationView(
-  store: ObservationClientStore,
-  scopeId?: string,
-): ObservationView {
-  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot);
-  useEffect(() => {
-    store.acquire();
-    return () => store.release();
-  }, [store]);
-
-  const scopedSnapshot: OverlaySnapshot =
-    scopeId === undefined
-      ? snapshot
-      : {
-          ...snapshot,
-          sessions: snapshot.sessions.filter((s) => visibleToScope(s, scopeId)),
-        };
-
-  const [pinnedId, setPinnedId] = useState<string | null>(null);
-  const pinned =
-    pinnedId !== null ? scopedSnapshot.sessions.find((s) => s.sessionId === pinnedId) : undefined;
-  const focus = pinned ?? focusOf(scopedSnapshot.sessions);
-  const onTogglePin = useCallback((sessionId: string) => {
-    setPinnedId((current) => (current === sessionId ? null : sessionId));
-  }, []);
-
-  const anyActive = scopedSnapshot.sessions.some((s) => s.action !== "idle");
-  const [now, setNow] = useState(() => Date.now());
-  useEffect(() => {
-    if (!anyActive) return;
-    const timer = setInterval(() => setNow(Date.now()), 1000);
-    return () => clearInterval(timer);
-  }, [anyActive]);
-
-  return {
-    snapshot: scopedSnapshot,
-    focus,
-    pinnedId: pinned !== undefined ? pinnedId : null,
-    onTogglePin,
-    now,
-  };
-}
-
-export interface PipHandle {
-  /** The open PiP window, or null while the content renders in its carrier. */
-  readonly pipWindow: Window | null;
-  /** Whether the browser exposes Document PiP (Chrome-only today). */
-  readonly pipSupported: boolean;
-  /**
-   * Upgrade the content into a native PiP window. Rejects silently without a
-   * user gesture (or when closed mid-request): the carrier keeps the content.
-   */
-  readonly popOut: (size?: { width: number; height: number }) => void;
-}
-
-export function usePip(): PipHandle {
-  const [pipWindow, setPipWindow] = useState<Window | null>(null);
-  const popOut = useCallback((size?: { width: number; height: number }): void => {
-    const pip = pipApi();
-    if (pip === undefined) return;
-    void pip
-      .requestWindow(size)
-      .then((win) => {
-        cloneStylesInto(win);
-        win.addEventListener("pagehide", () => setPipWindow(null));
-        setPipWindow(win);
-      })
-      .catch(() => {});
-  }, []);
-  // Unmounting the carrier (tab close, conversation switch, plugin HMR) does
-  // not destroy the PiP browsing context: close it ourselves or it survives
-  // as a blank window. close() on an already-closed window is a no-op.
-  useEffect(() => () => pipWindow?.close(), [pipWindow]);
-  return { pipWindow, pipSupported: pipApi() !== undefined, popOut };
-}

packages/dsh-plugin-browserskill/src/client/sidebar-mode.ts

@@ -1,26 +0,0 @@
-/**
- * Carrier switch for the observation view: while the better-sidebar
- * integration fiber is alive (the dsh-better-sidebar plugin provides its
- * `betterSidebar` service), the tracking view lives in a sidebar tab and the
- * floating overlay card/capsule hides itself. The flag is a tiny external
- * store so the overlay can read it through useSyncExternalStore and flip
- * without a remount when the sidebar plugin (un)loads.
- */
-
-let active = false;
-const listeners = new Set<() => void>();
-
-export function getSidebarMode(): boolean {
-  return active;
-}
-
-export function subscribeSidebarMode(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-export function setSidebarMode(next: boolean): void {
-  if (active === next) return;
-  active = next;
-  for (const listener of [...listeners]) listener();
-}

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

@@ -12,7 +12,6 @@
 
 import type { Context } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
-import { armArchiveCleanup } from "./archive-cleanup";
 import { armLazyTools } from "./lazy-tools";
 import { ObservationService } from "./observation";
 import { registerObservationRoutes } from "./observation-http";
@@ -108,10 +107,6 @@ export function apply(
     removeRoutes = registerObservationRoutes(injected, observation);
     return () => removeRoutes();
   });
-  // Reap a conversation's browsers when the conversation itself is archived:
-  // archived sessions are hidden from every surface, so their Agent Windows
-  // would otherwise linger unreachable until idle timeout or unload.
-  const disarmArchiveCleanup = armArchiveCleanup(ctx, registry, observation);
 
   // Non-blocking install probe: warn early when bsk is missing instead of
   // failing the first tool call with a bare spawn error. Uses --version on
@@ -137,7 +132,6 @@ export function apply(
       removeSuite();
       unregisterSkill();
       removeRoutes();
-      disarmArchiveCleanup();
       observation.dispose();
       runner.killAll();
       const stops = registry
@@ -150,7 +144,6 @@ export function apply(
   });
 }
 
-export { armArchiveCleanup, ownerSessionIds } from "./archive-cleanup";
 export type { ObservationEvent, ObservationOptions, SessionObservation } from "./observation";
 export { ObservationService } from "./observation";
 export { registerObservationRoutes } from "./observation-http";

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

@@ -8,7 +8,6 @@
  *   GET  /bsk-observation/state      → { sessions, available }
  *   GET  /bsk-observation/events     → SSE stream of ObservationEvent
  *   POST /bsk-observation/interrupt  → body {sessionId?} → {interrupted: boolean}
- *   POST /bsk-observation/stop       → body {sessionId} → {stopped: boolean}
  *   GET  /bsk-observation/thumbnail/<attachmentId> → image bytes
  *
  * Routes exist only when a webServer service is mounted (web composition);
@@ -167,42 +166,6 @@ export function registerObservationRoutes(
         });
       },
     }),
-    webServer.register({
-      kind: "exact",
-      path: `${ROUTE_BASE}/stop`,
-      handler: (req, res) => {
-        if (req.method !== "POST") {
-          sendJson(res, 405, { error: "method not allowed" });
-          return;
-        }
-        if (fenceRejected(req, res)) return;
-        let body = "";
-        req.on("data", (chunk: Buffer | string) => {
-          body += chunk;
-        });
-        req.on("end", () => {
-          let sessionId: string | undefined;
-          try {
-            const parsed = JSON.parse(body || "{}") as { sessionId?: unknown };
-            if (typeof parsed.sessionId === "string" && parsed.sessionId !== "") {
-              sessionId = parsed.sessionId;
-            }
-          } catch {
-            sendJson(res, 400, { error: "invalid JSON body" });
-            return;
-          }
-          // A destructive call always names its target (never "current").
-          if (sessionId === undefined) {
-            sendJson(res, 400, { error: "sessionId required" });
-            return;
-          }
-          void observation.stopSession(sessionId).then(
-            (stopped) => sendJson(res, 200, { stopped }),
-            () => sendJson(res, 500, { error: "stop failed" }),
-          );
-        });
-      },
-    }),
     webServer.register({
       kind: "prefix",
       path: `${ROUTE_BASE}/thumbnail`,

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

@@ -39,13 +39,6 @@ export interface SessionObservation {
    * greys it out until it is stopped/removed. No more frames are requested.
    */
   dead?: boolean;
-  /**
-   * The DSH conversations this session belongs to (the starting agent's
-   * session plus its seed-lineage ancestors), recorded at start. Scoped
-   * surfaces (the better-sidebar tab) filter by it; absent means untracked
-   * ownership — visible only in the global (unscoped) view.
-   */
-  dshSessionIds?: string[];
 }
 
 /** Incremental event carried to subscribers (SSE on the wire). */
@@ -160,13 +153,11 @@ export class ObservationService {
   /** Register a fresh owned session (called from browser_session_start). */
   addSession(sessionId: string, url?: string): void {
     if (!this.deps.options.enabled || this.disposed) return;
-    const dshSessionIds = this.deps.registry.dshOwnersOf(sessionId);
     this.put({
       sessionId,
       ...(url !== undefined ? { url } : {}),
       action: "idle",
       since: this.scheduler.now(),
-      ...(dshSessionIds.length > 0 ? { dshSessionIds } : {}),
     });
     this.lastActivity.set(sessionId, this.scheduler.now());
     this.scheduleCapture(sessionId, 0);
@@ -237,36 +228,6 @@ export class ObservationService {
     return this.deps.runner.killFor(target) > 0;
   }
 
-  /**
-   * Stop one owned session and close its Agent Window (the overlay's stop
-   * button — same end state as `browser_session_stop`). Never waits behind a
-   * hung in-flight command: tool children are killed first so the session's
-   * keyed queue drains immediately, and no further captures queue up. A
-   * session the daemon already forgot (dead strip entries) stops
-   * idempotently — the goal state (entry gone) is identical.
-   * @returns whether the session ended up stopped/removed.
-   */
-  async stopSession(sessionId: string): Promise<boolean> {
-    if (!this.deps.registry.isOwned(sessionId)) return false;
-    this.cancelCapture(sessionId);
-    this.deps.runner.killFor(sessionId);
-    const result = await this.deps.queue.run(sessionId, () =>
-      this.deps.runner.run(["session", "stop", sessionId], { timeoutMs: 30_000 }),
-    );
-    if (result.code !== 0) {
-      let code: string | undefined;
-      try {
-        code = (JSON.parse(result.stdout) as { code?: string }).code;
-      } catch {
-        code = undefined;
-      }
-      if (code !== "session_not_found") return false;
-    }
-    this.deps.registry.remove(sessionId);
-    this.removeSession(sessionId);
-    return true;
-  }
-
   /**
    * Read one captured thumbnail from the in-process ring. Powers the plugin's
    * own HTTP thumbnail route — frames are plugin-owned runtime data, never

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

@@ -24,13 +24,6 @@ export interface TrackedSession {
 export class SessionRegistry {
   private readonly sessions = new Map<string, TrackedSession>();
   private currentId: string | undefined;
-  /**
-   * bsk session id → the DSH session ids that may clean it up: the agent
-   * session that started it plus every ancestor along the seed lineage, so
-   * archiving a conversation at ANY level of the chain reaps its browsers
-   * (see archive-cleanup.ts).
-   */
-  private readonly dshOwners = new Map<string, ReadonlySet<string>>();
   /**
    * Slots reserved by in-flight starts. reserveStart/completeStart/abandonStart
    * run synchronously around the async spawn, so concurrent starts can never
@@ -79,37 +72,12 @@ export class SessionRegistry {
   /** Forget a session; falls back to the most recent remaining one. */
   remove(sessionId: string): void {
     this.sessions.delete(sessionId);
-    this.dshOwners.delete(sessionId);
     if (this.currentId === sessionId) {
       const rest = [...this.sessions.values()];
       this.currentId = rest.length > 0 ? rest[rest.length - 1].sessionId : undefined;
     }
   }
 
-  /**
-   * Record which DSH conversation(s) a freshly started bsk session belongs
-   * to (the starting agent's session plus its ancestors). No-op without ids
-   * — e.g. a start whose caller carried no agent identity.
-   */
-  trackOwner(sessionId: string, dshSessionIds: readonly string[]): void {
-    if (dshSessionIds.length === 0 || !this.sessions.has(sessionId)) return;
-    this.dshOwners.set(sessionId, new Set(dshSessionIds));
-  }
-
-  /** bsk session ids owned by the given DSH conversation (or its descendants). */
-  ownedByDsh(dshSessionId: string): string[] {
-    const owned: string[] = [];
-    for (const [sessionId, owners] of this.dshOwners) {
-      if (owners.has(dshSessionId)) owned.push(sessionId);
-    }
-    return owned;
-  }
-
-  /** The DSH conversation ids owning one bsk session (empty when untracked). */
-  dshOwnersOf(sessionId: string): string[] {
-    return [...(this.dshOwners.get(sessionId) ?? [])];
-  }
-
   /** Mark an owned session as most recently used (recency order refresh). */
   private touch(sessionId: string): void {
     const existing = this.sessions.get(sessionId);

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

@@ -17,7 +17,6 @@ import {
   type ToolResult,
   type ToolRunContext,
 } from "@deepseek-ai/dsh-tools";
-import { ownerSessionIds } from "./archive-cleanup";
 import { trySaveScreenshot } from "./image";
 import { actionForLabel, type ObservationService } from "./observation";
 import type { KeyedExecutor } from "./queue";
@@ -246,9 +245,6 @@ export function registerTools(deps: ToolDeps): () => void {
           browserInstanceId: reply.browser_instance_id,
           startedAtMs: Date.now(),
         });
-        // Ownership for archive cleanup: the calling conversation and its
-        // ancestors reap this session when any of them is archived.
-        registry.trackOwner(reply.session_id, ownerSessionIds(deps.ctx, exec.agent?.id));
         deps.observation.addSession(reply.session_id, args.url);
         try {
           if (args.device !== undefined) {

packages/dsh-plugin-browserskill/tests/archive-cleanup.test.ts

@@ -1,157 +0,0 @@
-// Archive-triggered cleanup: lineage resolution for browser-session
-// ownership, the registry's owner index, and the domain/changed watcher
-// that reaps a freshly archived conversation's bsk sessions.
-
-import { describe, expect, it, vi } from "vitest";
-import { armArchiveCleanup, ownerSessionIds } from "../src/archive-cleanup";
-import type { ObservationService } from "../src/observation";
-import { SessionRegistry } from "../src/sessions";
-
-/** A ctx stub carrying a session store with the given lineage headers. */
-function ctxWithSessions(headers: Record<string, { parentSession?: string }>) {
-  return {
-    get: (key: string) =>
-      key === "sessions"
-        ? {
-            get: (id: string) => (headers[id] === undefined ? undefined : { header: headers[id] }),
-          }
-        : undefined,
-  } as never;
-}
-
-describe("ownerSessionIds", () => {
-  it("walks the seed lineage to the root; empty without an agent identity", () => {
-    expect(ownerSessionIds(ctxWithSessions({}), undefined)).toEqual([]);
-    const ctx = ctxWithSessions({
-      child: { parentSession: "parent" },
-      parent: { parentSession: "root" },
-      root: {},
-    });
-    expect(ownerSessionIds(ctx, "child")).toEqual(["child", "parent", "root"]);
-  });
-
-  it("stops the walk at an unloaded ancestor", () => {
-    const ctx = ctxWithSessions({ child: { parentSession: "gone" } });
-    expect(ownerSessionIds(ctx, "child")).toEqual(["child", "gone"]);
-  });
-
-  it("never loops on a malformed parent cycle", () => {
-    const ctx = ctxWithSessions({
-      a: { parentSession: "b" },
-      b: { parentSession: "a" },
-    });
-    expect(ownerSessionIds(ctx, "a")).toEqual(["a", "b"]);
-  });
-});
-
-describe("SessionRegistry owner tracking", () => {
-  function start(registry: SessionRegistry, sessionId: string): void {
-    registry.reserveStart();
-    registry.completeStart({ sessionId, startedAtMs: 1 });
-  }
-
-  it("indexes owners and forgets them on remove; ignores empty/unknown ownership", () => {
-    const registry = new SessionRegistry(5);
-    start(registry, "bsk1");
-    start(registry, "bsk2");
-    registry.trackOwner("bsk1", ["conv-a", "root"]);
-    registry.trackOwner("bsk2", ["conv-b"]);
-    expect(registry.ownedByDsh("root")).toEqual(["bsk1"]);
-    expect(registry.ownedByDsh("conv-a")).toEqual(["bsk1"]);
-    expect(registry.ownedByDsh("conv-b")).toEqual(["bsk2"]);
-    expect(registry.ownedByDsh("nobody")).toEqual([]);
-    registry.remove("bsk1");
-    expect(registry.ownedByDsh("root")).toEqual([]);
-    // Empty owner lists and unknown session ids record nothing.
-    registry.trackOwner("bsk2", []);
-    registry.trackOwner("ghost", ["conv-c"]);
-    expect(registry.ownedByDsh("conv-c")).toEqual([]);
-  });
-});
-
-describe("armArchiveCleanup", () => {
-  function harness(opts: { archived?: string[] } = {}) {
-    const registry = new SessionRegistry(5);
-    const observation = { stopSession: vi.fn(async () => true) };
-    const listeners = new Set<(change: unknown) => void>();
-    const ctx = {
-      get: (key: string) =>
-        key === "workspaceRegistry" ? { archivedSessionIds: opts.archived ?? [] } : undefined,
-      on: (event: string, listener: (change: unknown) => void) => {
-        if (event === "domain/changed") listeners.add(listener);
-        return () => listeners.delete(listener);
-      },
-    };
-    const emit = (change: unknown) => {
-      for (const listener of [...listeners]) listener(change);
-    };
-    return {
-      registry,
-      observation: observation as unknown as ObservationService,
-      stopSession: observation.stopSession,
-      emit,
-      arm: () =>
-        armArchiveCleanup(ctx as never, registry, observation as unknown as ObservationService),
-    };
-  }
-
-  function startOwned(registry: SessionRegistry, bskId: string, owners: string[]): void {
-    registry.reserveStart();
-    registry.completeStart({ sessionId: bskId, startedAtMs: 1 });
-    registry.trackOwner(bskId, owners);
-  }
-
-  it("stops every bsk session owned by a freshly archived conversation, until disarmed", () => {
-    const h = harness();
-    startOwned(h.registry, "bsk1", ["conv-a", "root"]);
-    startOwned(h.registry, "bsk2", ["conv-b"]);
-    const disarm = h.arm();
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["root"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-    expect(h.stopSession).toHaveBeenCalledWith("bsk1");
-    // After the disposer runs the watcher is silent again.
-    disarm();
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["root", "conv-b"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-  });
-
-  it("ignores pre-archived ids, foreign domains, and malformed frames", () => {
-    const h = harness({ archived: ["old-conv"] });
-    startOwned(h.registry, "bsk1", ["old-conv"]);
-    startOwned(h.registry, "bsk2", ["conv-a"]);
-    h.arm();
-    // Seeded from the registry: the pre-archived id must not retro-fire.
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["old-conv"] } });
-    h.emit({ domain: "settings", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    h.emit({ domain: "workspace", table: "rows", value: { archivedSessionIds: ["conv-a"] } });
-    h.emit({ domain: "workspace", table: "", value: {} });
-    expect(h.stopSession).not.toHaveBeenCalled();
-    // A genuinely new archive still fires.
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["old-conv", "conv-a"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledWith("bsk2");
-  });
-
-  it("treats a re-archived session as fresh again after unarchive", () => {
-    const h = harness();
-    startOwned(h.registry, "bsk1", ["conv-a"]);
-    h.arm();
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-    // Unarchive, then re-archive: the second archival cleans up again.
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: [] } });
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    expect(h.stopSession).toHaveBeenCalledTimes(2);
-  });
-});

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

@@ -4,7 +4,7 @@
 // upgrade/fallback (mocked documentPictureInPicture). NOTE: use RTL's waitFor
 // (act-flushing), not vi.waitFor, when asserting store-driven UI updates.
 
-import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { applyResize, ObservationOverlay } from "../../src/client/ObservationOverlay";
 import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
@@ -157,45 +157,6 @@ describe("ObservationOverlay", () => {
     await screen.findByText(/s1 · clicking/);
   });
 
-  it("stop session: the first click only arms the confirm, the second posts", async () => {
-    const h = makeHarness([{ sessionId: "s1", action: "idle", since: Date.now() }]);
-    render(<ObservationOverlay store={h.store} />);
-    await screen.findByText(/s1 · idle/);
-    const stop = screen.getByRole("button", { name: "Stop session s1" });
-    fireEvent.click(stop);
-    // Armed: a plain click must never close an Agent Window by itself.
-    expect(h.fetches.some((f) => f.url === "/bsk-observation/stop")).toBe(false);
-    const confirm = await screen.findByRole("button", { name: "Confirm stop session s1" });
-    expect(confirm.getAttribute("aria-pressed")).toBe("true");
-    fireEvent.click(confirm);
-    await waitFor(() =>
-      expect(
-        h.fetches.some(
-          (f) => f.url === "/bsk-observation/stop" && f.init?.body === '{"sessionId":"s1"}',
-        ),
-      ).toBe(true),
-    );
-  });
-
-  it("disarms the stop confirm after the expiry window", async () => {
-    const h = makeHarness([{ sessionId: "s1", action: "idle", since: Date.now() }]);
-    render(<ObservationOverlay store={h.store} />);
-    const stop = await screen.findByRole("button", { name: "Stop session s1" });
-    vi.useFakeTimers();
-    try {
-      fireEvent.click(stop);
-      // Synchronous queries only: waitFor-style finds hang under fake timers.
-      expect(screen.getByRole("button", { name: "Confirm stop session s1" })).toBeTruthy();
-      act(() => {
-        vi.advanceTimersByTime(3100);
-      });
-      expect(screen.getByRole("button", { name: "Stop session s1" })).toBeTruthy();
-      expect(h.fetches.some((f) => f.url === "/bsk-observation/stop")).toBe(false);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
   it("resizes within min/max clamps", async () => {
     const h = makeHarness([BUSY]);
     render(<ObservationOverlay store={h.store} />);
@@ -261,7 +222,6 @@ describe("ObservationOverlay", () => {
         addEventListener: (name: string, fn: () => void) => {
           listeners.set(name, [...(listeners.get(name) ?? []), fn]);
         },
-        close: vi.fn(),
       } as unknown as Window;
     });
     (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
@@ -276,28 +236,6 @@ describe("ObservationOverlay", () => {
     await screen.findByTestId("obs-card");
   });
 
-  it("closes the PiP window when the carrier unmounts", async () => {
-    const h = makeHarness([BUSY]);
-    const pipDoc = document.implementation.createHTMLDocument("pip");
-    const close = vi.fn();
-    const requestWindow = vi.fn(async () => {
-      return {
-        document: pipDoc,
-        addEventListener: () => {},
-        close,
-      } as unknown as Window;
-    });
-    (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
-    const { unmount } = 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"));
-    // Unmounting (tab close, conversation switch, plugin HMR) closes the PiP
-    // instead of leaving a blank window behind.
-    unmount();
-    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/client/observation-sidebar.test.tsx

@@ -1,331 +0,0 @@
-// @vitest-environment happy-dom
-// better-sidebar carrier: tab registration + auto-open, the sidebar-mode
-// flag hiding the floating overlay, PiP pop-out from the tab, and the
-// store's refcounted acquire/release across overlapping carriers.
-
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { ObservationOverlay } from "../../src/client/ObservationOverlay";
-import {
-  type BetterSidebarLike,
-  OBSERVATION_TAB_PATH,
-  OBSERVATION_TAB_TYPE,
-  ObservationSidebarTab,
-  observationTabOpen,
-  registerObservationSidebar,
-  type SidebarNodeLike,
-  type SidebarStateLike,
-  type TabDescriptorLike,
-} from "../../src/client/observation-sidebar";
-import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
-import { getSidebarMode, setSidebarMode } from "../../src/client/sidebar-mode";
-import type { SessionObservation } from "../../src/observation";
-
-// Owned by the sidebar mock's active conversation ("conv-1") so the scoped
-// visibility logic lets it through; FOREIGN belongs to another conversation.
-const BUSY: SessionObservation = {
-  sessionId: "s1",
-  action: "clicking",
-  since: Date.now() - 7000,
-  dshSessionIds: ["conv-1"],
-};
-const FOREIGN: SessionObservation = {
-  sessionId: "s9",
-  action: "clicking",
-  since: Date.now() - 5000,
-  dshSessionIds: ["other-conv"],
-};
-
-interface Harness {
-  store: ObservationClientStore;
-  es: () => EventSourceLike | undefined;
-  push: (sessions: SessionObservation[]) => void;
-}
-
-function makeHarness(initial: SessionObservation[]): Harness {
-  let es: EventSourceLike | undefined;
-  let current = initial;
-  const store = new ObservationClientStore({
-    fetchFn: async (url: string) => {
-      if (url === "/bsk-observation/state") {
-        return { ok: true, json: async () => ({ sessions: current }) };
-      }
-      return { ok: true, json: async () => ({ interrupted: true }) };
-    },
-    eventSourceFactory: () => {
-      es = { onmessage: null, close: vi.fn() };
-      return es;
-    },
-    loadImage: async (id: string) => `blob:${id}`,
-  });
-  return {
-    store,
-    es: () => es,
-    push: (sessions) => {
-      current = sessions;
-      for (const s of sessions) {
-        es?.onmessage?.({ data: JSON.stringify({ type: "upsert", session: s }) });
-      }
-      if (sessions.length === 0) es?.onmessage?.({ data: JSON.stringify({ type: "reset" }) });
-    },
-  };
-}
-
-function leafWith(type: string, panelOpen = true): SidebarStateLike {
-  return {
-    panelOpen,
-    splits: {
-      kind: "split",
-      id: "root",
-      dir: "row",
-      sizes: [1],
-      children: [
-        {
-          kind: "leaf",
-          id: "pane-1",
-          active: type,
-          tabs: [{ id: type, type, title: type }],
-        },
-      ],
-    },
-    bottomSplits: { kind: "leaf", id: "pane-2", active: null, tabs: [] },
-  };
-}
-
-interface SidebarMock {
-  service: BetterSidebarLike;
-  descriptor: () => TabDescriptorLike;
-  openTab: ReturnType<typeof vi.fn>;
-  disposeTab: ReturnType<typeof vi.fn>;
-  setState: (state: SidebarStateLike | undefined) => void;
-}
-
-/** Insert a tab into the first leaf of the main tree (mirrors a real open). */
-function withTabOpened(state: SidebarStateLike, type: string): SidebarStateLike {
-  let done = false;
-  const walk = (node: SidebarNodeLike): SidebarNodeLike => {
-    if (done) return node;
-    if (node.kind === "leaf") {
-      done = true;
-      return { ...node, active: type, tabs: [...node.tabs, { id: type, type, title: type }] };
-    }
-    return { ...node, children: node.children.map(walk) };
-  };
-  return { ...state, splits: walk(state.splits) };
-}
-
-function makeSidebar(
-  initialState: SidebarStateLike | undefined = leafWith("explorer"),
-): SidebarMock {
-  let descriptor: TabDescriptorLike | undefined;
-  let state: SidebarStateLike | undefined = initialState;
-  const openTab = vi.fn((seed: { type: string }) => {
-    // Mirror the real feedback loop: a created tab lands in the state, so
-    // later evaluations see it open (single-instance dedupe re-focuses).
-    if (state !== undefined && !observationTabOpen(state)) {
-      state = withTabOpened(state, seed.type);
-    }
-  });
-  const disposeTab = vi.fn();
-  const service: BetterSidebarLike = {
-    registerTab: (next) => {
-      descriptor = next;
-      return disposeTab;
-    },
-    openTab,
-    getSnapshot: () => ({ sessionId: "conv-1", state }),
-    isTabEnabled: () => true,
-  };
-  return {
-    service,
-    descriptor: () => {
-      if (descriptor === undefined) throw new Error("no tab registered");
-      return descriptor;
-    },
-    openTab,
-    disposeTab,
-    setState: (next) => {
-      state = next;
-    },
-  };
-}
-
-afterEach(() => {
-  cleanup();
-  setSidebarMode(false);
-});
-
-describe("registerObservationSidebar", () => {
-  it("registers a single-instance tab and holds the feed for its lifetime", () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    expect(getSidebarMode()).toBe(false);
-    const dispose = registerObservationSidebar(sidebar.service, h.store);
-    expect(getSidebarMode()).toBe(true);
-    // The fiber holds the observation feed itself, so the auto-open watcher
-    // sees new sessions even while the tab is closed.
-    expect(h.es()).toBeDefined();
-    const descriptor = sidebar.descriptor();
-    expect(descriptor.id).toBe(OBSERVATION_TAB_TYPE);
-    expect(descriptor.single).toBe(true);
-    expect(descriptor.title).toBe("Browser Skill");
-    dispose();
-    expect(getSidebarMode()).toBe(false);
-    expect(sidebar.disposeTab).toHaveBeenCalledTimes(1);
-    expect(h.es()?.close).toHaveBeenCalled?.();
-  });
-
-  it("opens the tab right away when a session is already live at activation", async () => {
-    const h = makeHarness([BUSY]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    // The initial state fetch lands asynchronously; the 0→N watcher then fires.
-    await waitFor(() =>
-      expect(sidebar.openTab).toHaveBeenCalledWith({
-        type: OBSERVATION_TAB_TYPE,
-        path: OBSERVATION_TAB_PATH,
-      }),
-    );
-  });
-
-  it("auto-opens on the first session but never re-focuses an open tab", async () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-    // First session arrives: the tab lands in the sidebar.
-    h.push([BUSY]);
-    await waitFor(() => expect(sidebar.openTab).toHaveBeenCalledTimes(1));
-    // The sidebar now reports the tab open (persisted/restored): further
-    // session arrivals must not steal focus from whatever the user reads.
-    sidebar.setState(leafWith(OBSERVATION_TAB_TYPE));
-    h.push([]);
-    h.push([{ ...BUSY, sessionId: "s2" }]);
-    h.push([]);
-    h.push([{ ...BUSY, sessionId: "s3" }]);
-    await waitFor(() => expect(h.store.getSnapshot().sessions.length).toBe(1));
-    expect(sidebar.openTab).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not open while the sidebar has no active session state", () => {
-    const h = makeHarness([BUSY]);
-    const sidebar = makeSidebar(undefined);
-    registerObservationSidebar(sidebar.service, h.store);
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-  });
-
-  it("nudges an existing tab back into sight when the panel is collapsed", async () => {
-    const h = makeHarness([]);
-    // Tab already open (persisted), but the panel is collapsed: a new
-    // session should surface the tracking view again (focus + expand via a
-    // content open), like the floating card reappearing.
-    const sidebar = makeSidebar(leafWith(OBSERVATION_TAB_TYPE, false));
-    registerObservationSidebar(sidebar.service, h.store);
-    h.push([BUSY]);
-    await waitFor(() =>
-      expect(sidebar.openTab).toHaveBeenCalledWith({
-        type: OBSERVATION_TAB_TYPE,
-        path: OBSERVATION_TAB_PATH,
-      }),
-    );
-  });
-
-  it("shows the visible session count as the tab badge", () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    const badge = sidebar.descriptor().badge;
-    const scope = { sessionId: "conv-1" };
-    expect(badge?.(undefined, scope, undefined)).toBeNull();
-    h.store.acquire();
-    h.push([BUSY, FOREIGN]);
-    expect(badge?.(undefined, scope, undefined)).toBe(1);
-    expect(badge?.(undefined, { sessionId: "other-conv" }, undefined)).toBe(1);
-    expect(badge?.(undefined, { sessionId: "nobody" }, undefined)).toBeNull();
-    h.store.release();
-  });
-
-  it("does not auto-open for sessions owned by other conversations", async () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    h.push([FOREIGN]);
-    await waitFor(() => expect(h.store.getSnapshot().sessions.length).toBe(1));
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-    // A session visible to the active conversation does open the tab.
-    h.push([BUSY]);
-    await waitFor(() => expect(sidebar.openTab).toHaveBeenCalledTimes(1));
-  });
-});
-
-describe("observationTabOpen", () => {
-  it("finds the tab in either workbench tree", () => {
-    expect(observationTabOpen(undefined)).toBe(false);
-    expect(observationTabOpen(leafWith("explorer"))).toBe(false);
-    expect(observationTabOpen(leafWith(OBSERVATION_TAB_TYPE))).toBe(true);
-    const inBottom: SidebarStateLike = {
-      splits: { kind: "leaf", id: "p1", active: null, tabs: [] },
-      bottomSplits: {
-        kind: "leaf",
-        id: "p2",
-        active: OBSERVATION_TAB_TYPE,
-        tabs: [{ id: OBSERVATION_TAB_TYPE, type: OBSERVATION_TAB_TYPE, title: "Browser" }],
-      },
-    };
-    expect(observationTabOpen(inBottom)).toBe(true);
-  });
-});
-
-describe("ObservationSidebarTab", () => {
-  it("renders the tracking view without card chrome (no collapse, no drag header)", async () => {
-    const h = makeHarness([BUSY]);
-    render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    await screen.findByText(/s1 · clicking/);
-    expect(screen.queryByRole("button", { name: "Collapse" })).toBeNull();
-    expect(screen.getByTestId("obs-header").dataset.draggable).toBeUndefined();
-    // No resize handles — the sidebar owns the geometry.
-    expect(screen.queryByTestId("obs-resize-se")).toBeNull();
-    // Session controls ride along: interrupt + stop-with-confirm.
-    expect(screen.getByRole("button", { name: "Stop session s1" })).toBeTruthy();
-  });
-
-  it("scopes the view to the sidebar's conversation", async () => {
-    const h = makeHarness([BUSY, FOREIGN]);
-    render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    // Focus and content belong to the owned session; the foreign one never
-    // reaches the stage, the status line, or the strip (which needs 2+).
-    await screen.findByText(/s1 · clicking/);
-    expect(screen.queryByText(/s9/)).toBeNull();
-    expect(screen.queryByTestId("obs-strip")).toBeNull();
-    // Scoping to the other conversation swaps what's visible.
-    render(<ObservationSidebarTab store={h.store} scopeId="other-conv" />);
-    await screen.findByText(/s9 · clicking/);
-  });
-});
-
-describe("carrier switching", () => {
-  it("hides the floating overlay while sidebar mode is active", async () => {
-    const h = makeHarness([]);
-    const { container } = render(<ObservationOverlay store={h.store} />);
-    h.push([BUSY]);
-    await screen.findByTestId("obs-card");
-    setSidebarMode(true);
-    await waitFor(() => expect(container.firstChild).toBeNull());
-    setSidebarMode(false);
-    await screen.findByTestId("obs-card");
-  });
-
-  it("keeps the feed alive across overlapping carriers (refcount)", async () => {
-    const h = makeHarness([]);
-    const overlay = render(<ObservationOverlay store={h.store} />);
-    await waitFor(() => expect(h.es()).toBeDefined());
-    // A second carrier mounts (the sidebar tab), then the overlay unmounts:
-    // the stream must survive for the remaining consumer.
-    const tab = render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    overlay.unmount();
-    h.push([BUSY]);
-    await screen.findByText(/s1 · clicking/);
-    expect(h.es()?.close ?? vi.fn()).not.toHaveBeenCalled();
-    tab.unmount();
-  });
-});

packages/dsh-plugin-browserskill/tests/client/screenshot-toolview.test.tsx

@@ -137,9 +137,6 @@ describe("client plugin registration", () => {
     const sessions = { binding: () => undefined };
     const ctx = {
       get: (key: string) => (key === "sessions" ? sessions : undefined),
-      // cordis ctx.inject: the betterSidebar carrier upgrade stays dormant in
-      // this composition (the callback only runs once the service exists).
-      inject: (_deps: string[], _fn: (injected: unknown) => unknown) => {},
       slots: {
         inject: (_name: string, fn: () => unknown) => fn(),
         register: (slot: { name: string; key?: string; id?: string }, view: unknown) => {

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

@@ -61,8 +61,6 @@ function fakeRunner(
   opts: {
     screenshotFails?: boolean;
     screenshotNotFound?: boolean;
-    stopNotFound?: boolean;
-    stopFails?: boolean;
     killCount?: number;
     screenshotBytes?: () => Uint8Array;
   } = {},
@@ -74,21 +72,6 @@ function fakeRunner(
     killed,
     async run(args: string[], options: BskRunOptions = {}): Promise<BskRunResult> {
       calls.push({ args, options });
-      if (args[0] === "session" && args[1] === "stop") {
-        if (opts.stopNotFound) {
-          return {
-            code: 4,
-            stdout: JSON.stringify({ code: "session_not_found", message: "no such session" }),
-            stderr: "",
-            timedOut: false,
-            aborted: false,
-          };
-        }
-        if (opts.stopFails) {
-          return { code: 1, stdout: "", stderr: "boom", timedOut: false, aborted: false };
-        }
-        return { code: 0, stdout: "{}", stderr: "", timedOut: false, aborted: false };
-      }
       if (args[0] === "screenshot") {
         if (opts.screenshotNotFound) {
           return {
@@ -197,23 +180,6 @@ describe("state machine", () => {
     expect(events[events.length - 1].type).toBe("reset");
   });
 
-  it("stamps the registry-recorded DSH owners onto new entries", () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    own(registry, "s2");
-    registry.trackOwner("s1", ["conv-a", "root"]);
-    const { service } = setup({ registry });
-    service.addSession("s1");
-    service.addSession("s2");
-    expect(service.getState()).toEqual([
-      { sessionId: "s1", action: "idle", since: 1_000_000, dshSessionIds: ["conv-a", "root"] },
-      { sessionId: "s2", action: "idle", since: 1_000_000 },
-    ]);
-    // The owner stamp survives later upserts (action/url/frame churn).
-    service.beginAction("s1", "clicking");
-    expect(service.getState()[0].dshSessionIds).toEqual(["conv-a", "root"]);
-  });
-
   it("ignores instrumentation for unknown sessions (owned-only by construction)", () => {
     const { service } = setup({});
     service.beginAction("foreign", "clicking");
@@ -341,57 +307,6 @@ describe("interrupt routing", () => {
   });
 });
 
-describe("stopSession", () => {
-  it("stops an owned session: kills in-flight tools, runs session stop, removes the entry", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner();
-    const { service, events } = setup({ registry, runner });
-    service.addSession("s1");
-    expect(registry.isOwned("s1")).toBe(true);
-
-    await expect(service.stopSession("s1")).resolves.toBe(true);
-    expect(runner.killed).toEqual(["s1"]);
-    const stop = runner.calls.find((c) => c.args[0] === "session" && c.args[1] === "stop");
-    expect(stop?.args).toEqual(["session", "stop", "s1"]);
-    expect(registry.isOwned("s1")).toBe(false);
-    expect(service.getState()).toEqual([]);
-    expect(events[events.length - 1]).toMatchObject({ type: "remove" });
-  });
-
-  it("refuses foreign sessions without touching the runner", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner();
-    const { service } = setup({ registry, runner });
-    await expect(service.stopSession("foreign")).resolves.toBe(false);
-    expect(runner.killed).toEqual([]);
-    expect(runner.calls).toEqual([]);
-  });
-
-  it("stops idempotently when the daemon already forgot the session (dead entries)", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner({ stopNotFound: true });
-    const { service, events } = setup({ registry, runner });
-    service.addSession("s1");
-    await expect(service.stopSession("s1")).resolves.toBe(true);
-    expect(registry.isOwned("s1")).toBe(false);
-    expect(events[events.length - 1]).toMatchObject({ type: "remove" });
-  });
-
-  it("returns false and keeps the entry when the stop itself fails", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner({ stopFails: true });
-    const { service } = setup({ registry, runner });
-    service.addSession("s1");
-    await expect(service.stopSession("s1")).resolves.toBe(false);
-    expect(registry.isOwned("s1")).toBe(true);
-    expect(service.getState().map((s) => s.sessionId)).toEqual(["s1"]);
-  });
-});
-
 describe("HTTP/SSE interface", () => {
   interface RecordedRoute {
     path: string;
@@ -490,45 +405,11 @@ describe("HTTP/SSE interface", () => {
     await interruptRoute?.handler(postReq, interruptRes.res as never);
     expect(JSON.parse(interruptRes.res.body())).toEqual({ interrupted: true });
 
-    // stop (POST {sessionId}): owned session stops and leaves the state
-    const stopRoute = routes.get("/bsk-observation/stop");
-    const stopRes = fakeRes();
-    await stopRoute?.handler(postReq, stopRes.res as never);
-    // The stop is async behind the response-less handler — poll the state.
-    await waitFor(() => service.getState().length === 0);
-    expect(JSON.parse(stopRes.res.body())).toEqual({ stopped: true });
-
     dispose();
     expect(routes.size).toBe(0);
     service.dispose();
   });
 
-  it("refuses a stop without a sessionId", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const { service } = setup({ registry });
-    const { routes, webServer } = routeHarness();
-    const ctx = { get: (key: string) => (key === "webServer" ? webServer : undefined) } as never;
-    const dispose = registerObservationRoutes(ctx, service);
-
-    const stopRoute = routes.get("/bsk-observation/stop");
-    const res = fakeRes();
-    const emptyReq = fakeReq({
-      method: "POST",
-      headers: { host: "127.0.0.1:3999", "content-type": "application/json" },
-      on: (event: string, fn: (chunk?: string) => void) => {
-        if (event === "data") fn("{}");
-        if (event === "end") fn();
-      },
-    });
-    await stopRoute?.handler(emptyReq, res.res as never);
-    expect(res.res.status).toBe(400);
-    expect(registry.isOwned("s1")).toBe(true);
-
-    dispose();
-    service.dispose();
-  });
-
   it("fences off non-loopback, cross-site, and simple-request traffic", async () => {
     const registry = new SessionRegistry(5);
     own(registry, "s1");

packages/vom/src/__tests__/render.test.ts

@@ -333,84 +333,6 @@ describe("renderVom single-layer page", () => {
     expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
-  it("does not treat implementation CSS classes as control names", () => {
-    const out = renderVom(
-      scene([
-        node({ id: 1, role: "RootWebArea", name: "Doc" }),
-        node({
-          id: 2,
-          parentId: 1,
-          role: "generic",
-          cursor: "pointer",
-          attrs: { onclick: "handleClick()" },
-          rect: { x: 20, y: 20, w: 40, h: 40 },
-        }),
-        node({
-          id: 3,
-          parentId: 2,
-          role: "img",
-          tag: "svg",
-          attrs: { class: "kocomz" },
-        }),
-      ]),
-    );
-
-    expect(out.text).not.toContain("kocomz");
-    expect(out.refs).toEqual([]);
-  });
-
-  it("recovers icon controls only from explicit semantic icon evidence", () => {
-    const out = renderVom(
-      scene([
-        node({ id: 1, role: "RootWebArea", name: "Doc" }),
-        node({
-          id: 2,
-          parentId: 1,
-          role: "generic",
-          cursor: "pointer",
-          attrs: { onclick: "handleFilter()" },
-          rect: { x: 20, y: 20, w: 40, h: 40 },
-        }),
-        node({
-          id: 3,
-          parentId: 2,
-          role: "img",
-          tag: "svg",
-          attrs: { "aria-label": "Filter rows", class: "kocomz" },
-        }),
-      ]),
-    );
-
-    expect(out.text).toContain('@e1 button "Filter rows"');
-    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
-  });
-
-  it("keeps a semantic image as evidence for its clickable wrapper", () => {
-    const out = renderVom(
-      scene([
-        node({ id: 1, role: "RootWebArea", name: "Doc" }),
-        node({
-          id: 2,
-          parentId: 1,
-          role: "generic",
-          cursor: "pointer",
-          rect: { x: 20, y: 20, w: 40, h: 40 },
-        }),
-        node({
-          id: 3,
-          parentId: 2,
-          role: "img",
-          name: "Account",
-          cursor: "pointer",
-          tag: "div",
-        }),
-      ]),
-    );
-
-    expect(out.text).toContain('@e1 button "Account"');
-    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
-  });
-
   it("keeps the deepest custom control when wrapper and child both look clickable", () => {
     const out = renderVom(
       scene([

packages/vom/src/index.ts

@@ -1,9 +1,4 @@
-export {
-  applyVomInteractionRecovery,
-  isVomReferenceNode,
-  isVomStructuralRole,
-  renderVom,
-} from "./render";
+export { applyVomInteractionRecovery, isVomReferenceNode, renderVom } from "./render";
 export type {
   ActiveScopeBlock,
   BlockingLayer,

packages/vom/src/render.ts

@@ -75,10 +75,6 @@ const STRUCTURAL_ROLES = new Set([
   "webarea",
 ]);
 
-export function isVomStructuralRole(role: string | undefined): boolean {
-  return STRUCTURAL_ROLES.has(role?.toLowerCase() ?? "");
-}
-
 const SENSITIVE_MASK = "•••";
 const DEFAULT_MAX_DEPTH = Number.POSITIVE_INFINITY;
 const DEFAULT_MAX_TOKENS = Number.POSITIVE_INFINITY;
@@ -197,16 +193,13 @@ function shouldRender(node: VomNode): boolean {
   const role = normalizedRole(node);
   if (SKIP_ROLES.has(role)) return false;
   if (INTERACTIVE_ROLES.has(role)) return true;
-  if (isVomStructuralRole(role)) return true;
+  if (STRUCTURAL_ROLES.has(role)) return true;
 
   return cleaned(node.name) !== undefined;
 }
 
 export function isVomReferenceNode(node: VomNode): boolean {
-  return (
-    node.referenceable !== false &&
-    (INTERACTIVE_ROLES.has(normalizedRole(node)) || isUrlBearingStructuralAction(node))
-  );
+  return INTERACTIVE_ROLES.has(normalizedRole(node)) || isUrlBearingStructuralAction(node);
 }
 
 function hasRecoveryHandler(node: VomNode): boolean {
@@ -226,30 +219,14 @@ function isContentEditable(node: VomNode): boolean {
   return contentEditable === "true" || contentEditable === "plaintext-only";
 }
 
-const ICON_REFERENCE_MARKERS = new Set(["glyph", "icon", "icons", "symbol"]);
-const ICON_REFERENCE_DECORATORS = new Set(["fill", "filled", "line", "outline", "outlined"]);
-
-function iconReferenceName(value: string | undefined): string | undefined {
-  const reference = cleaned(value);
-  if (!reference) return undefined;
-  const fragment = reference.includes("#") ? reference.slice(reference.lastIndexOf("#") + 1) : "";
-  const tokens = (fragment || reference)
-    ?.split(/[#/.\s:_-]+/)
+function iconKeyword(value: string | undefined): string | undefined {
+  const cleanedValue = cleaned(value);
+  if (!cleanedValue) return undefined;
+  const last = cleanedValue
+    .split(/[#/.\s:_-]+/)
     .filter(Boolean)
-    .map((token) => token.toLowerCase());
-  if (tokens.length === 0) return undefined;
-  if (fragment) {
-    const semanticTokens = tokens.filter(
-      (token) => !ICON_REFERENCE_MARKERS.has(token) && !ICON_REFERENCE_DECORATORS.has(token),
-    );
-    return semanticTokens.length > 0 ? semanticTokens.join(" ") : undefined;
-  }
-  const marker = tokens.findLastIndex((token) => ICON_REFERENCE_MARKERS.has(token));
-  if (marker < 0) return undefined;
-  const semanticTokens = tokens
-    .slice(marker + 1)
-    .filter((token) => !ICON_REFERENCE_DECORATORS.has(token));
-  return semanticTokens.length > 0 ? semanticTokens.join(" ") : undefined;
+    .pop();
+  return last && /^[a-z][a-z0-9_-]{1,32}$/i.test(last) ? last.toLowerCase() : undefined;
 }
 
 function iconHintFromSubtree(
@@ -261,12 +238,12 @@ function iconHintFromSubtree(
   for (const child of children.get(node.id) ?? []) {
     const attrs = child.attrs ?? {};
     const hint =
-      cleaned(attrs["aria-label"]) ??
-      cleaned(attrs.title) ??
-      (normalizedRole(child) === "img" ? cleaned(child.name) : undefined) ??
-      (["img", "svg", "use"].includes(normalizedTag(child))
-        ? (iconReferenceName(attrs.href) ?? iconReferenceName(attrs["xlink:href"]))
-        : undefined);
+      iconKeyword(attrs["aria-label"]) ??
+      iconKeyword(attrs.title) ??
+      iconKeyword(attrs.href) ??
+      iconKeyword(attrs["xlink:href"]) ??
+      iconKeyword(attrs.class) ??
+      iconKeyword(child.text);
     if (hint) return hint;
     const nested = iconHintFromSubtree(child, children, depth + 1);
     if (nested) return nested;
@@ -292,7 +269,6 @@ function recoveredRole(
   node: VomNode,
   children?: Map<number | null, VomNode[]>,
 ): string | undefined {
-  const currentRole = normalizedRole(node);
   const explicitRole = node.attrs?.role?.toLowerCase() ?? "";
   const hasHandler = hasRecoveryHandler(node);
   const focusable = isFocusable(node);
@@ -314,9 +290,7 @@ function recoveredRole(
       : "button";
   }
   if (hasHandler && hasName) return "button";
-  if ((!currentRole || SKIP_ROLES.has(currentRole)) && node.cursor === "pointer" && hasName) {
-    return "button";
-  }
+  if (node.cursor === "pointer" && hasName) return "button";
   return undefined;
 }
 

packages/vom/src/types.ts

@@ -24,8 +24,6 @@ export interface VomNode {
   backendNodeId?: number;
   frameId?: string;
   contextScopeId?: string;
-  /** False for semantic-only nodes that cannot be addressed through CDP. */
-  referenceable?: boolean;
 
   role?: string;
   name?: string;

skill/SKILL.md

@@ -206,6 +206,29 @@ Both capture from the moment the tab is attached and read a bounded per-tab buff
 | `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 |