@fungi.computer/oyster 0.3.1 → 0.4.0

package/dist/browser/errors.js

@@ -1,7 +1,7 @@
 import * as Data from "effect/Data";
 /**
  * The cloud-browser backend's closed, typed failure channel. Every backend
- * (today only Cloudflare Browser Run) throws exclusively from this union;
+ * (Cloudflare Browser Run or on-box Chromium) throws 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).
@@ -9,7 +9,7 @@ import * as Data from "effect/Data";
 /** The target URL failed policy before any provider call was made. */
 export class CloudBrowserUrlDenied extends Data.TaggedError("CloudBrowserUrlDenied") {
 }
-/** The provider (Cloudflare Browser Run) answered with a failure. */
+/** The configured provider answered with a failure or is unreachable. */
 export class CloudBrowserUpstreamError extends Data.TaggedError("CloudBrowserUpstreamError") {
 }
 /** A call did not complete within its deadline. */

package/dist/browser/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * `@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
  * standalone Oyster. A host builds the port from a provider (`browserRunSessions`
- * or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
+ * or `bindingSessions` or `onboxBrowserSessions` on staging, plus Browser Run
+ * Quick Reads when it has them), its
  * required metering owner and an event sink; `createBrowser` owns lease
  * ownership, egress policy and billing order; `browserCapabilitySource` is
  * the agent's `cloudBrowser` tool. Raw CDP stays internal to this directory.
@@ -13,4 +14,4 @@ export type { LeaseOwner } from "./lease-registry.js";
 export { cloudBrowserBounds, extractInputSchema, extractResultSchema, linksResultSchema, markdownInputSchema, markdownResultSchema, navigateResultSchema, openResultSchema, scrapeInputSchema, scrapeResultSchema, snapshotResultSchema, type BinaryResult, type CloudBrowserAck, type CloudBrowserClosed, type CloudBrowserOperation, type CloudBrowserOperationResult, type ExtractInput, type ExtractResult, type LinksResult, type MarkdownInput, type MarkdownResult, type NavigateResult, type OpenResult, type ScrapeInput, type ScrapeResult, type SnapshotResult, } from "./operations.js";
 export type { CdpSocket, HttpFetch } from "./cdp-client.js";
 export { browserRunQuickReads, type BrowserRunQuickReadsConfig, type QuickRead, type QuickReads, } from "./quick-reads.js";
-export { bindingSessions, browserRunSessions, type BrowserBinding, type BrowserSessions, type CdpConnect, } from "./sessions.js";
+export { bindingSessions, browserRunSessions, onboxBrowserSessions, type BrowserBinding, type BrowserSessions, type CdpConnect, } from "./sessions.js";

package/dist/browser/index.js

@@ -1,7 +1,8 @@
 /**
  * `@fungi.computer/oyster/browser`: the one agent browser for the Hub and a
  * standalone Oyster. A host builds the port from a provider (`browserRunSessions`
- * or `bindingSessions`, plus Browser Run Quick Reads when it has them), its
+ * or `bindingSessions` or `onboxBrowserSessions` on staging, plus Browser Run
+ * Quick Reads when it has them), its
  * required metering owner and an event sink; `createBrowser` owns lease
  * ownership, egress policy and billing order; `browserCapabilitySource` is
  * the agent's `cloudBrowser` tool. Raw CDP stays internal to this directory.
@@ -11,4 +12,4 @@ export { browserCapabilitySource, CLOUD_BROWSER_DESCRIPTIONS, } from "./capabili
 export { CloudBrowserCapacityExceeded, CloudBrowserCreditDenied, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, CloudBrowserTimeout, CloudBrowserUnavailable, CloudBrowserUpstreamError, CloudBrowserUrlDenied, } from "./errors.js";
 export { cloudBrowserBounds, extractInputSchema, extractResultSchema, linksResultSchema, markdownInputSchema, markdownResultSchema, navigateResultSchema, openResultSchema, scrapeInputSchema, scrapeResultSchema, snapshotResultSchema, } from "./operations.js";
 export { browserRunQuickReads, } from "./quick-reads.js";
-export { bindingSessions, browserRunSessions, } from "./sessions.js";
+export { bindingSessions, browserRunSessions, onboxBrowserSessions, } from "./sessions.js";

package/dist/browser/page.js

@@ -8,7 +8,11 @@ import { cloudBrowserBounds, } from "./operations.js";
  * The session-create response shape was confirmed by the live workerd smoke
  * on 2026-10-03; see `test/browser/cdp-client.test.ts`.
  */
-const targetSchema = z.object({ targetId: z.string(), type: z.string() });
+const targetSchema = z.object({
+    targetId: z.string(),
+    type: z.string(),
+    browserContextId: z.string().optional(),
+});
 const getTargetsResultSchema = z.object({ targetInfos: z.array(targetSchema) });
 const attachResultSchema = z.object({ sessionId: z.string() });
 const navigateResultSchema = z.object({
@@ -31,11 +35,14 @@ const capturedDataSchema = z.object({ data: z.string() });
 /** Attach to the session's first page target (or a new blank one). */
 export async function attachPage(client) {
     const targets = getTargetsResultSchema.parse(await client.call("Target.getTargets", {}));
-    const targetId = targets.targetInfos.find((target) => target.type === "page")?.targetId ??
+    const targetId = targets.targetInfos.find((target) => target.type === "page" &&
+        (client.browserContextId === undefined ||
+            target.browserContextId === client.browserContextId))?.targetId ??
         z
             .object({ targetId: z.string() })
-            .parse(await client.call("Target.createTarget", { url: "about:blank" }))
-            .targetId;
+            .parse(await client.call("Target.createTarget", client.browserContextId === undefined
+            ? { url: "about:blank" }
+            : { url: "about:blank", browserContextId: client.browserContextId })).targetId;
     const { sessionId: cdpSessionId } = attachResultSchema.parse(await client.call("Target.attachToTarget", { targetId, flatten: true }));
     await client.call("Page.enable", {}, { sessionId: cdpSessionId });
     await client.call("Accessibility.enable", {}, { sessionId: cdpSessionId });

package/dist/browser/sessions.d.ts

@@ -11,16 +11,17 @@ import { type CdpClient, type CdpSocket, type HttpFetch } from "./cdp-client.js"
  * - Binding: `binding.fetch("http://fake.host/v1/devtools/…")`, the endpoints
  *   a Workers Browser Run binding answers.
  *
+ * Chromium on staging uses browser contexts rather than Browser Run endpoints.
  * Provider session ids stay inside the module; agent leases use their own ids.
  */
 export type AcquireOptions = Readonly<{
-    /** Provider idle keep-alive, clamped to Browser Run's 10s–20min range. */
+    /** Browser Run idle keep-alive (10s–20min); Chromium has no equivalent. */
     keepAliveMs: number;
-    /** Provider guardrail: the only hosts this session may load. */
+    /** Browser Run provider guardrail; Chromium relies on its caller's URL gate. */
     allowedDomains?: readonly string[];
 }>;
 /**
- * The provider half of the host port. Built only by the two functions below.
+ * The provider half of the host port.
  * Each step is separate so `createBrowser` owns a provider session id from the
  * moment it exists, including when its CDP connect then fails.
  */
@@ -31,7 +32,7 @@ export type BrowserSessions = Readonly<{
     connect: (sessionId: string, signal: AbortSignal) => Promise<CdpClient>;
     /** Ask the provider to delete a session; 404 is already gone. @internal */
     release: (sessionId: string, signal: AbortSignal) => Promise<"closed" | "closing">;
-    /** Reads the provider's session record until it reports an end time. @internal */
+    /** Confirm provider closure (Chromium checks context absence). @internal */
     confirmClosed: (sessionId: string, deadlineAt: number) => Promise<void>;
 }>;
 /** A Workers BROWSER binding (`Fetcher`), reduced to the call this module makes. */
@@ -50,3 +51,5 @@ export declare function browserRunSessions(config: Readonly<{
 }>): BrowserSessions;
 /** A standalone Oyster's own Workers BROWSER binding. */
 export declare function bindingSessions(binding: BrowserBinding): BrowserSessions;
+/** Staging uses Chromium's native CDP browser contexts; no session store. */
+export declare function onboxBrowserSessions(origin: string, fetcher?: HttpFetch): BrowserSessions;

package/dist/browser/sessions.js

@@ -116,3 +116,162 @@ export function bindingSessions(binding) {
         connect: (url, headers, signal) => openCdpSocket(fetcher, url, headers, signal),
     });
 }
+/** Staging uses Chromium's native CDP browser contexts; no session store. */
+export function onboxBrowserSessions(origin, fetcher = (url, init) => fetch(url, init)) {
+    const base = new URL(origin);
+    if (base.protocol !== "http:" ||
+        base.hostname !== "127.0.0.1" ||
+        base.username ||
+        base.password ||
+        base.pathname !== "/" ||
+        base.search ||
+        base.hash)
+        throw new TypeError("On-box browser origin must be bare IPv4 loopback");
+    const browserEndpointSchema = z.object({ webSocketDebuggerUrl: z.url() });
+    const contextsSchema = z.object({ browserContextIds: z.array(z.string()) });
+    const createdContextSchema = z.object({
+        browserContextId: z.string().min(1),
+    });
+    async function connectBrowser(signal) {
+        // Chromium's native discovery endpoint is not a Botanical session server.
+        let discovery;
+        try {
+            discovery = await fetcher(new URL("/json/version", base).href, {
+                signal,
+            });
+        }
+        catch (cause) {
+            if (signal.aborted)
+                throw cause;
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.connect",
+                status: null,
+                message: "On-box Chromium is unavailable",
+            });
+        }
+        if (!discovery.ok)
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.connect",
+                status: discovery.status,
+                message: "On-box Chromium is unavailable",
+            });
+        let body;
+        try {
+            body = await discovery.json();
+        }
+        catch (cause) {
+            if (signal.aborted)
+                throw cause;
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.connect",
+                status: null,
+                message: "On-box browser returned an unreadable CDP endpoint",
+            });
+        }
+        const discovered = browserEndpointSchema.safeParse(body);
+        if (!discovered.success)
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.connect",
+                status: null,
+                message: "On-box browser returned an unreadable CDP endpoint",
+            });
+        const { webSocketDebuggerUrl } = discovered.data;
+        const endpoint = new URL(webSocketDebuggerUrl);
+        if (endpoint.protocol !== "ws:" ||
+            endpoint.hostname !== "127.0.0.1" ||
+            endpoint.port !== base.port ||
+            !/^\/devtools\/browser\/[^/]+$/u.test(endpoint.pathname) ||
+            endpoint.username ||
+            endpoint.password ||
+            endpoint.search ||
+            endpoint.hash)
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.connect",
+                status: null,
+                message: "On-box browser returned an invalid CDP endpoint",
+            });
+        return createCdpClient(await openCdpSocket(fetcher, endpoint.href.replace(/^ws:/u, "http:"), {}, signal));
+    }
+    async function contexts(client, signal) {
+        const result = contextsSchema.safeParse(await client.call("Target.getBrowserContexts", {}, { signal }));
+        if (!result.success)
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.contexts",
+                status: null,
+                message: "On-box browser returned unreadable contexts",
+            });
+        return result.data.browserContextIds;
+    }
+    return {
+        create: async (_options, signal) => {
+            // Chromium has no idle keep-alive or allowedDomains create guardrail:
+            // Oyster's Agent URL policy and the boot page request gate remain active.
+            // A Chromium restart ends every context; no restart recovery is claimed.
+            const client = await connectBrowser(signal);
+            try {
+                const created = createdContextSchema.safeParse(await client.call("Target.createBrowserContext", {}, { signal }));
+                if (!created.success)
+                    throw new CloudBrowserUpstreamError({
+                        op: "onbox.create",
+                        status: null,
+                        message: "On-box browser returned an unreadable context",
+                    });
+                const { browserContextId } = created.data;
+                try {
+                    await client.call("Target.createTarget", { url: "about:blank", browserContextId }, { signal });
+                    return browserContextId;
+                }
+                catch (error) {
+                    await client.call("Target.disposeBrowserContext", { browserContextId }, { signal });
+                    throw error;
+                }
+            }
+            finally {
+                client.close();
+            }
+        },
+        connect: async (id, signal) => {
+            const client = await connectBrowser(signal);
+            try {
+                if (!(await contexts(client, signal)).includes(id))
+                    throw new CloudBrowserUpstreamError({
+                        op: "onbox.connect",
+                        status: null,
+                        message: "On-box browser context is gone",
+                    });
+                return { ...client, browserContextId: id };
+            }
+            catch (error) {
+                client.close();
+                throw error;
+            }
+        },
+        release: async (id, signal) => {
+            const client = await connectBrowser(signal);
+            try {
+                if ((await contexts(client, signal)).includes(id))
+                    await client.call("Target.disposeBrowserContext", { browserContextId: id }, { signal });
+                return "closed";
+            }
+            finally {
+                client.close();
+            }
+        },
+        confirmClosed: async (id, deadlineAt) => {
+            const signal = AbortSignal.timeout(Math.max(1, deadlineAt - Date.now()));
+            const client = await connectBrowser(signal);
+            try {
+                if (!(await contexts(client, signal)).includes(id))
+                    return;
+            }
+            finally {
+                client.close();
+            }
+            throw new CloudBrowserUpstreamError({
+                op: "onbox.close.confirm",
+                status: null,
+                message: "On-box browser did not confirm closure",
+            });
+        },
+    };
+}

package/dist/browser/url-policy.d.ts

@@ -12,7 +12,9 @@ export type UrlCheckOptions = Readonly<{
  * `169.254.169.254`, a private range like `10/8`, the box's own address, and
  * a rebinding hostname (one whose DNS answer is private) are all refused
  * here, before Cloudflare ever sees the URL. The name is resolved once; the
- * caller never connects to it directly — Cloudflare does, so this is a policy
- * gate, not a proxy.
+ * caller does not connect directly: Browser Run does in production, Chromium
+ * does on staging. This check is not network confinement: a page can redirect,
+ * load subresources or resolve the host differently after this check. Staging
+ * must isolate Chromium's network egress before enabling Agent leases.
  */
 export declare function assertCloudBrowserUrlAllowed(raw: string, options: UrlCheckOptions): Promise<URL>;

package/dist/browser/url-policy.js

@@ -10,8 +10,10 @@ import { CloudBrowserUrlDenied } from "./errors.js";
  * `169.254.169.254`, a private range like `10/8`, the box's own address, and
  * a rebinding hostname (one whose DNS answer is private) are all refused
  * here, before Cloudflare ever sees the URL. The name is resolved once; the
- * caller never connects to it directly — Cloudflare does, so this is a policy
- * gate, not a proxy.
+ * caller does not connect directly: Browser Run does in production, Chromium
+ * does on staging. This check is not network confinement: a page can redirect,
+ * load subresources or resolve the host differently after this check. Staging
+ * must isolate Chromium's network egress before enabling Agent leases.
  */
 export async function assertCloudBrowserUrlAllowed(raw, options) {
     let url;

package/dist/computer-control-port.d.ts

@@ -0,0 +1,26 @@
+import type { z } from "zod";
+import type { computerCreateRequestSchema, computerPageSchema } from "@fungi.computer/computer/fleet/inventory-wire";
+import type { computerStateSchema } from "@fungi.computer/computer/fleet/wire";
+import type { teamComputerDirectorySchema } from "@fungi.computer/nacre/workbench";
+import type { InvocationContext } from "@fungi.computer/mycelium";
+/** Host policy stays outside this family: Hub admits funded slots, standalone
+ * admits its current owner. Both call their durable fleet through this port.
+ * Keep the host contract independent of the Worker-only fleet lifecycle. */
+export type ComputerControlPort = Readonly<{
+    /** List a bounded page from the host-admitted inventory. */
+    list(page: z.output<typeof computerPageSchema>, context: InvocationContext): Promise<z.output<typeof teamComputerDirectorySchema>>;
+    /** Read liveness without waking the Computer. */
+    state(computerId: string, context: InvocationContext): Promise<z.output<typeof computerStateSchema>>;
+    /** Start one inventoried hosted Computer through the host's admission. */
+    start(computerId: string, context: InvocationContext): Promise<z.output<typeof computerStateSchema>>;
+    /** Create or replay a durable receipt tied to this request identity. */
+    create(input: z.output<typeof computerCreateRequestSchema>, context: InvocationContext): Promise<{
+        kind: "created";
+        computer: {
+            computerId: string;
+            name: string;
+        };
+    } | {
+        kind: "uncertain" | "denied" | "conflict" | "invalid";
+    }>;
+}>;

package/dist/computer-control-port.js

@@ -0,0 +1 @@
+export {};

package/dist/host.d.ts

@@ -1,6 +1,7 @@
 import type { OysterApprovalCall } from "./approval-home.js";
 import type { PendingApproval, ApprovalApplyResult } from "@fungi.computer/approvals";
 import type { WorkflowControl } from "./workflows.js";
+import type { ComputerControlPort } from "./computer-control-port.js";
 import { type InstallationOperations } from "./installation-operations.js";
 export type { InstallationOperations };
 import type { KnapsackComputer } from "@fungi.computer/knapsack";
@@ -192,6 +193,8 @@ export type OysterHost = Readonly<{
      * @inlineType WorkflowControl
      */
     workflows?: (principal: OysterPrincipal) => Promise<WorkflowControl | null>;
+    /** Owner-admitted durable Computer inventory, absent on hosts without a fleet. */
+    computerControl?: (principal: OysterPrincipal) => ComputerControlPort | null;
     auth: OysterAuth;
     /** Host-held sealing key for member writes; never exposed to the guest.
      * Absence refuses eligible named member writes, even when the App has no sync continuation.

package/dist/machine-link/delivery.d.ts

@@ -13,6 +13,6 @@ export declare function createHomeAwareAgentMailNamespace(options: {
     home: (agentId: string) => Promise<MachineAgentHome | null>;
     hosted: PostRoute<never, never>["namespace"];
     machine: (deviceId: string, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
-    /** Host's Agent grammar: throws unless the receipt is a well-formed Accepted. */
+    /** Host's Agent grammar: validates Accepted or Held without conflating them. */
     accepted: (receipt: Schema.Json) => void;
 }): PostRoute<never, never>["namespace"];

package/dist/machine-link/delivery.js

@@ -28,8 +28,7 @@ export function createHomeAwareAgentMailNamespace(options) {
                     address.scopeId !== options.sender.teamId ||
                     address.agentId !== agentId ||
                     mail.to.agentId !== agentId ||
-                    mail.from.agentId !== options.sender.agentId ||
-                    new TextEncoder().encode(JSON.stringify(mail)).byteLength > 256 * 1024)
+                    mail.from.agentId !== options.sender.agentId)
                     return "refused";
                 const projected = await options.home(agentId);
                 if (projected === null)
@@ -45,7 +44,7 @@ export function createHomeAwareAgentMailNamespace(options) {
                 if (result === "accepted" ||
                     result === "duplicate" ||
                     !("receipt" in result))
-                    throw new Error("Agent mail acknowledgment lacks an Accepted receipt");
+                    throw new Error("Agent mail acknowledgment lacks a valid acceptance or Held receipt");
                 if (result.status !== "refused")
                     options.accepted(result.receipt);
                 return result;

package/dist/machine-link/host.d.ts

@@ -1,5 +1,6 @@
-import type { PostEnvelope, PostDeliveryResult } from "@fungi.computer/carrier/post";
-import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type SeamReplayStore } from "@fungi.computer/seam";
+import { type PostEnvelope, type PostDeliveryResult } from "@fungi.computer/carrier/post";
+import { type WatchdogSqliteOwner } from "@fungi.computer/watchdog";
 export type MachineLinkDevice = Readonly<{
     deviceId: string;
     memberId: string;
@@ -8,16 +9,21 @@ export type MachineLinkDevice = Readonly<{
 }>;
 /**
  * Native device socket I/O. Pins/member authority and mail admission are supplied
- * by their existing owners. Native attachments survive hibernation; pending
- * Post I/O does not claim durable custody and is retried by Carrier.
+ * by their existing owners. Native attachments survive hibernation; Carrier
+ * owns durable custody and per-Agent ordering across socket lifetimes.
  */
 export declare class MachineLinkHost {
     #private;
     private readonly context;
+    private readonly owner;
     private readonly options;
     private readonly channels;
-    private readonly replay;
-    private readonly routes;
+    private replayRuntime;
+    private readonly router;
+    private readonly custodyRoutes;
+    private deviceId;
+    private custodyRuntime;
+    private readonly receipts;
     constructor(context: Pick<DurableObjectState, "getWebSockets" | "acceptWebSocket" | "setWebSocketAutoResponse" | "waitUntil">, owner: WatchdogSqliteOwner, options: Readonly<{
         teamId: string;
         directory: () => Promise<readonly {
@@ -25,14 +31,39 @@ export declare class MachineLinkHost {
             name: string;
         }[]>;
         authorize: (deviceId: string) => Promise<MachineLinkDevice>;
+        replay: () => Promise<SeamReplayStore>;
         receive: (device: MachineLinkDevice, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+        /** Arm the Durable Object alarm for Carrier/Watchdog progress. */
+        scheduleWake: (at: number) => Promise<void>;
         /** The host's failure log for refused dials and closed links. */
         report: (operation: string, cause: unknown) => void;
     }>);
     fetch(request: Request): Promise<Response>;
+    private replayStore;
+    /** Start the fresh socket and then hand durable rows to its live channel. */
+    connected(socket: WebSocket, deviceId: string): Promise<void>;
     private publishDirectory;
     private channel;
     deliver(deviceId: string, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    private deliverLiveOperation;
+    private deliverCustodyMail;
+    /** Run due Carrier work; expired rows remain visible as Carrier dead letters. */
+    alarm(): Promise<void>;
+    /** Expose terminal custody rows so S9 can stage its own disposition reply. */
+    deadLetters(afterKey?: string): Promise<Readonly<{
+        letters: readonly Readonly<{
+            key: string;
+            reason: "refused" | "exhausted" | "expired";
+            envelope: PostEnvelope;
+            attempts: number;
+        }>[];
+        nextCursor: string | undefined;
+    }>>;
+    private deliverToSocket;
+    private custody;
+    private createCustody;
+    private releaseCustody;
+    private drainCustody;
     message(socket: WebSocket, message: string | ArrayBuffer): Promise<void>;
     close(socket: WebSocket): void;
     private authorizeSocket;