docs(dsh-plugin): clarify package description

fix(session): cancel lifecycle RPCs cooperatively

Cargo.lock

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

Cargo.toml

@@ -36,7 +36,6 @@ 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:** August 20, 2026
+**Last updated:** May 25, 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, 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.
+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.
 
 ## 3. Data the Extension Accesses
 
@@ -26,7 +26,6 @@ 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
@@ -35,7 +34,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, saved passwords, or autofill data. It observes only the download initiated by an active `bsk download` call, not download history generally.
+- Read or transmit cookies, browsing history, bookmarks, downloads, saved passwords, or autofill data.
 - 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.
@@ -51,7 +50,6 @@ 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.
 
@@ -63,7 +61,6 @@ All Extension activity stays on the user's local device. The only network traffi
 
 - The instance ID and optional label persist in `chrome.storage.local` until the user uninstalls the Extension or clears extension storage.
 - Page content, screenshots, DOM snapshots, and other observed data are returned to the local daemon in response to commands and are **not retained by the Extension**. They live only as long as the agent's tool call.
-- Upload and download bytes are staged by the local daemon in a private, session-scoped directory. Download staging is removed after it is copied to the requested destination. Upload staging is retained until the session ends so a later form submission can still read the attached file. Remaining staging is removed when the session ends or disconnects, or when the daemon next starts after a crash.
 
 ## 8. User Control
 

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

@@ -168,107 +168,6 @@ 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({
@@ -304,6 +203,55 @@ describe("ToolDispatcher", () => {
     expect(sent[0]).toEqual({ id: "r-1", result: {} });
   });
 
+  it("forwards daemon cancellation into an in-flight session stop", async () => {
+    const { transport, sent, deliver } = fakeTransport();
+    const remove = vi.fn(async () => {});
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove,
+        ensureActiveTab: vi.fn(async () => {}),
+      },
+    });
+    await sessions.start("aa11");
+    let finishDetach: () => void = () => {};
+    const detach = new Promise<void>((resolve) => {
+      finishDetach = resolve;
+    });
+    const cdp = {
+      send: vi.fn(),
+      detachSession: vi.fn(() => detach),
+      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.session_stop", { session_id: "aa11" }));
+    await vi.waitFor(() => expect(cdp.detachSession).toHaveBeenCalledWith("aa11"));
+    deliver({ id: "cancel-stop", method: "cancel", params: { rpc_id: "r-1" } });
+    await flushMicrotasks();
+    finishDetach();
+    await flushMicrotasks();
+
+    expect(sent).toContainEqual({ id: "cancel-stop", result: { cancelled: true } });
+    expect(sent).toContainEqual({
+      id: "r-1",
+      error: expect.objectContaining({ code: "cancelled" }),
+    });
+    expect(sessions.has("aa11")).toBe(true);
+    expect(remove).not.toHaveBeenCalled();
+  });
+
   it("returns not_found when stopping an unknown session", async () => {
     const { transport, sent, deliver } = fakeTransport();
     const sessions = new SessionManager({

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

@@ -1,559 +0,0 @@
-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("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

@@ -8,6 +8,7 @@ import {
   buildFrameVomScene,
   buildVomScene,
   type CdpAxNode,
+  captureVomObservation,
   handleGetHtml,
   handleObserve,
   handleScreenshot,
@@ -1329,7 +1330,7 @@ describe("buildVomScene", () => {
     expect(rendered).toContain('      @e2 textbox "验证码"');
   });
 
-  it("does not mark non-password inputs sensitive from password-like labels", () => {
+  it("marks current-password autocomplete as sensitive even for text inputs", () => {
     const axNodes: CdpAxNode[] = [
       {
         nodeId: "1",
@@ -1364,7 +1365,7 @@ describe("buildVomScene", () => {
     expect(buildVomScene(axNodes, captured).nodes[0]).toEqual(
       expect.objectContaining({
         id: 10,
-        sensitive: false,
+        sensitive: true,
       }),
     );
   });
@@ -1659,7 +1660,9 @@ describe("buildVomScene", () => {
     );
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "close"');
-    expect(rendered.refs).toEqual([{ ref: "e1", backendNodeId: 20 }]);
+    expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
+      { ref: "e1", backendNodeId: 20 },
+    ]);
   });
 
   it("does not promote a clickable container that wraps a real interactive control", () => {
@@ -1803,7 +1806,9 @@ describe("buildVomScene", () => {
     expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("generic");
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "收藏"');
-    expect(rendered.refs).toEqual([{ ref: "e1", backendNodeId: 20 }]);
+    expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
+      { ref: "e1", backendNodeId: 20 },
+    ]);
   });
 
   it("builds active scope blocks from active aria-controls relationships", () => {
@@ -2904,10 +2909,360 @@ describe("handleSnapshot", () => {
       ],
     };
   }
+
+  function secretsSnapshotReply(secrets: {
+    email: string;
+    password: string;
+    otp: string;
+    card: string;
+  }) {
+    const S = [
+      "html",
+      "body",
+      "input",
+      "position",
+      "static",
+      "pointer-events",
+      "auto",
+      "type",
+      "text",
+      "password",
+      "autocomplete",
+      "one-time-code",
+      "cc-number",
+      "value",
+      secrets.email,
+      secrets.password,
+      secrets.otp,
+      secrets.card,
+    ];
+    const i = (s: string) => S.indexOf(s);
+    const style = [i("static"), i("auto"), i("auto")];
+    return {
+      strings: S,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 1, 1],
+            nodeName: [i("html"), i("body"), i("input"), i("input"), i("input"), i("input")],
+            backendNodeId: [10, 11, 12, 13, 14, 15],
+            attributes: [
+              [],
+              [],
+              [i("type"), i("text"), i("value"), i(secrets.email)],
+              [i("type"), i("password"), i("value"), i(secrets.password)],
+              [
+                i("type"),
+                i("text"),
+                i("autocomplete"),
+                i("one-time-code"),
+                i("value"),
+                i(secrets.otp),
+              ],
+              [
+                i("type"),
+                i("text"),
+                i("autocomplete"),
+                i("cc-number"),
+                i("value"),
+                i(secrets.card),
+              ],
+            ],
+            inputValue: {
+              index: [2, 3, 4, 5],
+              value: [i(secrets.email), i(secrets.password), i(secrets.otp), i(secrets.card)],
+            },
+          },
+          layout: {
+            nodeIndex: [1, 2, 3, 4, 5],
+            styles: [style, style, style, style, style],
+            bounds: [
+              [0, 0, 1000, 800],
+              [10, 10, 200, 32],
+              [10, 50, 200, 32],
+              [10, 90, 200, 32],
+              [10, 130, 200, 32],
+            ],
+            paintOrders: [0, 1, 2, 3, 4],
+          },
+        },
+      ],
+    };
+  }
+
   const VP_METRICS = {
     cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
   };
 
+  function makeFrameAwareDeps() {
+    const strings = ["html", "body", "iframe", "button", "title", "Remote", "static", "auto"];
+    const i = (value: string) => strings.indexOf(value);
+    const styles = [i("static"), i("auto"), i("auto")];
+    const snapshot = {
+      strings,
+      documents: [
+        {
+          frameId: "main",
+          nodes: {
+            parentIndex: [-1, 0, 1],
+            nodeName: [i("html"), i("body"), i("iframe")],
+            backendNodeId: [10, 11, 12],
+            attributes: [[], [], [i("title"), i("Remote")]],
+            contentDocumentIndex: { index: [2], value: [1] },
+          },
+          layout: {
+            nodeIndex: [0, 1, 2],
+            styles: [styles, styles, styles],
+            bounds: [
+              [0, 0, 1000, 800],
+              [0, 0, 1000, 800],
+              [100, 100, 400, 300],
+            ],
+            paintOrders: [0, 0, 1],
+          },
+        },
+        {
+          frameId: "child",
+          nodes: {
+            parentIndex: [-1, 0, 1],
+            nodeName: [i("html"), i("body"), i("button")],
+            backendNodeId: [20, 21, 22],
+            attributes: [[], [], []],
+          },
+          layout: {
+            nodeIndex: [0, 1, 2],
+            styles: [styles, styles, styles],
+            bounds: [
+              [0, 0, 400, 300],
+              [0, 0, 400, 300],
+              [20, 30, 120, 40],
+            ],
+            paintOrders: [0, 0, 1],
+          },
+        },
+      ],
+    };
+    const mainAx: CdpAxNode[] = [
+      {
+        nodeId: "main-root",
+        role: { type: "role", value: "RootWebArea" },
+        backendDOMNodeId: 11,
+        childIds: ["frame-owner"],
+      },
+      {
+        nodeId: "frame-owner",
+        parentId: "main-root",
+        role: { type: "role", value: "Iframe" },
+        name: { type: "computedString", value: "Remote" },
+        backendDOMNodeId: 12,
+      },
+    ];
+    const childAx: CdpAxNode[] = [
+      {
+        nodeId: "child-root",
+        role: { type: "role", value: "RootWebArea" },
+        backendDOMNodeId: 21,
+        childIds: ["child-button"],
+      },
+      {
+        nodeId: "child-button",
+        parentId: "child-root",
+        role: { type: "role", value: "button" },
+        name: { type: "computedString", value: "Frame action" },
+        backendDOMNodeId: 22,
+      },
+    ];
+    const send = vi.fn(async (_tabId: number, method: string) => {
+      if (method === "Page.getLayoutMetrics") return VP_METRICS;
+      if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "Accessibility.getFullAXTree") return { nodes: mainAx };
+      throw new Error(`unexpected root CDP method ${method}`);
+    });
+    const sendToTarget = vi.fn(async (_target, method: string) => {
+      if (method === "Accessibility.enable") return {};
+      if (method === "Accessibility.getFullAXTree") return { nodes: childAx };
+      throw new Error(`unexpected child CDP method ${method}`);
+    });
+    const cdp = {
+      send: send as unknown as CdpRunner["send"],
+      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 12,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+      trackSessionTab: vi.fn(),
+    } satisfies CdpRunner;
+    return {
+      cdp,
+      tabsApi: {
+        get: vi.fn(
+          async (tabId: number) => ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
+        ),
+        query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+      },
+    };
+  }
+
+  it("exposes the frame-aware observation result for recording", async () => {
+    const ax: CdpAxNode[] = [
+      {
+        nodeId: "root",
+        role: { type: "role", value: "RootWebArea" },
+        backendDOMNodeId: 11,
+        childIds: ["password"],
+      },
+      {
+        nodeId: "password",
+        parentId: "root",
+        role: { type: "role", value: "textbox" },
+        name: { type: "computedString", value: "Password" },
+        value: { value: "hunter2" },
+        backendDOMNodeId: 13,
+      },
+    ];
+    const deps = makeOverlayDeps(ax, loginSnapshotReply(), VP_METRICS);
+
+    const result = await captureVomObservation(deps.cdp, 4, "https://example.com", {
+      redactValues: true,
+    });
+
+    expect(result.text).not.toContain("hunter2");
+    expect(result.text).toContain("•••");
+    expect(result.refs[0]).toMatchObject({
+      backendNodeId: 13,
+      role: "textbox",
+      name: "Password",
+      line: expect.any(Number),
+    });
+    expect(result.rootFrameId).toBe("root");
+    expect(result).not.toHaveProperty("frameDocuments");
+    expect(result.frames).toEqual([{ frameId: "root", target: { tabId: 4 } }]);
+    expect(result.matchNodes.find((node) => node.backendNodeId === 13)).toMatchObject({
+      frameId: "root",
+      backendNodeId: 13,
+      tag: "input",
+      rect: { x: 400, y: 300, w: 200, h: 40 },
+      localRect: { x: 400, y: 300, w: 200, h: 40 },
+    });
+  });
+
+  it("does not leak form secrets through the record-safe observation payload", async () => {
+    const secrets = {
+      email: "user@example.com",
+      password: "hunter2",
+      otp: "847291",
+      card: "4111111111111111",
+    };
+    const ax: CdpAxNode[] = [
+      {
+        nodeId: "root",
+        role: { type: "role", value: "RootWebArea" },
+        backendDOMNodeId: 11,
+        childIds: ["email", "password", "otp", "card"],
+      },
+      {
+        nodeId: "email",
+        parentId: "root",
+        role: { type: "role", value: "textbox" },
+        name: { type: "computedString", value: "Email" },
+        value: { value: secrets.email },
+        backendDOMNodeId: 12,
+      },
+      {
+        nodeId: "password",
+        parentId: "root",
+        role: { type: "role", value: "textbox" },
+        name: { type: "computedString", value: "Password" },
+        value: { value: secrets.password },
+        backendDOMNodeId: 13,
+      },
+      {
+        nodeId: "otp",
+        parentId: "root",
+        role: { type: "role", value: "textbox" },
+        name: { type: "computedString", value: "Code" },
+        value: { value: secrets.otp },
+        backendDOMNodeId: 14,
+      },
+      {
+        nodeId: "card",
+        parentId: "root",
+        role: { type: "role", value: "textbox" },
+        name: { type: "computedString", value: "Card" },
+        value: { value: secrets.card },
+        backendDOMNodeId: 15,
+      },
+    ];
+    const deps = makeOverlayDeps(ax, secretsSnapshotReply(secrets), VP_METRICS);
+
+    const result = await captureVomObservation(deps.cdp, 4, "https://example.com", {
+      redactValues: true,
+    });
+    const dumped = JSON.stringify(result);
+
+    expect(result).not.toHaveProperty("frameDocuments");
+    expect(dumped).not.toContain(secrets.email);
+    expect(dumped).not.toContain(secrets.password);
+    expect(dumped).not.toContain(secrets.otp);
+    expect(dumped).not.toContain(secrets.card);
+    expect(dumped).not.toContain("formValue");
+    expect(dumped).not.toContain("formDefaultValue");
+    expect(dumped).not.toContain("axNodes");
+    expect(dumped).not.toContain("domNodes");
+    expect(dumped).not.toContain("attrs");
+    expect(result.text).toContain("•••");
+  });
+
+  it("keeps frames and rendered refs on the same frame identity", async () => {
+    const deps = makeFrameAwareDeps();
+
+    const result = await captureVomObservation(deps.cdp, 4, "https://example.com");
+
+    expect(result.rootFrameId).toBe("main");
+    expect(result.frames).toHaveLength(2);
+    expect(result.frames.find((frame) => frame.frameId === "child")).toEqual({
+      frameId: "child",
+      parentFrameId: "main",
+      ownerBackendNodeId: 12,
+      target: { tabId: 4, sessionId: "child-session" },
+    });
+    expect(result.matchNodes.find((node) => node.backendNodeId === 22)).toMatchObject({
+      frameId: "child",
+      tag: "button",
+      localRect: { x: 20, y: 30, w: 120, h: 40 },
+    });
+    expect(result.refs.find((ref) => ref.backendNodeId === 22)).toMatchObject({
+      frameId: "child",
+      name: "Frame action",
+    });
+  });
+
+  it("stores iframe refs with their owning CDP session", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    const deps = makeFrameAwareDeps();
+
+    const result = await handleSnapshot(sm, { session_id: "aa11" }, deps);
+
+    if ("code" in result) throw new Error(`unexpected error: ${JSON.stringify(result)}`);
+    expect(result.text).toContain('@e1 button "Frame action"');
+    const frameRef = [...ctx.refStore.entries()].find(([, entry]) => entry.backendNodeId === 22);
+    expect(frameRef?.[1]).toMatchObject({
+      tabId: 4,
+      frameId: "child",
+      cdpSessionId: "child-session",
+    });
+  });
+
   it("renders a blocking login overlay as the focused top layer", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     await sm.start("aa11");

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

@@ -66,6 +66,52 @@ function makeApis(
 }
 
 describe("handleSessionStop with auto-return", () => {
+  it("leaves the session untouched when cancellation arrived before teardown", async () => {
+    const aw = fakeAgentWindow([100]);
+    const sm = new SessionManager({ agentWindow: aw });
+    await sm.start("aa11");
+    const cdp = { detachSession: vi.fn(async () => {}) };
+    const controller = new AbortController();
+    controller.abort();
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { cdp, signal: controller.signal },
+    );
+
+    expect(res).toMatchObject({ code: "cancelled" });
+    expect(sm.has("aa11")).toBe(true);
+    expect(cdp.detachSession).not.toHaveBeenCalled();
+    expect(aw.remove).not.toHaveBeenCalled();
+  });
+
+  it("does not close the Agent Window when cancellation lands during CDP detach", async () => {
+    const aw = fakeAgentWindow([100]);
+    const sm = new SessionManager({ agentWindow: aw });
+    await sm.start("aa11");
+    const controller = new AbortController();
+    let finishDetach: () => void = () => {};
+    const detach = new Promise<void>((resolve) => {
+      finishDetach = resolve;
+    });
+    const cdp = { detachSession: vi.fn(() => detach) };
+
+    const stopping = handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { cdp, signal: controller.signal },
+    );
+    await vi.waitFor(() => expect(cdp.detachSession).toHaveBeenCalledWith("aa11"));
+    controller.abort();
+    finishDetach();
+
+    const res = await stopping;
+    expect(res).toMatchObject({ code: "cancelled" });
+    expect(sm.has("aa11")).toBe(true);
+    expect(aw.remove).not.toHaveBeenCalled();
+  });
+
   it("returns every borrowed tab and closes the Agent Window in the right order", async () => {
     const aw = fakeAgentWindow([100]);
     const sm = new SessionManager({ agentWindow: aw });

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

@@ -0,0 +1,9 @@
+export {
+  type CaptureVomObservationOptions,
+  captureVomObservation,
+} from "./observation";
+export {
+  type CaptureVomFrame,
+  type CaptureVomMatchNode,
+  type CaptureVomObservationResult,
+} from "./vom/record-safe-observation";

apps/extension/src/tools/dispatcher.ts

@@ -4,7 +4,6 @@ import type { Transport } from "@/transport/transport";
 import type {
   ClickParams,
   ConsoleParams,
-  DownloadParams,
   EmulateParams,
   EvaluateParams,
   FillParams,
@@ -29,12 +28,10 @@ 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";
@@ -77,7 +74,6 @@ import {
   type TabReturnParams,
   type TabSelectParams,
 } from "./tabs";
-import { handleUpload } from "./upload";
 import { handleWaitForNavigation } from "./waits";
 import { handleWindowResize, type WindowResizeParams } from "./window";
 
@@ -294,6 +290,7 @@ export class ToolDispatcher {
         await this.releaseHoverLatch((req.params as SessionStopParams).session_id);
         return handleSessionStop(this.sessions, req.params as SessionStopParams, {
           cdp: this.cdp,
+          signal,
         });
       }
       case "tool.tab_list":
@@ -508,40 +505,6 @@ 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,
@@ -759,8 +722,6 @@ 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

@@ -1,349 +0,0 @@
-// 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" } : {}),
-  });
-}
-
-export async function captureBrowserDownload(
-  options: DownloadCaptureOptions,
-): Promise<DownloadCaptureResult | RpcError> {
-  let click: ClickResult | undefined;
-  let intent: DownloadIntent | undefined;
-  let capturedId: number | undefined;
-  let capturedItem: chrome.downloads.DownloadItem | 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;
-    capturedItem = item;
-    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;
-    capturedItem = candidate.item;
-    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;
-    capturedItem = item;
-    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;
-        capturedItem = item;
-        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) {
-      const item = capturedItem ?? createdItems.get(capturedId);
-      try {
-        if (item?.state === "complete") {
-          await options.downloads.removeFile(capturedId);
-        } else {
-          await options.downloads.cancel(capturedId);
-        }
-      } catch {
-        if (failureResult?.data) failureResult.data.cleanup_state = "failed";
-      }
-    }
-  }
-}

apps/extension/src/tools/download.ts

@@ -1,64 +0,0 @@
-// 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,23 +2,10 @@
 // rendering. Extension handlers attach reasons here; human-facing copy
 // lives in bsk-cli `render_error.rs`.
 
-import type {
-  ErrorCode,
-  RpcError,
-  RpcErrorData,
-  RpcErrorReason,
-  TransferCleanupState,
-  TransferEffectState,
-} from "@/transport/types";
+import type { ErrorCode, RpcError, RpcErrorData, RpcErrorReason } from "@/transport/types";
 
 export type { RpcErrorData, RpcErrorReason };
 
-export interface TransferErrorOptions {
-  effectState: TransferEffectState;
-  phase: string;
-  cleanupState?: TransferCleanupState;
-}
-
 export function rpcError(
   code: ErrorCode,
   reason: RpcErrorReason,
@@ -28,16 +15,3 @@ 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

@@ -1,484 +0,0 @@
-// 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,7 +40,6 @@ import {
   enforceAgentWindow,
   isRpcError,
   lookupSession,
-  type ResolvedTargetTab,
   resolveTargetTab,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
@@ -57,15 +56,6 @@ 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;
 
@@ -138,7 +128,7 @@ async function wait(ms: number, signal?: AbortSignal): Promise<void> {
  * `RpcError` if the caller supplied neither (or both), or if neither
  * lookup matched.
  */
-export async function resolveBackendNode(
+async function resolveBackendNode(
   cdp: CdpRunner,
   ctx: SessionContext,
   target: { tabId: number },
@@ -225,17 +215,6 @@ export 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
 // ---------------------------------------------------------------------------
@@ -254,20 +233,11 @@ export async function handleClick(
   if (isRpcError(target)) return target;
   const denied = enforceAgentWindow(ctx, target, "click");
   if (denied) return denied;
-  const resolved = await resolveActionTarget(deps.cdp, ctx, target, params, "click");
-  if (isRpcError(resolved)) return resolved;
-  return clickResolvedTarget(ctx, resolved, params, deps);
-}
-
-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);
 
+  const node = await resolveBackendNode(deps.cdp, ctx, target, params, "click");
+  if (isRpcError(node)) return node;
+
   if (throwIfAborted(deps.signal)) {
     return { code: "cancelled", message: "click aborted" };
   }
@@ -277,9 +247,9 @@ export async function clickResolvedTarget(
     deps.cdp,
     target.tabId,
     {
-      target: resolved.cdpTarget,
-      backendNodeId: resolved.backendNodeId,
-      ...(resolved.frameId ? { frameId: resolved.frameId } : {}),
+      target: node.cdpTarget,
+      backendNodeId: node.backendNodeId,
+      ...(node.frameId ? { frameId: node.frameId } : {}),
     },
     { scrollIntoView: true },
   );
@@ -367,8 +337,8 @@ export async function clickResolvedTarget(
 
   return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
     tab_id: target.tabId,
-    used_ref: resolved.usedRef,
-    used_selector: resolved.usedSelector,
+    used_ref: node.usedRef,
+    used_selector: node.usedSelector,
     x: centre.x,
     y: centre.y,
   });

apps/extension/src/tools/observation.ts

@@ -10,6 +10,7 @@ import {
   isVomReferenceNode,
   renderVom,
   type VomNode,
+  type VomOptions,
   type VomScene,
 } from "@browser-skill/vom";
 import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
@@ -53,6 +54,10 @@ import {
   collectOverlayExcludedBackendIds,
 } from "./vom/capture";
 import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
+import {
+  type CaptureVomObservationResult,
+  projectRecordSafeObservation,
+} from "./vom/record-safe-observation";
 
 // ---------------------------------------------------------------------------
 // Shared helpers (legacy aliases — observation.ts kept exporting these
@@ -411,7 +416,15 @@ function isModalSignal(
 
 function isSensitive(capturedNode: CapturedNode | undefined): boolean {
   const attrs = capturedNode?.attrs ?? {};
-  return (attrs.type ?? "").toLowerCase() === "password";
+  const type = (attrs.type ?? "").toLowerCase();
+  if (type === "password") return true;
+  const autocomplete = (attrs.autocomplete ?? "").toLowerCase();
+  return (
+    autocomplete.startsWith("cc-") ||
+    autocomplete === "one-time-code" ||
+    autocomplete === "current-password" ||
+    autocomplete === "new-password"
+  );
 }
 
 interface AxNodeSignals {
@@ -461,7 +474,13 @@ const AX_TEXT_STOP_ROLES = new Set([
   "columnheader",
   "rowheader",
 ]);
-const SENSITIVE_AX_INPUT_TYPES = new Set(["password", "credit-card"]);
+const SENSITIVE_AX_INPUT_TYPES = new Set([
+  "password",
+  "credit-card",
+  "one-time-code",
+  "current-password",
+  "new-password",
+]);
 
 function axPropertyString(axNode: CdpAxNode, name: string): string | undefined {
   const prop = axNode.properties?.find((item) => item.name === name);
@@ -1537,14 +1556,13 @@ async function fallbackCapturedViewModel(
   try {
     const metrics = await cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
     throwIfAborted(signal, "observation");
-    const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
+    const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
     viewport = {
-      width: vpSrc.clientWidth ?? 0,
-      height: vpSrc.clientHeight ?? 0,
+      width: source.clientWidth ?? 0,
+      height: source.clientHeight ?? 0,
     };
-  } catch (err) {
-    if (isAbortError(err)) throw err;
-    // viewport stays zero-sized
+  } catch (error) {
+    if (isAbortError(error)) throw error;
   }
   const excludedBackendNodeIds = await collectOverlayExcludedBackendIds(cdp, tabId, signal);
   throwIfAborted(signal, "observation");
@@ -1554,22 +1572,58 @@ async function fallbackCapturedViewModel(
 async function captureForVom(
   cdp: CdpRunner,
   tabId: number,
-  conditionalSurfaceProbe: boolean,
-  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>,
-  signal?: AbortSignal,
+  options: CaptureVomObservationOptions,
 ): Promise<CapturedViewModel> {
   try {
     return await captureViewModel(cdp, tabId, {
-      conditionalSurfaceProbe,
-      hoverProbeBypassOverlay,
-      signal,
+      conditionalSurfaceProbe: options.conditionalSurfaceProbe ?? false,
+      hoverProbeBypassOverlay: options.hoverProbeBypassOverlay,
+      signal: options.signal,
     });
-  } catch (err) {
-    if (isAbortError(err)) throw err;
-    return fallbackCapturedViewModel(cdp, tabId, signal);
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    return fallbackCapturedViewModel(cdp, tabId, options.signal);
   }
 }
 
+export interface CaptureVomObservationOptions extends VomOptions {
+  conditionalSurfaceProbe?: boolean;
+  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
+  signal?: AbortSignal;
+}
+
+export async function captureVomObservation(
+  cdp: CdpRunner,
+  tabId: number,
+  url: string | undefined,
+  options: CaptureVomObservationOptions = {},
+): Promise<CaptureVomObservationResult> {
+  throwIfAborted(options.signal, "observation");
+  await cdp.ensureAttachedToUrl?.(tabId, url);
+  throwIfAborted(options.signal, "observation");
+  const captured = await captureForVom(cdp, tabId, options);
+  throwIfAborted(options.signal, "observation");
+  const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
+  throwIfAborted(options.signal, "observation");
+  const scene =
+    captured.rootFrameId && captured.frameNodes?.size
+      ? buildFrameVomScene(documents, captured, { pageUrl: url })
+      : buildVomScene(documents[0]?.axNodes ?? [], captured, { pageUrl: url });
+  const rendered = renderVom(scene, {
+    maxDepth: options.maxDepth,
+    maxTokens: options.maxTokens,
+    redactValues: options.redactValues,
+    activeRegionPolicy: options.activeRegionPolicy,
+  });
+  throwIfAborted(options.signal, "observation");
+  return projectRecordSafeObservation({
+    rootFrameId: captured.rootFrameId ?? documents[0]?.frameId ?? "root",
+    frameDocuments: documents,
+    rendered,
+    surfaceProbes: captured.surfaceProbes,
+  });
+}
+
 async function handleVomObservation(
   manager: SessionManager,
   params: SnapshotParams | ObserveParams,
@@ -1599,40 +1653,22 @@ async function handleVomObservation(
   try {
     throwIfAborted(signal, toolName);
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await deps.cdp.ensureAttachedToUrl?.(target.tabId, target.url);
-    throwIfAborted(signal, toolName);
     const effectiveConditionalSurfaceProbe =
       deps.conditionalSurfaceProbe ?? conditionalSurfaceProbe;
-    const captured = await captureForVom(
-      deps.cdp,
-      target.tabId,
-      effectiveConditionalSurfaceProbe,
-      deps.hoverProbeBypassOverlay,
-      signal,
-    );
-    throwIfAborted(signal, toolName);
-    const frameDocuments = await captureFrameData<CdpAxNode>(
-      deps.cdp,
-      target.tabId,
-      captured,
-      signal,
-    );
-    throwIfAborted(signal, toolName);
-    const scene =
-      captured.rootFrameId && captured.frameNodes?.size
-        ? buildFrameVomScene(frameDocuments, captured, { pageUrl: target.url })
-        : buildVomScene(frameDocuments[0]?.axNodes ?? [], captured, { pageUrl: target.url });
-    const rendered = renderVom(scene, {
+    const observation = await captureVomObservation(deps.cdp, target.tabId, target.url, {
       maxDepth: params.max_depth,
       maxTokens: params.max_tokens,
       activeRegionPolicy: true,
+      conditionalSurfaceProbe: effectiveConditionalSurfaceProbe,
+      hoverProbeBypassOverlay: deps.hoverProbeBypassOverlay,
+      signal,
     });
     throwIfAborted(signal, toolName);
     const targetByFrameId = new Map(
-      frameDocuments.map((document) => [document.frameId, document.target]),
+      observation.frames.map((frame) => [frame.frameId, frame.target]),
     );
     ctx.refStore.replace(
-      rendered.refs.map((ref) => {
+      observation.refs.map((ref) => {
         const refTarget = ref.frameId ? targetByFrameId.get(ref.frameId) : undefined;
         return [
           ref.ref,
@@ -1646,14 +1682,14 @@ async function handleVomObservation(
       }),
     );
     return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
-      text: rendered.text,
-      ref_count: rendered.refs.length,
+      text: observation.text,
+      ref_count: observation.refs.length,
       tab_id: target.tabId,
-      truncated: rendered.truncated,
+      truncated: observation.truncated,
       ...(toolName === "observe" && (params as ObserveParams).debug_surfaces
         ? {
             debug: {
-              surface_probes: (captured.surfaceProbes ?? []).map((probe) => ({
+              surface_probes: (observation.surfaceProbes ?? []).map((probe) => ({
                 trigger_backend_node_id: probe.triggerBackendNodeId,
                 ...(probe.triggerPoint ? { trigger_point: probe.triggerPoint } : {}),
                 trigger_action: probe.triggerAction,

apps/extension/src/tools/session.ts

@@ -76,6 +76,7 @@ export interface SessionStopResult {
 }
 
 export interface SessionStopDeps {
+  signal?: AbortSignal;
   cdp?: {
     detachSession(sessionId: string): Promise<void>;
   };
@@ -177,6 +178,9 @@ export async function handleSessionStop(
       message: `session ${params.session_id} unknown`,
     };
   }
+  if (deps.signal?.aborted) {
+    return { code: "cancelled", message: "session_stop aborted before teardown" };
+  }
 
   // Step 1: auto-return borrowed tabs. Iterate over a snapshot of the
   // ids so deletions during iteration do not break the Map iterator.
@@ -187,6 +191,7 @@ export async function handleSessionStop(
     try {
       const tabManagement = {
         ...(deps.tabManagement ?? {}),
+        signal: deps.signal,
         isAgentWindowId:
           deps.tabManagement?.isAgentWindowId ??
           ((windowId: number) => manager.findByWindowId(windowId) !== null),
@@ -214,6 +219,17 @@ export async function handleSessionStop(
     }
   }
 
+  if (deps.signal?.aborted) {
+    const nonCancelFailures = returnFailures?.filter((failure) => failure.code !== "cancelled");
+    if (nonCancelFailures && nonCancelFailures.length > 0) {
+      return {
+        ...(returnedTabIds.length > 0 ? { returned_tab_ids: returnedTabIds } : {}),
+        return_failures: nonCancelFailures,
+      };
+    }
+    return { code: "cancelled", message: "session_stop aborted during tab return" };
+  }
+
   const result: SessionStopResult = {};
   if (returnedTabIds.length > 0) result.returned_tab_ids = returnedTabIds;
   if (returnFailures && returnFailures.length > 0) {
@@ -233,6 +249,10 @@ export async function handleSessionStop(
   // Step 3: detach CDP sessions this session opened (no-op if none).
   await deps.cdp?.detachSession(params.session_id);
 
+  if (deps.signal?.aborted) {
+    return { code: "cancelled", message: "session_stop aborted before window close" };
+  }
+
   // Step 4: close the Agent Window and drop the context.
   await manager.stop(params.session_id);
 

apps/extension/src/tools/shared.ts

@@ -53,7 +53,6 @@ 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

@@ -1,59 +0,0 @@
-// 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/frame-document.ts

@@ -77,9 +77,12 @@ export function buildFrameDocuments<T extends FrameOwnedAxNode>(
 ): FrameDocument<T>[] {
   const frames = frameList(graph, batches, captured);
   const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
+  const rootFrameId = graph?.rootFrameId ?? captured.rootFrameId ?? frames[0]?.frameId;
+  const domNodesForFrame = (frameId: string): CapturedNode[] =>
+    captured.frameNodes?.get(frameId) ?? (frameId === rootFrameId ? captured.nodes : []);
   const backendOwner = new Map<string, string>();
   for (const frame of frames) {
-    for (const node of captured.frameNodes?.get(frame.frameId) ?? []) {
+    for (const node of domNodesForFrame(frame.frameId)) {
       backendOwner.set(targetBackendKey(frame.target, node.backendNodeId), frame.frameId);
     }
   }
@@ -165,6 +168,6 @@ export function buildFrameDocuments<T extends FrameOwnedAxNode>(
     ...frame,
     contextScopeId: frame.frameId,
     axNodes: axNodesByFrame.get(frame.frameId) ?? [],
-    domNodes: captured.frameNodes?.get(frame.frameId) ?? [],
+    domNodes: domNodesForFrame(frame.frameId),
   }));
 }

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

@@ -0,0 +1,77 @@
+import type { Rect, RenderedRef, VomResult } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CapturedSurfaceProbe } from "./capture";
+import type { CapturedFrameDocument, FrameAxNode } from "./frame-capture";
+
+/** Frame identity needed to resolve an `@eN` that lives in an iframe. */
+export interface CaptureVomFrame {
+  frameId: string;
+  target: CdpTarget;
+  parentFrameId?: string;
+  ownerBackendNodeId?: number;
+}
+
+/** Allowlisted geometry used to match a recorded action to a rendered ref. */
+export interface CaptureVomMatchNode {
+  frameId: string;
+  backendNodeId: number;
+  tag: string;
+  /** Top-level viewport-relative geometry. */
+  rect: Rect | null;
+  /** Frame-local viewport-relative geometry, when available. */
+  localRect?: Rect | null;
+}
+
+/**
+ * Raw AX/DOM trees are never returned. When `redactValues` is enabled by the
+ * caller, form values in `text` are masked as well.
+ */
+export interface CaptureVomObservationResult {
+  text: string;
+  refs: RenderedRef[];
+  truncated: boolean;
+  rootFrameId: string;
+  frames: CaptureVomFrame[];
+  matchNodes: CaptureVomMatchNode[];
+  surfaceProbes?: CapturedSurfaceProbe[];
+}
+
+function projectFrames(documents: CapturedFrameDocument<FrameAxNode>[]): CaptureVomFrame[] {
+  return documents.map((document) => ({
+    frameId: document.frameId,
+    target: document.target,
+    ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
+    ...(document.ownerBackendNodeId !== undefined
+      ? { ownerBackendNodeId: document.ownerBackendNodeId }
+      : {}),
+  }));
+}
+
+function projectMatchNodes(documents: CapturedFrameDocument<FrameAxNode>[]): CaptureVomMatchNode[] {
+  return documents.flatMap((document) =>
+    document.domNodes.map((node) => ({
+      frameId: document.frameId,
+      backendNodeId: node.backendNodeId,
+      tag: node.tag,
+      rect: node.rect,
+      ...(node.localRect !== undefined ? { localRect: node.localRect } : {}),
+    })),
+  );
+}
+
+export function projectRecordSafeObservation(input: {
+  rootFrameId: string;
+  frameDocuments: CapturedFrameDocument<FrameAxNode>[];
+  rendered: VomResult;
+  surfaceProbes?: CapturedSurfaceProbe[];
+}): CaptureVomObservationResult {
+  return {
+    text: input.rendered.text,
+    refs: input.rendered.refs,
+    truncated: input.rendered.truncated,
+    rootFrameId: input.rootFrameId,
+    frames: projectFrames(input.frameDocuments),
+    matchNodes: projectMatchNodes(input.frameDocuments),
+    surfaceProbes: input.surfaceProbes,
+  };
+}

apps/extension/src/transport/types.ts

@@ -33,22 +33,10 @@ 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;
 }
 
@@ -512,50 +500,6 @@ 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,7 +30,6 @@ export default defineConfig({
     permissions: [
       "alarms",
       "debugger",
-      "downloads",
       "idle",
       "notifications",
       "tabs",

crates/bsk-cli/Cargo.toml

@@ -53,7 +53,6 @@ flate2 = { workspace = true }
 tar = { workspace = true }
 zip = { workspace = true }
 sha2 = { workspace = true }
-base64 = { workspace = true }
 
 [target.'cfg(unix)'.dependencies]
 nix = { workspace = true }
@@ -64,7 +63,6 @@ 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,29 +206,6 @@ 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

@@ -1,75 +0,0 @@
-//! 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

@@ -1,147 +0,0 @@
-//! `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)
 }
 
-pub(crate) fn split_target(
+fn split_target(
     positional: Option<String>,
     explicit_ref: Option<String>,
     explicit_selector: Option<String>,

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

@@ -2,7 +2,6 @@
 
 use std::time::Duration;
 
-mod atomic_output;
 pub mod browser_wait;
 pub mod browsers;
 pub mod business_rpc;
@@ -10,7 +9,6 @@ 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;
@@ -32,7 +30,6 @@ pub mod snapshot;
 pub mod status;
 pub mod tab;
 pub mod update;
-pub mod upload;
 pub mod waits;
 pub mod window;
 
@@ -40,7 +37,6 @@ 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;
@@ -56,7 +52,6 @@ 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;
 
@@ -181,12 +176,6 @@ 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,12 +49,6 @@ 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;
 }
 
@@ -202,20 +196,6 @@ 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(
@@ -289,36 +269,6 @@ 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,
     }
 }
@@ -442,38 +392,6 @@ 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

@@ -1,185 +0,0 @@
-//! `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

@@ -1,728 +0,0 @@
-//! 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,8 +27,7 @@ use bsk_protocol::system::{
     VersionSkewEntry,
 };
 use bsk_protocol::tools::{
-    DownloadParams, DownloadResult, HelpOutcome, RequestHelpResult, ReturnFailure,
-    TransferBeginParams, TransferIdParams, UploadParams, WaitMsParams, WaitMsResult,
+    HelpOutcome, RequestHelpResult, ReturnFailure, WaitMsParams, WaitMsResult,
 };
 use bsk_protocol::{
     CancelParams, CancelResult, ErrorCode, Method, PingResult, ResponseBody, RpcError, RpcId,
@@ -62,10 +61,6 @@ 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
@@ -211,15 +206,15 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
                     Ok(v) => ResponseBody::Ok(v),
                     Err(e) => ResponseBody::Err(e),
                 },
-                Method::SessionStart => match handle_session_start(&state, params).await {
+                Method::SessionStart => match handle_session_start(&state, rpc_id, params).await {
                     Ok(v) => ResponseBody::Ok(v),
                     Err(e) => ResponseBody::Err(e),
                 },
-                Method::SessionStop => match handle_session_stop(&state, params).await {
+                Method::SessionStop => match handle_session_stop(&state, rpc_id, params).await {
                     Ok(v) => ResponseBody::Ok(v),
                     Err(e) => ResponseBody::Err(e),
                 },
-                Method::SessionStopAll => match handle_session_stop_all(&state).await {
+                Method::SessionStopAll => match handle_session_stop_all_rpc(&state, rpc_id).await {
                     Ok(v) => ResponseBody::Ok(v),
                     Err(e) => ResponseBody::Err(e),
                 },
@@ -228,11 +223,6 @@ 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
@@ -256,8 +246,6 @@ 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
@@ -336,7 +324,7 @@ async fn handle_tool_dispatch(
             data: None,
         });
     }
-    let timeout = match tool_dispatch_transport_timeout(&method, &params) {
+    let timeout = match tool_dispatch_timeout(&params) {
         Ok(timeout) => timeout,
         Err(err) => return ResponseBody::Err(err),
     };
@@ -350,180 +338,24 @@ 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.clone(), params, timeout, Some(entry))
+            .dispatch_unlocked(&session_id, method, params, timeout, Some(entry))
             .await
     } else {
         state
             .tool_queues
-            .dispatch(&session_id, method.clone(), params, timeout, Some(entry))
+            .dispatch(&session_id, method, 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) => {
-            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,
+        Err(err) => ResponseBody::Err(err.into_rpc()),
     }
 }
 
@@ -602,8 +434,9 @@ async fn handle_wait_ms(
 /// cancellation surfaces (M10.2 + review C2):
 ///
 /// 1. [`AbortRegistry`] — answers daemon-local cancellable runners
-///    (currently `tool.wait_ms`). If a token is registered we trip it
-///    and stop.
+///    (`tool.wait_ms` and `session.*` lifecycle calls). If a token is
+///    registered we trip it and stop. Lifecycle handlers forward their
+///    own WS cancel after preserving request-before-cancel ordering.
 /// 2. [`super::inflight::ToolInflightRegistry`] — every IPC-tracked
 ///    `tool.*` RPC, registered the moment the IPC handler accepts the
 ///    request. Trips the entry's cancel token regardless of whether
@@ -700,16 +533,6 @@ 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
@@ -812,7 +635,20 @@ fn clamp_browser_wait(wait_ms: Option<u64>) -> Option<Duration> {
     ))
 }
 
-async fn handle_session_start(state: &Arc<DaemonState>, params: Value) -> Result<Value, RpcError> {
+async fn handle_session_start(
+    state: &Arc<DaemonState>,
+    rpc_id: RpcId,
+    params: Value,
+) -> Result<Value, RpcError> {
+    let abort_guard = state
+        .abort_registry
+        .register(rpc_id)
+        .map_err(|err| RpcError {
+            code: ErrorCode::ProtocolError,
+            message: format!("session.start cancellation registration failed: {err:?}"),
+            data: None,
+        })?;
+    let cancel = abort_guard.token().clone();
     let params: CliSessionStartParams = if params.is_null() {
         CliSessionStartParams {
             browser_instance_id: None,
@@ -851,6 +687,7 @@ async fn handle_session_start(state: &Arc<DaemonState>, params: Value) -> Result
         },
         state.config.extension_connect_wait,
         DEFAULT_RPC_TIMEOUT,
+        Some(cancel),
     )
     .await
     {
@@ -874,6 +711,8 @@ fn map_start_error(err: StartSessionError) -> RpcError {
         StartSessionError::AmbiguousBrowserLabel { .. } => ErrorCode::InvalidParams,
         StartSessionError::IdExhausted => ErrorCode::ProtocolError,
         StartSessionError::Timeout => ErrorCode::Timeout,
+        StartSessionError::Cancelled => ErrorCode::Cancelled,
+        StartSessionError::CleanupFailed { .. } => ErrorCode::ProtocolError,
         StartSessionError::TransportClosed => ErrorCode::ProtocolError,
         StartSessionError::ExtensionError(inner) => inner.code,
     };
@@ -889,6 +728,16 @@ fn map_start_error(err: StartSessionError) -> RpcError {
             "label": label,
             "instance_ids": instance_ids,
         })),
+        StartSessionError::CleanupFailed {
+            session_id,
+            agent_window_id,
+            ..
+        } => Some(serde_json::json!({
+            "reason": "cleanup_failed",
+            "session_id": session_id.0,
+            "agent_window_id": agent_window_id,
+        })),
+        StartSessionError::ExtensionError(inner) => inner.data.clone(),
         _ => None,
     };
     RpcError {
@@ -898,7 +747,20 @@ fn map_start_error(err: StartSessionError) -> RpcError {
     }
 }
 
-async fn handle_session_stop(state: &Arc<DaemonState>, params: Value) -> Result<Value, RpcError> {
+async fn handle_session_stop(
+    state: &Arc<DaemonState>,
+    rpc_id: RpcId,
+    params: Value,
+) -> Result<Value, RpcError> {
+    let abort_guard = state
+        .abort_registry
+        .register(rpc_id)
+        .map_err(|err| RpcError {
+            code: ErrorCode::ProtocolError,
+            message: format!("session.stop cancellation registration failed: {err:?}"),
+            data: None,
+        })?;
+    let cancel = abort_guard.token().clone();
     let params: CliSessionStopParams = if params.is_null() {
         CliSessionStopParams {
             session_id: None,
@@ -912,7 +774,7 @@ async fn handle_session_stop(state: &Arc<DaemonState>, params: Value) -> Result<
         })?
     };
     if params.all {
-        return handle_session_stop_all(state).await;
+        return handle_session_stop_all(state, Some(cancel)).await;
     }
     let session_id = match params.session_id {
         Some(s) => SessionId(s),
@@ -931,11 +793,11 @@ async fn handle_session_stop(state: &Arc<DaemonState>, params: Value) -> Result<
         &state.session_interrupts,
         &session_id,
         DEFAULT_SESSION_STOP_TIMEOUT,
+        Some(cancel),
     )
     .await
     {
         Ok(stop) => {
-            state.transfers.release_session(&session_id.0);
             let result = CliSessionStopResult {
                 stopped: vec![session_id.0],
                 failed: Vec::new(),
@@ -983,7 +845,25 @@ fn map_stop_error(err: StopSessionError) -> RpcError {
     }
 }
 
-async fn handle_session_stop_all(state: &Arc<DaemonState>) -> Result<Value, RpcError> {
+async fn handle_session_stop_all_rpc(
+    state: &Arc<DaemonState>,
+    rpc_id: RpcId,
+) -> Result<Value, RpcError> {
+    let abort_guard = state
+        .abort_registry
+        .register(rpc_id)
+        .map_err(|err| RpcError {
+            code: ErrorCode::ProtocolError,
+            message: format!("session.stop_all cancellation registration failed: {err:?}"),
+            data: None,
+        })?;
+    handle_session_stop_all(state, Some(abort_guard.token().clone())).await
+}
+
+async fn handle_session_stop_all(
+    state: &Arc<DaemonState>,
+    cancel: Option<super::abort::AbortToken>,
+) -> Result<Value, RpcError> {
     let ids: Vec<SessionId> = state
         .sessions
         .snapshot()
@@ -995,6 +875,16 @@ async fn handle_session_stop_all(state: &Arc<DaemonState>) -> Result<Value, RpcE
     let mut returned_tab_ids = Vec::new();
     let mut return_failures = Vec::new();
     for id in ids {
+        if cancel
+            .as_ref()
+            .is_some_and(super::abort::AbortToken::is_cancelled)
+        {
+            return Err(RpcError {
+                code: ErrorCode::Cancelled,
+                message: "session.stop_all was cancelled".into(),
+                data: None,
+            });
+        }
         match stop_session(
             &state.browsers,
             &state.sessions,
@@ -1002,11 +892,11 @@ async fn handle_session_stop_all(state: &Arc<DaemonState>) -> Result<Value, RpcE
             &state.session_interrupts,
             &id,
             DEFAULT_SESSION_STOP_TIMEOUT,
+            cancel.clone(),
         )
         .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);
@@ -1028,6 +918,15 @@ async fn handle_session_stop_all(state: &Arc<DaemonState>) -> Result<Value, RpcE
                 returned_tab_ids.extend(stop.returned_tab_ids);
                 return_failures.extend(stop.return_failures);
             }
+            Err(err)
+                if matches!(
+                    &err,
+                    StopSessionError::ExtensionError(inner)
+                        if inner.code == ErrorCode::Cancelled
+                ) =>
+            {
+                return Err(map_stop_error(err));
+            }
             Err(err) => {
                 debug!(session = %id, ?err, "session.stop_all: failure (continuing)");
                 let rpc = map_stop_error(err);
@@ -1430,30 +1329,6 @@ 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,7 +3,6 @@
 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

@@ -43,6 +43,7 @@ use serde_json::Value;
 use tokio::sync::{mpsc, oneshot};
 use tracing::{debug, warn};
 
+use super::abort::AbortToken;
 use super::browsers::BrowserRegistry;
 use super::inflight::{PromoteOutcome, ToolInflightEntry};
 use super::sessions::{SessionId, SessionRegistry};
@@ -83,6 +84,14 @@ pub struct ToolJob {
     /// IPC request id (e.g. `session.stop`'s queued teardown call —
     /// those already carry their own bespoke retry / abort path).
     pub inflight: Option<Arc<ToolInflightEntry>>,
+    /// Cancellation token for session-lifecycle work registered in the
+    /// daemon-local abort registry. Unlike `inflight`, lifecycle callers
+    /// forward their own WS cancel after the request has been queued.
+    pub lifecycle_cancel: Option<AbortToken>,
+    /// How long cancellation keeps the worker busy while the extension
+    /// finishes compensation. Session teardown uses its full RPC budget
+    /// so daemon state is reconciled even after the CLI exits.
+    pub cancel_cleanup_timeout: Duration,
     /// Owning session — used by `ToolInflightRegistry::cancel_session`
     /// to drain queued jobs that have not yet been promoted to
     /// "forwarded". Worker callers also have access to it via the
@@ -322,6 +331,8 @@ impl ToolQueueRegistry {
             timeout,
             false,
             inflight,
+            None,
+            CANCEL_CLEANUP_TIMEOUT,
         )
         .await;
         // A long-running request may outlive the idle threshold. Touching
@@ -360,6 +371,8 @@ impl ToolQueueRegistry {
             timeout,
             respond: respond_tx,
             inflight,
+            lifecycle_cancel: None,
+            cancel_cleanup_timeout: CANCEL_CLEANUP_TIMEOUT,
             session_id: sid.clone(),
         };
         match forward_one(sid, &self.browsers, &self.sessions, &job).await {
@@ -378,6 +391,7 @@ impl ToolQueueRegistry {
         method: Method,
         params: Value,
         timeout: Duration,
+        cancel: Option<AbortToken>,
     ) -> Result<Value, DispatchError> {
         let (sender, state) = {
             let mut guard = self.queues.lock().expect("tool queue registry poisoned");
@@ -404,6 +418,8 @@ impl ToolQueueRegistry {
             timeout,
             true,
             None,
+            cancel,
+            timeout,
         )
         .await
     }
@@ -419,12 +435,9 @@ async fn dispatch_with_sender(
     timeout: Duration,
     wait_for_capacity: bool,
     inflight: Option<Arc<ToolInflightEntry>>,
+    lifecycle_cancel: Option<AbortToken>,
+    cancel_cleanup_timeout: Duration,
 ) -> Result<Value, DispatchError> {
-    let response_grace = if is_effect_aware_transfer(&method) {
-        CANCEL_CLEANUP_TIMEOUT
-    } else {
-        Duration::ZERO
-    };
     let (respond_tx, respond_rx) = oneshot::channel();
     let job = ToolJob {
         method,
@@ -432,8 +445,11 @@ async fn dispatch_with_sender(
         timeout,
         respond: respond_tx,
         inflight,
+        lifecycle_cancel,
+        cancel_cleanup_timeout,
         session_id,
     };
+    let lifecycle_cancellable = job.lifecycle_cancel.is_some();
     if wait_for_capacity {
         let waited = tokio::time::timeout(
             timeout.saturating_add(Duration::from_secs(1)),
@@ -458,13 +474,15 @@ async fn dispatch_with_sender(
             mpsc::error::TrySendError::Closed(_) => DispatchError::QueueClosed,
         });
     }
-    let waited = tokio::time::timeout(
-        timeout
-            .saturating_add(response_grace)
-            .saturating_add(Duration::from_secs(1)),
-        respond_rx,
-    )
-    .await;
+    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;
     match waited {
         Ok(Ok(Ok(v))) => Ok(v),
         Ok(Ok(Err(rpc))) => Err(DispatchError::Rpc(rpc)),
@@ -502,11 +520,17 @@ async fn forward_one(
     // / browser resolution work, and before any WS frame leaves the
     // daemon (review C2). We keep the `tokio::select!` later so
     // cancels arriving mid-WS-hop also unblock the worker.
-    if let Some(entry) = job.inflight.as_ref()
-        && entry.is_cancelled()
+    if job
+        .inflight
+        .as_ref()
+        .is_some_and(|entry| entry.is_cancelled())
+        || job
+            .lifecycle_cancel
+            .as_ref()
+            .is_some_and(AbortToken::is_cancelled)
     {
         return Err(cancelled_error(
-            Some(entry),
+            job.inflight.as_deref(),
             "tool dispatch cancelled before forwarding",
         ));
     }
@@ -570,11 +594,20 @@ async fn forward_one(
             }
         }
         None => {
-            // Daemon-internal callers (e.g. queued session.stop drain)
-            // don't carry an inflight entry; they cannot be cancelled
-            // through the IPC `cancel` surface, so a plain sink send
-            // is sufficient and keeps the existing transport-error
-            // behaviour.
+            // Daemon-internal callers do not carry a tool-inflight entry.
+            // Session lifecycle jobs instead use the abort-registry token
+            // below; other internal callers keep the plain send path.
+            if job
+                .lifecycle_cancel
+                .as_ref()
+                .is_some_and(AbortToken::is_cancelled)
+            {
+                client.pending.lock().unwrap().cancel(&rpc_id);
+                return Err(cancelled_error(
+                    None,
+                    "session lifecycle cancelled before forwarding",
+                ));
+            }
             if client.sink.send(request).is_err() {
                 client.pending.lock().unwrap().cancel(&rpc_id);
                 return Err(RpcError {
@@ -583,120 +616,92 @@ async fn forward_one(
                     data: None,
                 });
             }
-            None
+            job.lifecycle_cancel.clone()
         }
     };
-    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 forward_lifecycle_cancel = || {
+        if job.lifecycle_cancel.is_none() {
+            return;
+        }
+        let cancel = Frame::Request(RequestFrame {
+            id: format!("cancel-{rpc_id}"),
+            method: Method::Cancel,
+            params: Some(serde_json::json!({ "rpc_id": rpc_id })),
+        });
+        if let Err(err) = client.sink.send(cancel) {
+            warn!(%rpc_id, ?err, "failed to forward session lifecycle cancel");
+        }
     };
-    let deadline_cancel: Option<&(dyn Fn() -> bool + Sync)> =
-        is_effect_aware_transfer(&job.method).then_some(&send_deadline_cancel);
+    let on_abort: Option<&(dyn Fn() + Sync)> = job
+        .lifecycle_cancel
+        .as_ref()
+        .map(|_| &forward_lifecycle_cancel as &(dyn Fn() + Sync));
     let waited = await_with_optional_cancel(
         job.timeout,
-        CANCEL_CLEANUP_TIMEOUT,
+        job.cancel_cleanup_timeout,
         waiter,
         cancel_token.as_ref(),
-        deadline_cancel,
+        on_abort,
     )
     .await;
     let response = match waited {
         WaitOutcome::Response(resp) => resp,
         WaitOutcome::CancelledAfterResponse(resp) => {
-            // 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",
-                ));
+            if job.method == Method::ToolSessionStop
+                && 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);
             }
-        }
-        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,
-                ));
+            // 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);
             }
-            return Err(RpcError {
-                code: ErrorCode::Timeout,
-                message: format!(
-                    "cancelled tool did not finish cleanup within {:?}",
-                    CANCEL_CLEANUP_TIMEOUT
-                ),
-                data: Some(serde_json::json!({ "reason": "cancel_cleanup_timeout" })),
-            });
+            return Err(cancelled_error(
+                job.inflight.as_deref(),
+                "tool dispatch cancelled after extension cleanup",
+            ));
         }
         WaitOutcome::TimedOutAfterResponse(resp) => match resp.body {
-            ResponseBody::Ok(value) => return Ok(value),
+            ResponseBody::Ok(value) if job.method == Method::ToolSessionStop => {
+                // The close crossed its irreversible boundary during the
+                // timeout cleanup grace. Reconcile daemon state instead of
+                // reopening a session whose window is already gone.
+                return Ok(value);
+            }
             ResponseBody::Err(err)
                 if !matches!(err.code, ErrorCode::Cancelled | ErrorCode::UserAborted) =>
             {
                 return Err(err);
             }
-            ResponseBody::Err(err) => {
-                return Err(timed_out_transfer_error(&err));
+            _ => {
+                return Err(RpcError {
+                    code: ErrorCode::Timeout,
+                    message: format!("tool RPC timed out after {:?}", job.timeout),
+                    data: None,
+                });
             }
         },
-        WaitOutcome::TimeoutCleanupFailed => {
+        WaitOutcome::CleanupTimeout => {
             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,
-            ));
+            return Err(RpcError {
+                code: ErrorCode::Timeout,
+                message: format!(
+                    "cancelled tool did not finish cleanup within {:?}",
+                    job.cancel_cleanup_timeout
+                ),
+                data: Some(serde_json::json!({ "reason": "cancel_cleanup_timeout" })),
+            });
         }
         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(),
@@ -705,14 +710,6 @@ 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),
@@ -726,65 +723,12 @@ 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),
-    CleanupTimeout,
     TimedOutAfterResponse(bsk_protocol::ResponseFrame),
-    TimeoutCleanupFailed,
+    CleanupTimeout,
     WaiterClosed,
     Timeout,
 }
@@ -794,7 +738,7 @@ async fn await_with_optional_cancel(
     cleanup_timeout: Duration,
     mut waiter: oneshot::Receiver<bsk_protocol::ResponseFrame>,
     cancel: Option<&super::abort::AbortToken>,
-    on_deadline: Option<&(dyn Fn() -> bool + Sync)>,
+    on_abort: Option<&(dyn Fn() + Sync)>,
 ) -> WaitOutcome {
     match cancel {
         Some(token) => {
@@ -806,6 +750,9 @@ async fn await_with_optional_cancel(
                 // after compensation or the cleanup deadline expires.
                 biased;
                 _ = token.cancelled() => {
+                    if let Some(on_abort) = on_abort {
+                        on_abort();
+                    }
                     match tokio::time::timeout(cleanup_timeout, &mut waiter).await {
                         Ok(Ok(resp)) => WaitOutcome::CancelledAfterResponse(resp),
                         Ok(Err(_)) => WaitOutcome::WaiterClosed,
@@ -816,31 +763,23 @@ async fn await_with_optional_cancel(
                     Ok(resp) => WaitOutcome::Response(resp),
                     Err(_) => WaitOutcome::WaiterClosed,
                 },
-                _ = &mut deadline => 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,
-                        }
+                _ = &mut deadline => {
+                    let Some(on_abort) = on_abort else {
+                        return WaitOutcome::Timeout;
+                    };
+                    on_abort();
+                    match tokio::time::timeout(cleanup_timeout, &mut waiter).await {
+                        Ok(Ok(resp)) => WaitOutcome::TimedOutAfterResponse(resp),
+                        Ok(Err(_)) => WaitOutcome::WaiterClosed,
+                        Err(_) => WaitOutcome::CleanupTimeout,
                     }
-                    Some(_) => WaitOutcome::TimeoutCleanupFailed,
-                    None => WaitOutcome::Timeout,
                 },
             }
         }
         None => match tokio::time::timeout(timeout, &mut waiter).await {
             Ok(Ok(resp)) => WaitOutcome::Response(resp),
             Ok(Err(_)) => WaitOutcome::WaiterClosed,
-            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,
-            },
+            Err(_) => WaitOutcome::Timeout,
         },
     }
 }
@@ -1015,37 +954,29 @@ mod await_with_optional_cancel_tests {
     }
 
     #[tokio::test]
-    async fn transfer_deadline_sends_cancel_and_waits_for_cleanup_response() {
+    async fn lifecycle_timeout_forwards_abort_and_waits_for_cleanup_response() {
+        use std::sync::atomic::{AtomicBool, Ordering};
+
+        let token = AbortToken::new();
         let (tx, rx) = oneshot::channel();
+        let abort_forwarded = AtomicBool::new(false);
+        let forward_abort = || abort_forwarded.store(true, Ordering::SeqCst);
         tokio::spawn(async move {
-            tokio::time::sleep(Duration::from_millis(5)).await;
+            tokio::time::sleep(Duration::from_millis(20)).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,
-            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),
+            Duration::from_millis(5),
+            Duration::from_millis(100),
             rx,
-            None,
-            Some(&send_cancel),
+            Some(&token),
+            Some(&forward_abort),
         )
         .await;
-        assert!(matches!(outcome, WaitOutcome::TimeoutCleanupFailed));
+
+        assert!(abort_forwarded.load(Ordering::SeqCst));
+        assert!(matches!(outcome, WaitOutcome::TimedOutAfterResponse(_)));
     }
 }
 
@@ -1109,6 +1040,8 @@ mod tool_job_session_id_tests {
             timeout: Duration::from_secs(1),
             respond: tx,
             inflight: None,
+            lifecycle_cancel: None,
+            cancel_cleanup_timeout: CANCEL_CLEANUP_TIMEOUT,
             session_id: SessionId("sess-A".into()),
         };
         assert_eq!(job.session_id.0, "sess-A");

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

@@ -12,13 +12,14 @@ use bsk_protocol::system::{BrowserStatusEntry, SessionStatusEntry};
 use bsk_protocol::tools::{
     SessionStartParams, SessionStartResult, SessionStopParams, SessionStopResult,
 };
-use bsk_protocol::{Frame, RequestFrame, ResponseBody, RpcError, RpcId};
+use bsk_protocol::{ErrorCode, Frame, Method, RequestFrame, ResponseBody, RpcError, RpcId};
 use rand::Rng;
 use serde::{Deserialize, Serialize};
 use tokio::time::{Duration, timeout};
 
+use super::abort::AbortToken;
 use super::browsers::{BrowserClient, BrowserId, BrowserRegistry, SelectError};
-use super::queue::{DispatchError, ToolQueueRegistry};
+use super::queue::{CANCEL_CLEANUP_TIMEOUT, DispatchError, ToolQueueRegistry};
 use super::session_interrupt::SessionInterruptRegistry;
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
@@ -339,6 +340,14 @@ pub enum StartSessionError {
     IdExhausted,
     #[error("session creation timed out waiting for extension")]
     Timeout,
+    #[error("session creation was cancelled")]
+    Cancelled,
+    #[error("session creation cancellation cleanup failed for {session_id}: {message}")]
+    CleanupFailed {
+        session_id: SessionId,
+        agent_window_id: Option<i64>,
+        message: String,
+    },
     #[error("extension rejected tool.session_start: {0:?}")]
     ExtensionError(RpcError),
     #[error("transport closed while waiting for extension response")]
@@ -354,6 +363,8 @@ impl StartSessionError {
             StartSessionError::AmbiguousBrowserLabel { .. } => "invalid_params",
             StartSessionError::IdExhausted => "protocol_error",
             StartSessionError::Timeout => "timeout",
+            StartSessionError::Cancelled => "cancelled",
+            StartSessionError::CleanupFailed { .. } => "protocol_error",
             StartSessionError::TransportClosed => "protocol_error",
             StartSessionError::ExtensionError(err) => match err.code {
                 bsk_protocol::ErrorCode::Timeout => "timeout",
@@ -407,6 +418,7 @@ pub struct AgentWindowOptions {
 /// On success the matching per-session dispatch queue (M6.5,
 /// design §5) is also spawned so that subsequent `tool.*` RPCs serialise
 /// against this session's Agent Window / ref-store.
+#[allow(clippy::too_many_arguments)]
 pub async fn start_session(
     registry: &Arc<BrowserRegistry>,
     sessions: &Arc<SessionRegistry>,
@@ -415,24 +427,32 @@ pub async fn start_session(
     window: AgentWindowOptions,
     connect_wait: Duration,
     timeout_dur: Duration,
+    cancel: Option<AbortToken>,
 ) -> Result<Session, StartSessionError> {
-    let client: Arc<BrowserClient> = registry
-        .select_with_connect_wait(requested, connect_wait)
-        .await
-        .map_err(|e| match e {
-            SelectError::NoBrowserConnected => StartSessionError::NoBrowserConnected,
-            SelectError::MultipleBrowsersOnline => StartSessionError::MultipleBrowsersOnline {
-                browsers: snapshot_status_entries(registry, sessions),
-            },
-            SelectError::NotFound => StartSessionError::BrowserNotFound,
-            SelectError::AmbiguousLabel {
-                label,
-                instance_ids,
-            } => StartSessionError::AmbiguousBrowserLabel {
-                label,
-                instance_ids,
-            },
-        })?;
+    let selection = registry.select_with_connect_wait(requested, connect_wait);
+    tokio::pin!(selection);
+    let selected = match cancel.as_ref() {
+        Some(token) => tokio::select! {
+            biased;
+            _ = token.cancelled() => return Err(StartSessionError::Cancelled),
+            selected = &mut selection => selected,
+        },
+        None => selection.await,
+    };
+    let client: Arc<BrowserClient> = selected.map_err(|e| match e {
+        SelectError::NoBrowserConnected => StartSessionError::NoBrowserConnected,
+        SelectError::MultipleBrowsersOnline => StartSessionError::MultipleBrowsersOnline {
+            browsers: snapshot_status_entries(registry, sessions),
+        },
+        SelectError::NotFound => StartSessionError::BrowserNotFound,
+        SelectError::AmbiguousLabel {
+            label,
+            instance_ids,
+        } => StartSessionError::AmbiguousBrowserLabel {
+            label,
+            instance_ids,
+        },
+    })?;
     let session_id = sessions
         .reserve_id(client.id.clone(), SESSION_ID_MAX_RESERVE_ATTEMPTS, now_ms)
         .ok_or(StartSessionError::IdExhausted)?;
@@ -453,22 +473,71 @@ pub async fn start_session(
         let mut pending = client.pending.lock().unwrap();
         pending.register(rpc_id.clone())
     };
+    if cancel.as_ref().is_some_and(AbortToken::is_cancelled) {
+        sessions.cancel_reservation(&session_id);
+        client.pending.lock().unwrap().cancel(&rpc_id);
+        return Err(StartSessionError::Cancelled);
+    }
     if client.sink.send(Frame::Request(request)).is_err() {
         sessions.cancel_reservation(&session_id);
         client.pending.lock().unwrap().cancel(&rpc_id);
         return Err(StartSessionError::TransportClosed);
     }
-    let response = match timeout(timeout_dur, waiter).await {
-        Ok(Ok(resp)) => resp,
-        Ok(Err(_)) => {
+    let mut waiter = waiter;
+    enum StartWaitOutcome {
+        Response(bsk_protocol::ResponseFrame),
+        WaiterClosed,
+        Cancelled,
+        Timeout,
+    }
+    let wait_outcome = match cancel.as_ref() {
+        Some(token) => {
+            let deadline = tokio::time::sleep(timeout_dur);
+            tokio::pin!(deadline);
+            tokio::select! {
+                biased;
+                _ = token.cancelled() => StartWaitOutcome::Cancelled,
+                response = &mut waiter => match response {
+                    Ok(response) => StartWaitOutcome::Response(response),
+                    Err(_) => StartWaitOutcome::WaiterClosed,
+                },
+                _ = &mut deadline => StartWaitOutcome::Timeout,
+            }
+        }
+        None => match timeout(timeout_dur, &mut waiter).await {
+            Ok(Ok(response)) => StartWaitOutcome::Response(response),
+            Ok(Err(_)) => StartWaitOutcome::WaiterClosed,
+            Err(_) => StartWaitOutcome::Timeout,
+        },
+    };
+    let response = match wait_outcome {
+        StartWaitOutcome::Response(response) => response,
+        StartWaitOutcome::WaiterClosed => {
             sessions.cancel_reservation(&session_id);
             client.pending.lock().unwrap().cancel(&rpc_id);
             return Err(StartSessionError::TransportClosed);
         }
-        Err(_) => {
-            sessions.cancel_reservation(&session_id);
-            client.pending.lock().unwrap().cancel(&rpc_id);
-            return Err(StartSessionError::Timeout);
+        StartWaitOutcome::Cancelled => {
+            return Err(finish_aborted_start(
+                &client,
+                sessions,
+                &session_id,
+                &rpc_id,
+                waiter,
+                StartAbortReason::Cancelled,
+            )
+            .await);
+        }
+        StartWaitOutcome::Timeout => {
+            return Err(finish_aborted_start(
+                &client,
+                sessions,
+                &session_id,
+                &rpc_id,
+                waiter,
+                StartAbortReason::Timeout,
+            )
+            .await);
         }
     };
     let agent_window_id = match response.body {
@@ -504,6 +573,124 @@ pub async fn start_session(
     Ok(session)
 }
 
+#[derive(Clone, Copy)]
+enum StartAbortReason {
+    Cancelled,
+    Timeout,
+}
+
+impl StartAbortReason {
+    fn error(self) -> StartSessionError {
+        match self {
+            Self::Cancelled => StartSessionError::Cancelled,
+            Self::Timeout => StartSessionError::Timeout,
+        }
+    }
+}
+
+async fn finish_aborted_start(
+    client: &Arc<BrowserClient>,
+    sessions: &Arc<SessionRegistry>,
+    session_id: &SessionId,
+    rpc_id: &RpcId,
+    mut waiter: tokio::sync::oneshot::Receiver<bsk_protocol::ResponseFrame>,
+    reason: StartAbortReason,
+) -> StartSessionError {
+    sessions.cancel_reservation(session_id);
+    let cancel = Frame::Request(RequestFrame {
+        id: format!("cancel-{rpc_id}"),
+        method: Method::Cancel,
+        params: Some(serde_json::json!({ "rpc_id": rpc_id })),
+    });
+    if client.sink.send(cancel).is_err() {
+        client.pending.lock().unwrap().cancel(rpc_id);
+        return StartSessionError::TransportClosed;
+    }
+
+    match timeout(CANCEL_CLEANUP_TIMEOUT, &mut waiter).await {
+        Ok(Ok(response)) => match response.body {
+            ResponseBody::Err(err)
+                if matches!(err.code, ErrorCode::Cancelled | ErrorCode::UserAborted) =>
+            {
+                reason.error()
+            }
+            ResponseBody::Err(err) => StartSessionError::ExtensionError(err),
+            ResponseBody::Ok(value) => {
+                let agent_window_id = serde_json::from_value::<SessionStartResult>(value)
+                    .ok()
+                    .and_then(|result| result.agent_window_id);
+                match rollback_extension_session(client, session_id).await {
+                    Ok(()) => reason.error(),
+                    Err(message) => StartSessionError::CleanupFailed {
+                        session_id: session_id.clone(),
+                        agent_window_id,
+                        message,
+                    },
+                }
+            }
+        },
+        Ok(Err(_)) => {
+            client.pending.lock().unwrap().cancel(rpc_id);
+            StartSessionError::TransportClosed
+        }
+        Err(_) => {
+            // The cancel frame is already queued behind session_start. Even
+            // if chrome.windows.create is still blocked, the extension will
+            // observe the aborted signal and compensate before replying.
+            client.pending.lock().unwrap().cancel(rpc_id);
+            reason.error()
+        }
+    }
+}
+
+async fn rollback_extension_session(
+    client: &Arc<BrowserClient>,
+    session_id: &SessionId,
+) -> Result<(), String> {
+    let rollback_id = next_rpc_id("sess-start-rollback");
+    let waiter = {
+        let mut pending = client.pending.lock().unwrap();
+        pending.register(rollback_id.clone())
+    };
+    let request = RequestFrame {
+        id: rollback_id.clone(),
+        method: Method::ToolSessionStop,
+        params: Some(
+            serde_json::to_value(SessionStopParams {
+                session_id: session_id.0.clone(),
+            })
+            .expect("serialize session_start rollback params"),
+        ),
+    };
+    if client.sink.send(Frame::Request(request)).is_err() {
+        client.pending.lock().unwrap().cancel(&rollback_id);
+        return Err("browser disconnected before rollback was queued".into());
+    }
+    let response = match timeout(CANCEL_CLEANUP_TIMEOUT, waiter).await {
+        Ok(Ok(response)) => response,
+        Ok(Err(_)) => return Err("browser disconnected during rollback".into()),
+        Err(_) => {
+            client.pending.lock().unwrap().cancel(&rollback_id);
+            return Err(format!(
+                "extension did not finish rollback within {CANCEL_CLEANUP_TIMEOUT:?}"
+            ));
+        }
+    };
+    match response.body {
+        ResponseBody::Ok(value) => {
+            let result: SessionStopResult = serde_json::from_value(value)
+                .map_err(|err| format!("invalid rollback response: {err}"))?;
+            if result.return_failures.is_empty() {
+                Ok(())
+            } else {
+                Err("rollback reported borrowed-tab return failures".into())
+            }
+        }
+        ResponseBody::Err(err) if err.code == ErrorCode::NotFound => Ok(()),
+        ResponseBody::Err(err) => Err(format!("rollback failed: {} ({:?})", err.message, err.code)),
+    }
+}
+
 /// Tear down a single session id (round-trips `tool.session_stop` to the
 /// owning extension and unregisters on success). Also tears down the
 /// per-session dispatch queue so the worker task exits.
@@ -514,6 +701,7 @@ pub async fn stop_session(
     interrupts: &Arc<SessionInterruptRegistry>,
     session_id: &SessionId,
     timeout_dur: Duration,
+    cancel: Option<AbortToken>,
 ) -> Result<SessionStopResult, StopSessionError> {
     let session = sessions.get(session_id).ok_or(StopSessionError::NotFound)?;
     if registry.get(&session.browser_id).is_none() {
@@ -524,12 +712,17 @@ pub async fn stop_session(
         session_id: session_id.0.clone(),
     })
     .unwrap();
+    // Internal callers (idle reaping and shutdown) do not have a CLI-owned
+    // token, but still need timeout-driven WS cancellation so a late window
+    // close cannot leave daemon state pointing at a vanished session.
+    let lifecycle_cancel = Some(cancel.unwrap_or_default());
     match queues
         .dispatch_after_closing(
             session_id,
             bsk_protocol::Method::ToolSessionStop,
             params,
             timeout_dur,
+            lifecycle_cancel,
         )
         .await
     {
@@ -567,6 +760,10 @@ pub async fn stop_session(
                 drop_session_local(queues, interrupts, session_id);
                 return Ok(SessionStopResult::default());
             }
+            if err.code == bsk_protocol::ErrorCode::Timeout {
+                queues.reopen(session_id);
+                return Err(StopSessionError::Timeout);
+            }
             queues.reopen(session_id);
             Err(StopSessionError::ExtensionError(err))
         }

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

@@ -226,10 +226,6 @@ 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:
@@ -462,7 +458,6 @@ 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");
                     }
                 }
@@ -496,13 +491,11 @@ pub(crate) fn spawn_session_idle_reaper(state: Arc<DaemonState>) -> tokio::task:
                     &state.session_interrupts,
                     &session_id,
                     Duration::from_secs(10),
+                    None,
                 )
                 .await
                 {
-                    Ok(_) => {
-                        state.transfers.release_session(&session_id.0);
-                        info!(session = %session_id, "idle session stopped");
-                    }
+                    Ok(_) => info!(session = %session_id, "idle session stopped"),
                     Err(StopSessionError::SessionBusy | StopSessionError::Stopping) => {
                         debug!(session = %session_id, "idle session still active; retrying later");
                     }
@@ -513,7 +506,6 @@ 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,7 +7,6 @@ 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;
@@ -35,8 +34,8 @@ pub struct DaemonState {
     /// `stop_session` / browser disconnect.
     pub tool_queues: Arc<ToolQueueRegistry>,
     /// Per-rpc-id cancellation tokens for daemon-side long-runners
-    /// (M9.3 — currently only `tool.wait_ms`). The CLI's `cancel
-    /// { rpc_id }` consults this registry first.
+    /// (`tool.wait_ms` plus `session.*` lifecycle calls). The CLI's
+    /// `cancel { rpc_id }` consults this registry first.
     pub abort_registry: Arc<AbortRegistry>,
     /// Tracks `tool.*` RPCs that have been forwarded to an extension
     /// over WS but have not yet received a response. Indexed by the
@@ -52,9 +51,6 @@ 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 {
@@ -68,7 +64,6 @@ 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,
@@ -77,7 +72,6 @@ impl DaemonState {
             abort_registry,
             tool_inflight,
             session_interrupts,
-            transfers,
         }
     }
 }

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

@@ -295,7 +295,6 @@ 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>();
@@ -408,7 +407,6 @@ 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 {
@@ -505,7 +503,6 @@ 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,8 +97,6 @@ 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,45 +213,6 @@ fn rejects_zero_click_count() {
     );
 }
 
-#[test]
-fn parses_upload_with_repeated_files() {
-    let cli = parse(&[
-        "bsk",
-        "upload",
-        "@e3",
-        "--file",
-        "one.png",
-        "--file",
-        "two.png",
-        "--session",
-        "s1",
-    ]);
-    let Command::Upload(args) = cli.command else {
-        panic!("expected upload command");
-    };
-    assert_eq!(args.target.as_deref(), Some("@e3"));
-    assert_eq!(args.files.len(), 2);
-}
-
-#[test]
-fn parses_download_with_exact_output_policy() {
-    let cli = parse(&[
-        "bsk",
-        "download",
-        "#export",
-        "--out",
-        "result.zip",
-        "--session",
-        "s1",
-        "--overwrite",
-    ]);
-    let Command::Download(args) = cli.command else {
-        panic!("expected download command");
-    };
-    assert_eq!(args.target.as_deref(), Some("#export"));
-    assert!(args.overwrite);
-}
-
 #[test]
 fn parses_record_start_with_browser_and_url() {
     let cli = parse(&[

crates/bsk-cli/tests/per_session_queue.rs

@@ -325,6 +325,7 @@ async fn session_stop_fast_fails_while_tool_is_in_flight() {
         &state.session_interrupts,
         &sid,
         Duration::from_secs(5),
+        None,
     )
     .await;
     assert!(
@@ -366,6 +367,7 @@ async fn session_stop_fast_fails_while_tool_is_in_flight() {
         &state.session_interrupts,
         &sid,
         Duration::from_secs(5),
+        None,
     )
     .await
     .expect("session.stop ok after tool completes");

crates/bsk-cli/tests/sessions_ipc.rs

@@ -10,9 +10,14 @@ use std::time::Duration;
 
 use bsk::daemon::{self, DaemonConfig};
 use bsk::ipc_client::IpcClient;
+use bsk_protocol::cancel::{CancelParams, CancelResult};
 use bsk_protocol::system::{HandshakeParams, HandshakeResult, StatusResult};
-use bsk_protocol::tools::{SessionStartParams, SessionStartResult, SessionStopParams};
-use bsk_protocol::{BrowserPeerInfo, Frame, Method, RequestFrame, ResponseBody, ResponseFrame};
+use bsk_protocol::tools::{
+    SessionStartParams, SessionStartResult, SessionStopParams, SessionStopResult,
+};
+use bsk_protocol::{
+    BrowserPeerInfo, ErrorCode, Frame, Method, RequestFrame, ResponseBody, ResponseFrame, RpcError,
+};
 use futures_util::{SinkExt, StreamExt};
 use rand::Rng;
 use tokio_tungstenite::tungstenite::handshake::client::generate_key;
@@ -23,6 +28,9 @@ use support::{wait_for_browser_count, wait_for_no_sessions};
 
 const TEST_EXT_ID: &str = "abcdefghijklmnopabcdefghijklmnop";
 
+type TestWs =
+    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
+
 fn tempfile_path(prefix: &str) -> PathBuf {
     let mut p = std::env::temp_dir();
     let mut rng = rand::thread_rng();
@@ -56,9 +64,7 @@ async fn spawn_daemon_with_session_idle(session_idle: Duration) -> (daemon::Daem
     (handle, sock)
 }
 
-async fn connect_ext(
-    addr: std::net::SocketAddr,
-) -> tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>> {
+async fn connect_ext(addr: std::net::SocketAddr) -> TestWs {
     let origin = format!("chrome-extension://{TEST_EXT_ID}");
     let url = format!("ws://{addr}/");
     let req = Request::builder()
@@ -76,11 +82,7 @@ async fn connect_ext(
     ws
 }
 
-async fn handshake_as_ext(
-    ws: &mut tokio_tungstenite::WebSocketStream<
-        tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
-    >,
-) -> HandshakeResult {
+async fn handshake_as_ext(ws: &mut TestWs) -> HandshakeResult {
     let params = HandshakeParams {
         client: "browser-skill-extension".into(),
         version: "0.1.0-dev.0".parse().unwrap(),
@@ -114,6 +116,128 @@ async fn handshake_as_ext(
     }
 }
 
+async fn next_extension_request(ws: &mut TestWs) -> RequestFrame {
+    loop {
+        let message = ws.next().await.expect("daemon closed websocket").unwrap();
+        match message {
+            Message::Text(text) => match serde_json::from_str::<Frame>(&text).unwrap() {
+                Frame::Request(request) => return request,
+                Frame::Response(_) | Frame::Event(_) => continue,
+            },
+            Message::Ping(payload) => ws.send(Message::Pong(payload)).await.unwrap(),
+            Message::Close(_) => panic!("daemon closed websocket before sending request"),
+            _ => {}
+        }
+    }
+}
+
+async fn send_extension_response(ws: &mut TestWs, response: ResponseFrame) {
+    ws.send(Message::Text(serde_json::to_string(&response).unwrap()))
+        .await
+        .unwrap();
+}
+
+async fn acknowledge_extension_cancel(ws: &mut TestWs, cancel: RequestFrame, target_rpc_id: &str) {
+    assert_eq!(cancel.method, Method::Cancel);
+    let params: CancelParams = serde_json::from_value(cancel.params.unwrap()).unwrap();
+    assert_eq!(params.rpc_id, target_rpc_id);
+    send_extension_response(
+        ws,
+        ResponseFrame {
+            id: cancel.id,
+            body: ResponseBody::Ok(serde_json::to_value(CancelResult { cancelled: true }).unwrap()),
+        },
+    )
+    .await;
+}
+
+async fn respond_to_aborted_start(
+    ws: &mut TestWs,
+    start_seen: Option<tokio::sync::oneshot::Sender<()>>,
+    agent_window_id: i64,
+) {
+    let start = next_extension_request(ws).await;
+    assert_eq!(start.method, Method::ToolSessionStart);
+    let params: SessionStartParams = serde_json::from_value(start.params.clone().unwrap()).unwrap();
+    if let Some(start_seen) = start_seen {
+        start_seen.send(()).unwrap();
+    }
+
+    let cancel = next_extension_request(ws).await;
+    acknowledge_extension_cancel(ws, cancel, &start.id).await;
+
+    // Model the hardest race: chrome.windows.create completed just as
+    // cancellation arrived, so the extension's original call succeeds.
+    send_extension_response(
+        ws,
+        ResponseFrame {
+            id: start.id,
+            body: ResponseBody::Ok(
+                serde_json::to_value(SessionStartResult {
+                    agent_window_id: Some(agent_window_id),
+                })
+                .unwrap(),
+            ),
+        },
+    )
+    .await;
+
+    let rollback = next_extension_request(ws).await;
+    assert_eq!(rollback.method, Method::ToolSessionStop);
+    let rollback_params: SessionStopParams =
+        serde_json::from_value(rollback.params.unwrap()).unwrap();
+    assert_eq!(rollback_params.session_id, params.session_id);
+    send_extension_response(
+        ws,
+        ResponseFrame {
+            id: rollback.id,
+            body: ResponseBody::Ok(serde_json::to_value(SessionStopResult::default()).unwrap()),
+        },
+    )
+    .await;
+}
+
+async fn respond_to_aborted_stop(
+    ws: &mut TestWs,
+    stop_seen: Option<tokio::sync::oneshot::Sender<()>>,
+) {
+    let start = next_extension_request(ws).await;
+    assert_eq!(start.method, Method::ToolSessionStart);
+    send_extension_response(
+        ws,
+        ResponseFrame {
+            id: start.id,
+            body: ResponseBody::Ok(
+                serde_json::to_value(SessionStartResult {
+                    agent_window_id: Some(4242),
+                })
+                .unwrap(),
+            ),
+        },
+    )
+    .await;
+
+    let stop = next_extension_request(ws).await;
+    assert_eq!(stop.method, Method::ToolSessionStop);
+    if let Some(stop_seen) = stop_seen {
+        stop_seen.send(()).unwrap();
+    }
+    let cancel = next_extension_request(ws).await;
+    acknowledge_extension_cancel(ws, cancel, &stop.id).await;
+    send_extension_response(
+        ws,
+        ResponseFrame {
+            id: stop.id,
+            body: ResponseBody::Err(RpcError {
+                code: ErrorCode::Cancelled,
+                message: "session_stop aborted before window close".into(),
+                data: None,
+            }),
+        },
+    )
+    .await;
+}
+
 #[tokio::test]
 async fn session_start_stop_round_trip_via_ipc() {
     let (handle, sock) = spawn_daemon().await;
@@ -250,6 +374,240 @@ async fn session_start_stop_round_trip_via_ipc() {
     handle.shutdown().await;
 }
 
+#[tokio::test]
+async fn cancelling_session_start_rolls_back_a_late_extension_success() {
+    const START_RPC_ID: &str = "session-start-cancel";
+
+    let (handle, sock) = spawn_daemon().await;
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = handshake_as_ext(&mut ws).await;
+    let (start_seen_tx, start_seen_rx) = tokio::sync::oneshot::channel();
+    let (release_tx, release_rx) = tokio::sync::oneshot::channel();
+
+    let responder = tokio::spawn(async move {
+        respond_to_aborted_start(&mut ws, Some(start_seen_tx), 4242).await;
+        let _ = release_rx.await;
+    });
+
+    let mut start_ipc = IpcClient::connect(&sock).await.unwrap();
+    let start_call = tokio::spawn(async move {
+        let outcome: Result<serde_json::Value, RpcError> = start_ipc
+            .call_with_id(
+                START_RPC_ID.to_string(),
+                Method::SessionStart,
+                Some(serde_json::json!({ "focused": false })),
+                Duration::from_secs(5),
+            )
+            .await
+            .unwrap();
+        outcome
+    });
+
+    start_seen_rx.await.unwrap();
+    let mut cancel_ipc = IpcClient::connect(&sock).await.unwrap();
+    let cancel: CancelResult = cancel_ipc
+        .call(
+            "cancel-start",
+            Method::Cancel,
+            Some(CancelParams {
+                rpc_id: START_RPC_ID.to_string(),
+            }),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(cancel.cancelled);
+
+    let start_error = start_call.await.unwrap().unwrap_err();
+    assert_eq!(start_error.code, ErrorCode::Cancelled);
+
+    let mut status_ipc = IpcClient::connect(&sock).await.unwrap();
+    let status: StatusResult = status_ipc
+        .call::<(), _>(
+            "status-after-start-cancel",
+            Method::SystemStatus,
+            None,
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(status.sessions.is_empty());
+    assert_eq!(status.browsers[0].session_count, 0);
+
+    let _ = release_tx.send(());
+    responder.await.unwrap();
+    handle.shutdown().await;
+}
+
+#[tokio::test]
+async fn timing_out_session_start_rolls_back_a_late_extension_success() {
+    let (handle, _sock) = spawn_daemon().await;
+    let state = handle.state();
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = handshake_as_ext(&mut ws).await;
+    let (release_tx, release_rx) = tokio::sync::oneshot::channel();
+
+    let responder = tokio::spawn(async move {
+        respond_to_aborted_start(&mut ws, None, 4343).await;
+        let _ = release_rx.await;
+    });
+
+    let start = bsk::daemon::sessions::start_session(
+        &state.browsers,
+        &state.sessions,
+        &state.tool_queues,
+        None,
+        bsk::daemon::sessions::AgentWindowOptions::default(),
+        Duration::ZERO,
+        Duration::from_millis(20),
+        None,
+    )
+    .await;
+    assert!(matches!(
+        start,
+        Err(bsk::daemon::sessions::StartSessionError::Timeout)
+    ));
+    assert!(state.sessions.is_empty());
+
+    let _ = release_tx.send(());
+    responder.await.unwrap();
+    handle.shutdown().await;
+}
+
+#[tokio::test]
+async fn cancelling_session_stop_keeps_the_session_retryable() {
+    const STOP_RPC_ID: &str = "session-stop-cancel";
+
+    let (handle, sock) = spawn_daemon().await;
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = handshake_as_ext(&mut ws).await;
+    let (stop_seen_tx, stop_seen_rx) = tokio::sync::oneshot::channel();
+    let (release_tx, release_rx) = tokio::sync::oneshot::channel();
+
+    let responder = tokio::spawn(async move {
+        respond_to_aborted_stop(&mut ws, Some(stop_seen_tx)).await;
+        let _ = release_rx.await;
+    });
+
+    let mut start_ipc = IpcClient::connect(&sock).await.unwrap();
+    let start: serde_json::Value = start_ipc
+        .call(
+            "start-before-stop-cancel",
+            Method::SessionStart,
+            Some(serde_json::json!({ "focused": false })),
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    let session_id = start["session_id"].as_str().unwrap().to_string();
+
+    let mut stop_ipc = IpcClient::connect(&sock).await.unwrap();
+    let stop_session_id = session_id.clone();
+    let stop_call = tokio::spawn(async move {
+        let outcome: Result<serde_json::Value, RpcError> = stop_ipc
+            .call_with_id(
+                STOP_RPC_ID.to_string(),
+                Method::SessionStop,
+                Some(serde_json::json!({
+                    "session_id": stop_session_id,
+                    "all": false,
+                })),
+                Duration::from_secs(5),
+            )
+            .await
+            .unwrap();
+        outcome
+    });
+
+    stop_seen_rx.await.unwrap();
+    let mut cancel_ipc = IpcClient::connect(&sock).await.unwrap();
+    let cancel: CancelResult = cancel_ipc
+        .call(
+            "cancel-stop",
+            Method::Cancel,
+            Some(CancelParams {
+                rpc_id: STOP_RPC_ID.to_string(),
+            }),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(cancel.cancelled);
+
+    let stop_error = stop_call.await.unwrap().unwrap_err();
+    assert_eq!(stop_error.code, ErrorCode::Cancelled);
+
+    let mut status_ipc = IpcClient::connect(&sock).await.unwrap();
+    let status: StatusResult = status_ipc
+        .call::<(), _>(
+            "status-after-stop-cancel",
+            Method::SystemStatus,
+            None,
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(status.sessions.len(), 1);
+    assert_eq!(status.sessions[0].session_id, session_id);
+
+    let _ = release_tx.send(());
+    responder.await.unwrap();
+    handle.shutdown().await;
+}
+
+#[tokio::test]
+async fn timing_out_session_stop_cancels_extension_teardown_and_keeps_session() {
+    let (handle, sock) = spawn_daemon().await;
+    let state = handle.state();
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = handshake_as_ext(&mut ws).await;
+    let (release_tx, release_rx) = tokio::sync::oneshot::channel();
+
+    let responder = tokio::spawn(async move {
+        respond_to_aborted_stop(&mut ws, None).await;
+        let _ = release_rx.await;
+    });
+
+    let mut start_ipc = IpcClient::connect(&sock).await.unwrap();
+    let start: serde_json::Value = start_ipc
+        .call(
+            "start-before-stop-timeout",
+            Method::SessionStart,
+            Some(serde_json::json!({ "focused": false })),
+            Duration::from_secs(5),
+        )
+        .await
+        .unwrap()
+        .unwrap();
+    let session_id =
+        bsk::daemon::sessions::SessionId(start["session_id"].as_str().unwrap().to_string());
+
+    let stop = bsk::daemon::sessions::stop_session(
+        &state.browsers,
+        &state.sessions,
+        &state.tool_queues,
+        &state.session_interrupts,
+        &session_id,
+        Duration::from_millis(20),
+        None,
+    )
+    .await;
+    assert!(matches!(
+        stop,
+        Err(bsk::daemon::sessions::StopSessionError::Timeout)
+    ));
+    assert!(state.sessions.get(&session_id).is_some());
+
+    let _ = release_tx.send(());
+    responder.await.unwrap();
+    handle.shutdown().await;
+}
+
 #[tokio::test]
 async fn session_idle_timeout_stops_and_unregisters_session() {
     let (handle, _sock) = spawn_daemon_with_session_idle(Duration::from_millis(50)).await;

crates/bsk-protocol/schema/tool_download_params.json

@@ -1,56 +0,0 @@
-{
-  "$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

@@ -1,62 +0,0 @@
-{
-  "$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

@@ -1,70 +0,0 @@
-{
-  "$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

@@ -1,33 +0,0 @@
-{
-  "$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,10 +85,6 @@ 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,10 +78,6 @@ 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")]
@@ -109,17 +105,6 @@ 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,
 }
@@ -171,8 +156,6 @@ 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.
@@ -211,11 +194,6 @@ 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

@@ -1,176 +0,0 @@
-//! 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,7 +3,6 @@
 pub mod console;
 pub mod dialog;
 pub mod emulate;
-pub mod file_transfer;
 pub mod human_loop;
 pub mod interaction;
 pub mod navigation;
@@ -19,7 +18,6 @@ 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,15 +143,6 @@ 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/README.md

@@ -20,22 +20,43 @@ extension keep owning the actual browser control — this package is a thin, wel
 | `browser_snapshot` | `bsk snapshot` | Indented aria-tree snapshot with `@eN` refs for interaction tools. |
 | `browser_observe` | `bsk observe` | Semantic VOM observation (read-only) with `@eN` refs. |
 | `browser_click` | `bsk click` | Click a snapshot ref or CSS selector (button / click-count options). |
+| `browser_hover` | `bsk hover` | Hover a ref or selector and allow hover-triggered UI to settle. |
 | `browser_fill` | `bsk fill` | Fill an input / textarea / contenteditable (clears first by default). |
+| `browser_select` | `bsk select` | Select one or more option values on a `<select>`. |
 | `browser_press` | `bsk press` | Dispatch a key or combo, optionally focusing a target first. |
 | `browser_screenshot` | `bsk screenshot` | PNG capture of the tab or a ref-cropped element; inlines the image when the deployment supports image input, otherwise returns a file path. |
 | `browser_emulate` | `bsk emulate` | Apply or clear mobile device emulation on the active tab. |
+| `browser_tab_list` | `bsk tab list` | List user and/or Agent Window tabs visible to an owned session. |
+| `browser_tab_create` | `bsk tab create` | Create a foreground or background tab in the Agent Window. |
+| `browser_tab_select` | `bsk tab select` | Focus an Agent Window tab. |
+| `browser_tab_close` | `bsk tab close` | Close an Agent Window tab. |
+| `browser_tab_borrow` | `bsk tab borrow` | Move a user tab into the Agent Window for controlled interaction. |
+| `browser_tab_return` | `bsk tab return` | Return a borrowed tab to its original user window. |
+| `browser_navigate_back` / `browser_navigate_forward` | `bsk navigate-back` / `bsk navigate-forward` | Traverse tab history and wait for a lifecycle phase. |
+| `browser_reload` | `bsk reload` | Reload the active tab, optionally bypassing cache. |
+| `browser_wait_for_navigation` | `bsk wait-for-navigation` | Wait explicitly for a page lifecycle event. |
+| `browser_request_help` | `bsk request-help` | Pause for login, captcha, OTP, confirmation, or another human browser step. |
+| `browser_get_html` | `bsk get-html` | Read raw document or ref-scoped HTML after semantic observation is insufficient. |
+| `browser_console` | `bsk console` | Read buffered console/log/exception entries without evaluating JavaScript. |
+| `browser_network` | `bsk network` | Read buffered network response/failure metadata. |
+| `browser_window_resize` | `bsk window resize` | Resize the owned session's Agent Window. |
+
+`bsk evaluate` and `bsk record` are intentionally not exposed by this plugin: arbitrary page
+evaluation is a higher-risk capability, while recording is long-running and needs a dedicated
+DeepSeek Harness lifecycle before it can be added safely.
 
 ## Agent skill (progressive disclosure)
 
 Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
 official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
 resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
-tool. The body is assembled at build time from two parts, so there is exactly one source of
-truth: a dsh-specific prelude (`skill/prelude.md` — tool↔CLI map, owned-session semantics,
-plugin-only overrides) followed verbatim by the canonical CLI skill (`skill/SKILL.md` at the
-repo root — the same file `crates/bsk-cli/build.rs` mirrors for the CLI package; workflows,
-stop-when-done rules, refs usage, sandbox rules). Registration and every pre-step catalog
-snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
+tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
+`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
+concatenated: its command examples belong to a different execution interface and would bypass
+the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
+The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
+missing supported browser tools before embedding the Markdown. Registration and every pre-step
+catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
 seam degrade silently.
 
 ## Multi-session model
@@ -88,7 +109,7 @@ All fields are optional and validated through the plugin's Schemastery `Config`:
         # lazyTools: true              # reveal browser_* tools only after the skill is invoked
 ```
 
-- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the eleven
+- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the 28
   `browser_*` tool schemas stay OUT of the system prompt (zero schema tokens) until the
   `browser-skill` skill is actually invoked — the skill catalog entry is the only
   advertisement. One successful invocation (model tool call, or a `/browser-skill` user
@@ -152,7 +173,7 @@ shell's theme cannot bleed back in.
   card). Screenshots additionally attach the image itself when the host mounts an attachment store
   and the active model route declares image input; otherwise the PNG path is returned.
 - **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
-  `lib/client.js`, which registers a keyed `tool.call.toolview` view for `browser_screenshot`. The
+  `lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_screenshot`. The
   custom view keeps the terminal block (command + output) and, when the settled result carries an
   image block, resolves the durable attachment through the client session's authorized
   `readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
@@ -183,8 +204,8 @@ as `@wxg-prc-cpg/browser-skill-dsh-plugin`. The Cordis plugin id stays
 Trigger it by pushing a tag that matches `package.json`'s `version`:
 
 ```sh
-git tag dsh-plugin-v0.1.0
-git push origin dsh-plugin-v0.1.0
+git tag dsh-plugin-v0.1.2
+git push origin dsh-plugin-v0.1.2
 ```
 
 Or run the workflow from the Actions tab (`workflow_dispatch`). The job reads the

packages/dsh-plugin-browserskill/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxg-prc-cpg/browser-skill-dsh-plugin",
-  "description": "DeepSeek Harness tool plugin that exposes BrowserSkill (bsk) browser automation to the model",
-  "version": "0.1.1",
+  "description": "DeepSeek Harness tool plugin that exposes BrowserSkill browser automation (browser_* tools) to the model",
+  "version": "0.1.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

packages/dsh-plugin-browserskill/scripts/build-skill-content.mjs

@@ -1,20 +1,15 @@
-// Assemble the plugin's skill content: a dsh-specific routing prelude, the
-// canonical CLI skill body verbatim (repo-root skill/SKILL.md — the same source
-// crates/bsk-cli's build.rs mirrors), then a dsh routing reminder postlude. The
-// original's YAML frontmatter is stripped: name/description are supplied by the
-// registration.
+// Embed the DeepSeek Harness-specific browser skill at build time. The model-facing
+// skill deliberately documents only injected browser_* tools; the repository's CLI
+// skill is a separate interface and must never be concatenated here.
 // Output: src/skill-content.generated.ts (gitignored, built before tsdown and
-// before vitest) so the markdown ships inlined in the bundle and registration
-// is a pure in-memory read — never a per-step disk access.
+// before vitest), so registration is a pure in-memory read.
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkg = join(here, "..");
-const prelude = readFileSync(join(pkg, "skill", "prelude.md"), "utf8");
-const upstream = readFileSync(join(pkg, "..", "..", "skill", "SKILL.md"), "utf8");
-const postlude = readFileSync(join(pkg, "skill", "postlude.md"), "utf8");
+const source = readFileSync(join(pkg, "skill", "SKILL.md"), "utf8");
 
 function stripFrontmatter(markdown) {
   if (!markdown.startsWith("---\n")) return markdown;
@@ -22,18 +17,69 @@ function stripFrontmatter(markdown) {
   return end === -1 ? markdown : markdown.slice(end + 5).replace(/^\s*\n/, "");
 }
 
+const SUPPORTED_BROWSER_TOOLS = [
+  "browser_session_start",
+  "browser_session_stop",
+  "browser_session_list",
+  "browser_navigate",
+  "browser_navigate_back",
+  "browser_navigate_forward",
+  "browser_reload",
+  "browser_wait_for_navigation",
+  "browser_snapshot",
+  "browser_observe",
+  "browser_get_html",
+  "browser_screenshot",
+  "browser_console",
+  "browser_network",
+  "browser_click",
+  "browser_hover",
+  "browser_fill",
+  "browser_select",
+  "browser_press",
+  "browser_tab_list",
+  "browser_tab_create",
+  "browser_tab_select",
+  "browser_tab_close",
+  "browser_tab_borrow",
+  "browser_tab_return",
+  "browser_request_help",
+  "browser_emulate",
+  "browser_window_resize",
+];
+
+function validateModelFacingSkill(markdown) {
+  if (/\bbsk\b/i.test(markdown)) {
+    throw new Error("DSH skill must not expose the internal CLI name");
+  }
+  if (/```(?:bash|sh|shell)\b/i.test(markdown)) {
+    throw new Error("DSH skill must not contain command-line code blocks");
+  }
+
+  const mentioned = new Set(markdown.match(/\bbrowser_[a-z][a-z_]*\b/g) ?? []);
+  const supported = new Set(SUPPORTED_BROWSER_TOOLS);
+  const unknown = [...mentioned].filter((name) => !supported.has(name));
+  const missing = SUPPORTED_BROWSER_TOOLS.filter((name) => !mentioned.has(name));
+  if (unknown.length > 0) {
+    throw new Error(`DSH skill mentions unsupported browser tools: ${unknown.join(", ")}`);
+  }
+  if (missing.length > 0) {
+    throw new Error(`DSH skill omits supported browser tools: ${missing.join(", ")}`);
+  }
+}
+
 const NAME = "browser-skill";
 const DESCRIPTION =
-  "Browser automation against the user's logged-in Chromium through this plugin's injected browser_* tools; never invoke bsk through bash or shell. " +
-  "tools (bsk engine): visit and read pages, fill forms, click through flows, scrape data, " +
-  "smoke-test UI changes. Use when a task needs a real browser; requires the bsk CLI and the " +
-  "browser-skill extension connected.";
+  "Browser automation against the user's logged-in Chromium through this plugin's injected " +
+  "browser_* tools. Use to visit and read pages, fill forms, click through flows, inspect tabs, " +
+  "debug page activity, or smoke-test UI changes in a managed Agent Window.";
 
-const content = `${prelude.trim()}\n\n${stripFrontmatter(upstream).trim()}\n\n${postlude.trim()}\n`;
+const content = `${stripFrontmatter(source).trim()}\n`;
+validateModelFacingSkill(content);
 
 const banner =
   "// GENERATED by scripts/build-skill-content.mjs — do not edit.\n" +
-  "// Sources: skill/prelude.md + ../../../skill/SKILL.md + skill/postlude.md.\n";
+  "// Source: skill/SKILL.md (DeepSeek Harness browser_* tool instructions).\n";
 
 writeFileSync(
   join(pkg, "src", "skill-content.generated.ts"),

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

@@ -0,0 +1,271 @@
+---
+name: browser-skill
+description: |
+  Use the injected browser_* tools to automate the user's logged-in Chromium
+  browser in a managed Agent Window.
+---
+
+# browser-skill for DeepSeek Harness
+
+Drive the user's real Chromium browser through the structured `browser_*` tools provided by this
+plugin. The browser keeps the user's existing logins and cookies while isolating automation in an
+Agent Window. Use the tool schemas exactly as exposed by DeepSeek Harness; arguments are structured
+fields, not command-line flags.
+
+## Tool availability
+
+Loading this skill reveals the browser tools for the rest of the conversation. If the tools were
+hidden before this skill was loaded, start browser work only after the skill invocation succeeds.
+
+All browser operations must use the injected tools directly. Do not translate the examples in this
+document into terminal commands or invoke another process to control the browser. Direct tool calls
+preserve session ownership, the live observation window, tool cards, cancellation, and cleanup.
+
+## When to use
+
+- Visit and read pages that require the user's existing browser session.
+- Fill forms, select options, click through bounded flows, or smoke-test a web UI.
+- Inspect tabs, page structure, screenshots, console messages, or network metadata.
+- Work with a user tab after explicitly borrowing it into the Agent Window.
+
+Do not use browser automation for tasks that need only local files, a purpose-built API, or an
+explanation. Never extract credentials, cookies, tokens, or other secrets. Do not keep control of a
+personal tab longer than the immediate task requires.
+
+## Mandatory workflow
+
+Every browser task follows this lifecycle:
+
+1. Call `browser_session_start` and retain its returned `sessionId`.
+2. Use that session for every browser operation. Pass `session` explicitly when more than one
+   session exists.
+3. Call `browser_session_stop` when the bounded goal is reached or an error ends the task. Treat
+   cleanup like a `finally` path unless the user explicitly asks to keep the session open.
+
+Conceptual tool-call sequence:
+
+```text
+browser_session_start({ url: "https://example.com" })
+browser_observe({ session: sessionId })
+browser_click({ session: sessionId, target: "@e4" })
+browser_observe({ session: sessionId })
+browser_session_stop({ session: sessionId })
+```
+
+The plugin owns only sessions created by `browser_session_start`. `browser_session_list` reports
+only those owned sessions. Never guess or reuse a session id from another program. When `session`
+is omitted, most tools use the most recently started or used owned session; explicit ids are safer
+for multi-session work.
+
+## Stop when the goal is met
+
+Browser work is a bounded task, not open-ended browsing.
+
+1. Define one observable success condition from the user's request.
+2. Take the shortest path: observe, act, then perform at most one relevant check.
+3. Stop immediately when success is visible. Do not refresh, navigate, click, or perform extra
+   verification after success.
+4. If a human-only step appears, use `browser_request_help`. If an action fails twice without
+   progress, pause instead of brute-forcing.
+5. When uncertain, make at most one fresh observation. If the state is still ambiguous, ask the
+   user rather than continuing to click.
+
+## Core interaction loop
+
+Use `browser_navigate` to open a destination in the active Agent Window tab, then inspect the page
+before interacting:
+
+1. `browser_observe` is the primary semantic view. It returns roles, states, text, and `@eN` refs,
+   including hints about conditional hover or focus surfaces.
+2. `browser_snapshot` is the static accessibility-tree fallback when the semantic view is
+   insufficient or a stricter tree is useful.
+3. Prefer a fresh `@eN` ref over a raw CSS selector for `browser_click`, `browser_hover`,
+   `browser_fill`, `browser_select`, and targeted `browser_press` calls.
+4. Observe again after navigation or a meaningful DOM change before using another ref.
+
+Refs invalidate after navigation and may also become stale after large DOM changes. Never carry a
+ref to a new page. If an observation marks a control as hover-triggered, call `browser_hover` on the
+trigger, observe again, and then act on the newly visible ref.
+
+Use interaction tools according to their schemas:
+
+- `browser_click`: click a ref or selector; optionally choose mouse button and click count.
+- `browser_hover`: move to a ref or selector and allow hover UI to settle; then observe again.
+- `browser_fill`: clear and fill a text-capable element; set `noClear` only when appending is
+  intentional.
+- `browser_select`: pass `values` as an array, including for a single option.
+- `browser_press`: send a key or combo, optionally focusing `target` first.
+
+Actions may trigger a navigation after the action itself returns. Use
+`browser_wait_for_navigation` only when that lifecycle wait is actually needed, then observe the
+new page.
+
+## Observation and page reading priority
+
+Escalate page reading only as needed:
+
+1. `browser_observe` for normal semantic understanding and interaction refs.
+2. `browser_snapshot` for a stricter static accessibility tree.
+3. `browser_get_html` for hidden DOM, metadata, or exact markup that the semantic views cannot
+   provide. A `ref` must come from a fresh observation; keep `maxBytes` bounded.
+4. `browser_screenshot` for layout, styling, canvas, image content, or another genuinely visual
+   question. Pass a fresh `ref` to crop to one element, or omit it for the visible tab.
+
+Do not start with raw HTML or a screenshot merely to discover ordinary controls. Screenshots may
+return an inline image or a saved path depending on the deployment.
+
+## Tabs and the Agent Window boundary
+
+Write actions normally affect only Agent Window tabs.
+
+- `browser_tab_list` lists `agent`, `user`, or `all` tabs visible to the owned session. Use
+  `scope: "user"` to locate a user tab before borrowing it.
+- `browser_tab_create` creates an Agent Window tab. It is active by default; set `active: false`
+  for a background tab.
+- `browser_tab_select` focuses an Agent Window tab.
+- `browser_tab_close` closes an Agent Window tab.
+- `browser_tab_borrow` moves a chosen user tab into the Agent Window before any write action.
+- `browser_tab_return` returns a borrowed tab to its original window and position. Return it as
+  soon as the immediate task is finished; stopping the session is only the fallback cleanup.
+
+Use only a `tabId` returned by `browser_tab_list` or `browser_tab_create`. Do not assume a tab id
+from page position or title.
+
+## Navigation and lifecycle
+
+- `browser_navigate` opens a URL and can wait for a requested lifecycle phase.
+- `browser_navigate_back` and `browser_navigate_forward` move one history entry.
+- `browser_reload` reloads the current tab; use `hard: true` only when bypassing cache is necessary.
+- `browser_wait_for_navigation` waits for a lifecycle event after an action that did not already
+  wait. Avoid speculative waits when no navigation is expected.
+
+After navigation, history traversal, or reload, discard old refs and call `browser_observe` or
+`browser_snapshot` again.
+
+## Ask the user for browser help
+
+Call `browser_request_help` for login, captcha, OTP, payment confirmation, consent, or another step
+that requires the user. Give a clear `prompt`; when the prompt refers to a concrete control, pass
+its fresh ref or selector in `targets` so the overlay can highlight it. Use `title` only when it
+adds clarity.
+
+Optional `completionCriteria` can finish the pause automatically when the page has an explicit,
+stable success signal. It supports `any` or `all` conditions using `urlContains`, `urlMatches`,
+`selectorExists`, `selectorMissing`, `textExists`, or `textMissing`, plus `stableForMs`.
+
+```text
+browser_request_help({
+  session: sessionId,
+  title: "Sign in required",
+  prompt: "Complete sign-in, then return control after the account page appears.",
+  targets: ["@e7"],
+  timeoutMs: 300000,
+  completionCriteria: {
+    any: [{ urlContains: "/account" }, { selectorExists: "[data-testid='account-menu']" }],
+    stableForMs: 1000
+  }
+})
+```
+
+Interpret outcomes deliberately:
+
+- `continued` or `completed`: the user returned control or the explicit detector matched. Observe
+  again before reasoning about the new state or using refs.
+- `cancelled`: stop the requested flow.
+- `timed_out`: report the timeout; do not repeatedly reopen the prompt.
+- `disabled`: unattended mode does not allow help; proceed only if safe or stop gracefully.
+- `navigated`: legacy outcome; do not treat navigation alone as proof of success.
+
+## Debugging without page scripting
+
+Use the read-only debugging tools only when relevant to the user's task:
+
+- `browser_console` reads buffered console messages, browser logs, and JavaScript exceptions.
+  Set `includeStack: true` when stack frames are useful.
+- `browser_network` reads buffered response and failure metadata. It does not return request or
+  response headers or bodies and does not modify traffic.
+
+Both tools accept `tabId`, `since`, `limit`, and `maxTextChars`. Their result returns `nextSince`;
+pass that value as the next `since` cursor instead of repeatedly requesting the same entries.
+
+Arbitrary page script evaluation and interaction recording are intentionally unsupported in this
+DeepSeek Harness plugin. Do not invent tool names or route around this limitation. If the task
+strictly requires either capability, explain that it is not available in this phase.
+
+## Window and device controls
+
+- `browser_window_resize` changes the Agent Window's outer `width` and `height`; each dimension
+  must be from 100 through 7680 CSS pixels.
+- `browser_emulate` applies a built-in device preset or explicit viewport settings to the active
+  tab. Explicit `width` and `height` must be supplied together. `mobile: true` also requires both
+  dimensions. Use `off: true` alone to clear emulation. Emulation is per-tab and new tabs do not
+  inherit it.
+
+## Tool reference
+
+### Sessions
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_session_start` | Start an owned Agent Window session, optionally with URL, size, browser instance, focus behavior, or device preset. |
+| `browser_session_stop` | Stop an owned session and close its Agent Window. |
+| `browser_session_list` | List owned sessions and identify the current one. |
+
+### Navigation and reading
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_navigate` | Navigate the active tab to a URL. |
+| `browser_navigate_back` | Go back one history entry. |
+| `browser_navigate_forward` | Go forward one history entry. |
+| `browser_reload` | Reload the active tab, optionally bypassing cache. |
+| `browser_wait_for_navigation` | Wait for an expected page lifecycle event. |
+| `browser_observe` | Read the primary semantic page representation with refs. |
+| `browser_snapshot` | Read the static accessibility-tree fallback with refs. |
+| `browser_get_html` | Read raw document or ref-scoped HTML as a last resort. |
+| `browser_screenshot` | Capture the visible tab or a ref-cropped element. |
+
+### Interaction
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_click` | Click a ref or CSS selector. |
+| `browser_hover` | Hover a ref or selector to reveal conditional UI. |
+| `browser_fill` | Fill a text-capable element. |
+| `browser_select` | Select one or more option values. |
+| `browser_press` | Send a keyboard key or combo. |
+
+### Tabs
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_tab_list` | List visible user and Agent Window tabs. |
+| `browser_tab_create` | Create an Agent Window tab. |
+| `browser_tab_select` | Focus an Agent Window tab. |
+| `browser_tab_close` | Close an Agent Window tab. |
+| `browser_tab_borrow` | Move a user tab into the Agent Window. |
+| `browser_tab_return` | Return a borrowed tab to its original window. |
+
+### Assistance, diagnostics, and display
+
+| Tool | Purpose |
+| --- | --- |
+| `browser_request_help` | Pause for an explicit user browser step. |
+| `browser_console` | Read buffered console and exception entries. |
+| `browser_network` | Read buffered response and failure metadata. |
+| `browser_window_resize` | Resize the Agent Window. |
+| `browser_emulate` | Apply or clear per-tab device emulation. |
+
+## Error handling and final checklist
+
+On a stale ref, observe again and retry once with a fresh ref. On a closed or unknown tab, list
+tabs instead of guessing. On an unknown session, list owned sessions or start a new one; never try
+foreign ids. On timeout, decide whether one longer, purposeful wait is justified. Avoid repeated
+actions with unchanged state.
+
+Before finishing a browser task, verify that:
+
+- The user's observable goal is met, or the blocker is clearly reported.
+- Any borrowed tab has been returned when practical.
+- The owned session has been stopped unless the user explicitly asked to keep it open.
+- No further page action is taken after success.

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

@@ -1,10 +0,0 @@
----
-
-## DSH routing reminder
-
-The CLI-oriented reference above describes behavior, not the execution mechanism in
-DeepSeek Harness. For every browser operation, call the injected `browser_*` model
-tool. Do not translate these examples into `bash` commands and do not execute `bsk`
-directly; the plugin invokes `bsk` internally. In particular, always begin with
-`browser_session_start`, pass its returned session id to subsequent `browser_*`
-tools, and finish with `browser_session_stop`.

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

@@ -1,71 +0,0 @@
-# browser-skill (dsh edition)
-
-## DSH tool-routing requirement (highest priority)
-
-This skill is running inside DeepSeek Harness, where the plugin has injected
-structured `browser_*` model tools. **Always call those injected `browser_*` tools
-for browser work. Never use `bash`, `shell`, `exec`, or another tool to invoke the
-`bsk` CLI directly.** The CLI command names shown below are only conceptual
-mappings for understanding the tools; they are not instructions to run commands.
-If a `browser_*` tool is available, using the CLI directly is incorrect because it
-bypasses plugin session ownership, observation UI, tool cards, and cleanup.
-
-Use the injected tool whose name matches the operation, for example:
-`browser_session_start`, `browser_navigate`, `browser_observe`, `browser_snapshot`,
-`browser_click`, `browser_fill`, `browser_press`, `browser_screenshot`, and
-`browser_session_stop`. Pass arguments as the tool schema specifies (not CLI flags).
-
-Drive the user's **real Chromium browser** (logins, cookies, Agent Window isolation)
-through this plugin's `browser_*` tools. Each injected tool is implemented by the
-plugin using the `bsk` engine internally — the model must not invoke that engine
-itself. The workflow, judgment rules, and safety constraints remain identical to
-the canonical CLI skill.
-
-> **Tool availability**: invoking this skill (which you just did) makes the plugin's
-> `browser_*` tools available for the rest of the session — they are injected on
-> successful skill load. Until then they are deliberately hidden, so do not attempt
-> a browser action before loading this skill.
-
-## Tool ↔ CLI map
-
-The tools below are thin, structured wrappers over the bsk CLI verbs of the same
-name; `session` parameters take the 4-letter session id (no `--session` flag
-spelling here):
-
-| dsh tool | bsk equivalent |
-|---|---|
-| `browser_session_start` / `browser_session_stop` / `browser_session_list` | `bsk session start/stop/list` |
-| `browser_navigate` | `bsk navigate` |
-| `browser_snapshot` / `browser_observe` | `bsk snapshot` / `bsk observe` |
-| `browser_click` / `browser_fill` / `browser_press` | `bsk click` / `bsk fill` / `bsk press` |
-| `browser_screenshot` | `bsk screenshot` |
-| `browser_emulate` | `bsk emulate` |
-
-(`bsk console` / `bsk network` have no tool counterpart in this plugin yet.)
-
-Plugin-specific semantics that override or narrow the CLI rules below:
-
-- **Owned sessions only**: this plugin sees and acts on just the sessions IT
-  started via `browser_session_start`. `browser_session_list` shows only those
-  (with the current marker); passing a session id created by another program
-  (or person) sharing the bsk daemon is refused outright — never retry those
-  with the same id.
-- **Current session**: omitted `session` parameters resolve to the most
-  recently started or used OWNED session. With several sessions in flight,
-  pass `session` explicitly to avoid surprises.
-- **Screenshots**: when the model route accepts images, `browser_screenshot`
-  returns the PNG inline as an image attachment; otherwise it returns the
-  saved file path.
-- **`browser_emulate mobile`**: requires `width`+`height` — the bsk daemon
-  refuses `--mobile` without viewport dimensions.
-- **Live observation**: in the dsh Web UI, every owned session is watched by
-  the floating overlay (thumbnails, action, interrupt) — observational side
-  traffic is free and never steals your command turn; just keep acting.
-
-The canonical CLI skill body follows verbatim (source of truth: `skill/SKILL.md`
-in the BrowserSkill repo, mirrored by build into `crates/bsk-cli/skill/SKILL.md`).
-Read `bsk <verb> --session <id>` as "the `browser_<verb>` tool with
-`session: <id>`"; everything else — when to use, the stop-when-done rules, the
-interaction loop, refs, sandbox rules — applies unchanged.
-
----

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

@@ -1,6 +1,6 @@
 /**
  * Lazy tool-schema injection ("progressive disclosure", final stage): with
- * `lazyTools` on (the default), the 11 browser_* tool schemas stay OUT of the
+ * `lazyTools` on (the default), the 28 browser_* tool schemas stay OUT of the
  * system prompt until the `browser-skill` skill has actually been invoked —
  * the skill catalog entry is the only advertisement. One successful
  * invocation (model tool call, or a user's `/browser-skill` gesture) reveals
@@ -96,7 +96,7 @@ export function hasSuccessfulSkillInvocation(events: readonly SessionEventLike[]
 /**
  * Arm the lazy reveal. Returns a disposer tearing down listeners and — when
  * the reveal already happened — the tool suite itself.
- * @param registerSuite - registers the 11 browser_* tools, returns their disposer.
+ * @param registerSuite - registers the 28 browser_* tools, returns their disposer.
  */
 export function armLazyTools(ctx: Context, registerSuite: () => () => void): () => void {
   let suiteDisposer: (() => void) | undefined;

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

@@ -12,7 +12,7 @@
  * events, and never move the registry's current pointer.
  */
 
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFile, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -78,6 +78,7 @@ const FAILURE_BACKOFF_THRESHOLD = 3;
 const FRAME_RING_SIZE = 2;
 
 export class ObservationService {
+  private readonly scratchNamespace = randomUUID();
   private readonly observations = new Map<string, SessionObservation>();
   private readonly listeners = new Set<(event: ObservationEvent) => void>();
   private readonly captureTimers = new Map<string, unknown>();
@@ -304,9 +305,9 @@ export class ObservationService {
     if (current === undefined || current.dead === true) return;
     if (this.captureInFlight.has(sessionId)) return;
     this.captureInFlight.add(sessionId);
-    // One fixed scratch path per session (overwritten each frame) and always
-    // unlinked after the bytes are read — /tmp must not grow without bound.
-    const outPath = join(tmpdir(), `bsk-obs-${sessionId}.png`);
+    // Stable within this service, isolated from captures owned by other instances.
+    const sessionKey = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+    const outPath = join(tmpdir(), `bsk-obs-${this.scratchNamespace}-${sessionKey}.png`);
     let writtenPath = outPath;
     try {
       const result = await this.deps.queue.run(sessionId, () =>
@@ -399,14 +400,48 @@ export function actionForLabel(label: string): string {
       return "observing";
     case "click":
       return "clicking";
+    case "hover":
+      return "hovering";
     case "fill":
       return "filling";
+    case "select":
+      return "selecting";
     case "press":
       return "pressing";
     case "screenshot":
       return "capturing";
     case "emulate":
       return "emulating";
+    case "tab list":
+      return "listing tabs";
+    case "tab create":
+      return "creating tab";
+    case "tab close":
+      return "closing tab";
+    case "tab select":
+      return "selecting tab";
+    case "tab borrow":
+      return "borrowing tab";
+    case "tab return":
+      return "returning tab";
+    case "navigate-back":
+      return "navigating back";
+    case "navigate-forward":
+      return "navigating forward";
+    case "reload":
+      return "reloading";
+    case "wait-for-navigation":
+      return "waiting for navigation";
+    case "request-help":
+      return "waiting for user";
+    case "get-html":
+      return "reading HTML";
+    case "console":
+      return "reading console";
+    case "network":
+      return "reading network";
+    case "window resize":
+      return "resizing window";
     default:
       return label;
   }

packages/dsh-plugin-browserskill/src/phase-one-runtime.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition, ToolResult, ToolRunContext } from "@deepseek-ai/dsh-tools";
+import type { ToolDeps } from "./tools";
+
+export type ToolRegistrar = (definition: ToolDefinition) => () => void;
+
+type TerminalPresentation = { card: "terminal"; output: string; exitCode: number } | undefined;
+
+/** Existing tool runtime seams reused by the phase-one capability modules. */
+export interface PhaseOneRuntime {
+  run(
+    exec: ToolRunContext,
+    args: string[],
+    label: string,
+    observeSession?: string,
+    runnerTimeoutMs?: number,
+  ): Promise<unknown>;
+  commandLine(args: string[]): string;
+  presentTerminalResult: (_args: never, result: ToolResult) => TerminalPresentation;
+}
+
+export function requireNonEmpty(value: string, name: string): void {
+  if (value.trim().length === 0) throw new Error(`${name} must be a non-empty string`);
+}
+
+export function requirePositive(value: number | undefined, name: string): void {
+  if (value !== undefined && value <= 0) throw new Error(`${name} must be greater than zero`);
+}
+
+/** CLI positional target detection is shared by hover/select/request-help. */
+export function isSnapshotRef(target: string): boolean {
+  return /^@?e\d+$/.test(target);
+}
+
+/**
+ * Give the child enough time to honour a command-level timeout plus IPC
+ * settlement slack, without shortening the plugin's configured default.
+ */
+export function runnerTimeout(deps: ToolDeps, commandTimeoutMs: number | undefined): number {
+  if (commandTimeoutMs === undefined) return deps.config.defaultTimeoutMs;
+  return Math.max(deps.config.defaultTimeoutMs, commandTimeoutMs + 15_000);
+}
+
+export function appendTarget(args: string[], target: string): void {
+  args.push(target);
+}
+
+export function appendTabId(args: string[], tabId: number | undefined): void {
+  if (tabId !== undefined) args.push("--tab-id", String(tabId));
+}
+
+export function appendWaitOptions(
+  args: string[],
+  waitUntil: string | undefined,
+  timeoutMs: number | undefined,
+): void {
+  if (waitUntil !== undefined) args.push("--wait-until", waitUntil);
+  if (timeoutMs !== undefined) args.push("--timeout", `${timeoutMs}ms`);
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-interaction.ts

@@ -0,0 +1,197 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  appendTabId,
+  appendTarget,
+  type PhaseOneRuntime,
+  requireNonEmpty,
+  requirePositive,
+  runnerTimeout,
+  type ToolRegistrar,
+} from "./phase-one-runtime";
+import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+const MODIFIERS = ["alt", "ctrl", "meta", "shift"] as const;
+
+/** Add hover and select without bypassing session ownership or observation. */
+export function registerPhaseOneInteractionTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  register(
+    defineTool({
+      name: "browser_hover",
+      description:
+        "Move the mouse over a snapshot ref or CSS selector to reveal hover-triggered UI. " +
+        "Run browser_observe or browser_snapshot again afterwards to discover newly visible refs.",
+      parameters: {
+        target: {
+          type: "string",
+          required: true,
+          description: "Snapshot ref (@e3 / e3) or CSS selector of the element to hover.",
+        },
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        modifiers: {
+          type: "array",
+          items: { type: "string", enum: MODIFIERS },
+          description: "Keyboard modifiers held during the mouse move.",
+        },
+        settleMs: {
+          type: "integer",
+          description: "Milliseconds to wait for hover-triggered UI to settle (default: 200).",
+        },
+        timeoutMs: TIMEOUT_MS_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            x: { type: "number", required: true },
+            y: { type: "number", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] hovered at (${value.x}, ${value.y}) on tab ${value.tabId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requireNonEmpty(args.target, "target");
+        requirePositive(args.timeoutMs, "timeoutMs");
+        requirePositive(args.settleMs, "settleMs");
+        const sessionId = registry.resolve(args.session, "browser_hover");
+        const cmdArgs = ["hover", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.modifiers !== undefined && args.modifiers.length > 0) {
+          cmdArgs.push("--modifiers", args.modifiers.join(","));
+        }
+        if (args.settleMs !== undefined) cmdArgs.push("--settle", `${args.settleMs}ms`);
+        if (args.timeoutMs !== undefined) cmdArgs.push("--timeout", `${args.timeoutMs}ms`);
+        appendTarget(cmdArgs, args.target);
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "hover",
+          sessionId,
+          runnerTimeout(deps, args.timeoutMs),
+        )) as { tab_id: number; x: number; y: number };
+        return { session: sessionId, tabId: reply.tab_id, x: reply.x, y: reply.y };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "hover",
+          args.target,
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Hover an element",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_select",
+      description:
+        "Set a select element's option values. Pass one value for a normal select or multiple " +
+        "values for a multi-select; values replace the current selection.",
+      parameters: {
+        target: {
+          type: "string",
+          required: true,
+          description: "Snapshot ref (@e3 / e3) or CSS selector of the select element.",
+        },
+        values: {
+          type: "array",
+          required: true,
+          items: { type: "string" },
+          description: "Option value attributes to select; at least one value is required.",
+        },
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        timeoutMs: TIMEOUT_MS_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            multiple: { type: "boolean", required: true },
+            selectedValues: {
+              type: "array",
+              required: true,
+              items: { type: "string" },
+            },
+            selectedLabels: {
+              type: "array",
+              required: true,
+              items: { type: "string" },
+            },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] selected ` +
+              `${value.selectedValues.join(", ") || "(none)"} on tab ${value.tabId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requireNonEmpty(args.target, "target");
+        requirePositive(args.timeoutMs, "timeoutMs");
+        if (args.values.length === 0) throw new Error("values must contain at least one option");
+        const sessionId = registry.resolve(args.session, "browser_select");
+        const cmdArgs = ["select", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        for (const value of args.values) cmdArgs.push("--value", value);
+        if (args.timeoutMs !== undefined) cmdArgs.push("--timeout", `${args.timeoutMs}ms`);
+        appendTarget(cmdArgs, args.target);
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "select",
+          sessionId,
+          runnerTimeout(deps, args.timeoutMs),
+        )) as {
+          tab_id: number;
+          multiple: boolean;
+          selected_values: string[];
+          selected_labels: string[];
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          multiple: reply.multiple,
+          selectedValues: reply.selected_values,
+          selectedLabels: reply.selected_labels,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "select",
+          args.target,
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: `Select ${args.values.length} option${args.values.length === 1 ? "" : "s"}`,
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-navigation.ts

@@ -0,0 +1,230 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  appendTabId,
+  appendWaitOptions,
+  type PhaseOneRuntime,
+  requirePositive,
+  runnerTimeout,
+  type ToolRegistrar,
+} from "./phase-one-runtime";
+import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM, WAIT_UNTIL_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+interface RawHistoryResult {
+  tab_id: number;
+  previous_url?: string;
+  final_url?: string;
+  reached: string;
+  error_text?: string;
+}
+
+const HISTORY_OUTPUT = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    session: { type: "string", required: true },
+    tabId: { type: "integer", required: true },
+    previousUrl: { type: "string" },
+    finalUrl: { type: "string" },
+    reached: { type: "string", required: true },
+    errorText: { type: "string" },
+  },
+} as const;
+
+function mapHistory(sessionId: string, reply: RawHistoryResult) {
+  return {
+    session: sessionId,
+    tabId: reply.tab_id,
+    ...(reply.previous_url !== undefined ? { previousUrl: reply.previous_url } : {}),
+    ...(reply.final_url !== undefined ? { finalUrl: reply.final_url } : {}),
+    reached: reply.reached,
+    ...(reply.error_text !== undefined ? { errorText: reply.error_text } : {}),
+  };
+}
+
+/** Add browser history, reload, and explicit lifecycle waiting. */
+export function registerPhaseOneNavigationTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  const registerHistory = (direction: "back" | "forward") => {
+    const toolName = `browser_navigate_${direction}` as const;
+    const command = `navigate-${direction}`;
+    register(
+      defineTool({
+        name: toolName,
+        description: `Navigate the active Agent Window tab ${direction} by one history entry.`,
+        parameters: {
+          session: SESSION_PARAM,
+          tabId: TAB_ID_PARAM,
+          waitUntil: WAIT_UNTIL_PARAM,
+          timeoutMs: TIMEOUT_MS_PARAM,
+        },
+        output: {
+          schema: HISTORY_OUTPUT,
+          render: (_args, value) => [
+            {
+              type: "text",
+              text:
+                `[session ${value.session}] navigated ${direction} on tab ${value.tabId}` +
+                (value.finalUrl !== undefined ? ` to ${value.finalUrl}` : "") +
+                ` (reached: ${value.reached})` +
+                (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
+            },
+          ],
+        },
+        async execute(args, exec) {
+          requirePositive(args.timeoutMs, "timeoutMs");
+          const sessionId = registry.resolve(args.session, toolName);
+          const cmdArgs = [command, "--session", sessionId];
+          appendTabId(cmdArgs, args.tabId);
+          appendWaitOptions(cmdArgs, args.waitUntil, args.timeoutMs);
+          const reply = (await runtime.run(
+            exec,
+            cmdArgs,
+            command,
+            sessionId,
+            runnerTimeout(deps, args.timeoutMs),
+          )) as RawHistoryResult;
+          if (reply.final_url !== undefined) deps.observation.setUrl(sessionId, reply.final_url);
+          return mapHistory(sessionId, reply);
+        },
+        presentCall: (args) => ({
+          card: "terminal",
+          title: runtime.commandLine([command, "--session", args.session ?? "(current)"]),
+          description: `Navigate ${direction}`,
+        }),
+        presentResult: runtime.presentTerminalResult,
+      }),
+    );
+  };
+  registerHistory("back");
+  registerHistory("forward");
+
+  register(
+    defineTool({
+      name: "browser_reload",
+      description:
+        "Reload the active Agent Window tab and wait for a lifecycle phase. Set hard=true to " +
+        "bypass the HTTP cache.",
+      parameters: {
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        waitUntil: WAIT_UNTIL_PARAM,
+        timeoutMs: TIMEOUT_MS_PARAM,
+        hard: { type: "boolean", description: "Bypass the HTTP cache while reloading." },
+      },
+      output: {
+        schema: HISTORY_OUTPUT,
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] reloaded tab ${value.tabId}` +
+              (value.finalUrl !== undefined ? ` at ${value.finalUrl}` : "") +
+              ` (reached: ${value.reached})` +
+              (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requirePositive(args.timeoutMs, "timeoutMs");
+        const sessionId = registry.resolve(args.session, "browser_reload");
+        const cmdArgs = ["reload", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        appendWaitOptions(cmdArgs, args.waitUntil, args.timeoutMs);
+        if (args.hard === true) cmdArgs.push("--hard");
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "reload",
+          sessionId,
+          runnerTimeout(deps, args.timeoutMs),
+        )) as RawHistoryResult;
+        if (reply.final_url !== undefined) deps.observation.setUrl(sessionId, reply.final_url);
+        return mapHistory(sessionId, reply);
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "reload",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.hard === true ? ["--hard"] : []),
+        ]),
+        description: "Reload the active tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_wait_for_navigation",
+      description:
+        "Wait for a page lifecycle event on the active Agent Window tab. Use after an action " +
+        "that may navigate when the action result itself does not wait for navigation.",
+      parameters: {
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        waitUntil: WAIT_UNTIL_PARAM,
+        timeoutMs: TIMEOUT_MS_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            reached: { type: "string", required: true },
+            errorText: { type: "string" },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] navigation wait on tab ${value.tabId}: ${value.reached}` +
+              (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requirePositive(args.timeoutMs, "timeoutMs");
+        const sessionId = registry.resolve(args.session, "browser_wait_for_navigation");
+        const timeoutMs = args.timeoutMs ?? 30_000;
+        const cmdArgs = ["wait-for-navigation", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.waitUntil !== undefined) cmdArgs.push("--wait-until", args.waitUntil);
+        cmdArgs.push("--timeout", `${timeoutMs}ms`);
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "wait-for-navigation",
+          sessionId,
+          runnerTimeout(deps, timeoutMs),
+        )) as { tab_id: number; reached: string; error_text?: string };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          reached: reply.reached,
+          ...(reply.error_text !== undefined ? { errorText: reply.error_text } : {}),
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "wait-for-navigation",
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Wait for page navigation",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-support.ts

@@ -0,0 +1,672 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  appendTabId,
+  isSnapshotRef,
+  type PhaseOneRuntime,
+  requireNonEmpty,
+  requirePositive,
+  runnerTimeout,
+  type ToolRegistrar,
+} from "./phase-one-runtime";
+import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+interface HelpConditionInput {
+  urlContains?: string;
+  urlMatches?: string;
+  selectorExists?: string;
+  selectorMissing?: string;
+  textExists?: string;
+  textMissing?: string;
+}
+
+interface CompletionCriteriaInput {
+  any?: HelpConditionInput[];
+  all?: HelpConditionInput[];
+  stableForMs?: number;
+}
+
+interface RawConsoleFrame {
+  function_name?: string;
+  url?: string;
+  line?: number;
+  column?: number;
+}
+
+interface RawConsoleEntry {
+  sequence: number;
+  kind: string;
+  level: string;
+  text: string;
+  url?: string;
+  line?: number;
+  column?: number;
+  timestamp?: number;
+  stack_trace?: RawConsoleFrame[];
+  truncated?: boolean;
+}
+
+interface RawNetworkEntry {
+  sequence: number;
+  kind: "response" | "failure";
+  method?: string;
+  url?: string;
+  status?: number;
+  status_text?: string;
+  mime_type?: string;
+  resource_type?: string;
+  error_text?: string;
+  timestamp?: number;
+  truncated?: boolean;
+}
+
+const HELP_CONDITION_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    urlContains: { type: "string" },
+    urlMatches: { type: "string" },
+    selectorExists: { type: "string" },
+    selectorMissing: { type: "string" },
+    textExists: { type: "string" },
+    textMissing: { type: "string" },
+  },
+} as const;
+
+const DEBUG_PARAMETERS = {
+  session: SESSION_PARAM,
+  tabId: TAB_ID_PARAM,
+  since: {
+    type: "integer",
+    description: "Return entries with a sequence strictly greater than this cursor.",
+  },
+  limit: {
+    type: "integer",
+    description: "Maximum entries to return (default: 50, daemon cap: 200).",
+  },
+  maxTextChars: {
+    type: "integer",
+    description: "Maximum characters per entry text/URL (default: 1000, daemon cap: 4096).",
+  },
+} as const;
+
+function mapCondition(condition: HelpConditionInput) {
+  return {
+    ...(condition.urlContains !== undefined ? { url_contains: condition.urlContains } : {}),
+    ...(condition.urlMatches !== undefined ? { url_matches: condition.urlMatches } : {}),
+    ...(condition.selectorExists !== undefined
+      ? { selector_exists: condition.selectorExists }
+      : {}),
+    ...(condition.selectorMissing !== undefined
+      ? { selector_missing: condition.selectorMissing }
+      : {}),
+    ...(condition.textExists !== undefined ? { text_exists: condition.textExists } : {}),
+    ...(condition.textMissing !== undefined ? { text_missing: condition.textMissing } : {}),
+  };
+}
+
+function mapCompletionCriteria(criteria: CompletionCriteriaInput) {
+  return {
+    ...(criteria.any !== undefined ? { any: criteria.any.map(mapCondition) } : {}),
+    ...(criteria.all !== undefined ? { all: criteria.all.map(mapCondition) } : {}),
+    ...(criteria.stableForMs !== undefined ? { stable_for_ms: criteria.stableForMs } : {}),
+  };
+}
+
+function validateDebugArgs(args: { since?: number; limit?: number; maxTextChars?: number }): void {
+  if (args.since !== undefined && args.since < 0) {
+    throw new Error("since must be zero or greater");
+  }
+  requirePositive(args.limit, "limit");
+  requirePositive(args.maxTextChars, "maxTextChars");
+}
+
+function appendDebugOptions(
+  args: string[],
+  options: { tabId?: number; since?: number; limit?: number; maxTextChars?: number },
+): void {
+  appendTabId(args, options.tabId);
+  if (options.since !== undefined) args.push("--since", String(options.since));
+  if (options.limit !== undefined) args.push("--limit", String(options.limit));
+  if (options.maxTextChars !== undefined) {
+    args.push("--max-text-chars", String(options.maxTextChars));
+  }
+}
+
+/** Human help, raw HTML, diagnostics, and Agent Window sizing. */
+export function registerPhaseOneSupportTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  register(
+    defineTool({
+      name: "browser_request_help",
+      description:
+        "Pause browser automation and ask the user to complete an in-page step such as login, " +
+        "captcha, OTP, or confirmation. After continued/completed, observe again before using refs.",
+      parameters: {
+        prompt: {
+          type: "string",
+          required: true,
+          description: "Clear instructions shown to the user in the browser help overlay.",
+        },
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        title: { type: "string", description: "Optional title for the help overlay." },
+        targets: {
+          type: "array",
+          items: { type: "string" },
+          description: "Snapshot refs or CSS selectors to scroll to and highlight for the user.",
+        },
+        timeoutMs: {
+          ...TIMEOUT_MS_PARAM,
+          description: "Maximum wait for the user in milliseconds (default: 300000).",
+        },
+        completionCriteria: {
+          type: "object",
+          additionalProperties: false,
+          description: "Optional explicit success detector for automatic completion.",
+          properties: {
+            any: { type: "array", items: HELP_CONDITION_SCHEMA },
+            all: { type: "array", items: HELP_CONDITION_SCHEMA },
+            stableForMs: {
+              type: "integer",
+              description: "How long criteria must remain true before completing.",
+            },
+          },
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            outcome: {
+              type: "string",
+              required: true,
+              enum: ["continued", "cancelled", "timed_out", "completed", "navigated", "disabled"],
+            },
+            completedBy: { type: "string" },
+            note: { type: "string" },
+            resolvedTargets: {
+              type: "array",
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  matched: { type: "boolean", required: true },
+                  ref: { type: "string" },
+                  selector: { type: "string" },
+                },
+              },
+            },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] user help outcome on tab ${value.tabId}: ${value.outcome}` +
+              (value.note !== undefined ? ` — ${value.note}` : "") +
+              (value.resolvedTargets !== undefined
+                ? `\ntargets: ${value.resolvedTargets
+                    .map(
+                      (target) =>
+                        `${target.ref ?? target.selector ?? "(unknown)"}=${target.matched ? "matched" : "not found"}`,
+                    )
+                    .join(", ")}`
+                : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        requireNonEmpty(args.prompt, "prompt");
+        if (args.title !== undefined) requireNonEmpty(args.title, "title");
+        requirePositive(args.timeoutMs, "timeoutMs");
+        for (const target of args.targets ?? []) requireNonEmpty(target, "target");
+        const criteria = args.completionCriteria as CompletionCriteriaInput | undefined;
+        if (criteria?.stableForMs !== undefined && criteria.stableForMs < 0) {
+          throw new Error("completionCriteria.stableForMs must be zero or greater");
+        }
+        const sessionId = registry.resolve(args.session, "browser_request_help");
+        const timeoutMs = args.timeoutMs ?? 300_000;
+        const cmdArgs = [
+          "request-help",
+          "--session",
+          sessionId,
+          "--prompt",
+          args.prompt,
+          "--timeout",
+          `${timeoutMs}ms`,
+        ];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.title !== undefined) cmdArgs.push("--title", args.title);
+        for (const target of args.targets ?? []) cmdArgs.push("--target", target);
+        if (criteria !== undefined) {
+          cmdArgs.push("--completion-criteria", JSON.stringify(mapCompletionCriteria(criteria)));
+        }
+        const reply = (await runtime.run(
+          exec,
+          cmdArgs,
+          "request-help",
+          sessionId,
+          runnerTimeout(deps, timeoutMs),
+        )) as {
+          outcome: "continued" | "cancelled" | "timed_out" | "completed" | "navigated" | "disabled";
+          completed_by?: string;
+          note?: string;
+          tab_id: number;
+          resolved_targets?: { matched: boolean; ref?: string; selector?: string }[];
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          outcome: reply.outcome,
+          ...(reply.completed_by !== undefined ? { completedBy: reply.completed_by } : {}),
+          ...(reply.note !== undefined ? { note: reply.note } : {}),
+          ...(reply.resolved_targets !== undefined
+            ? { resolvedTargets: reply.resolved_targets }
+            : {}),
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine(["request-help", "--session", args.session ?? "(current)"]),
+        description: "Ask the user for browser help",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_get_html",
+      description:
+        "Read raw DOM HTML from the active Agent Window tab, optionally scoped to a fresh " +
+        "snapshot ref. Use only when browser_observe/browser_snapshot cannot answer the question.",
+      parameters: {
+        session: SESSION_PARAM,
+        tabId: TAB_ID_PARAM,
+        ref: { type: "string", description: "Fresh snapshot ref that scopes the HTML subtree." },
+        maxBytes: {
+          type: "integer",
+          description: "Maximum returned HTML bytes before truncation (default: 524288).",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            html: { type: "string", required: true },
+            truncated: { type: "boolean", required: true },
+            byteSize: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.html +
+              (value.truncated ? `\n(HTML truncated; original size ${value.byteSize} bytes)` : ""),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        if (args.ref !== undefined) {
+          requireNonEmpty(args.ref, "ref");
+          if (!isSnapshotRef(args.ref)) throw new Error("ref must be a snapshot ref such as @e3");
+        }
+        requirePositive(args.maxBytes, "maxBytes");
+        const sessionId = registry.resolve(args.session, "browser_get_html");
+        const cmdArgs = ["get-html", "--session", sessionId];
+        appendTabId(cmdArgs, args.tabId);
+        if (args.ref !== undefined) cmdArgs.push("--ref", args.ref);
+        if (args.maxBytes !== undefined) cmdArgs.push("--max-bytes", String(args.maxBytes));
+        const reply = (await runtime.run(exec, cmdArgs, "get-html", sessionId)) as {
+          tab_id: number;
+          html: string;
+          truncated?: boolean;
+          byte_size: number;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          html: reply.html,
+          truncated: reply.truncated ?? false,
+          byteSize: reply.byte_size,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "get-html",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.ref !== undefined ? ["--ref", args.ref] : []),
+        ]),
+        description: "Read raw page HTML",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_console",
+      description:
+        "Read buffered console messages, browser log entries, and JavaScript exceptions from a tab. " +
+        "This is read-only and does not evaluate JavaScript.",
+      parameters: {
+        ...DEBUG_PARAMETERS,
+        includeStack: {
+          type: "boolean",
+          description: "Include structured stack frames in returned console entries.",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            entries: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  sequence: { type: "integer", required: true },
+                  kind: { type: "string", required: true },
+                  level: { type: "string", required: true },
+                  text: { type: "string", required: true },
+                  url: { type: "string" },
+                  line: { type: "integer" },
+                  column: { type: "integer" },
+                  timestamp: { type: "number" },
+                  stackTrace: {
+                    type: "array",
+                    required: true,
+                    items: {
+                      type: "object",
+                      additionalProperties: false,
+                      properties: {
+                        functionName: { type: "string" },
+                        url: { type: "string" },
+                        line: { type: "integer" },
+                        column: { type: "integer" },
+                      },
+                    },
+                  },
+                  truncated: { type: "boolean", required: true },
+                },
+              },
+            },
+            nextSince: { type: "integer", required: true },
+            truncated: { type: "boolean", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.entries.length === 0
+                ? "(no console messages captured)"
+                : value.entries
+                    .map((entry) => {
+                      const location =
+                        entry.url === undefined
+                          ? ""
+                          : ` ${entry.url}${entry.line !== undefined ? `:${entry.line}` : ""}${entry.column !== undefined ? `:${entry.column}` : ""}`;
+                      const stack = entry.stackTrace
+                        .map(
+                          (frame) =>
+                            `\n  at ${frame.functionName ?? "<anonymous>"} ${frame.url ?? ""}` +
+                            `${frame.line !== undefined ? `:${frame.line}` : ""}` +
+                            `${frame.column !== undefined ? `:${frame.column}` : ""}`,
+                        )
+                        .join("");
+                      return `#${entry.sequence} ${entry.level} ${entry.kind}${location} ${entry.text}${stack}`;
+                    })
+                    .join("\n") +
+                  (value.truncated
+                    ? `\n(output truncated; continue with since=${value.nextSince})`
+                    : ""),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        validateDebugArgs(args);
+        const sessionId = registry.resolve(args.session, "browser_console");
+        const cmdArgs = ["console", "--session", sessionId];
+        appendDebugOptions(cmdArgs, args);
+        if (args.includeStack === true) cmdArgs.push("--include-stack");
+        const reply = (await runtime.run(exec, cmdArgs, "console", sessionId)) as {
+          tab_id: number;
+          entries?: RawConsoleEntry[];
+          next_since: number;
+          truncated?: boolean;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          entries: (reply.entries ?? []).map((entry) => ({
+            sequence: entry.sequence,
+            kind: entry.kind,
+            level: entry.level,
+            text: entry.text,
+            ...(entry.url !== undefined ? { url: entry.url } : {}),
+            ...(entry.line !== undefined ? { line: entry.line } : {}),
+            ...(entry.column !== undefined ? { column: entry.column } : {}),
+            ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+            stackTrace: (entry.stack_trace ?? []).map((frame) => ({
+              ...(frame.function_name !== undefined ? { functionName: frame.function_name } : {}),
+              ...(frame.url !== undefined ? { url: frame.url } : {}),
+              ...(frame.line !== undefined ? { line: frame.line } : {}),
+              ...(frame.column !== undefined ? { column: frame.column } : {}),
+            })),
+            truncated: entry.truncated ?? false,
+          })),
+          nextSince: reply.next_since,
+          truncated: reply.truncated ?? false,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine(["console", "--session", args.session ?? "(current)"]),
+        description: "Read browser console messages",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_network",
+      description:
+        "Read buffered network responses and failures from a tab. Returns metadata only; request " +
+        "and response headers and bodies are not captured.",
+      parameters: DEBUG_PARAMETERS,
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            entries: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  sequence: { type: "integer", required: true },
+                  kind: { type: "string", required: true, enum: ["response", "failure"] },
+                  method: { type: "string" },
+                  url: { type: "string" },
+                  status: { type: "integer" },
+                  statusText: { type: "string" },
+                  mimeType: { type: "string" },
+                  resourceType: { type: "string" },
+                  errorText: { type: "string" },
+                  timestamp: { type: "number" },
+                  truncated: { type: "boolean", required: true },
+                },
+              },
+            },
+            nextSince: { type: "integer", required: true },
+            truncated: { type: "boolean", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.entries.length === 0
+                ? "(no network activity captured)"
+                : value.entries
+                    .map((entry) =>
+                      entry.kind === "failure"
+                        ? `#${entry.sequence} FAILED ${entry.method ?? "?"} ${entry.url ?? "(unknown)"} — ${entry.errorText ?? "failed"}`
+                        : `#${entry.sequence} ${entry.status ?? "?"} ${entry.method ?? "?"} ${entry.url ?? "(unknown)"}`,
+                    )
+                    .join("\n") +
+                  (value.truncated
+                    ? `\n(output truncated; continue with since=${value.nextSince})`
+                    : ""),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        validateDebugArgs(args);
+        const sessionId = registry.resolve(args.session, "browser_network");
+        const cmdArgs = ["network", "--session", sessionId];
+        appendDebugOptions(cmdArgs, args);
+        const reply = (await runtime.run(exec, cmdArgs, "network", sessionId)) as {
+          tab_id: number;
+          entries?: RawNetworkEntry[];
+          next_since: number;
+          truncated?: boolean;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          entries: (reply.entries ?? []).map((entry) => ({
+            sequence: entry.sequence,
+            kind: entry.kind,
+            ...(entry.method !== undefined ? { method: entry.method } : {}),
+            ...(entry.url !== undefined ? { url: entry.url } : {}),
+            ...(entry.status !== undefined ? { status: entry.status } : {}),
+            ...(entry.status_text !== undefined ? { statusText: entry.status_text } : {}),
+            ...(entry.mime_type !== undefined ? { mimeType: entry.mime_type } : {}),
+            ...(entry.resource_type !== undefined ? { resourceType: entry.resource_type } : {}),
+            ...(entry.error_text !== undefined ? { errorText: entry.error_text } : {}),
+            ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+            truncated: entry.truncated ?? false,
+          })),
+          nextSince: reply.next_since,
+          truncated: reply.truncated ?? false,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine(["network", "--session", args.session ?? "(current)"]),
+        description: "Read browser network activity",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_window_resize",
+      description: "Resize the owned session's Agent Window using outer CSS-pixel dimensions.",
+      parameters: {
+        width: {
+          type: "integer",
+          required: true,
+          description: "Agent Window outer width in CSS pixels (100..=7680).",
+        },
+        height: {
+          type: "integer",
+          required: true,
+          description: "Agent Window outer height in CSS pixels (100..=7680).",
+        },
+        session: SESSION_PARAM,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            windowId: { type: "integer", required: true },
+            width: { type: "integer", required: true },
+            height: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] resized window ${value.windowId} to ${value.width}x${value.height}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        if (args.width < 100 || args.width > 7680 || args.height < 100 || args.height > 7680) {
+          throw new Error("width and height must each be in the range 100..=7680");
+        }
+        const sessionId = registry.resolve(args.session, "browser_window_resize");
+        const reply = (await runtime.run(
+          exec,
+          [
+            "window",
+            "resize",
+            "--session",
+            sessionId,
+            "--width",
+            String(args.width),
+            "--height",
+            String(args.height),
+          ],
+          "window resize",
+          sessionId,
+        )) as { window_id: number; width: number; height: number };
+        return {
+          session: sessionId,
+          windowId: reply.window_id,
+          width: reply.width,
+          height: reply.height,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "window",
+          "resize",
+          "--session",
+          args.session ?? "(current)",
+          "--width",
+          String(args.width),
+          "--height",
+          String(args.height),
+        ]),
+        description: "Resize the Agent Window",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

packages/dsh-plugin-browserskill/src/phase-one-tools-tabs.ts

@@ -0,0 +1,402 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import type { PhaseOneRuntime, ToolRegistrar } from "./phase-one-runtime";
+import { requireNonEmpty } from "./phase-one-runtime";
+import { SESSION_PARAM } from "./tool-params";
+import type { ToolDeps } from "./tools";
+
+const TAB_ID_REQUIRED = {
+  type: "integer",
+  required: true,
+  description: "Chrome tab id returned by browser_tab_list or browser_tab_create.",
+} as const;
+
+interface RawTabInfo {
+  tab_id: number;
+  title?: string;
+  url?: string;
+  window_id?: number;
+  active?: boolean;
+  scope?: "user" | "agent";
+}
+
+/** Add Agent Window tab management while preserving the owned-session boundary. */
+export function registerPhaseOneTabTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  const { registry } = deps;
+
+  register(
+    defineTool({
+      name: "browser_tab_list",
+      description:
+        "List tabs visible to an owned browser session. Other sessions' Agent Windows remain " +
+        "hidden; use scope=user to find a user tab before borrowing it.",
+      parameters: {
+        session: SESSION_PARAM,
+        scope: {
+          type: "string",
+          enum: ["user", "agent", "all"],
+          description: "Which tabs to list (default: all).",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabs: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  tabId: { type: "integer", required: true },
+                  title: { type: "string" },
+                  url: { type: "string" },
+                  windowId: { type: "integer" },
+                  active: { type: "boolean" },
+                  scope: { type: "string", enum: ["user", "agent"] },
+                },
+              },
+            },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.tabs.length === 0
+                ? `[session ${value.session}] no matching tabs`
+                : value.tabs
+                    .map(
+                      (tab) =>
+                        `${tab.tabId} [${tab.scope ?? "unknown"}]${tab.active === true ? " [active]" : ""} ` +
+                        `${tab.title ?? "(untitled)"} — ${tab.url ?? "(unknown URL)"}`,
+                    )
+                    .join("\n"),
+          },
+        ],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_list");
+        const cmdArgs = ["tab", "list", "--session", sessionId];
+        if (args.scope !== undefined) cmdArgs.push("--scope", args.scope);
+        const reply = (await runtime.run(exec, cmdArgs, "tab list", sessionId)) as {
+          tabs: RawTabInfo[];
+        };
+        return {
+          session: sessionId,
+          tabs: reply.tabs.map((tab) => ({
+            tabId: tab.tab_id,
+            ...(tab.title !== undefined ? { title: tab.title } : {}),
+            ...(tab.url !== undefined ? { url: tab.url } : {}),
+            ...(tab.window_id !== undefined ? { windowId: tab.window_id } : {}),
+            ...(tab.active !== undefined ? { active: tab.active } : {}),
+            ...(tab.scope !== undefined ? { scope: tab.scope } : {}),
+          })),
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "list",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.scope !== undefined ? ["--scope", args.scope] : []),
+        ]),
+        description: "List browser tabs",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_create",
+      description:
+        "Create a tab inside the owned session's Agent Window. The tab is focused by default; " +
+        "set active=false to open it in the background.",
+      parameters: {
+        session: SESSION_PARAM,
+        url: { type: "string", description: "Initial URL (default: chrome://newtab/)." },
+        active: { type: "boolean", description: "Whether to focus the new tab (default: true)." },
+        index: { type: "integer", description: "Insertion index in the Agent Window tab strip." },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            windowId: { type: "integer", required: true },
+            url: { type: "string", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] created tab ${value.tabId} in window ${value.windowId} (${value.url || "pending URL"})`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        if (args.url !== undefined) requireNonEmpty(args.url, "url");
+        const sessionId = registry.resolve(args.session, "browser_tab_create");
+        const cmdArgs = ["tab", "create", "--session", sessionId];
+        if (args.url !== undefined) cmdArgs.push("--url", args.url);
+        if (args.active === false) cmdArgs.push("--no-active");
+        if (args.index !== undefined) cmdArgs.push("--index", String(args.index));
+        const reply = (await runtime.run(exec, cmdArgs, "tab create", sessionId)) as {
+          tab_id: number;
+          window_id: number;
+          url: string;
+        };
+        if (args.active !== false && reply.url.length > 0) {
+          deps.observation.setUrl(sessionId, reply.url);
+        }
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          windowId: reply.window_id,
+          url: reply.url,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "create",
+          "--session",
+          args.session ?? "(current)",
+          ...(args.url !== undefined ? ["--url", args.url] : []),
+        ]),
+        description: "Create an Agent Window tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_close",
+      description: "Close a tab in the owned session's Agent Window.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          { type: "text", text: `[session ${value.session}] closed tab ${value.tabId}` },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_close");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "close", String(args.tabId), "--session", sessionId],
+          "tab close",
+          sessionId,
+        )) as { tab_id: number };
+        return { session: sessionId, tabId: reply.tab_id };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "close",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Close an Agent Window tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_select",
+      description: "Focus a tab in the owned session's Agent Window.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            windowId: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: `[session ${value.session}] selected tab ${value.tabId} in window ${value.windowId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_select");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "select", String(args.tabId), "--session", sessionId],
+          "tab select",
+          sessionId,
+        )) as { tab_id: number; window_id: number };
+        return { session: sessionId, tabId: reply.tab_id, windowId: reply.window_id };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "select",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Select an Agent Window tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_borrow",
+      description:
+        "Move a user-window tab into the owned session's Agent Window for controlled interaction. " +
+        "Return it with browser_tab_return when finished; stopping the session also auto-returns it.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            originalWindowId: { type: "integer", required: true },
+            originalIndex: { type: "integer", required: true },
+            agentWindowId: { type: "integer", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] borrowed tab ${value.tabId} from window ` +
+              `${value.originalWindowId} into Agent Window ${value.agentWindowId}`,
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_borrow");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "borrow", String(args.tabId), "--session", sessionId],
+          "tab borrow",
+          sessionId,
+        )) as {
+          tab_id: number;
+          original_window_id: number;
+          original_index: number;
+          agent_window_id: number;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          originalWindowId: reply.original_window_id,
+          originalIndex: reply.original_index,
+          agentWindowId: reply.agent_window_id,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "borrow",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Borrow a user tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+
+  register(
+    defineTool({
+      name: "browser_tab_return",
+      description: "Return a borrowed tab to its original user window and tab-strip position.",
+      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            session: { type: "string", required: true },
+            tabId: { type: "integer", required: true },
+            returnedToWindowId: { type: "integer", required: true },
+            returnedToIndex: { type: "integer", required: true },
+            fallback: { type: "boolean", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              `[session ${value.session}] returned tab ${value.tabId} to window ` +
+              `${value.returnedToWindowId} at index ${value.returnedToIndex}` +
+              (value.fallback ? " (original window unavailable; used fallback)" : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const sessionId = registry.resolve(args.session, "browser_tab_return");
+        const reply = (await runtime.run(
+          exec,
+          ["tab", "return", String(args.tabId), "--session", sessionId],
+          "tab return",
+          sessionId,
+        )) as {
+          tab_id: number;
+          returned_to_window_id: number;
+          returned_to_index: number;
+          fallback?: boolean;
+        };
+        return {
+          session: sessionId,
+          tabId: reply.tab_id,
+          returnedToWindowId: reply.returned_to_window_id,
+          returnedToIndex: reply.returned_to_index,
+          fallback: reply.fallback ?? false,
+        };
+      },
+      presentCall: (args) => ({
+        card: "terminal",
+        title: runtime.commandLine([
+          "tab",
+          "return",
+          String(args.tabId),
+          "--session",
+          args.session ?? "(current)",
+        ]),
+        description: "Return a borrowed tab",
+      }),
+      presentResult: runtime.presentTerminalResult,
+    }),
+  );
+}

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

@@ -0,0 +1,18 @@
+import type { PhaseOneRuntime, ToolRegistrar } from "./phase-one-runtime";
+import { registerPhaseOneInteractionTools } from "./phase-one-tools-interaction";
+import { registerPhaseOneNavigationTools } from "./phase-one-tools-navigation";
+import { registerPhaseOneSupportTools } from "./phase-one-tools-support";
+import { registerPhaseOneTabTools } from "./phase-one-tools-tabs";
+import type { ToolDeps } from "./tools";
+
+/** Register the first DSH capability-parity tranche on the existing runtime. */
+export function registerPhaseOneTools(
+  deps: ToolDeps,
+  register: ToolRegistrar,
+  runtime: PhaseOneRuntime,
+): void {
+  registerPhaseOneInteractionTools(deps, register, runtime);
+  registerPhaseOneTabTools(deps, register, runtime);
+  registerPhaseOneNavigationTools(deps, register, runtime);
+  registerPhaseOneSupportTools(deps, register, runtime);
+}

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

@@ -2,10 +2,10 @@
  * Progressive disclosure of the BrowserSkill agent skill through the harness's
  * official skill seam (`ctx.skills`). The catalog entry (name + description)
  * is resident; the body is loaded only when the model invokes the `skill`
- * tool. The markdown is build-time assembled into a static module (dsh
- * prelude + the canonical CLI skill body verbatim), so registration and every
- * pre-step catalog snapshot are pure in-memory reads — no disk, no process,
- * no daemon.
+ * tool. The dedicated DeepSeek Harness markdown is embedded into a static
+ * module at build time, so registration and every pre-step catalog snapshot
+ * are pure in-memory reads — no disk, no process, no daemon. The CLI-oriented
+ * repository skill is intentionally a separate interface.
  */
 
 import type { Context } from "@deepseek-ai/cordis";
@@ -26,7 +26,7 @@ interface SkillsLike {
 }
 
 /**
- * Publish the BSK skill as an embedded runtime skill. Returns the unregistration
+ * Publish the browser skill as an embedded runtime skill. Returns the unregistration
  * disposer. A composition without the `skills` service (or with dsh-tool-skill
  * retired) leaves the rest of the plugin unaffected — the no-op is silent.
  */

packages/dsh-plugin-browserskill/src/tool-params.ts

@@ -0,0 +1,24 @@
+/** Shared model-facing parameter schemas for browser tools. */
+
+export const SESSION_PARAM = {
+  type: "string",
+  description:
+    "bsk session id to act on; must be one created by this plugin's browser_session_start. " +
+    "Omit to use the current session (the one most recently started or used).",
+} as const;
+
+export const TAB_ID_PARAM = {
+  type: "integer",
+  description: "Target tab id. Omit to use the Agent Window's active tab.",
+} as const;
+
+export const WAIT_UNTIL_PARAM = {
+  type: "string",
+  enum: ["load", "domcontentloaded", "networkidle", "commit"],
+  description: "Page lifecycle phase to wait for (default: load).",
+} as const;
+
+export const TIMEOUT_MS_PARAM = {
+  type: "integer",
+  description: "Command timeout in milliseconds; must be greater than zero.",
+} as const;

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

@@ -19,9 +19,11 @@ import {
 } from "@deepseek-ai/dsh-tools";
 import { trySaveScreenshot } from "./image";
 import { actionForLabel, type ObservationService } from "./observation";
+import { registerPhaseOneTools } from "./phase-one-tools";
 import type { KeyedExecutor } from "./queue";
 import { type BskRunner, bskInstallMessage, isCommandNotFound, parseBskJson } from "./runner";
 import type { SessionRegistry } from "./sessions";
+import { SESSION_PARAM } from "./tool-params";
 
 /** Plugin configuration resolved from the Schemastery schema in index.ts. */
 export interface PluginConfig {
@@ -61,13 +63,6 @@ const DEVICE_PRESETS = [
   "galaxy-tab-s8",
 ] as const;
 
-const SESSION_PARAM = {
-  type: "string",
-  description:
-    "bsk session id to act on; must be one created by this plugin's browser_session_start. " +
-    "Omit to use the current session (the one most recently started or used).",
-} as const;
-
 /**
  * Run one bsk command and return its parsed JSON payload, or throw.
  * `observeSession` marks the run as model-facing work on that session: it is
@@ -81,6 +76,7 @@ async function runBsk(
   args: string[],
   label: string,
   observeSession?: string,
+  runnerTimeoutMs?: number,
 ): Promise<unknown> {
   // beginAction must fire only when the task actually starts inside the
   // per-session queue — marking it while still queued would overwrite the
@@ -97,7 +93,7 @@ async function runBsk(
         }
         return deps.runner.run(args, {
           signal: exec.signal,
-          timeoutMs: deps.config.defaultTimeoutMs,
+          timeoutMs: runnerTimeoutMs ?? deps.config.defaultTimeoutMs,
           ...(observeSession !== undefined ? { tag: observeSession } : {}),
         });
       };
@@ -955,6 +951,12 @@ export function registerTools(deps: ToolDeps): () => void {
       presentResult: presentTerminalResult,
     }),
   );
+  registerPhaseOneTools(deps, register, {
+    run: (exec, args, label, observeSession, runnerTimeoutMs) =>
+      runBsk(deps, exec, args, label, observeSession, runnerTimeoutMs),
+    commandLine: (args) => cmdline(deps, args),
+    presentTerminalResult,
+  });
   return () => {
     for (const dispose of disposers.splice(0)) dispose();
   };

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

@@ -5,7 +5,7 @@
 import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   actionForLabel,
@@ -530,6 +530,9 @@ describe("actionForLabel", () => {
     expect(actionForLabel("navigate")).toBe("navigating");
     expect(actionForLabel("screenshot")).toBe("capturing");
     expect(actionForLabel("session start")).toBe("starting");
+    expect(actionForLabel("tab borrow")).toBe("borrowing tab");
+    expect(actionForLabel("request-help")).toBe("waiting for user");
+    expect(actionForLabel("wait-for-navigation")).toBe("waiting for navigation");
   });
 });
 
@@ -548,8 +551,12 @@ describe("scratch files and thumbnail references", () => {
     );
     const firstOut = runner.calls.filter((c) => c.args[0] === "screenshot").at(-1)?.args;
     const pathOf = (args: string[]) => args[args.indexOf("--out") + 1];
-    expect(pathOf(firstOut ?? [])).toBe(join(tmpdir(), "bsk-obs-s1.png"));
-    expect(existsSync(pathOf(firstOut ?? []))).toBe(false);
+    const firstPath = pathOf(firstOut ?? []);
+    expect(dirname(firstPath)).toBe(tmpdir());
+    expect(basename(firstPath)).toMatch(
+      /^bsk-obs-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-[0-9a-f]{16}\.png$/,
+    );
+    expect(existsSync(firstPath)).toBe(false);
     // second frame: same path, deleted again
     service.endAction("s1");
     scheduler.runNext();
@@ -559,11 +566,33 @@ describe("scratch files and thumbnail references", () => {
         scheduler.pending().length === 1,
     );
     const secondOut = runner.calls.filter((c) => c.args[0] === "screenshot").at(-1)?.args;
-    expect(pathOf(secondOut ?? [])).toBe(join(tmpdir(), "bsk-obs-s1.png"));
-    await waitFor(() => !existsSync(pathOf(secondOut ?? [])));
+    const secondPath = pathOf(secondOut ?? []);
+    expect(secondPath).toBe(firstPath);
+    await waitFor(() => !existsSync(secondPath));
     service.dispose();
   });
 
+  it("isolates scratch paths between service instances", async () => {
+    const first = setup({ scheduler: fakeScheduler(), runner: fakeRunner() });
+    const second = setup({ scheduler: fakeScheduler(), runner: fakeRunner() });
+    first.service.addSession("s1");
+    second.service.addSession("s1");
+    first.scheduler.runNext();
+    second.scheduler.runNext();
+    await waitFor(
+      () =>
+        first.service.getState()[0]?.thumbnailAttachmentId !== undefined &&
+        second.service.getState()[0]?.thumbnailAttachmentId !== undefined,
+    );
+    const pathOf = (runner: FakeRunner) => {
+      const args = runner.calls.find((call) => call.args[0] === "screenshot")?.args ?? [];
+      return args[args.indexOf("--out") + 1];
+    };
+    expect(pathOf(first.runner)).not.toBe(pathOf(second.runner));
+    first.service.dispose();
+    second.service.dispose();
+  });
+
   it("keeps the last two distinct frames and evicts the third", async () => {
     let n = 0;
     const runner = fakeRunner({

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

@@ -1,4 +1,4 @@
-// BSK skill injection: registration wiring, catalog content, progressive-load
+// Browser skill injection: registration wiring, catalog content, progressive-load
 // weight, and silent degradation without the skill seam.
 
 import { describe, expect, it } from "vitest";
@@ -9,7 +9,7 @@ function fakeCtx(skills?: unknown) {
 }
 
 describe("registerBskSkill", () => {
-  it("registers the catalog entry with the assembled body", () => {
+  it("registers the catalog entry with the DSH browser-tool body", () => {
     const registrations: { skill: Record<string, unknown>; disposer: () => void }[] = [];
     const skills = {
       register(skill: Record<string, unknown>) {
@@ -26,23 +26,51 @@ describe("registerBskSkill", () => {
     expect(skill.name).toBe("browser-skill");
     expect(typeof skill.description).toBe("string");
     expect(String(skill.description)).toContain("browser_*");
-    // body = dsh prelude + canonical CLI skill body + dsh postlude
     const content = String(skill.content);
-    expect(content).toContain("browser_observe");
-    expect(String(skill.description)).toContain("never invoke bsk through bash or shell");
-    expect(content).toContain("Always call those injected `browser_*` tools");
-    expect(content).toContain("Never use `bash`, `shell`, `exec`");
-    expect(content).toContain("## DSH routing reminder");
-    expect(content.trimEnd()).toMatch(
-      /always begin with[\s\S]*`browser_session_start`[\s\S]*`browser_session_stop`\.$/,
-    );
-    expect(content).toContain("Owned sessions only");
+    const mentionedTools = [...new Set(content.match(/\bbrowser_[a-z][a-z_]*\b/g) ?? [])].sort();
+    expect(mentionedTools).toEqual([
+      "browser_click",
+      "browser_console",
+      "browser_emulate",
+      "browser_fill",
+      "browser_get_html",
+      "browser_hover",
+      "browser_navigate",
+      "browser_navigate_back",
+      "browser_navigate_forward",
+      "browser_network",
+      "browser_observe",
+      "browser_press",
+      "browser_reload",
+      "browser_request_help",
+      "browser_screenshot",
+      "browser_select",
+      "browser_session_list",
+      "browser_session_start",
+      "browser_session_stop",
+      "browser_snapshot",
+      "browser_tab_borrow",
+      "browser_tab_close",
+      "browser_tab_create",
+      "browser_tab_list",
+      "browser_tab_return",
+      "browser_tab_select",
+      "browser_wait_for_navigation",
+      "browser_window_resize",
+    ]);
+    expect(String(skill.description)).not.toMatch(/\bbsk\b/i);
+    expect(content).not.toMatch(/\bbsk\b/i);
+    expect(content).not.toMatch(/```(?:bash|sh|shell)\b/i);
+    expect(content).not.toMatch(/--[a-z]/);
+    expect(content).toContain("All browser operations must use the injected tools directly");
     expect(content).toContain("Mandatory workflow");
     expect(content).toContain("Refs invalidate after navigation");
+    expect(content).toContain("evaluation and interaction recording are intentionally unsupported");
     expect(content.length).toBeGreaterThan(10_000);
     expect(skill.source).toBe("bundled");
-    // the original YAML frontmatter must not leak into the body
-    expect(content.includes("name: browser-skill\ndescription:")).toBe(false);
+    // Source frontmatter is registration metadata and must not leak into the body.
+    expect(content.startsWith("---")).toBe(false);
+    expect(content).not.toContain("name: browser-skill\ndescription:");
     // disposer passthrough
     unregister();
     expect(skill.__disposed).toBe(true);

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

@@ -142,16 +142,33 @@ describe("tool registration", () => {
     const { tools } = setup({});
     expect([...tools.keys()].sort()).toEqual([
       "browser_click",
+      "browser_console",
       "browser_emulate",
       "browser_fill",
+      "browser_get_html",
+      "browser_hover",
       "browser_navigate",
+      "browser_navigate_back",
+      "browser_navigate_forward",
+      "browser_network",
       "browser_observe",
       "browser_press",
+      "browser_reload",
+      "browser_request_help",
       "browser_screenshot",
+      "browser_select",
       "browser_session_list",
       "browser_session_start",
       "browser_session_stop",
       "browser_snapshot",
+      "browser_tab_borrow",
+      "browser_tab_close",
+      "browser_tab_create",
+      "browser_tab_list",
+      "browser_tab_return",
+      "browser_tab_select",
+      "browser_wait_for_navigation",
+      "browser_window_resize",
     ]);
   });
 
@@ -436,6 +453,336 @@ describe("interaction tools", () => {
       /mutually exclusive/,
     );
   });
+
+  it("browser_hover and browser_select map their structured arguments", async () => {
+    const { tools, calls } = setup({
+      "session start": START_REPLY("s1"),
+      hover: { tab_id: 7, used_ref: "@e3", x: 12, y: 24 },
+      select: {
+        tab_id: 7,
+        used_ref: "@e4",
+        multiple: true,
+        selected_values: ["a", "b"],
+        selected_labels: ["Alpha", "Beta"],
+      },
+    });
+    await startSession(tools);
+    const hovered = (await tools
+      .get("browser_hover")
+      ?.execute(
+        { target: "@e3", modifiers: ["shift"], settleMs: 250, timeoutMs: 2000 },
+        makeExec(),
+      )) as { x: number; y: number };
+    expect(hovered).toMatchObject({ x: 12, y: 24 });
+    expect(calls[1].args).toEqual([
+      "hover",
+      "--session",
+      "s1",
+      "--modifiers",
+      "shift",
+      "--settle",
+      "250ms",
+      "--timeout",
+      "2000ms",
+      "@e3",
+    ]);
+
+    const selected = (await tools
+      .get("browser_select")
+      ?.execute({ target: "@e4", values: ["a", "b"], tabId: 7 }, makeExec())) as {
+      selectedValues: string[];
+      selectedLabels: string[];
+    };
+    expect(selected).toMatchObject({
+      selectedValues: ["a", "b"],
+      selectedLabels: ["Alpha", "Beta"],
+    });
+    expect(calls[2].args).toEqual([
+      "select",
+      "--session",
+      "s1",
+      "--tab-id",
+      "7",
+      "--value",
+      "a",
+      "--value",
+      "b",
+      "@e4",
+    ]);
+  });
+});
+
+describe("phase-one tab tools", () => {
+  it("maps list/create/close/select/borrow/return through the owned session", async () => {
+    const { tools, calls } = setup({
+      "session start": START_REPLY("s1"),
+      "tab list": {
+        tabs: [
+          {
+            tab_id: 7,
+            title: "Example",
+            url: "https://example.test",
+            window_id: 2,
+            active: true,
+            scope: "agent",
+          },
+        ],
+      },
+      "tab create": { tab_id: 8, window_id: 2, url: "https://new.test" },
+      "tab close": { tab_id: 8 },
+      "tab select": { tab_id: 7, window_id: 2 },
+      "tab borrow": {
+        tab_id: 20,
+        original_window_id: 9,
+        original_index: 1,
+        agent_window_id: 2,
+      },
+      "tab return": {
+        tab_id: 20,
+        returned_to_window_id: 9,
+        returned_to_index: 1,
+        fallback: false,
+      },
+    });
+    await startSession(tools);
+
+    const listed = (await tools
+      .get("browser_tab_list")
+      ?.execute({ scope: "agent" }, makeExec())) as { tabs: { tabId: number }[] };
+    expect(listed.tabs[0].tabId).toBe(7);
+    const created = (await tools
+      .get("browser_tab_create")
+      ?.execute({ url: "https://new.test", active: false, index: 1 }, makeExec())) as {
+      tabId: number;
+    };
+    expect(created.tabId).toBe(8);
+    await tools.get("browser_tab_close")?.execute({ tabId: 8 }, makeExec());
+    await tools.get("browser_tab_select")?.execute({ tabId: 7 }, makeExec());
+    const borrowed = (await tools
+      .get("browser_tab_borrow")
+      ?.execute({ tabId: 20 }, makeExec())) as { originalWindowId: number };
+    expect(borrowed.originalWindowId).toBe(9);
+    const returned = (await tools
+      .get("browser_tab_return")
+      ?.execute({ tabId: 20 }, makeExec())) as { fallback: boolean };
+    expect(returned.fallback).toBe(false);
+
+    expect(calls.slice(1).map((call) => call.args)).toEqual([
+      ["tab", "list", "--session", "s1", "--scope", "agent"],
+      [
+        "tab",
+        "create",
+        "--session",
+        "s1",
+        "--url",
+        "https://new.test",
+        "--no-active",
+        "--index",
+        "1",
+      ],
+      ["tab", "close", "8", "--session", "s1"],
+      ["tab", "select", "7", "--session", "s1"],
+      ["tab", "borrow", "20", "--session", "s1"],
+      ["tab", "return", "20", "--session", "s1"],
+    ]);
+  });
+});
+
+describe("phase-one navigation tools", () => {
+  it("maps back/forward/reload/wait and preserves timeout budgets", async () => {
+    const { tools, calls } = setup({
+      "session start": START_REPLY("s1"),
+      "navigate-back": {
+        tab_id: 7,
+        previous_url: "https://b.test",
+        final_url: "https://a.test",
+        reached: "load",
+      },
+      "navigate-forward": {
+        tab_id: 7,
+        previous_url: "https://a.test",
+        final_url: "https://b.test",
+        reached: "load",
+      },
+      reload: {
+        tab_id: 7,
+        previous_url: "https://b.test",
+        final_url: "https://b.test",
+        reached: "networkidle",
+      },
+      "wait-for-navigation": { tab_id: 7, reached: "timeout", error_text: "no navigation" },
+    });
+    await startSession(tools);
+    await tools
+      .get("browser_navigate_back")
+      ?.execute({ tabId: 7, waitUntil: "commit", timeoutMs: 1000 }, makeExec());
+    await tools.get("browser_navigate_forward")?.execute({}, makeExec());
+    await tools
+      .get("browser_reload")
+      ?.execute({ hard: true, waitUntil: "networkidle" }, makeExec());
+    const waited = (await tools
+      .get("browser_wait_for_navigation")
+      ?.execute({ timeoutMs: 2500 }, makeExec())) as { reached: string; errorText: string };
+    expect(waited).toMatchObject({ reached: "timeout", errorText: "no navigation" });
+    expect(calls[1].args).toEqual([
+      "navigate-back",
+      "--session",
+      "s1",
+      "--tab-id",
+      "7",
+      "--wait-until",
+      "commit",
+      "--timeout",
+      "1000ms",
+    ]);
+    expect(calls[2].args).toEqual(["navigate-forward", "--session", "s1"]);
+    expect(calls[3].args).toEqual([
+      "reload",
+      "--session",
+      "s1",
+      "--wait-until",
+      "networkidle",
+      "--hard",
+    ]);
+    expect(calls[4].args).toEqual([
+      "wait-for-navigation",
+      "--session",
+      "s1",
+      "--timeout",
+      "2500ms",
+    ]);
+    expect(calls[4].options.timeoutMs).toBe(120_000);
+  });
+});
+
+describe("phase-one support tools", () => {
+  it("maps request-help targets and structured completion criteria", async () => {
+    const { tools, calls } = setup({
+      "session start": START_REPLY("s1"),
+      "request-help": {
+        outcome: "completed",
+        completed_by: "system",
+        note: "signed in",
+        tab_id: 7,
+        resolved_targets: [{ matched: true, ref: "@e3" }],
+      },
+    });
+    await startSession(tools);
+    const value = (await tools.get("browser_request_help")?.execute(
+      {
+        prompt: "Please sign in",
+        title: "Login required",
+        targets: ["@e3", "#submit"],
+        timeoutMs: 300_000,
+        completionCriteria: {
+          any: [{ urlContains: "/dashboard" }, { selectorExists: "[data-user]" }],
+          stableForMs: 1000,
+        },
+      },
+      makeExec(),
+    )) as { outcome: string; note: string };
+    expect(value).toMatchObject({ outcome: "completed", note: "signed in" });
+    expect(calls[1].options.timeoutMs).toBe(315_000);
+    expect(calls[1].args.slice(0, 8)).toEqual([
+      "request-help",
+      "--session",
+      "s1",
+      "--prompt",
+      "Please sign in",
+      "--timeout",
+      "300000ms",
+      "--title",
+    ]);
+    const criteriaIndex = calls[1].args.indexOf("--completion-criteria");
+    expect(JSON.parse(calls[1].args[criteriaIndex + 1])).toEqual({
+      any: [{ url_contains: "/dashboard" }, { selector_exists: "[data-user]" }],
+      stable_for_ms: 1000,
+    });
+  });
+
+  it("maps get-html, console, and network results without raw shell access", async () => {
+    const { tools, calls } = setup({
+      "session start": START_REPLY("s1"),
+      "get-html": { tab_id: 7, html: "<main>Hi</main>", truncated: false, byte_size: 15 },
+      console: {
+        tab_id: 7,
+        entries: [
+          {
+            sequence: 3,
+            kind: "exception",
+            level: "error",
+            text: "boom",
+            stack_trace: [{ function_name: "run", url: "https://a.test/app.js", line: 4 }],
+          },
+        ],
+        next_since: 3,
+        truncated: false,
+      },
+      network: {
+        tab_id: 7,
+        entries: [
+          {
+            sequence: 5,
+            kind: "response",
+            method: "GET",
+            url: "https://a.test/api",
+            status: 200,
+            mime_type: "application/json",
+          },
+        ],
+        next_since: 5,
+        truncated: false,
+      },
+    });
+    await startSession(tools);
+    const html = (await tools
+      .get("browser_get_html")
+      ?.execute({ ref: "@e2", maxBytes: 2048 }, makeExec())) as { html: string };
+    expect(html.html).toBe("<main>Hi</main>");
+    const consoleValue = (await tools
+      .get("browser_console")
+      ?.execute({ since: 1, limit: 10, includeStack: true }, makeExec())) as {
+      entries: { stackTrace: { functionName: string }[] }[];
+    };
+    expect(consoleValue.entries[0].stackTrace[0].functionName).toBe("run");
+    const networkValue = (await tools
+      .get("browser_network")
+      ?.execute({ tabId: 7, maxTextChars: 512 }, makeExec())) as {
+      entries: { mimeType: string }[];
+    };
+    expect(networkValue.entries[0].mimeType).toBe("application/json");
+    expect(calls.slice(1).map((call) => call.args)).toEqual([
+      ["get-html", "--session", "s1", "--ref", "@e2", "--max-bytes", "2048"],
+      ["console", "--session", "s1", "--since", "1", "--limit", "10", "--include-stack"],
+      ["network", "--session", "s1", "--tab-id", "7", "--max-text-chars", "512"],
+    ]);
+  });
+
+  it("resizes only within the CLI-supported range", async () => {
+    const { tools, calls } = setup({
+      "session start": START_REPLY("s1"),
+      "window resize": { window_id: 2, width: 1280, height: 800 },
+    });
+    await startSession(tools);
+    const resize = tools.get("browser_window_resize");
+    const value = (await resize?.execute({ width: 1280, height: 800 }, makeExec())) as {
+      windowId: number;
+    };
+    expect(value.windowId).toBe(2);
+    expect(calls[1].args).toEqual([
+      "window",
+      "resize",
+      "--session",
+      "s1",
+      "--width",
+      "1280",
+      "--height",
+      "800",
+    ]);
+    await expect(resize?.execute({ width: 99, height: 800 }, makeExec())).rejects.toThrow(
+      /100\.\.=7680/,
+    );
+  });
 });
 
 describe("browser_screenshot", () => {

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

@@ -24,6 +24,10 @@ function scene(nodes: VomNode[]): VomScene {
   };
 }
 
+function coreRefs(refs: ReturnType<typeof renderVom>["refs"]) {
+  return refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }));
+}
+
 describe("renderVom single-layer page", () => {
   it("does not derive handle context across frame scopes", () => {
     const out = renderVom(
@@ -130,7 +134,7 @@ describe("renderVom single-layer page", () => {
         '      @e2 button "加入购物车"',
       ].join("\n"),
     );
-    expect(out.refs).toEqual([
+    expect(coreRefs(out.refs)).toEqual([
       { ref: "e1", backendNodeId: 3 },
       { ref: "e2", backendNodeId: 6 },
     ]);
@@ -151,7 +155,7 @@ describe("renderVom single-layer page", () => {
     expect(out.text).toContain('    heading "Title"');
     expect(out.text).toContain('    img "Logo"');
     expect(out.text).toContain('    @e1 button "Continue"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 4 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 4 }]);
   });
 
   it("assigns refs to listbox controls", () => {
@@ -163,7 +167,7 @@ describe("renderVom single-layer page", () => {
     );
 
     expect(out.text).toContain('    @e1 listbox "Choices"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
   it("annotates external links regardless of role casing", () => {
@@ -200,7 +204,7 @@ describe("renderVom single-layer page", () => {
     expect(out.text).toContain("    alertdialog");
     expect(out.text).toContain("      section");
     expect(out.text).toContain('        @e1 button "Close"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 5 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 5 }]);
   });
 
   it("skips generic nodes without adding an extra indentation level", () => {
@@ -291,7 +295,7 @@ describe("renderVom single-layer page", () => {
     expect(out.text).toContain("    section");
     expect(out.text).not.toContain("Too deep");
     expect(out.text).toContain('    @e1 button "Later"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 4 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 4 }]);
   });
 
   it("truncates when maxTokens is exceeded while keeping refs in sync with rendered text", () => {
@@ -326,7 +330,7 @@ describe("renderVom single-layer page", () => {
     );
 
     expect(out.text).toContain('@e1 button "Open settings"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
   it("keeps the deepest custom control when wrapper and child both look clickable", () => {
@@ -356,7 +360,7 @@ describe("renderVom single-layer page", () => {
 
     expect(out.text).not.toContain('@e1 button "Card"');
     expect(out.text).toContain('@e1 button "Details"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 3 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 3 }]);
   });
 
   it("does not recover clickable wrappers around native controls", () => {
@@ -379,7 +383,7 @@ describe("renderVom single-layer page", () => {
 
     expect(out.text).not.toContain('@e1 button "Checkout"');
     expect(out.text).toContain('@e1 button "Pay"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 3 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 3 }]);
   });
 
   it("adds context to duplicate weak action labels", () => {
@@ -442,7 +446,7 @@ describe("renderVom single-layer page", () => {
 
     expect(out.text).toContain("@layers 1 focus=L1");
     expect(out.text).toContain('@e1 button "Background"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
   it("can filter refs blocked by active positioned regions without changing layer output", () => {
@@ -485,7 +489,7 @@ describe("renderVom single-layer page", () => {
     expect(out.text).not.toContain("active-region");
     expect(out.text).not.toContain("Background");
     expect(out.text).toContain('@e1 button "Foreground"');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 4 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 4 }]);
   });
 
   it("keeps paint-order comparisons inside their frame document", () => {
@@ -600,7 +604,7 @@ describe("renderVom single-layer page", () => {
     });
 
     expect(out.text).toContain('@e1 button "Products" [hover first: Shoes | Bags | Accessories]');
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
   it("injects active scope blocks immediately after their trigger without refs", () => {
@@ -626,7 +630,7 @@ describe("renderVom single-layer page", () => {
         "        Bob - great sound",
       ].join("\n"),
     );
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
   it("does not render redundant children inside named ref controls", () => {
@@ -640,7 +644,7 @@ describe("renderVom single-layer page", () => {
 
     expect(out.text).toContain('@e1 button "Save"');
     expect(out.text).not.toContain("disk icon");
-    expect(out.refs).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
   it("does not render redundant children inside native text inputs", () => {
@@ -807,7 +811,7 @@ describe("renderVom double-layer page", () => {
       ].join("\n"),
     );
     expect(out.text).not.toContain("底层按钮");
-    expect(out.refs).toEqual([
+    expect(coreRefs(out.refs)).toEqual([
       { ref: "e1", backendNodeId: 4 },
       { ref: "e2", backendNodeId: 5 },
     ]);
@@ -859,4 +863,36 @@ describe("renderVom double-layer page", () => {
     expect(out.text).toContain('    @e2 textbox "密码" [filled] ="•••"');
     expect(out.refs.map((r) => r.backendNodeId)).toEqual([101, 102]);
   });
+
+  it("redacts form values and returns semantic metadata for rendered refs", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Form" }),
+        node({
+          id: 2,
+          backendNodeId: 42,
+          frameId: "child-frame",
+          parentId: 1,
+          role: "textbox",
+          name: "Email",
+          value: "user@example.com",
+          inputState: "filled",
+          tag: "input",
+        }),
+      ]),
+      { redactValues: true },
+    );
+
+    expect(out.text).toContain('[filled] ="•••"');
+    expect(out.text).not.toContain("user@example.com");
+    expect(out.refs[0]).toMatchObject({
+      ref: "e1",
+      backendNodeId: 42,
+      frameId: "child-frame",
+      role: "textbox",
+      name: "Email",
+      line: expect.any(Number),
+    });
+    expect(out.text.split("\n")[out.refs[0]?.line ?? -1]).toContain('@e1 textbox "Email"');
+  });
 });

packages/vom/src/index.ts

@@ -5,6 +5,7 @@ export type {
   CondSurface,
   LayerKind,
   Rect,
+  RenderedRef,
   Viewport,
   VomNode,
   VomOptions,

packages/vom/src/render.ts

@@ -4,9 +4,9 @@ import type {
   BlockingLayer,
   CondSurface,
   Rect,
+  RenderedRef,
   VomNode,
   VomOptions,
-  VomRef,
   VomResult,
   VomScene,
 } from "./types";
@@ -615,6 +615,7 @@ function renderNodeLine(
   ref: string | undefined,
   context: string[] = [],
   surface: CondSurface | undefined = undefined,
+  redactValues = false,
 ): string {
   let line = `${"  ".repeat(depth)}${ref ? `@${ref} ` : ""}${node.role}`;
 
@@ -636,13 +637,14 @@ function renderNodeLine(
   }
   const placeholder = cleaned(node.placeholder);
   if (placeholder) line += ` placeholder=${JSON.stringify(placeholder)}`;
-  const sensitiveHasValue =
+  const hasValue =
     rawValue !== undefined || node.inputState === "filled" || node.inputState === "default";
-  const value = node.sensitive
-    ? sensitiveHasValue
-      ? SENSITIVE_MASK
-      : undefined
-    : rawValue?.slice(0, MAX_VALUE_LENGTH);
+  const value =
+    node.sensitive || redactValues
+      ? hasValue
+        ? SENSITIVE_MASK
+        : undefined
+      : rawValue?.slice(0, MAX_VALUE_LENGTH);
   if (value !== undefined) line += ` =${JSON.stringify(value)}`;
 
   if (surface && surface.subItems.length > 0) {
@@ -695,11 +697,12 @@ function shouldSkipRedundantChildren(node: VomNode, state: RenderState): boolean
 
 interface RenderState {
   lines: string[];
-  refs: VomRef[];
+  refs: RenderedRef[];
   nextRef: number;
   tokens: number;
   maxDepth: number;
   maxTokens: number;
+  redactValues: boolean;
   truncated: boolean;
   stopped: boolean;
   children: Map<number | null, VomNode[]>;
@@ -764,7 +767,7 @@ function renderTree(
     const ref = isVomReferenceNode(node) ? `e${state.nextRef}` : undefined;
     const context = ref ? handleContext(node, state) : [];
     const surface = state.surfaceMap.get(node.id);
-    const line = renderNodeLine(node, depth, ref, context, surface);
+    const line = renderNodeLine(node, depth, ref, context, surface, state.redactValues);
     const nextTokens = state.tokens + estimateTokens(line);
     if (nextTokens > state.maxTokens) {
       state.truncated = true;
@@ -775,10 +778,15 @@ function renderTree(
     state.lines.push(line);
     state.tokens = nextTokens;
     if (ref) {
+      const name = cleaned(node.name);
       state.refs.push({
         ref,
         backendNodeId: node.backendNodeId ?? node.id,
         ...(node.frameId ? { frameId: node.frameId } : {}),
+        ...(node.role ? { role: node.role } : {}),
+        ...(name ? { name } : {}),
+        ...(context.length > 0 ? { ctx: context.join(" > ") } : {}),
+        line: state.lines.length - 1,
       });
       state.nextRef += 1;
     }
@@ -808,6 +816,7 @@ function renderNodes(
     tokens: estimateTokens(initialLines.join("\n")),
     maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
     maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+    redactValues: options.redactValues ?? false,
     truncated: false,
     stopped: false,
     children,

packages/vom/src/types.ts

@@ -64,6 +64,10 @@ export interface VomScene {
 export interface VomOptions {
   maxDepth?: number;
   maxTokens?: number;
+  /**
+   * When true, form values are rendered as masks instead of literal values.
+   */
+  redactValues?: boolean;
   /**
    * Experimental: filter refs that are geometrically blocked by foreground
    * fixed/absolute/sticky regions. Disabled by default and does not alter the
@@ -90,9 +94,17 @@ export interface VomRef {
   frameId?: string;
 }
 
+export interface RenderedRef extends VomRef {
+  role?: string;
+  name?: string;
+  ctx?: string;
+  /** Zero-based line index in `VomResult.text`. */
+  line: number;
+}
+
 export interface VomResult {
   text: string;
-  refs: VomRef[];
+  refs: RenderedRef[];
   truncated: boolean;
 }
 

skill/SKILL.md

@@ -206,29 +206,6 @@ 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 |