@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/browser/capability-source.js

@@ -0,0 +1,338 @@
+import { CapabilityFailed, Mycelium, } from "@fungi.computer/mycelium";
+import { z } from "zod";
+import { clickInputSchema, closeInputSchema, extractInputSchema, leaseAckSchema, markdownInputSchema, navigateInputSchema, openInputSchema, pressInputSchema, scrapeInputSchema, scrollInputSchema, snapshotInputSchema, typeInputSchema, urlInputSchema, markdownResultSchema, linksResultSchema, scrapeResultSchema, extractResultSchema, openResultSchema, navigateResultSchema, snapshotResultSchema, closeResultSchema, } from "./operations.js";
+import { CloudBrowserCapacityExceeded, CloudBrowserCreditDenied, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, CloudBrowserTimeout, CloudBrowserUnavailable, CloudBrowserUpstreamError, CloudBrowserUrlDenied, } from "./errors.js";
+/**
+ * The `cloudBrowser` Mycelium module: a work browser for reading and driving
+ * public pages. To show the member something, use the Session browser
+ * tools. Quick Reads (`markdown`/`links`/`scrape`/`extract`) need no open
+ * session; `open`..`close` share one driven session by `leaseId`.
+ * `screenshot`/`pdf` save to a named Computer path instead of returning
+ * bytes, and `handoff` asks a Team member to drive the page for a login or
+ * captcha, through the existing `handoff` card, never a CDP URL.
+ */
+/**
+ * The one source of truth for every `cloudBrowser` description: the module
+ * itself and each operation. `cloud-browser-descriptions.test.ts` imports
+ * this and asserts every entry stays under 1000 characters (the acceptance
+ * criterion in `issues/retained-features-v1/02-*.md`); the guard right below
+ * repeats that check at import time so a regression fails fast either way.
+ */
+export const CLOUD_BROWSER_DESCRIPTIONS = Object.freeze({
+    module: "A work browser for reading and driving public pages. markdown/links/scrape/extract " +
+        "need no session. open/navigate/snapshot/click/type/press/scroll drive one session by " +
+        "leaseId; screenshot/pdf save to a Computer path (bytes never enter this transcript). " +
+        "handoff asks a Team member to take over for a login or captcha; close ends the lease. " +
+        "To show the member something yourself, use the Session browser tools, not this.",
+    markdown: "Render a JavaScript page and return it as markdown, truncated to maxChars (default 20000).",
+    links: "Render a page and return up to 500 links found on it.",
+    scrape: "Render a page and return matched elements for up to 10 CSS selectors, bounded to 64 KiB.",
+    extract: "Render a page and extract structured data matching a prompt.",
+    open: "Open a driven browser session, optionally navigating to a URL, and return its leaseId.",
+    navigate: "Navigate an open session's page to a URL.",
+    snapshot: "Read an open session's page as a bounded accessibility-tree text summary.",
+    click: "Click at a viewport pixel coordinate in an open session.",
+    type: "Insert text at the current focus in an open session.",
+    press: 'Press one key (e.g. "Enter", "Tab") in an open session.',
+    scroll: "Scroll an open session's page by a pixel delta.",
+    screenshot: "Capture a PNG screenshot of an open session's page and save it to a Computer path; returns the saved byte count, never the bytes.",
+    pdf: "Render an open session's page to PDF and save it to a Computer path; returns the saved byte count, never the bytes.",
+    handoff: "Ask a Team member to take over an open session for a login or captcha; a card appears in the conversation and the run continues once they finish.",
+    close: "End a driven session and release its lease.",
+});
+for (const [name, text] of Object.entries(CLOUD_BROWSER_DESCRIPTIONS))
+    if (text.length >= 1000)
+        throw new Error(`cloudBrowser.${name} description must stay under 1000 characters`);
+function isCloudBrowserFailure(cause) {
+    return (cause instanceof CloudBrowserUrlDenied ||
+        cause instanceof CloudBrowserUpstreamError ||
+        cause instanceof CloudBrowserTimeout ||
+        cause instanceof CloudBrowserLeaseNotFound ||
+        cause instanceof CloudBrowserLeasePaused ||
+        cause instanceof CloudBrowserCapacityExceeded ||
+        cause instanceof CloudBrowserCreditDenied ||
+        cause instanceof CloudBrowserUnavailable);
+}
+/** Map the closed cloud-browser failure union onto Mycelium's admitted diagnostic. */
+function cloudBrowserFailureMessage(error) {
+    switch (error._tag) {
+        case "CloudBrowserUrlDenied":
+            return error.message;
+        case "CloudBrowserUpstreamError":
+            return `the cloud browser could not complete ${error.op}`;
+        case "CloudBrowserTimeout":
+            return `${error.op} did not answer in time`;
+        case "CloudBrowserLeaseNotFound":
+            return "that leaseId is not open for this session; call open first";
+        case "CloudBrowserLeasePaused":
+            return "a Team member is driving this lease; wait for them to finish";
+        case "CloudBrowserCapacityExceeded":
+            return "this Team has too many cloud browsers open at once; close one first";
+        case "CloudBrowserCreditDenied":
+            return "this Team has no credit for cloud browser time";
+        case "CloudBrowserUnavailable":
+            return error.reason === "paused"
+                ? "the cloud browser is turned off for this deployment"
+                : "the cloud browser is not configured";
+    }
+}
+function toCapabilityFailed(operation, cause) {
+    if (cause instanceof CapabilityFailed)
+        return cause;
+    if (isCloudBrowserFailure(cause))
+        return new CapabilityFailed({
+            namespace: "cloudBrowser",
+            operation,
+            cause: {
+                kind: cause._tag === "CloudBrowserUrlDenied"
+                    ? "InvalidInput"
+                    : cause._tag === "CloudBrowserLeaseNotFound"
+                        ? "InvalidInput"
+                        : "Unavailable",
+                message: cloudBrowserFailureMessage(cause),
+            },
+            rawCause: cause,
+        });
+    return new CapabilityFailed({
+        namespace: "cloudBrowser",
+        operation,
+        cause: { kind: "Unavailable", message: "the cloud browser failed" },
+        rawCause: cause,
+    });
+}
+const destinationSchema = z.strictObject({
+    leaseId: leaseAckSchema.shape.leaseId,
+    computerId: z.string().min(1).max(256),
+    path: z.string().min(1).max(1024),
+});
+const destinationResultSchema = z.strictObject({
+    leaseId: z.string(),
+    computerId: z.string(),
+    path: z.string(),
+    bytes: z.number().int().nonnegative(),
+});
+const handoffResultSchema = z.strictObject({
+    status: z.literal("handed_off"),
+});
+/** Build the `cloudBrowser` module once a Session identity is known. */
+function buildCloudBrowserModule(options) {
+    /** Run one call, mapping any thrown failure and parsing the result through `schema`. */
+    async function run(operation, schema, action) {
+        try {
+            return schema.parse(await action());
+        }
+        catch (error) {
+            throw toCapabilityFailed(operation, error);
+        }
+    }
+    const binaryResultSchema = z.strictObject({
+        leaseId: z.string(),
+        bytes: z.instanceof(Uint8Array),
+        contentType: z.string(),
+    });
+    function saveBinary(saveFile) {
+        return async (operation, leaseId, computerId, path, defaultContentType, signal) => {
+            const raw = await run(operation, binaryResultSchema, () => options.call({ kind: operation, leaseId }, signal));
+            try {
+                const saved = await saveFile({
+                    computerId,
+                    path,
+                    bytes: raw.bytes,
+                    contentType: raw.contentType || defaultContentType,
+                });
+                return destinationResultSchema.parse({ leaseId, ...saved });
+            }
+            catch (error) {
+                throw toCapabilityFailed(operation, error);
+            }
+        };
+    }
+    function saveOperations(saveFile) {
+        const save = saveBinary(saveFile);
+        return {
+            screenshot: Mycelium.operation({
+                replay: "unsafe",
+                description: CLOUD_BROWSER_DESCRIPTIONS.screenshot,
+                input: destinationSchema,
+                output: destinationResultSchema,
+                execute: (input, context) => save("screenshot", input.leaseId, input.computerId, input.path, "image/png", context.signal),
+            }),
+            pdf: Mycelium.operation({
+                replay: "unsafe",
+                description: CLOUD_BROWSER_DESCRIPTIONS.pdf,
+                input: destinationSchema,
+                output: destinationResultSchema,
+                execute: (input, context) => save("pdf", input.leaseId, input.computerId, input.path, "application/pdf", context.signal),
+            }),
+        };
+    }
+    function handoffOperation(handoff) {
+        return {
+            handoff: Mycelium.operation({
+                replay: "unsafe",
+                description: CLOUD_BROWSER_DESCRIPTIONS.handoff,
+                input: z.strictObject({
+                    leaseId: leaseAckSchema.shape.leaseId,
+                    reason: z.string().min(1).max(500),
+                }),
+                output: handoffResultSchema,
+                execute: (input) => run("handoff", handoffResultSchema, async () => {
+                    await handoff(input.leaseId, input.reason);
+                    return { status: "handed_off" };
+                }),
+            }),
+        };
+    }
+    const quickReads = {
+        markdown: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.markdown,
+            input: markdownInputSchema,
+            output: markdownResultSchema,
+            execute: (input, context) => run("markdown", markdownResultSchema, () => options.call({ kind: "markdown", input }, context.signal)),
+        }),
+        links: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.links,
+            input: urlInputSchema,
+            output: linksResultSchema,
+            execute: (input, context) => run("links", linksResultSchema, () => options.call({ kind: "links", url: input.url }, context.signal)),
+        }),
+        scrape: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.scrape,
+            input: scrapeInputSchema,
+            output: scrapeResultSchema,
+            execute: (input, context) => run("scrape", scrapeResultSchema, () => options.call({ kind: "scrape", input }, context.signal)),
+        }),
+        extract: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.extract,
+            input: extractInputSchema,
+            output: extractResultSchema,
+            execute: (input, context) => run("extract", extractResultSchema, () => options.call({ kind: "extract", input }, context.signal)),
+        }),
+    };
+    const driven = {
+        open: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.open,
+            input: openInputSchema,
+            output: openResultSchema,
+            execute: (input, context) => run("open", openResultSchema, () => options.call({ kind: "open", url: input.url }, context.signal)),
+        }),
+        navigate: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.navigate,
+            input: navigateInputSchema,
+            output: navigateResultSchema,
+            execute: (input, context) => run("navigate", navigateResultSchema, () => options.call({ kind: "navigate", leaseId: input.leaseId, url: input.url }, context.signal)),
+        }),
+        snapshot: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.snapshot,
+            input: snapshotInputSchema,
+            output: snapshotResultSchema,
+            execute: (input, context) => run("snapshot", snapshotResultSchema, () => options.call({ kind: "snapshot", leaseId: input.leaseId }, context.signal)),
+        }),
+        click: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.click,
+            input: clickInputSchema,
+            output: leaseAckSchema,
+            execute: (input, context) => run("click", leaseAckSchema, () => options.call({ kind: "click", leaseId: input.leaseId, x: input.x, y: input.y }, context.signal)),
+        }),
+        type: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.type,
+            input: typeInputSchema,
+            output: leaseAckSchema,
+            execute: (input, context) => run("type", leaseAckSchema, () => options.call({ kind: "type", leaseId: input.leaseId, text: input.text }, context.signal)),
+        }),
+        press: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.press,
+            input: pressInputSchema,
+            output: leaseAckSchema,
+            execute: (input, context) => run("press", leaseAckSchema, () => options.call({ kind: "press", leaseId: input.leaseId, key: input.key }, context.signal)),
+        }),
+        scroll: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.scroll,
+            input: scrollInputSchema,
+            output: leaseAckSchema,
+            execute: (input, context) => run("scroll", leaseAckSchema, () => options.call({
+                kind: "scroll",
+                leaseId: input.leaseId,
+                deltaX: input.deltaX,
+                deltaY: input.deltaY,
+            }, context.signal)),
+        }),
+        close: Mycelium.operation({
+            replay: "unsafe",
+            description: CLOUD_BROWSER_DESCRIPTIONS.close,
+            input: closeInputSchema,
+            output: closeResultSchema,
+            execute: (input, context) => run("close", closeResultSchema, () => options.call({ kind: "close", leaseId: input.leaseId }, context.signal)),
+        }),
+    };
+    // The host offers only what it has: Quick Reads, a Computer to save to and
+    // a member to hand off to are each optional; driven sessions never are.
+    const operations = { ...driven };
+    if (options.quickReads)
+        Object.assign(operations, quickReads);
+    if (options.saveFile !== null)
+        Object.assign(operations, saveOperations(options.saveFile));
+    if (options.handoff !== null)
+        Object.assign(operations, handoffOperation(options.handoff));
+    return Mycelium.module({
+        id: "cloud-browser",
+        name: "cloudBrowser",
+        description: CLOUD_BROWSER_DESCRIPTIONS.module,
+        operations,
+    });
+}
+/**
+ * Compose the `cloudBrowser` source for one Session, on either host. `browser`
+ * is the module's lease door (in-process, or the Hub's egress RPC); `saveFile`
+ * is the host's Computer bytes writer and `requestHandoff` its "needs you"
+ * card. A host without one passes `null` and the matching operations are not
+ * offered. A lease needs a Session identity, so a session-free host (e.g. the
+ * MCP execute path) gets no module at all.
+ */
+export function browserCapabilitySource(deps) {
+    return {
+        id: "cloud-browser",
+        acquire: ({ signal, session }) => {
+            signal.throwIfAborted();
+            const sessionId = session?.sessionId;
+            const identity = deps.identity();
+            if (sessionId === undefined || identity === null)
+                return Promise.resolve({
+                    snapshot: { version: "0", modules: [] },
+                    release: () => Promise.resolve(),
+                });
+            const owner = {
+                teamId: identity.teamId,
+                agentId: identity.agentId,
+                sessionId,
+            };
+            const requestHandoff = deps.requestHandoff;
+            const registration = buildCloudBrowserModule({
+                call: (op, opSignal) => deps.browser.call(owner, op, opSignal),
+                quickReads: deps.quickReads,
+                saveFile: deps.saveFile,
+                handoff: requestHandoff === null
+                    ? null
+                    : async (leaseId, reason) => {
+                        await deps.browser.handoff(owner, leaseId);
+                        requestHandoff(sessionId, `cloud browser: ${reason}`);
+                    },
+            });
+            return Promise.resolve({
+                snapshot: { version: "cloud-browser-v1", modules: [registration] },
+                release: () => Promise.resolve(),
+            });
+        },
+    };
+}

package/dist/browser/cdp-client.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+/**
+ * A minimal Chrome DevTools Protocol client over one WebSocket to a browser
+ * session (Browser Run REST or a Workers BROWSER binding; see `sessions.ts`).
+ * This is the ONLY place in the browser module that speaks the CDP wire; it
+ * exposes `call` (one request/response), `waitForEvent` (one named event)
+ * and `on` (a bounded subscription for the host boot observer). It is
+ * internal: no export path or agent tool exposes it, so the Agent never sees
+ * a `send`/raw-method tool.
+ */
+/** CDP's own wire values are arbitrary JSON; every caller parses its own
+ * expected shape with a schema (e.g. `getTargetsResultSchema.parse(...)`). */
+export type Json = z.core.util.JSONType;
+/**
+ * The minimal WebSocket surface this client drives (a fake in tests). A real
+ * `WebSocket`'s `addEventListener` structurally satisfies this: the listener
+ * accepts any platform `Event` and `readCdpMessage` parses a message's `data`.
+ */
+export type CdpSocket = Readonly<{
+    /** Send one JSON text frame. */
+    send: (data: string) => void;
+    /** Close the transport. */
+    close: (code?: number, reason?: string) => void;
+    /** Observe frames, closure and transport errors. */
+    addEventListener: (type: "message" | "close" | "error", listener: (event: Event) => void) => void;
+}>;
+/** The one fetch shape the module calls: global `fetch` or a binding's. */
+export type HttpFetch = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Workers/workerd outbound WebSocket: a `fetch` with an `upgrade` header
+ * returns a `Response.webSocket` to `.accept()`. Browser Run's REST CDP
+ * endpoint and a BROWSER binding's `/v1/devtools/browser/{id}` answer the
+ * same upgrade (https://developers.cloudflare.com/browser-run/cdp/).
+ */
+export declare function openCdpSocket(fetcher: HttpFetch, url: string, headers: Readonly<Record<string, string>>, signal: AbortSignal): Promise<CdpSocket>;
+export type CdpClient = Readonly<{
+    /** One command/response round trip, optionally flattened into `sessionId`. */
+    call: (method: string, params: Readonly<Record<string, Json>>, options?: Readonly<{
+        sessionId?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }>) => Promise<Json>;
+    /** Resolves on the next matching event, or times out. */
+    waitForEvent: (method: string, options: Readonly<{
+        sessionId?: string;
+        timeoutMs: number;
+    }>) => Promise<Json>;
+    /**
+     * Every matching event, with the flattened CDP session it came from,
+     * until the returned function unsubscribes.
+     */
+    on: (method: string, listener: (params: Json, sessionId: string | undefined) => void) => () => void;
+    close: () => void;
+}>;
+/** Wrap one connected CDP socket with id-correlated calls and event waits. */
+export declare function createCdpClient(socket: CdpSocket): CdpClient;

package/dist/browser/cdp-client.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { CloudBrowserTimeout, CloudBrowserUpstreamError } from "./errors.js";
+/**
+ * Workers/workerd outbound WebSocket: a `fetch` with an `upgrade` header
+ * returns a `Response.webSocket` to `.accept()`. Browser Run's REST CDP
+ * endpoint and a BROWSER binding's `/v1/devtools/browser/{id}` answer the
+ * same upgrade (https://developers.cloudflare.com/browser-run/cdp/).
+ */
+export async function openCdpSocket(fetcher, url, headers, signal) {
+    const response = await fetcher(url, {
+        headers: { ...headers, upgrade: "websocket" },
+        signal,
+    });
+    const socket = response.webSocket;
+    if (socket === null)
+        throw new CloudBrowserUpstreamError({
+            op: "cdp.connect",
+            status: response.status,
+            message: "The browser did not upgrade the CDP connection",
+        });
+    socket.accept();
+    return socket;
+}
+const cdpMessageSchema = z.object({
+    id: z.number().optional(),
+    method: z.string().optional(),
+    params: z.json().optional(),
+    result: z.json().optional(),
+    error: z.object({ code: z.number(), message: z.string() }).optional(),
+    sessionId: z.string().optional(),
+});
+/**
+ * CDP frames are always a JSON text message. `cdpMessageSchema` is the one
+ * place that decides what counts as a real CDP message; anything else
+ * (binary, malformed JSON, the wrong shape) is silently dropped, same as a
+ * CDP client ignoring a frame it does not understand.
+ */
+const textFrameSchema = z.object({ data: z.string() });
+const unreadable = { kind: "unreadable" };
+function readCdpMessage(event) {
+    const text = textFrameSchema.safeParse(event);
+    if (!text.success)
+        return unreadable;
+    let candidate;
+    try {
+        candidate = JSON.parse(text.data.data);
+    }
+    catch {
+        return unreadable;
+    }
+    const parsed = cdpMessageSchema.safeParse(candidate);
+    return parsed.success
+        ? { kind: "message", message: parsed.data }
+        : unreadable;
+}
+/** Wrap one connected CDP socket with id-correlated calls and event waits. */
+export function createCdpClient(socket) {
+    const pending = new Map();
+    const waiters = [];
+    const subscribers = new Set();
+    let nextRequestNumber = 1;
+    let closed = false;
+    socket.addEventListener("message", (event) => {
+        const frame = readCdpMessage(event);
+        if (frame.kind === "unreadable")
+            return;
+        const { message } = frame;
+        if (message.id !== undefined) {
+            const waiting = pending.get(message.id);
+            if (waiting === undefined)
+                return;
+            pending.delete(message.id);
+            if (message.error !== undefined)
+                waiting.reject(new CloudBrowserUpstreamError({
+                    op: "cdp.call",
+                    status: null,
+                    message: message.error.message,
+                }));
+            else
+                waiting.resolve(message.result ?? null);
+            return;
+        }
+        if (message.method === undefined)
+            return;
+        for (const subscriber of subscribers)
+            if (subscriber.method === message.method)
+                subscriber.listener(message.params ?? null, message.sessionId);
+        for (let index = waiters.length - 1; index >= 0; index -= 1) {
+            const waiter = waiters[index];
+            if (waiter?.method === message.method &&
+                (waiter.sessionId === undefined ||
+                    waiter.sessionId === message.sessionId)) {
+                waiters.splice(index, 1);
+                waiter.resolve(message.params ?? null);
+            }
+        }
+    });
+    socket.addEventListener("close", () => {
+        closed = true;
+        for (const { reject } of pending.values())
+            reject(new CloudBrowserUpstreamError({
+                op: "cdp.socket",
+                status: null,
+                message: "browser CDP socket closed",
+            }));
+        pending.clear();
+    });
+    socket.addEventListener("error", () => {
+        closed = true;
+    });
+    return {
+        call: (method, params, options) => new Promise((resolve, reject) => {
+            if (closed) {
+                reject(new CloudBrowserUpstreamError({
+                    op: method,
+                    status: null,
+                    message: "browser CDP socket is closed",
+                }));
+                return;
+            }
+            const requestNumber = nextRequestNumber;
+            nextRequestNumber += 1;
+            const timeoutMs = options?.timeoutMs ?? 15_000;
+            const timer = setTimeout(() => {
+                pending.delete(requestNumber);
+                reject(new CloudBrowserTimeout({ op: method, timeoutMs }));
+            }, timeoutMs);
+            const onAbort = () => {
+                pending.delete(requestNumber);
+                clearTimeout(timer);
+                reject(new CloudBrowserTimeout({ op: method, timeoutMs: 0 }));
+            };
+            options?.signal?.addEventListener("abort", onAbort, { once: true });
+            pending.set(requestNumber, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    options?.signal?.removeEventListener("abort", onAbort);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    options?.signal?.removeEventListener("abort", onAbort);
+                    reject(error);
+                },
+            });
+            const frame = { id: requestNumber, method, params };
+            socket.send(JSON.stringify(options?.sessionId === undefined
+                ? frame
+                : { ...frame, sessionId: options.sessionId }));
+        }),
+        waitForEvent: (method, options) => new Promise((resolve, reject) => {
+            const waiter = {
+                method,
+                sessionId: options.sessionId,
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+            };
+            const timer = setTimeout(() => {
+                const index = waiters.indexOf(waiter);
+                if (index >= 0)
+                    waiters.splice(index, 1);
+                reject(new CloudBrowserTimeout({
+                    op: method,
+                    timeoutMs: options.timeoutMs,
+                }));
+            }, options.timeoutMs);
+            waiters.push(waiter);
+        }),
+        on: (method, listener) => {
+            const subscriber = { method, listener };
+            subscribers.add(subscriber);
+            return () => {
+                subscribers.delete(subscriber);
+            };
+        },
+        close: () => {
+            closed = true;
+            subscribers.clear();
+            socket.close();
+        },
+    };
+}

package/dist/browser/errors.d.ts

@@ -0,0 +1,79 @@
+declare const CloudBrowserUrlDenied_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserUrlDenied";
+} & Readonly<A>;
+/**
+ * The cloud-browser backend's closed, typed failure channel. Every backend
+ * (today only Cloudflare Browser Run) throws exclusively from this union;
+ * `agent-cloud-browser-source.ts` is the one place that maps it onto
+ * Mycelium's `CapabilityFailed`, so the model only ever sees a bounded,
+ * owner-admitted message (never a raw provider error body or stack).
+ */
+/** The target URL failed policy before any provider call was made. */
+export declare class CloudBrowserUrlDenied extends CloudBrowserUrlDenied_base<{
+    readonly reason: "invalid_url" | "unsupported_scheme" | "credentials_in_url" | "not_public" | "dns_unavailable";
+    readonly message: string;
+}> {
+}
+declare const CloudBrowserUpstreamError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserUpstreamError";
+} & Readonly<A>;
+/** The provider (Cloudflare Browser Run) answered with a failure. */
+export declare class CloudBrowserUpstreamError extends CloudBrowserUpstreamError_base<{
+    readonly op: string;
+    readonly status: number | null;
+    readonly message: string;
+}> {
+}
+declare const CloudBrowserTimeout_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserTimeout";
+} & Readonly<A>;
+/** A call did not complete within its deadline. */
+export declare class CloudBrowserTimeout extends CloudBrowserTimeout_base<{
+    readonly op: string;
+    readonly timeoutMs: number;
+}> {
+}
+declare const CloudBrowserLeaseNotFound_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserLeaseNotFound";
+} & Readonly<A>;
+/** The named lease is not held by this (teamId, agentId, sessionId). */
+export declare class CloudBrowserLeaseNotFound extends CloudBrowserLeaseNotFound_base<{
+    readonly leaseId: string;
+}> {
+}
+declare const CloudBrowserLeasePaused_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserLeasePaused";
+} & Readonly<A>;
+/** A member was asked to take over; the Agent cannot drive it until "Done". */
+export declare class CloudBrowserLeasePaused extends CloudBrowserLeasePaused_base<{
+    readonly leaseId: string;
+}> {
+}
+declare const CloudBrowserCapacityExceeded_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserCapacityExceeded";
+} & Readonly<A>;
+/** The Team has no more concurrent leases available right now. */
+export declare class CloudBrowserCapacityExceeded extends CloudBrowserCapacityExceeded_base<{
+    readonly teamId: string;
+    readonly limit: number;
+}> {
+}
+declare const CloudBrowserCreditDenied_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserCreditDenied";
+} & Readonly<A>;
+/** The Team has no credit to start or continue a lease. */
+export declare class CloudBrowserCreditDenied extends CloudBrowserCreditDenied_base<{
+    readonly teamId: string;
+}> {
+}
+declare const CloudBrowserUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CloudBrowserUnavailable";
+} & Readonly<A>;
+/** No backend is configured (credentials absent, or the feature is paused). */
+export declare class CloudBrowserUnavailable extends CloudBrowserUnavailable_base<{
+    readonly reason: "unconfigured" | "paused";
+}> {
+}
+/** Every typed failure the browser module throws; nothing else escapes it. */
+export type CloudBrowserFailure = CloudBrowserUrlDenied | CloudBrowserUpstreamError | CloudBrowserTimeout | CloudBrowserLeaseNotFound | CloudBrowserLeasePaused | CloudBrowserCapacityExceeded | CloudBrowserCreditDenied | CloudBrowserUnavailable;
+export {};