@vymalo/opencode-browser 0.7.0

package/dist/endpoint.js

@@ -0,0 +1,117 @@
+import { AgentClient } from "./agent-client.js";
+import { Broker } from "./broker.js";
+import { isAddrInUse } from "./transport.js";
+/**
+ * Unifies host and guest: tries to **bind** the port (election) — on success it
+ * hosts the broker and drives it via an in-process agent; on `EADDRINUSE` it
+ * connects to the existing broker as a guest agent. Re-elects on drop. Tools
+ * call `send()` and never know which mode they're in.
+ */
+export async function createEndpoint(opts, deps) {
+    const url = deps.url ?? `ws://${opts.host}:${opts.port}`;
+    const reelectMs = opts.reelectMs ?? 500;
+    let mode = "electing";
+    let broker = null;
+    let agentClient = null;
+    let current = null;
+    let closed = false;
+    let reelectTimer = null;
+    const scheduleReelect = () => {
+        broker = null;
+        agentClient = null;
+        current = null;
+        mode = "electing";
+        if (closed || reelectTimer) {
+            return;
+        }
+        reelectTimer = setTimeout(() => {
+            reelectTimer = null;
+            void elect();
+        }, reelectMs);
+    };
+    async function elect() {
+        if (closed) {
+            return;
+        }
+        mode = "electing";
+        // 1) Try to host (win the bind).
+        const transport = deps.createServerTransport();
+        const candidate = new Broker({
+            host: opts.host,
+            port: opts.port,
+            token: opts.token,
+            executor: opts.executor,
+            timeoutMs: opts.timeoutMs
+        }, { logger: deps.logger, transport });
+        try {
+            await candidate.start();
+            broker = candidate;
+            current = candidate.createLocalAgent();
+            mode = "host";
+            deps.logger.info("browser_endpoint_mode", { mode: "host" });
+            return;
+        }
+        catch (err) {
+            try {
+                candidate.stop();
+            }
+            catch {
+                /* never bound */
+            }
+            if (!isAddrInUse(err)) {
+                deps.logger.warn("browser_endpoint_bind_error", {
+                    message: err instanceof Error ? err.message : String(err)
+                });
+            }
+        }
+        // 2) Someone else hosts — join as a guest.
+        const client = new AgentClient({ url, token: opts.token, label: opts.label, timeoutMs: opts.timeoutMs }, {
+            logger: deps.logger,
+            createSocket: deps.createAgentSocket,
+            onClose: () => {
+                if (!closed) {
+                    scheduleReelect();
+                }
+            }
+        });
+        try {
+            await client.connect();
+            agentClient = client;
+            current = client;
+            mode = "guest";
+            deps.logger.info("browser_endpoint_mode", { mode: "guest" });
+        }
+        catch {
+            scheduleReelect();
+        }
+    }
+    await elect();
+    return {
+        send: (action, group, params, signal, target) => current
+            ? current.send(action, group, params, signal, target)
+            : Promise.reject(new Error("bridge is re-electing — retry shortly")),
+        release: () => current?.release(),
+        shutdown: () => {
+            closed = true;
+            if (reelectTimer) {
+                clearTimeout(reelectTimer);
+                reelectTimer = null;
+            }
+            try {
+                broker?.stop();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                agentClient?.stop();
+            }
+            catch {
+                /* ignore */
+            }
+        },
+        mode: () => mode,
+        broker: () => broker
+    };
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./opencode.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// Intentionally tiny. OpenCode iterates every named export of the main entry
+// and rejects anything that isn't a `Plugin` function, so the only thing this
+// module exposes is the default plugin. Library/utility exports live in
+// `./lib` (see lib.ts), which OpenCode never inspects.
+export { default } from "./opencode.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8EAA8E;AAC9E,wEAAwE;AACxE,uDAAuD;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,12 @@
+export { type BrowserPluginFactoryOptions, createBrowserPlugin, OpencodeBrowserPlugin } from "./opencode.js";
+export { type AgentEndpoint, Broker, BrokerError, type BrokerDeps, type BrokerOptions } from "./broker.js";
+export { AgentClient, AgentClientError, type AgentClientDeps, type AgentClientOptions, type AgentSocket, type AgentSocketFactory, type AgentSocketHandlers } from "./agent-client.js";
+export { createEndpoint, type Endpoint, type EndpointDeps, type EndpointMode, type EndpointOptions } from "./endpoint.js";
+export { type BridgeTransport, type ClientConnection, createBunTransport, isAddrInUse, type TransportHandlers } from "./transport.js";
+export { type BridgeFile, readBridgeFile, resolveSharedToken, type TokenSource, writeBridgeFile } from "./token-file.js";
+export { createBrowserTools, type SaveScreenshot, type SendFn, type ToolDeps } from "./tools.js";
+export { BROWSER_TOOLS, DEFAULT_GROUPS, type NeutralResult, TOOL_GROUPS, type ToolGroup, type ToolSpec } from "./catalog.js";
+export { type Field, type JsonInput, type JsonSchema, toJsonSchema } from "./schema.js";
+export { createJsonConsoleLogger, DEFAULT_LOG_LEVEL, fromOpenCodeLogLevel, type LogFields, type Logger, type LogLevel } from "./logging.js";
+export { BROWSER_ACTIONS, type BrowserAction, type BrowserEventName, type ClientRole, type CommandFrame, decodeFrame, encodeFrame, type EventFrame, type Frame, type HelloFrame, helloFrame, nextId, PROTOCOL_VERSION, type ReadyFrame, type ResultFrame } from "./protocol.js";
+export type { BrowserPluginOptions, ExecutorMode, ResolvedBrowserOptions, ScreenshotResult } from "./types.js";

package/dist/lib.js

@@ -0,0 +1,12 @@
+export { createBrowserPlugin, OpencodeBrowserPlugin } from "./opencode.js";
+export { Broker, BrokerError } from "./broker.js";
+export { AgentClient, AgentClientError } from "./agent-client.js";
+export { createEndpoint } from "./endpoint.js";
+export { createBunTransport, isAddrInUse } from "./transport.js";
+export { readBridgeFile, resolveSharedToken, writeBridgeFile } from "./token-file.js";
+export { createBrowserTools } from "./tools.js";
+export { BROWSER_TOOLS, DEFAULT_GROUPS, TOOL_GROUPS } from "./catalog.js";
+export { toJsonSchema } from "./schema.js";
+export { createJsonConsoleLogger, DEFAULT_LOG_LEVEL, fromOpenCodeLogLevel } from "./logging.js";
+export { BROWSER_ACTIONS, decodeFrame, encodeFrame, helloFrame, nextId, PROTOCOL_VERSION } from "./protocol.js";
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEL,MAAM,EACN,WAAW,EAGZ,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,gBAAgB,EAMjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EAKf,MAAM,eAAe,CAAC;AAEvB,OAAO,EAGL,kBAAkB,EAClB,WAAW,EAEZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAEL,cAAc,EACd,kBAAkB,EAElB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,kBAAkB,EAAmD,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,EACb,cAAc,EAEd,WAAW,EAGZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAA+C,YAAY,EAAE,MAAM,aAAa,CAAC;AAExF,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EAIrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EAKf,WAAW,EACX,WAAW,EAIX,UAAU,EACV,MAAM,EACN,gBAAgB,EAGjB,MAAM,eAAe,CAAC"}

package/dist/logging.d.ts

@@ -0,0 +1,15 @@
+import type { LogLevel } from "./types.js";
+export type { LogLevel } from "./types.js";
+export declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+export interface LogFields {
+    [key: string]: unknown;
+}
+export interface Logger {
+    debug(event: string, fields?: LogFields): void;
+    info(event: string, fields?: LogFields): void;
+    warn(event: string, fields?: LogFields): void;
+    error(event: string, fields?: LogFields): void;
+}
+export declare function createJsonConsoleLogger(minLevel?: LogLevel): Logger;
+export declare function fromOpenCodeLogLevel(value: unknown): LogLevel | undefined;

package/dist/logging.js

@@ -0,0 +1,69 @@
+export const LOG_LEVEL_PRIORITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40
+};
+export const DEFAULT_LOG_LEVEL = "info";
+function redactFields(fields) {
+    if (!fields) {
+        return undefined;
+    }
+    const redacted = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (/token|secret|password|authorization/i.test(key)) {
+            redacted[key] = "[redacted]";
+            continue;
+        }
+        redacted[key] = value;
+    }
+    return redacted;
+}
+export function createJsonConsoleLogger(minLevel = DEFAULT_LOG_LEVEL) {
+    const minPriority = LOG_LEVEL_PRIORITY[minLevel];
+    const write = (level, event, fields) => {
+        if (LOG_LEVEL_PRIORITY[level] < minPriority) {
+            return;
+        }
+        const payload = {
+            ts: new Date().toISOString(),
+            level,
+            event,
+            ...(redactFields(fields) ?? {})
+        };
+        const line = JSON.stringify(payload);
+        if (level === "error") {
+            console.error(line);
+            return;
+        }
+        if (level === "warn") {
+            console.warn(line);
+            return;
+        }
+        console.log(line);
+    };
+    return {
+        debug: (event, fields) => write("debug", event, fields),
+        info: (event, fields) => write("info", event, fields),
+        warn: (event, fields) => write("warn", event, fields),
+        error: (event, fields) => write("error", event, fields)
+    };
+}
+export function fromOpenCodeLogLevel(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    switch (value.toUpperCase()) {
+        case "DEBUG":
+            return "debug";
+        case "INFO":
+            return "info";
+        case "WARN":
+            return "warn";
+        case "ERROR":
+            return "error";
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=logging.js.map

package/dist/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAa,MAAM,CAAC;AAalD,SAAS,YAAY,CAAC,MAAkB;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,sCAAsC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,QAAQ,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;YAC7B,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,WAAqB,iBAAiB;IAC5E,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAEjD,MAAM,KAAK,GAAG,CAAC,KAAe,EAAE,KAAa,EAAE,MAAkB,EAAQ,EAAE;QACzE,IAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG,WAAW,EAAE,CAAC;YAC5C,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG;YACd,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,KAAK;YACL,KAAK;YACL,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SAChC,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;QACvD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;QACrD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;QACrD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,QAAQ,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;QACjB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;QACjB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/opencode.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { AgentSocketFactory } from "./agent-client.js";
+import { type Logger } from "./logging.js";
+import { type SaveScreenshot } from "./tools.js";
+import { type BridgeTransport } from "./transport.js";
+export interface BrowserPluginFactoryOptions {
+    /** Inject a logger (defaults to the OpenCode-piped logger). */
+    logger?: Logger;
+    /** Inject the server transport factory for host mode (defaults to Bun.serve). */
+    createServerTransport?: () => BridgeTransport;
+    /** Inject the agent-socket factory for guest mode (defaults to global WebSocket). */
+    createAgentSocket?: AgentSocketFactory;
+    /** Inject the screenshot disk-writer (tests). */
+    saveScreenshot?: SaveScreenshot;
+    /** Inject token generation (tests). */
+    generateToken?: () => string;
+}
+export declare function createBrowserPlugin(factoryOptions?: BrowserPluginFactoryOptions): Plugin;
+export declare const OpencodeBrowserPlugin: Plugin;
+export default OpencodeBrowserPlugin;

package/dist/opencode.js

@@ -0,0 +1,149 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_GROUPS, TOOL_GROUPS } from "./catalog.js";
+import { createEndpoint } from "./endpoint.js";
+import { createJsonConsoleLogger, DEFAULT_LOG_LEVEL, fromOpenCodeLogLevel, LOG_LEVEL_PRIORITY } from "./logging.js";
+import { resolveSharedToken, writeBridgeFile } from "./token-file.js";
+import { createBrowserTools } from "./tools.js";
+import { createBunTransport } from "./transport.js";
+/** Agent-socket factory using the runtime's global WebSocket (Bun provides one). */
+const bunAgentSocket = (url, handlers) => {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor) {
+        throw new Error("global WebSocket is not available in this runtime");
+    }
+    const ws = new Ctor(url);
+    ws.addEventListener("open", () => handlers.onOpen());
+    ws.addEventListener("message", (event) => handlers.onMessage(typeof event.data === "string" ? event.data : String(event.data)));
+    ws.addEventListener("close", () => handlers.onClose());
+    ws.addEventListener("error", () => { });
+    return { send: (data) => ws.send(data), close: () => ws.close() };
+};
+function resolveGroups(raw) {
+    if (!Array.isArray(raw)) {
+        return [...DEFAULT_GROUPS];
+    }
+    const valid = raw.filter((g) => TOOL_GROUPS.includes(g));
+    return valid.length > 0 ? valid : [...DEFAULT_GROUPS];
+}
+const PLUGIN_SERVICE_NAME = "opencode-browser-plugin";
+const DEFAULTS = {
+    host: "127.0.0.1",
+    port: 4517,
+    executor: "auto",
+    timeoutMs: 30_000,
+    screenshotDir: ".opencode/browser"
+};
+/**
+ * Pipe plugin logs through OpenCode's `client.app.log` so they show up in the
+ * host's structured log stream, with the JSON console as a reliable fallback.
+ * Mirrors the pattern used by `@vymalo/opencode-oauth2` / `-ratelimit`.
+ */
+function createOpenCodeLogger(client, getMinLevel) {
+    const fallback = createJsonConsoleLogger("debug");
+    const write = (level, event, fields) => {
+        if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[getMinLevel()]) {
+            return;
+        }
+        fallback[level](event, fields);
+        void client.app
+            .log({ body: { service: PLUGIN_SERVICE_NAME, level, message: event, extra: fields } })
+            .catch(() => {
+            /* best-effort */
+        });
+    };
+    return {
+        debug: (event, fields) => write("debug", event, fields),
+        info: (event, fields) => write("info", event, fields),
+        warn: (event, fields) => write("warn", event, fields),
+        error: (event, fields) => write("error", event, fields)
+    };
+}
+function resolveOptions(raw, generateToken) {
+    const opts = (raw ?? {});
+    const token = typeof opts.token === "string" && opts.token.length > 0 ? opts.token : generateToken();
+    return {
+        enabled: opts.enabled !== false,
+        host: opts.host ?? DEFAULTS.host,
+        port: opts.port ?? DEFAULTS.port,
+        token,
+        executor: opts.executor ?? DEFAULTS.executor,
+        groups: resolveGroups(opts.groups),
+        timeoutMs: opts.timeoutMs ?? DEFAULTS.timeoutMs,
+        screenshotDir: opts.screenshotDir ?? DEFAULTS.screenshotDir
+    };
+}
+export function createBrowserPlugin(factoryOptions = {}) {
+    return async ({ client }, pluginOptions) => {
+        let currentLogLevel = DEFAULT_LOG_LEVEL;
+        const logger = factoryOptions.logger ?? createOpenCodeLogger(client, () => currentLogLevel);
+        const generateToken = factoryOptions.generateToken ?? (() => randomBytes(24).toString("hex"));
+        const options = resolveOptions(pluginOptions, generateToken);
+        const rawOptions = pluginOptions;
+        // Empty string is NOT an explicit token (resolveOptions generates one for
+        // it). Treating "" as provided would mark the shared token "explicit" and
+        // skip the paste_into_extension log, leaving the extension unable to learn
+        // the generated token.
+        const tokenProvided = typeof rawOptions?.token === "string" && rawOptions.token.length > 0;
+        // Only forward the executor preference when the operator set it explicitly;
+        // otherwise the extension keeps its own dashboard choice.
+        const executorProvided = typeof rawOptions?.executor === "string";
+        if (!options.enabled) {
+            logger.info("browser_plugin_disabled", {});
+            return {
+                config: async (config) => {
+                    currentLogLevel = fromOpenCodeLogLevel(config.logLevel) ?? DEFAULT_LOG_LEVEL;
+                }
+            };
+        }
+        // Share the token across adapters via the per-user state file (explicit wins).
+        const { token, source } = resolveSharedToken(options.port, tokenProvided ? options.token : undefined, generateToken);
+        writeBridgeFile(options.port, token);
+        // Auto-elect: host the broker (win the bind) or join an existing one as a guest.
+        const endpoint = await createEndpoint({
+            host: options.host,
+            port: options.port,
+            token,
+            executor: executorProvided ? options.executor : undefined,
+            timeoutMs: options.timeoutMs,
+            label: "opencode-plugin"
+        }, {
+            logger,
+            createServerTransport: factoryOptions.createServerTransport ?? createBunTransport,
+            createAgentSocket: factoryOptions.createAgentSocket ?? bunAgentSocket
+        });
+        // When OpenCode exits, hand the browser back automatically — the user
+        // shouldn't have to click Disconnect.
+        process.once("exit", () => {
+            try {
+                endpoint.shutdown();
+            }
+            catch {
+                /* best-effort */
+            }
+        });
+        if (source !== "explicit") {
+            // Make the token visible so it can be pasted into the extension. The
+            // `paste_into_extension` field name dodges the logger's redaction filter.
+            logger.info("browser_bridge_token", {
+                paste_into_extension: token,
+                source,
+                mode: endpoint.mode()
+            });
+        }
+        const tools = createBrowserTools({
+            send: endpoint.send,
+            options,
+            logger,
+            saveScreenshot: factoryOptions.saveScreenshot
+        });
+        return {
+            tool: tools,
+            config: async (config) => {
+                currentLogLevel = fromOpenCodeLogLevel(config.logLevel) ?? DEFAULT_LOG_LEVEL;
+            }
+        };
+    };
+}
+export const OpencodeBrowserPlugin = createBrowserPlugin();
+export default OpencodeBrowserPlugin;
+//# sourceMappingURL=opencode.js.map

package/dist/opencode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode.js","sourceRoot":"","sources":["../src/opencode.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Wire protocol shared by the OpenCode plugin (the bridge **server**) and the
+ * browser extension (the **client**). This module is intentionally
+ * dependency-free and runtime-agnostic so the extension can mirror it verbatim
+ * into a browser bundle without pulling in any Bun/Node code.
+ *
+ * Canonical copy lives here (`packages/opencode-browser/src/protocol.ts`); the
+ * extension keeps a byte-for-byte copy at
+ * `apps/browser-extension/src/shared/protocol.ts`. Keep them in sync.
+ *
+ * Topology: extensions cannot host servers, so the plugin opens the WebSocket
+ * server on 127.0.0.1 and the extension's background worker dials out to it.
+ * The extension authenticates with a `hello`; the server replies `ready`. From
+ * then on the server issues `command` frames and the extension answers with a
+ * matching `result` frame (correlated by `id`). The extension may also push
+ * unsolicited `event` frames. Heartbeats use `ping`/`pong`.
+ */
+/** Bump when the frame shapes change incompatibly. */
+export declare const PROTOCOL_VERSION = 1;
+/** Every browser action the plugin can ask the extension to perform. */
+export type BrowserAction = "open" | "navigate" | "click" | "double_click" | "type" | "fill" | "select" | "scroll" | "press_key" | "screenshot" | "snapshot" | "get_text" | "wait" | "tabs" | "close" | "back" | "forward" | "reload" | "hover" | "activate" | "drag" | "upload" | "get_html" | "get_attribute" | "query" | "eval" | "console" | "network" | "handle_dialog" | "set_viewport" | "cookies" | "targets" | "release";
+export declare const BROWSER_ACTIONS: readonly BrowserAction[];
+/** A connection's role on the bridge. Absent → "extension" (back-compat). */
+export type ClientRole = "agent" | "extension";
+/** Client → broker: first frame after the socket opens. */
+export interface HelloFrame {
+    v: number;
+    type: "hello";
+    /** Shared secret; must equal the bridge token. */
+    token: string;
+    /** "extension" (executor) or "agent" (producer). Default extension. */
+    role?: ClientRole;
+    /** Free-form client descriptor for logging (browser name/version, agent name). */
+    client?: string;
+    /** Extensions: stable per-install id (persisted), usable as a routing target. */
+    id?: string;
+    /** Extensions: user-editable label from the dashboard (defaults to id). */
+    label?: string;
+    /** Extensions: "chrome" | "firefox" | UA hint. */
+    browser?: string;
+}
+/** Broker → client: handshake accepted. */
+export interface ReadyFrame {
+    v: number;
+    type: "ready";
+    server: "opencode-browser";
+    protocol: number;
+    /** Role the broker accepted this connection as. */
+    role?: ClientRole;
+    /** Id the broker assigned/echoed for this client. */
+    clientId?: string;
+    /** Operator's executor preference, if configured plugin-side (extensions only). */
+    executor?: "auto" | "cdp" | "content";
+}
+/** Server → extension: perform an action, expect a matching `result`. */
+export interface CommandFrame {
+    v: number;
+    type: "command";
+    /** Correlation id; the `result` echoes it. */
+    id: string;
+    action: BrowserAction;
+    /** Named tab group the action targets. */
+    group: string;
+    /** Action-specific arguments (already validated plugin-side). */
+    params: Record<string, unknown>;
+    /**
+     * Optional executor selector (browser label or id) used by the broker when a
+     * command creates a new group; ignored by executors.
+     */
+    target?: string;
+}
+/** Extension → server: response to a `command`. */
+export interface ResultFrame {
+    v: number;
+    type: "result";
+    id: string;
+    ok: boolean;
+    /** Present when `ok` is true. */
+    data?: unknown;
+    /** Present when `ok` is false. */
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/** Names of unsolicited events the extension can push. */
+export type BrowserEventName = "tab_closed" | "navigated" | "group_removed" | "tab_created";
+/** Extension → server: unsolicited notification (not correlated to a command). */
+export interface EventFrame {
+    v: number;
+    type: "event";
+    name: BrowserEventName;
+    group?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Server → extension: stop driving and release control (detach the CDP
+ * debugger) without closing tabs. The next command re-attaches. Lets the plugin
+ * hand the browser back without waiting for the socket to drop.
+ */
+export interface ReleaseFrame {
+    v: number;
+    type: "release";
+}
+export interface PingFrame {
+    v: number;
+    type: "ping";
+}
+export interface PongFrame {
+    v: number;
+    type: "pong";
+}
+export type Frame = HelloFrame | ReadyFrame | CommandFrame | ResultFrame | EventFrame | ReleaseFrame | PingFrame | PongFrame;
+/** Serialize a frame for the wire. */
+export declare function encodeFrame(frame: Frame): string;
+/**
+ * Parse and shape-check an inbound frame. Returns the typed frame, or `null` if
+ * the payload is not a recognizable frame (caller decides whether to drop or
+ * log). Validation is deliberately lightweight — both ends are trusted once the
+ * token handshake succeeds; this guards against malformed JSON and version skew,
+ * not a hostile peer.
+ */
+export declare function decodeFrame(raw: string): Frame | null;
+/**
+ * Monotonic correlation id for command frames. Process-local and collision-free
+ * within a single bridge instance, which is all that's required (the server is
+ * the only id minter).
+ */
+export declare function nextId(): string;
+export declare function helloFrame(token: string, opts?: {
+    role?: ClientRole;
+    client?: string;
+    id?: string;
+    label?: string;
+    browser?: string;
+}): HelloFrame;
+export declare function resultFrame(id: string, data: unknown): ResultFrame;
+export declare function errorFrame(id: string, message: string, code?: string): ResultFrame;