@reclaimprotocol/agent 0.1.35 → 0.1.37

package/lib/cdp/launcher.js

@@ -1,9 +1,29 @@
+import { conflict, failedDependency, gatewayTimeout, preconditionFailed, } from '@hapi/boom';
+import assert from 'node:assert';
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { existsSync, lstatSync, mkdirSync, readlinkSync, unlinkSync } from 'node:fs';
+import { homedir, hostname, platform } from 'node:os';
 import { join } from 'node:path';
 import { chromePath, localAppData } from "../consts.js";
+import { LOGGER } from "../logger.js";
 import { reclaimHomeDirPath } from "../paths.js";
+import { installChromeForTesting } from "./chrome-for-testing.js";
+/** How long a launched browser gets to answer CDP. A cold first start on a
+ *  slow disk, or Chrome for Testing's first run, can take well over 10s. */
+export const CDP_READY_TIMEOUT_MS = 30000;
+/** How much of the browser's stderr to keep for error messages. */
+const STDERR_TAIL_CHARS = 4096;
+/** The files Chrome uses on POSIX to claim a profile. `SingletonLock` is a
+ *  symlink to `<hostname>-<pid>`; the other two point at the IPC socket and a
+ *  random cookie, and are only meaningful while that process lives. */
+const SINGLETON_FILES = ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
+const DEFAULT_DEPENDENCIES = {
+    platform,
+    env: () => process.env,
+    chromePath,
+    findInstalled: () => findInstalledBrowsers(),
+    installChromeForTesting,
+};
 /**
  * Build the platform-specific list of Chromium-family binaries to probe.
  * Order matters: Chrome first, then Chromium, then Edge (Edge is
@@ -15,8 +35,8 @@ import { reclaimHomeDirPath } from "../paths.js";
  * without admin rights ("Install for me only"). Skipping this was the
  * #1 first-run failure observed in the field.
  */
-function browserCandidates() {
-    switch (platform()) {
+export function browserCandidates(os = platform()) {
+    switch (os) {
         case 'darwin':
             return [
                 '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
@@ -50,26 +70,105 @@ function browserCandidates() {
             return [];
     }
 }
+/** The candidates that exist on this machine, in preference order. */
+export function findInstalledBrowsers(candidates = browserCandidates()) {
+    return candidates.filter((c) => existsSync(c));
+}
 export function defaultProfileDir() {
     return join(reclaimHomeDirPath(), 'chrome-profile');
 }
 export function findChromeBinary() {
     const candidates = browserCandidates();
-    for (const c of candidates) {
-        if (existsSync(c)) {
-            return c;
-        }
+    const found = chromePath() ?? findInstalledBrowsers(candidates)[0];
+    if (found) {
+        return found;
     }
     throw new Error(`No Chromium-family browser found on ${platform()}. Tried:\n  ` +
         candidates.join('\n  ') +
         '\nSet RECLAIM_AGENT_CHROME_PATH to point at ' +
         'your chrome.exe / msedge.exe / chromium binary.');
 }
-export function launchChrome(opts) {
-    const binary = chromePath() ?? findChromeBinary();
-    if (!existsSync(opts.profileDir)) {
-        mkdirSync(opts.profileDir, { recursive: true });
+/**
+ * Why a visible browser cannot open here, or undefined when it can. Only
+ * Linux needs a display server named in the environment; an MCP server
+ * started outside the desktop session (a sandboxed agent, a service) often
+ * has neither variable, and Chrome then exits before CDP ever answers.
+ */
+export function missingDisplayReason(os = platform(), env = process.env) {
+    if (os !== 'linux' || env.WAYLAND_DISPLAY || env.DISPLAY) {
+        return undefined;
+    }
+    return 'No display: neither WAYLAND_DISPLAY nor DISPLAY is set in the '
+        + 'Reclaim MCP server\'s environment, so a visible browser cannot open. '
+        + 'Start the agent from the desktop session, or pass the variables to '
+        + 'the MCP server (for example DISPLAY=:0, or WAYLAND_DISPLAY=wayland-0 '
+        + 'with XDG_RUNTIME_DIR), then restart the agent.';
+}
+/**
+ * Launch a visible browser on this machine with the given profile, and wait
+ * until it answers CDP.
+ *
+ * Uses `RECLAIM_AGENT_CHROME_PATH` when set, else the first installed browser
+ * (Chrome, then Chromium, then Edge). When none is installed, or that one
+ * fails to start, it falls back to Chrome for Testing, downloaded once into
+ * `~/.reclaim/browsers`. A missing display fails fast instead: no browser can
+ * open without one, so a download would only waste time.
+ */
+export async function launchLocalBrowser(opts, dependencies = {}) {
+    const deps = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+    const noDisplay = missingDisplayReason(deps.platform(), deps.env());
+    assert(!noDisplay, preconditionFailed(noDisplay));
+    // A live owner would make every launch below fail the same way, so refuse
+    // once with the reason instead of trying Chrome for Testing too.
+    releaseStaleProfileLock(opts.profileDir, deps.platform());
+    const override = deps.chromePath();
+    const preferred = override ?? deps.findInstalled()[0];
+    let fallbackReason = 'No Chrome, Chromium, or Edge is installed.';
+    if (preferred) {
+        try {
+            return {
+                binary: preferred,
+                source: override ? 'override' : 'installed',
+                process: await startChrome(preferred, opts),
+                downloaded: false,
+            };
+        }
+        catch (err) {
+            fallbackReason = errorMessage(err);
+            LOGGER.warn({ binary: preferred, reason: fallbackReason }, 'local browser failed to start; trying Chrome for Testing');
+        }
+    }
+    let cft;
+    try {
+        cft = await deps.installChromeForTesting();
+    }
+    catch (err) {
+        throw failedDependency(`${fallbackReason}\nChrome for Testing could not be installed into `
+            + `~/.reclaim/browsers: ${errorMessage(err)}`);
     }
+    try {
+        return {
+            binary: cft.executablePath,
+            source: 'chrome-for-testing',
+            process: await startChrome(cft.executablePath, opts),
+            downloaded: cft.downloaded,
+            fallbackReason,
+        };
+    }
+    catch (err) {
+        throw failedDependency(`${fallbackReason}\nChrome for Testing (${cft.executablePath}) also `
+            + `failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Spawn `binary` on `opts.profileDir` and wait for CDP. On failure the
+ * process is stopped and the error says why: it could not be spawned, it
+ * exited (with its code and the tail of its stderr), or it never answered.
+ */
+export async function startChrome(binary, opts) {
+    const timeoutMs = opts.timeoutMs ?? CDP_READY_TIMEOUT_MS;
+    mkdirSync(opts.profileDir, { recursive: true });
+    releaseStaleProfileLock(opts.profileDir);
     const args = [
         `--remote-debugging-port=${opts.port}`,
         `--user-data-dir=${opts.profileDir}`,
@@ -80,24 +179,145 @@ export function launchChrome(opts) {
         args.push('--headless=new', '--disable-gpu');
     }
     const child = spawn(binary, args, {
-        stdio: 'ignore',
+        stdio: ['ignore', 'ignore', 'pipe'],
         detached: false,
     });
-    return child;
-}
-export async function waitForCdpReady(port, timeoutMs = 10000) {
+    // Drained for the browser's whole life, not just until it is ready: a
+    // full pipe would block its writes.
+    let stderr = '';
+    child.stderr?.setEncoding('utf8');
+    child.stderr?.on('data', (chunk) => {
+        stderr = (stderr + chunk).slice(-STDERR_TAIL_CHARS);
+    });
+    let spawnError;
+    child.once('error', (err) => {
+        spawnError = err;
+    });
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
+        if (await cdpAnswers(opts.port)) {
+            return child;
+        }
+        if (spawnError) {
+            throw failedDependency(`Could not start ${binary}: ${spawnError.message}`);
+        }
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw failedDependency(`${binary} exited with ${child.exitCode !== null
+                ? `code ${child.exitCode}`
+                : `signal ${child.signalCode}`} before CDP answered on port `
+                + `${opts.port}.${stderrTail()}`);
+        }
+        await sleep(150);
+    }
+    await stopProcess(child);
+    throw gatewayTimeout(`${binary} did not answer CDP on port ${opts.port} within `
+        + `${timeoutMs}ms.${stderrTail()}`);
+    function stderrTail() {
+        const tail = stderr.trim();
+        return tail ? `\nBrowser stderr (last ${tail.length} chars):\n${tail}` : '';
+    }
+}
+/**
+ * Remove a dead browser's claim on `profileDir` so a new launch can take it.
+ *
+ * Chrome on POSIX claims a profile with `SingletonLock -> <hostname>-<pid>`.
+ * If that process is gone (a crash, a killed session) the links stay behind
+ * and the next launch hands off to the missing owner and exits. A lock whose
+ * PID is alive on this host belongs to a running browser, and is left alone:
+ * that browser must be closed first. A lock from another hostname is treated
+ * as stale: `~/.reclaim` is local, and a sandbox or container that changes the
+ * hostname between runs is the usual way to get one. Callers reach this only
+ * after nothing answered CDP on the port.
+ */
+export function releaseStaleProfileLock(profileDir, os = platform()) {
+    // Windows locks the profile with a plain file the OS releases on exit.
+    if (os === 'win32') {
+        return;
+    }
+    const target = readLink(join(profileDir, 'SingletonLock'));
+    const owner = target?.match(/^(.+)-(\d+)$/);
+    if (owner?.[1] === hostname() && processAlive(Number(owner[2]))) {
+        throw conflict(`The browser profile ${profileDir} is in use by a running browser `
+            + `(PID ${owner[2]}) that is not answering CDP on the requested port. `
+            + 'Close that browser window, then retry.');
+    }
+    const removed = SINGLETON_FILES.filter((name) => {
+        const path = join(profileDir, name);
+        if (readLink(path) === undefined) {
+            return false;
+        }
         try {
-            const res = await fetch(`http://127.0.0.1:${port}/json/version`);
-            if (res.ok) {
-                return;
-            }
+            unlinkSync(path);
+            return true;
+        }
+        catch (err) {
+            LOGGER.warn({ err, path }, 'could not remove a stale profile lock');
+            return false;
         }
-        catch {
-            // retry
+    });
+    if (removed.length) {
+        LOGGER.info({ profileDir, removed, owner: target }, 'removed a stale browser profile lock');
+    }
+}
+/**
+ * Wait until something answers CDP on `port`, polling every 150ms.
+ */
+export async function waitForCdpReady(port, timeoutMs = CDP_READY_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await cdpAnswers(port)) {
+            return;
         }
-        await new Promise((r) => setTimeout(r, 150));
+        await sleep(150);
     }
-    throw new Error(`Chrome CDP did not become ready on port ${port} within ${timeoutMs}ms`);
+    throw gatewayTimeout(`Chrome CDP did not become ready on port ${port} within ${timeoutMs}ms`);
+}
+/** A listener that accepts but never answers (a stale non-CDP service on the
+ *  port) fails the poll after 2s instead of outliving the launch deadline. */
+async function cdpAnswers(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** SIGTERM, then SIGKILL if it lingers, and wait for the exit either way, so
+ *  the profile lock is released before anything launches on it again. */
+async function stopProcess(child) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    const exited = new Promise((r) => child.once('exit', () => r()));
+    child.kill('SIGTERM');
+    const timer = setTimeout(() => child.kill('SIGKILL'), 3000);
+    await exited;
+    clearTimeout(timer);
+}
+function readLink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink() ? readlinkSync(path) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists, it just belongs to someone else.
+        return err instanceof Error && 'code' in err && err.code === 'EPERM';
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
 }

package/lib/logger.js

@@ -1,8 +1,10 @@
 import pino, { stdTimeFunctions } from 'pino';
 import { LOG_LEVEL } from "./consts.js";
+// stderr, not pino's default stdout: the MCP server speaks JSON-RPC over
+// stdout, so a log line there corrupts the protocol stream.
 export const LOGGER = pino({
     name: '@reclaimprotocol/agent',
     timestamp: stdTimeFunctions.isoTime,
     base: { hostname: undefined, pid: undefined },
-});
+}, pino.destination(2));
 LOGGER.level = LOG_LEVEL;

package/lib/mcp/api/operations.gen.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:de7373741e35).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:96339e8dff91).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.

package/lib/mcp/instructions.js

@@ -51,9 +51,9 @@ const TOPIC_SUMMARIES = {
     'auth': 'Signing in to the backend, and which token authorizes what.',
     'devtools-migration': 'Importing a public legacy provider with the same '
         + 'UUID.',
-    'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
-        + 'Docker, a remote Builder browser, or a custom CDP endpoint), '
-        + 'geolocation, live view, and launch troubleshooting.',
+    'browser': 'The default local browser, the opt-in modes (attach, the '
+        + 'Reclaim runtime in Docker, a remote Builder browser, a custom CDP '
+        + 'endpoint), geolocation, live view, and launch troubleshooting.',
     'capture': 'Tabs, sign-in detection, capturing through the navigation '
         + 'script, and picking an authenticated request to prove.',
     'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '

package/lib/mcp/start.js

@@ -10,8 +10,9 @@ import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
 import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
+import { startZkFilesDownload } from "../proof/zk-files.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, stopAllForwarders, } from "./tools/index.js";
+import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, sessionRefreshingFetch, stopAllForwarders, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
@@ -31,11 +32,19 @@ export async function startMcpServer() {
     const agentToolsEnabled = !agentDisabled();
     /** The agent state this server registered, for shutdown to release. */
     let agentState;
+    const envToken = apiToken();
     const builderClient = new ReclaimClient({
         baseUrl: apiUrl(),
         // Builder access is orthogonal to publishing mode. A legacy-devtools
         // session can authenticate here solely to allocate a remote browser.
-        token: apiToken() || readSession()?.token,
+        token: envToken || readSession()?.token,
+        // The cached sign-in refreshes itself; an explicit RECLAIM_API_TOKEN
+        // takes precedence and is sent as is.
+        ...(envToken
+            ? {}
+            : {
+                fetch: sessionRefreshingFetch(oldMode ? 'authenticate_builder' : 'reclaim_authenticate'),
+            }),
         headers: { 'User-Agent': `${NAME}/${VERSION}` },
     });
     // Backend-mode toggle — available in both modes and regardless of whether
@@ -99,6 +108,12 @@ export async function startMcpServer() {
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Fetch the proof files in the background so the first proof doesn't wait
+    // for them. Progress goes to stderr; `check_attestor` reports the state,
+    // and every proof still awaits the same download.
+    if (agentToolsEnabled) {
+        startZkFilesDownload();
+    }
 }
 /** How long teardown gets before the process leaves anyway. */
 const SHUTDOWN_GRACE_MS = 10000;

package/lib/mcp/tools/agent/attach.d.ts

@@ -1,6 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api';
 import { type CdpHandles, connectCdp, connectCdpUrl } from '../../../cdp/client.ts';
 import { dockerAvailable, startContainer } from '../../../cdp/container.ts';
+import { launchLocalBrowser, type LocalBrowser, waitForCdpReady } from '../../../cdp/launcher.ts';
 import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
 export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom' | 'container';
@@ -34,6 +35,8 @@ export interface AttachState {
     viewerPort?: number;
     /** Whether the runtime image had to be downloaded on this attach. */
     imagePulled?: boolean;
+    /** `dedicated` mode: the browser this attach launched, if it launched one. */
+    launched?: Omit<LocalBrowser, 'process'>;
     disposeRemote?: () => Promise<void>;
 }
 export interface AttachRef {
@@ -46,6 +49,9 @@ interface AttachDependencies {
     /** Injected so container mode is testable without Docker installed. */
     dockerAvailable: typeof dockerAvailable;
     startContainer: typeof startContainer;
+    /** Injected so the default launch is testable without a real browser. */
+    launchLocal: typeof launchLocalBrowser;
+    waitForCdp: typeof waitForCdpReady;
 }
 export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, beforeReplace?: () => Promise<void>, dependencies?: Partial<AttachDependencies>): RegisteredTool;
 export declare function disposeAttached(state: AttachRef): Promise<void>;