@reclaimprotocol/agent 0.1.24 → 0.1.25

package/README.md

@@ -12,6 +12,7 @@ This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depen
 
 - **Node 20 or later.** Any line works, including non-LTS ones such as 25, but a current LTS line (22 or 24) is recommended.
 - **A local Chrome, Chromium, or Edge**, used for capture and for the dashboard login.
+- **Docker** — only for `attach_browser`'s `container` mode, which runs the Reclaim browser runtime (the same image the hosted browser uses) and gives you a link you can send to whoever holds the account. It is the free way to get that link; the hosted remote browser is the other, and it is chargeable. Not needed if you are doing the work yourself. The image is amd64, so Apple Silicon runs it translated. OrbStack handles that itself; Docker Desktop needs Rosetta enabled. `RECLAIM_BROWSER_RUNTIME_IMAGE` overrides the pinned digest.
 - **`cloudflared`** — not required up front. `share_browser_view` uses an existing install if one is on `PATH`, and otherwise downloads it once to `~/.reclaim/bin` on first share (never at install time). Set `RECLAIM_CLOUDFLARED_PATH` to point at your own copy.
 
 The first time you call `run_proof`, the agent downloads the ZK circuit files it needs (about 280 MB), so allow a moment for that first proof. The download is deferred to the first proof rather than run at install time, so the MCP server itself starts immediately.
@@ -87,7 +88,7 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 
 | Tool                                        | Purpose                                                                                                        |
 | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `attach_browser`                            | Connect through local Chrome, Builder-hosted Popcorn, or a custom CDP websocket. All four options — including how each one is watched live — are spelled out in the tool description, so an agent can put the choice to the developer and connect in one call |
+| `attach_browser`                            | Connect to a browser. Grouped by use case: working alone → local Chrome (launched, or the one already open); someone else has to sign in → the Reclaim runtime in Docker (free) or a hosted remote browser (chargeable). The tool description asks which case applies before listing anything, so an agent can put the choice to the developer and connect in one call |
 | `list_tabs`                                 | List open Chrome tabs                                                                                          |
 | `navigate`, `wait_for_page`, `eval_in_page` | Drive the tab; poll for login completion                                                                       |
 | `start_capture`, `stop_capture`             | Network capture lifecycle                                                                                      |
@@ -100,7 +101,7 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 | `create_provider_version_from_capture`      | Publish a drafted provider to the backend                                                                      |
 | `authenticate_builder`                      | In old-devtools mode only, sign in to Builder for remote-browser allocation                                   |
 | `list_builder_organizations`                | In old-devtools mode only, list organization ids for a quota-accounted Builder browser                         |
-| `share_browser_view`, `stop_browser_view`   | Put a LOCAL attached tab behind a public HTTPS URL (cloudflared quick tunnel) so someone elsewhere can watch it and, by default, click and type in it. Local CDP modes only — a `builder` browser already returns a hosted `liveViewUrl` |
+| `share_browser_view`, `stop_browser_view`   | Put the `container` browser's own live view behind a public HTTPS URL (cloudflared quick tunnel), so someone elsewhere can watch it and act in it — from a phone if they like. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
 | `dispose_browser`                           | Stop captures, disconnect CDP, and immediately release a Builder-hosted browser                               |
 | `get_session`, `reset_session`              | Session state                                                                                                  |
 

package/lib/cdp/claims.d.ts

@@ -0,0 +1,21 @@
+/** Whether a process is still running. Signal 0 checks without delivering. */
+export declare function processAlive(pid: number): boolean;
+/** Slots with at least one live claimant, so a caller can avoid them. */
+export declare function busySlots(): Set<string>;
+/**
+ * Slots THIS process already holds.
+ *
+ * Its own claim must not push it onto a new slot: re-attaching in one session
+ * should come back to the browser it is already running, not start a second.
+ */
+export declare function ownSlots(): Set<string>;
+/** Take a claim on `slot`. Returns the token to release it with. */
+export declare function claim(slot: string): string;
+/**
+ * Give up this process's claim.
+ *
+ * Returns true when nobody is left, which is the caller's signal to stop the
+ * container. Returns false while another live session still holds it — stopping
+ * then would pull the browser out from under them.
+ */
+export declare function release(slot: string, token: string): boolean;

package/lib/cdp/claims.js

@@ -0,0 +1,129 @@
+/**
+ * Which sessions are using which browser container.
+ *
+ * A container is worth sharing: about 2 GB of RAM and 7 to 17 seconds to start,
+ * so a developer running one session after another should get the same one back
+ * rather than pay for a new one each time.
+ *
+ * It can only be shared SEQUENTIALLY, and the profile is why. Every container
+ * mounts a host directory as Chromium's `user-data-dir`, and the runtime
+ * deletes `SingletonLock` on boot — so a second container on the same profile
+ * is a second writer on one cookie jar. Chromium does not support that, and the
+ * failure is silent corruption of the thing most worth keeping: the login.
+ *
+ * So each container gets a SLOT. A slot has one profile and at most one live
+ * claimant. A session adopts the first slot nobody holds; when the last claim
+ * on a slot goes, the container stops.
+ *
+ * State lives in a file because each MCP session is its own OS process, with
+ * no shared memory to count in. Claims are process ids, and liveness is a
+ * signal-0 check — the same test the orphan reaper uses. It fails the harmless
+ * way: a recycled pid keeps a container alive rather than pulling one out from
+ * under a running session.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LOGGER } from "../logger.js";
+import { reclaimHomeDirPath } from "../paths.js";
+/** Distinguishes claims made by this same process. */
+let claimSeq = 0;
+/** The pid a token belongs to, or 0 when it is malformed. */
+function tokenPid(token) {
+    const pid = Number(token.split('.')[0]);
+    return Number.isInteger(pid) ? pid : 0;
+}
+function claimsPath() {
+    return join(reclaimHomeDirPath(), 'browser-runtime-claims.json');
+}
+function read() {
+    try {
+        const parsed = JSON.parse(readFileSync(claimsPath(), 'utf8'));
+        // Drop claims whose process is gone: that is what makes a slot free again
+        // after a session was killed without cleaning up.
+        const live = {};
+        for (const [slot, tokens] of Object.entries(parsed)) {
+            const alive = (Array.isArray(tokens) ? tokens : [])
+                .filter((token) => processAlive(tokenPid(token)));
+            if (alive.length) {
+                live[slot] = alive;
+            }
+        }
+        return live;
+    }
+    catch {
+        // Missing or unreadable: nobody has claimed anything.
+        return {};
+    }
+}
+function write(claims) {
+    const path = claimsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // Write then rename, so a reader never sees a half-written file. Two sessions
+    // racing here means last-writer-wins on a file that is pruned on every read,
+    // which costs at most one redundant container.
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(claims, null, '\t')}\n`);
+    renameSync(temp, path);
+}
+/** Whether a process is still running. Signal 0 checks without delivering. */
+export function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but belongs to another user — alive either way.
+        return err.code === 'EPERM';
+    }
+}
+/** Slots with at least one live claimant, so a caller can avoid them. */
+export function busySlots() {
+    return new Set(Object.keys(read()));
+}
+/**
+ * Slots THIS process already holds.
+ *
+ * Its own claim must not push it onto a new slot: re-attaching in one session
+ * should come back to the browser it is already running, not start a second.
+ */
+export function ownSlots() {
+    const mine = new Set();
+    for (const [slot, tokens] of Object.entries(read())) {
+        if (tokens.some((token) => tokenPid(token) === process.pid)) {
+            mine.add(slot);
+        }
+    }
+    return mine;
+}
+/** Take a claim on `slot`. Returns the token to release it with. */
+export function claim(slot) {
+    const token = `${process.pid}.${++claimSeq}`;
+    const claims = read();
+    claims[slot] = [...claims[slot] ?? [], token];
+    write(claims);
+    LOGGER.debug({ slot, held: claims[slot] }, 'claimed a browser slot');
+    return token;
+}
+/**
+ * Give up this process's claim.
+ *
+ * Returns true when nobody is left, which is the caller's signal to stop the
+ * container. Returns false while another live session still holds it — stopping
+ * then would pull the browser out from under them.
+ */
+export function release(slot, token) {
+    const claims = read();
+    const remaining = (claims[slot] ?? []).filter((held) => held !== token);
+    if (remaining.length) {
+        claims[slot] = remaining;
+        write(claims);
+        LOGGER.debug({ slot, remaining }, 'released a claim; others still hold it');
+        return false;
+    }
+    delete claims[slot];
+    write(claims);
+    return true;
+}

package/lib/cdp/client.d.ts

@@ -19,16 +19,6 @@ interface CdpTabEventMap {
     'Network.loadingFinished': {
         requestId: string;
     };
-    /** Screencast frames, for the live view (`live/viewer.ts`). Each carries a
-     *  `sessionId` that MUST be acked with `Page.screencastFrameAck`, or CDP
-     *  stops sending. */
-    'Page.screencastFrame': {
-        data: string;
-        sessionId: number;
-        metadata?: {
-            timestamp?: number;
-        };
-    };
 }
 export interface CdpTabClient {
     send: (method: string, params?: object) => Promise<unknown>;

package/lib/cdp/container.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The pinned runtime image.
+ *
+ * A digest, not a tag. Upstream publishes 40-char git SHAs plus moving
+ * `main`/`latest` aliases and no semver at all, and its own docs say to
+ * "prefer immutable digests". Pinning one means an agent release cannot have
+ * the browser changed underneath it.
+ *
+ * Digest of `latest` as of 2026-08-22, built from popcorn-oss
+ * `4df751c25c7b329699033957b93f6486837e4acb`.
+ */
+export declare const BROWSER_RUNTIME_IMAGE: string;
+export interface ContainerBrowser {
+    /** Local viewer origin — what `share_browser_view` tunnels. */
+    viewerUrl: string;
+    /** Browser-level CDP websocket, for `connectCdpUrl`. */
+    cdpUrl: string;
+    /** Loopback port the viewer is published on. */
+    viewerPort: number;
+    /** Docker's name for this container. */
+    name: string;
+    /** Whether the image had to be pulled first — worth telling the developer. */
+    pulled: boolean;
+    /** Which slot this browser occupies, for diagnostics. */
+    slot: number;
+    stop: () => Promise<void>;
+}
+export interface ContainerOptions {
+    /** Loopback port for the viewer. Allocated when omitted. */
+    viewerPort?: number;
+    /** Loopback port for full CDP. Allocated when omitted. */
+    cdpPort?: number;
+    /** Override the pinned image, e.g. a local `build.sh` output. */
+    image?: string;
+    /** Framebuffer size, which is also the browser window's size. */
+    width?: number;
+    height?: number;
+    /** Page to open on start. */
+    url?: string;
+}
+/**
+ * Where the container's Chromium profile lives on the host.
+ *
+ * Mounted, unlike the reference dev script, for two reasons. Provider authoring
+ * means signing in once and capturing an authenticated request, which a profile
+ * that dies with the container makes impossible. And the profile holds the
+ * persisted fingerprint identity — canvas/audio seed, timezone, locale — which
+ * upstream warns must stay stable, since "flipping any of them against the same
+ * cookie jar is itself a bot signal".
+ */
+export declare function containerProfileDir(slot?: number): string;
+/** Docker CLI present AND its daemon reachable. */
+export declare function dockerAvailable(): Promise<boolean>;
+/** Message for the case we cannot fix for them. */
+export declare function dockerMissingMessage(): string;
+/**
+ * The `docker run` argv.
+ *
+ * A pure function because every flag here is load bearing and none of it is
+ * obvious from the outside: which ports are loopback-only, that the image is
+ * digest-pinned, that the profile is mounted. Tests assert on this directly
+ * rather than trying to observe a running container.
+ */
+export declare function buildRunArgs(opts: ContainerOptions & {
+    viewerPort: number;
+    cdpPort: number;
+}, image: string, name: string, profileDir: string): string[];
+/**
+ * Start a browser container and wait until it is actually serving.
+ *
+ * Ports are allocated per call, so concurrent sessions never land on the same
+ * container. Pass `viewerPort` to pin one — re-attaching with the same port
+ * reuses the container that is already there.
+ */
+export declare function startContainer(options?: ContainerOptions): Promise<ContainerBrowser>;
+/**
+ * Remove containers whose owning process is gone.
+ *
+ * Shutdown cleanup covers an orderly exit, but a SIGKILL or a crash runs
+ * nothing — and a 1.3 GB container with a live browser in it should not outlive
+ * the session that made it. Reaping at startup catches those, and the owner-PID
+ * label keeps it safe: a container whose owner still runs belongs to another
+ * session and is left alone.
+ */
+export declare function reapOrphanedContainers(): Promise<string[]>;