@opencode/plugin-browser 0.0.0-reserved → 2.0.1

package/README.md

@@ -1,5 +1,128 @@
-# @opencode/plugin-browser
+# Browser plugin
 
-This package is reserved for OpenCode's desktop browser plugin. This bootstrap
-version is not a functional release. The implementation is published by the
-`anomalyco/opencode` repository's release workflow.
+`@opencode/plugin-browser` exposes the desktop browser through Code Mode.
+The server owns tools, invocation scope, and permissions; the desktop owns tabs,
+CDP, captured traffic, evaluations, and capture files. Core only registers the
+plugin. Neither endpoint imports the other's implementation.
+
+```js
+const tab = await tools.browser.tabs.open({ url: "https://example.com" })
+return await tools.browser.snapshot({ tabID: tab.id })
+```
+
+All page operations require a `tabID` returned by `browser.tabs.open/list`.
+Focus selects the visible Review tab, not an implicit command target. Discover
+current signatures with `search({ namespace: "browser" })`.
+Screenshots require a focused, visible tab; call `browser.tabs.focus` first.
+
+## Tools
+
+- Tabs: `tabs.list`, `tabs.open`, `tabs.focus`, `tabs.close`.
+- Navigation: `navigate`, `back`, `forward`, `reload`, `stop`, `frames`.
+- Observation: `snapshot`, `find`, `evaluate`, `wait`, `screenshot`.
+- Input: `click`, `hover`, `drag`, `fill`, `fill_form`, `select`, `check`, `press`, `scroll`, `dialog`.
+- Files: `files.upload`, `files.drop`, `files.list`, `files.get`.
+- Diagnostics: `console`, `network.list`, `network.get`.
+- Performance: `trace.start`, `trace.stop`, `trace.analyze`, `cpu.start`, `cpu.stop`, `cpu.analyze`.
+- Memory: `heap.snapshot`, `heap.summary`, `heap.query`, `heap.object`, `heap.compare`.
+- Audits: `lighthouse` (accessibility, SEO, best practices).
+
+The source of truth for inputs, descriptions, and outputs is
+`Browser.Operations` in `@opencode/plugin-browser/rpc`.
+
+The plugin entrypoint only composes its two owners: `connection.ts` manages
+desktop attachments and pending RPC requests; `tools.ts` runs the tool workflow.
+Server-local file IO stays in `files.ts`. The public `rpc.ts` entrypoint remains
+pure and does not load any of these runtime modules.
+
+## Tests
+
+Run `bun test` and `bun typecheck` from this package for its contract checks.
+Native browser coverage lives with the desktop implementation
+(`packages/desktop/test/browser-native.test.ts`), not in this package.
+
+## RPC
+
+The plugin-owned contract is `@opencode/plugin-browser/rpc`. This entrypoint
+contains only schemas and descriptions; it does not load the server plugin or
+filesystem code. The desktop subscribes
+to control events before starting `attach` with `version: 4`. The attachment call
+stays pending for its lifetime. A matching `attached` event is the readiness barrier.
+
+- `state` publishes the authoritative tab inventory. Tab lookups read only this
+  inventory, so the desktop must publish `state` and wait for its acknowledgment
+  before sending `result` for `tabs.open` or `tabs.close`.
+- `control` announces a request ID or cancellation; it never broadcasts arguments,
+  script source, file bytes, or browser results on the server-wide event feed.
+- `command` retrieves the pending request through authenticated RPC.
+- `result` completes it. The plugin validates the selected operation's output.
+- Inspection commands return only target/source metadata. Execution checks that
+  the approved target has not changed while permission was pending.
+- `attach` returns `replaced` when another desktop takes ownership. That is not
+  a retryable disconnect; the old desktop must not reclaim the session automatically.
+
+The connection ID is correlation, not separate client authentication. Requests
+are bound to their attachment and tab. Disconnect, replacement, session movement,
+and unload fail outstanding work. Calls are not replayed automatically: a lost
+response does not prove that a click or evaluation never happened.
+
+## Files and remote servers
+
+Upload paths are **server-local**. File bytes cross RPC and the desktop writes its
+own temporary copy. Captures/downloads travel back as bounded bytes and are saved
+to server-local temporary files. Returned `files[].path` values refer to that
+server; bytes are not included in the model's structured output. Images are also
+attached for the model to inspect. Temporary exports are not deleted on plugin
+reload, so a returned path remains usable; they follow the host's temporary-file
+lifetime.
+
+Each transfer is limited to 5 MiB total. There is no shared filesystem assumption,
+resumable file-transfer service or object store. Browsing uses the connected
+server's network: `localhost:8000` reaches that server's port 8000, while Chromium
+and page JavaScript still run on the desktop. Dev-server ports need not be public.
+
+`tunnel.open/read/write/close` relay bounded TCP chunks through the existing
+authenticated plugin RPC route. The desktop-only `/proxy` entrypoint adapts
+Chromium's HTTP/CONNECT proxy traffic, including WebSockets, to those methods.
+Network bytes never go onto the global event stream. Attachment closure releases
+the sockets; failed writes are not replayed and there is no direct-network fallback.
+The tunnel relays whatever a loaded page requests and is not filtered per request:
+page traffic has the server host's network reach, including its loopback and LAN.
+
+Remote endpoints can use HTTPS and the existing server credentials. A reverse
+proxy must allow long-lived event and attachment requests; the attachment RPC
+stays open rather than sending response-body heartbeats.
+
+Lighthouse audits use snapshot mode without changing device emulation or adding
+an embedded report screenshot; use `browser.screenshot` for images. Trace exports
+contain the target renderer process, not the whole desktop application. A tab
+process change or trace-buffer loss is reported as an incomplete capture. Heap
+summaries report shallow size, not computed retained size, and do not prove leaks.
+
+All page-derived data is untrusted, including structured outputs. Schema
+validation does not make page text an instruction or grant it authority.
+
+## Recovering from errors
+
+Errors name the failed operation and the next supported action. Refresh tab IDs
+with `browser.tabs.list`, element refs with `browser.snapshot`, and frame IDs with
+`browser.frames`. File and network request IDs must come from the same tab's
+current listing. Trace, CPU, and heap files are not interchangeable.
+
+A timeout, cancellation, or disconnection does not prove the action never ran.
+Inspect the tab and completed files before repeating clicks, uploads, submissions,
+or evaluations. Do not retry a permission denial through another tool or weaken
+browser security to work around a TLS or unsupported-operation error.
+
+File errors distinguish server-local upload paths from desktop capture files.
+Pending/failed downloads and unavailable response bodies are not empty files.
+Oversized output requires a smaller request or capture, not an identical retry.
+
+Per-URL and server-file permission checks belong to the final permission layer
+(#46530). This base plugin layer intentionally does not enforce those rules.
+
+Disable through normal configuration:
+
+```jsonc
+{ "plugins": ["-opencode.browser"] }
+```

package/dist/connection.d.ts

@@ -0,0 +1,234 @@
+export * as BrowserConnection from "./connection.js";
+import type { Context } from "@opencode/plugin/effect/plugin";
+import { Tool } from "@opencode/schema/tool";
+import { Effect } from "effect";
+import { Browser } from "./rpc.js";
+export type Connection = Effect.Success<ReturnType<typeof make>>;
+export declare const make: (ctx: Pick<Context, "location" | "rpc" | "event" | "session">) => Effect.Effect<{
+    target: (sessionID: string & import("effect/Brand").Brand<"SessionID">, action: {
+        readonly type: "tabs.list";
+    } | {
+        readonly type: "tabs.open";
+        readonly url?: string | undefined;
+        readonly focus?: boolean | undefined;
+    } | {
+        readonly type: "tabs.focus";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "tabs.close";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "navigate";
+        readonly url: string;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "back";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "forward";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "reload";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "stop";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "frames";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "snapshot";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly ref?: (string & import("effect/Brand").Brand<"Browser.Ref">) | undefined;
+        readonly depth?: number | undefined;
+        readonly boxes?: boolean | undefined;
+        readonly frameID?: string | undefined;
+    } | {
+        readonly type: "find";
+        readonly text: string;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly frameID?: string | undefined;
+    } | {
+        readonly type: "evaluate";
+        readonly script: string;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly frameID?: string | undefined;
+    } | {
+        readonly type: "click";
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly count?: 2 | 1 | undefined;
+        readonly button?: "left" | "right" | "middle" | undefined;
+        readonly modifiers?: readonly ("Alt" | "Control" | "Meta" | "Shift")[] | undefined;
+    } | {
+        readonly type: "hover";
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "drag";
+        readonly from: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly to: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "fill";
+        readonly text: string;
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "fill_form";
+        readonly fields: readonly ({
+            readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+            readonly type: "text";
+            readonly value: string;
+        } | {
+            readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+            readonly type: "select";
+            readonly values: readonly string[];
+        } | {
+            readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+            readonly type: "check";
+            readonly checked: boolean;
+        })[];
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "select";
+        readonly values: readonly string[];
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "check";
+        readonly checked: boolean;
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "press";
+        readonly key: string;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "scroll";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly deltaY: number;
+        readonly deltaX?: number | undefined;
+    } | {
+        readonly type: "wait";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly condition: "text" | "load" | "textGone";
+        readonly text?: string | undefined;
+        readonly frameID?: string | undefined;
+        readonly timeoutMs?: number | undefined;
+    } | {
+        readonly type: "screenshot";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly format?: "png" | "jpeg" | "webp" | undefined;
+        readonly ref?: (string & import("effect/Brand").Brand<"Browser.Ref">) | undefined;
+        readonly fullPage?: boolean | undefined;
+        readonly quality?: number | undefined;
+        readonly maxWidth?: number | undefined;
+    } | {
+        readonly type: "dialog";
+        readonly action: "get" | "accept" | "dismiss";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly promptText?: string | undefined;
+    } | {
+        readonly type: "files.upload";
+        readonly paths: readonly string[];
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "files.drop";
+        readonly paths: readonly string[];
+        readonly ref: string & import("effect/Brand").Brand<"Browser.Ref">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "files.list";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "files.get";
+        readonly fileID: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "console";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly limit?: number | undefined;
+        readonly level?: "error" | "info" | "warning" | "debug" | undefined;
+    } | {
+        readonly type: "network.list";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly limit?: number | undefined;
+        readonly resourceType?: "websocket" | "image" | "media" | "document" | "fetch" | "stylesheet" | "font" | "script" | "xhr" | "eventsource" | "manifest" | "other" | undefined;
+        readonly urlContains?: string | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "network.get";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly includeBody?: boolean | undefined;
+        readonly maxBodyChars?: number | undefined;
+    } | {
+        readonly type: "trace.start";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly durationMs?: number | undefined;
+    } | {
+        readonly type: "trace.stop";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "trace.analyze";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly fileID: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly limit?: number | undefined;
+    } | {
+        readonly type: "cpu.start";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "cpu.stop";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "cpu.analyze";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly fileID: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly limit?: number | undefined;
+    } | {
+        readonly type: "heap.snapshot";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    } | {
+        readonly type: "heap.summary";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly fileID: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly limit?: number | undefined;
+    } | {
+        readonly type: "heap.query";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly fileID: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly name?: string | undefined;
+        readonly limit?: number | undefined;
+    } | {
+        readonly id: number;
+        readonly type: "heap.object";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly fileID: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly limit?: number | undefined;
+    } | {
+        readonly type: "heap.compare";
+        readonly before: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly after: string & import("effect/Brand").Brand<"Browser.FileID">;
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+        readonly limit?: number | undefined;
+    } | {
+        readonly type: "lighthouse";
+        readonly tabID: string & import("effect/Brand").Brand<"Browser.TabID">;
+    }) => Effect.Effect<{
+        tab: {
+            readonly id: string & import("effect/Brand").Brand<"Browser.TabID">;
+            readonly url: string;
+            readonly title: string;
+            readonly loading: boolean;
+            readonly canGoBack: boolean;
+            readonly canGoForward: boolean;
+            readonly generation: number;
+        } | undefined;
+        inspect: () => Effect.Effect<{
+            readonly resources: readonly string[];
+            readonly key: string;
+        }, Tool.Error, never>;
+        request: (files: readonly Browser.File[], target?: Browser.Target) => Effect.Effect<Browser.Result, Tool.Error, never>;
+    }, Tool.Error, never>;
+}, never, import("effect/Scope").Scope>;

package/dist/connection.js

@@ -0,0 +1,133 @@
+export * as BrowserConnection from "./connection.js";
+import { Tool } from "@opencode/schema/tool";
+import { Deferred, Effect, Schema, Stream } from "effect";
+import { Browser } from "./rpc.js";
+import { BrowserTunnel } from "./tunnel.js";
+export const make = Effect.fn("BrowserConnection.make")(function* (ctx) {
+    const browsers = new Map();
+    let active = true;
+    const close = (sessionID, reason = "closed") => Effect.gen(function* () {
+        const browser = browsers.get(sessionID);
+        if (!browser)
+            return;
+        browsers.delete(sessionID);
+        browser.tunnels.dispose();
+        yield* Deferred.succeed(browser.closed, reason);
+    });
+    yield* Effect.addFinalizer(() => {
+        active = false;
+        return Effect.forEach(browsers.keys(), (id) => close(id), { discard: true });
+    });
+    const tunnels = (input) => {
+        const browser = browsers.get(input.sessionID);
+        return browser?.connectionID === input.connectionID
+            ? Effect.succeed(browser.tunnels)
+            : Effect.fail(new Error("Browser attachment is unavailable; its network connections were closed."));
+    };
+    const rpc = yield* ctx.rpc
+        .register(Browser.Definition, {
+        attach: (input, call) => Effect.gen(function* () {
+            const session = yield* ctx.session
+                .get({ sessionID: input.sessionID })
+                .pipe(Effect.mapError(() => call.error("unavailable", "Session not found.", {})));
+            if (session.location.directory !== ctx.location.directory ||
+                session.location.workspaceID !== ctx.location.workspaceID)
+                return yield* Effect.fail(call.error("unavailable", "Session belongs to another location.", {}));
+            const browser = yield* Effect.acquireRelease(Effect.gen(function* () {
+                if (!active)
+                    return yield* Effect.fail(call.error("unavailable", "Browser is unavailable.", {}));
+                yield* close(input.sessionID, "replaced");
+                const browser = {
+                    connectionID: input.connectionID,
+                    state: { tabs: [], focusedTabID: null },
+                    closed: yield* Deferred.make(),
+                    pending: new Map(),
+                    tunnels: BrowserTunnel.make(),
+                };
+                browsers.set(input.sessionID, browser);
+                return browser;
+            }), (browser) => (browsers.get(input.sessionID) === browser ? close(input.sessionID) : Effect.void));
+            yield* rpc.events
+                .emit("control", { type: "attached", connectionID: input.connectionID, version: 4 })
+                .pipe(Effect.orDie);
+            return yield* Deferred.await(browser.closed);
+        }).pipe(Effect.scoped),
+        state: (input, call) => Effect.gen(function* () {
+            const browser = browsers.get(input.sessionID);
+            if (!browser || browser.connectionID !== input.connectionID)
+                return yield* Effect.fail(call.error("unavailable", "Browser is unavailable.", {}));
+            browser.state = input.state;
+        }),
+        command: (input, call) => Effect.gen(function* () {
+            const browser = browsers.get(input.sessionID);
+            const pending = browser?.connectionID === input.connectionID ? browser.pending.get(input.requestID) : undefined;
+            if (!pending)
+                return yield* Effect.fail(call.error("unavailable", "Browser request is no longer available.", {}));
+            return pending.command;
+        }),
+        result: (input, call) => Effect.gen(function* () {
+            const browser = browsers.get(input.sessionID);
+            if (!browser || browser.connectionID !== input.connectionID)
+                return yield* Effect.fail(call.error("unavailable", "Browser is unavailable.", {}));
+            const pending = browser.pending.get(input.requestID);
+            if (!pending)
+                return;
+            if (input.outcome.type === "failure")
+                return yield* Deferred.fail(pending.result, new Tool.Error({ message: `[browser.${input.outcome.code}] ${input.outcome.message}` })).pipe(Effect.asVoid);
+            yield* Deferred.succeed(pending.result, input.outcome.result);
+        }).pipe(Effect.asVoid),
+        "tunnel.open": (input, call) => tunnels(input).pipe(Effect.flatMap((network) => network.open(input.target)), Effect.mapError((error) => call.error("unavailable", error.message, {}))),
+        "tunnel.read": (input, call) => tunnels(input).pipe(Effect.flatMap((network) => network.read(input.tunnelID)), Effect.mapError((error) => call.error("unavailable", error.message, {}))),
+        "tunnel.write": (input, call) => tunnels(input).pipe(Effect.flatMap((network) => network.write(input.tunnelID, input.data, input.end)), Effect.mapError((error) => call.error("unavailable", error.message, {}))),
+        "tunnel.close": (input, call) => tunnels(input).pipe(Effect.flatMap((network) => network.close(input.tunnelID)), Effect.mapError((error) => call.error("unavailable", error.message, {}))),
+    })
+        .pipe(Effect.orDie);
+    yield* ctx.event.subscribe().pipe(Stream.filter((event) => event.type === "session.deleted" || event.type === "session.moved"), Stream.runForEach((event) => close(event.data.sessionID)), Effect.forkScoped({ startImmediately: true }));
+    return {
+        target: Effect.fn("BrowserConnection.target")(function* (sessionID, action) {
+            const browser = browsers.get(sessionID);
+            if (!browser)
+                return yield* new Tool.Error({
+                    message: "[browser.disconnected] No desktop browser is connected to this session. Open this session in the desktop app, enable the experimental browser setting, and wait for it to connect. Then call browser.tabs.list({}). Repeating browser actions while disconnected will not help.",
+                });
+            const tab = "tabID" in action ? browser.state.tabs.find((tab) => tab.id === action.tabID) : undefined;
+            if ("tabID" in action && !tab)
+                return yield* new Tool.Error({
+                    message: "[browser.tab_unavailable] This tab is closed or does not belong to the connected session. Call browser.tabs.list({}) and use an exact returned tabID. If no tabs exist, use browser.tabs.open({}). Never substitute a request ID, file ID, or element ref for tabID.",
+                });
+            // Keep the selected attachment and document, even while permissions or file IO wait.
+            return {
+                tab,
+                inspect: () => request(rpc, browser, action, tab, [], { inspect: true }).pipe(Effect.flatMap((result) => Schema.decodeUnknownEffect(Browser.Target)(result.value)), Effect.mapError((error) => new Tool.Error({
+                    message: error instanceof Tool.Error
+                        ? error.message
+                        : "Browser returned invalid target metadata. Check desktop/plugin versions; no action was authorized.",
+                    error,
+                }))),
+                request: (files, target) => request(rpc, browser, action, tab, files, { target }),
+            };
+        }),
+    };
+});
+const request = Effect.fn("BrowserConnection.request")(function* (rpc, browser, action, tab, files, inspection) {
+    const requestID = crypto.randomUUID();
+    const pending = yield* Deferred.make();
+    const command = (action.type === "files.upload" || action.type === "files.drop") && !inspection.inspect
+        ? { ...action, paths: files.map((file) => file.name) }
+        : action;
+    browser.pending.set(requestID, {
+        command: { action: command, ...(tab ? { generation: tab.generation } : {}), files, ...inspection },
+        result: pending,
+    });
+    return yield* rpc.events.emit("control", { type: "command", connectionID: browser.connectionID, requestID }).pipe(Effect.mapError((error) => new Tool.Error({
+        message: `Could not dispatch browser.${action.type}. Check the desktop connection and call browser.tabs.list({}) before deciding whether to retry.`,
+        error,
+    })), Effect.andThen(Deferred.await(pending)), Effect.raceFirst(Deferred.await(browser.closed).pipe(Effect.andThen(new Tool.Error({
+        message: "[browser.disconnected] Browser connection closed; the action may already have run. Reconnect this session in the desktop app, call browser.tabs.list({}), and inspect the target tab with browser.snapshot({tabID}). Do not repeat clicks, submissions, uploads, or evaluations until their outcome is known.",
+    })))), Effect.onInterrupt(() => rpc.events.emit("control", { type: "cancel", connectionID: browser.connectionID, requestID }).pipe(Effect.ignore)), Effect.timeoutOrElse({
+        duration: "60 seconds",
+        orElse: () => new Tool.Error({
+            message: `[browser.timeout] browser.${action.type} did not finish within 60 seconds; its outcome is unknown. Check the desktop connection, call browser.tabs.list({}), and inspect the tab or browser.files.list({tabID}) for completed work. Do not blindly repeat a mutating action or start another recording.`,
+        }),
+    }), Effect.ensuring(Effect.sync(() => browser.pending.delete(requestID))));
+});

package/dist/files.d.ts

@@ -0,0 +1,18 @@
+export * as BrowserFiles from "./files.js";
+import { Browser } from "./rpc.js";
+import { Tool } from "@opencode/schema/tool";
+import { Effect } from "effect";
+export declare const read: (paths: readonly string[], directory: string) => Effect.Effect<{
+    id: string & import("effect/Brand").Brand<"Browser.FileID">;
+    name: string;
+    mime: string;
+    data: Uint8Array<ArrayBuffer>;
+}[], Tool.Error, never>;
+export declare const save: (files: readonly Browser.File[]) => Effect.Effect<{
+    id: string & import("effect/Brand").Brand<"Browser.FileID">;
+    name: string;
+    mime: string;
+    bytes: number;
+    path: string;
+}[], Tool.Error, never>;
+export declare function captureName(name: string): string;

package/dist/files.js

@@ -0,0 +1,89 @@
+export * as BrowserFiles from "./files.js";
+import { Browser } from "./rpc.js";
+import { Tool } from "@opencode/schema/tool";
+import { Effect } from "effect";
+// Files cross machines as bytes. Only this endpoint interprets its local paths.
+export const read = Effect.fn("BrowserFiles.read")((paths, directory) => Effect.tryPromise({
+    try: async () => {
+        const { open } = await import("node:fs/promises");
+        const { resolve, basename, extname } = await import("node:path");
+        const files = await Promise.all(paths.map(async (input) => {
+            const file = await open(resolve(directory, input), "r");
+            try {
+                const stat = await file.stat();
+                if (!stat.isFile())
+                    throw new Error("Upload paths must name files, not directories. Select a server-local file.");
+                if (stat.size > Browser.MAX_FILE_BYTES)
+                    throw new Error(`Upload is ${stat.size} bytes; the limit is ${Browser.MAX_FILE_BYTES} bytes (5 MiB). Select a smaller file; do not retry the same upload.`);
+                return {
+                    id: Browser.FileID.make(`file_${crypto.randomUUID()}`),
+                    name: basename(input),
+                    mime: types[extname(input).toLowerCase()] ?? "application/octet-stream",
+                    data: new Uint8Array(await file.readFile()),
+                };
+            }
+            finally {
+                await file.close();
+            }
+        }));
+        if (files.reduce((size, file) => size + file.data.byteLength, 0) > Browser.MAX_FILE_BYTES)
+            throw new Error("The selected upload files exceed 5 MiB in total. Send fewer or smaller files; splitting them into one batch does not bypass the total limit.");
+        return files;
+    },
+    catch: (error) => failure("read", error),
+}));
+const types = {
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+};
+export const save = Effect.fn("BrowserFiles.save")((files) => Effect.tryPromise({
+    try: async () => {
+        if (files.length === 0)
+            return [];
+        if (files.reduce((size, file) => size + file.data.byteLength, 0) > Browser.MAX_FILE_BYTES)
+            throw new Error("Capture files exceed the 5 MiB total transfer limit. Use a smaller screenshot, a shorter trace/profile, or a smaller page for heap capture; do not retry the identical capture.");
+        const { mkdtemp, mkdir, writeFile } = await import("node:fs/promises");
+        const { join } = await import("node:path");
+        const { tmpdir } = await import("node:os");
+        const directory = await mkdtemp(join(tmpdir(), "opencode-browser-"));
+        return Promise.all(files.map(async (file, index) => {
+            const name = captureName(file.name);
+            await mkdir(join(directory, String(index)));
+            const path = join(directory, String(index), name);
+            await writeFile(path, file.data, { flag: "wx" });
+            return { id: file.id, name: file.name, mime: file.mime, bytes: file.data.byteLength, path };
+        }));
+    },
+    catch: (error) => failure("save", error),
+}));
+// `.`/`..` escape the per-file directory and Windows resolves device names such as CON.txt regardless of directory.
+export function captureName(name) {
+    const sanitized = name.replace(/[^a-zA-Z0-9._-]/g, "_").slice(-160);
+    if (!sanitized || /^\.{1,2}$/.test(sanitized) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i.test(sanitized))
+        return "capture";
+    return sanitized;
+}
+function failure(operation, error) {
+    const detail = error instanceof Error ? error.message.slice(0, 400) : String(error).slice(0, 400);
+    const code = error instanceof Error && "code" in error && typeof error.code === "string" && !detail.startsWith(error.code)
+        ? `${error.code}: `
+        : "";
+    const recovery = operation === "save"
+        ? "The browser may have completed the capture, but no server-local export is confirmed. Check free space and write access on the server. Use browser.files.list({tabID}) and browser.files.get({tabID,fileID}) to retrieve an existing completed capture instead of repeating its browser action."
+        : "Upload paths are on the server, not the desktop. Check that each path exists, is a file, and is readable on the server; correct paths or select smaller files before retrying.";
+    return new Tool.Error({
+        message: `Cannot ${operation} browser files on the server. ${recovery} Details: ${code}${detail}`,
+        error,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin/effect";
+declare const _default: Plugin.Plugin<import("effect/Scope").Scope>;
+export default _default;

package/dist/index.js

@@ -0,0 +1,11 @@
+import { Plugin } from "@opencode/plugin/effect";
+import { Effect } from "effect";
+import { BrowserConnection } from "./connection.js";
+import { BrowserTools } from "./tools.js";
+export default Plugin.define({
+    id: "opencode.browser",
+    effect: (ctx) => Effect.gen(function* () {
+        const connection = yield* BrowserConnection.make(ctx);
+        yield* BrowserTools.register(ctx, connection);
+    }),
+});

package/dist/proxy.d.ts

@@ -0,0 +1,19 @@
+export * as BrowserProxy from "./proxy.js";
+import { Browser } from "./rpc.js";
+export type Transport = {
+    open(target: Browser.TunnelTarget, signal: AbortSignal): Promise<string>;
+    read(id: string, signal: AbortSignal): Promise<Browser.TunnelRead>;
+    write(id: string, data: Uint8Array, end: boolean, signal: AbortSignal): Promise<void>;
+    close(id: string): Promise<void>;
+};
+export type Proxy = Awaited<ReturnType<typeof make>>;
+export declare function make(transport: Transport): Promise<{
+    url: string;
+    host: string;
+    port: number;
+    credentials: {
+        username: string;
+        password: string;
+    };
+    close(): Promise<void>;
+}>;