@reclaimprotocol/agent 0.1.24 → 0.1.26

package/lib/mcp/tools/agent/live-view.js

@@ -16,12 +16,9 @@
 import { badRequest, conflict } from '@hapi/boom';
 import assert from 'node:assert';
 import { startTunnel } from "../../../live/tunnel.js";
-import { startLiveView } from "../../../live/viewer.js";
 import { LOGGER } from "../../../logger.js";
 import { defineTool } from "../../server.js";
-/** Modes whose browser we reach over our own CDP connection, and which
- *  therefore have no hosted live view of their own. */
-const SHAREABLE_MODES = new Set(['dedicated', 'attach', 'custom']);
+import { SHAREABLE_MODES } from "./attach.js";
 /** Tear down whatever share is running. Safe when none is. Exported so the
  *  session tools can call it from `dispose_browser` / `reset_session`. */
 export async function stopLiveShare(ref) {
@@ -30,98 +27,87 @@ export async function stopLiveShare(ref) {
         return false;
     }
     ref.current = undefined;
-    await share.view.stop().catch((err) => {
-        LOGGER.warn({ err }, 'live view: server stop failed');
-    });
+    // Only the tunnel is ours to close. The browser and its viewer belong to the
+    // container, which keeps running until the browser is disposed.
     await share.tunnel.stop().catch((err) => {
         LOGGER.warn({ err }, 'live view: tunnel stop failed');
     });
     return true;
 }
-export function liveViewTools(attachRef, captures, shareRef) {
+export function liveViewTools(attachRef, shareRef) {
     return [
         defineTool({
             name: 'share_browser_view',
-            description: 'Put the attached tab behind a PUBLIC HTTPS URL (a cloudflared '
-                + 'quick tunnel) so someone elsewhere can watch it live, and by '
-                + 'default click and type in it. Use it to hand a login or a 2FA '
-                + 'step to the person who holds the credentials, or to let a '
-                + 'colleague watch a capture. Returns the URL — relay it to the '
-                + 'developer VERBATIM, on its own line. '
-                + 'ONLY for a locally attached browser (attach_browser mode '
-                + '`dedicated`, `attach`, or `custom`). In `builder` mode the '
-                + 'Popcorn browser already has a hosted live view: use the '
-                + '`liveViewUrl` that attach_browser returned instead. '
-                + 'THE URL IS A CREDENTIAL: anyone holding it can see this tab, '
-                + 'and with the default `interactive: true` can act in it as the '
-                + 'signed-in user. Share it only with the person who needs it, and '
-                + 'call stop_browser_view the moment they are done. Pass '
-                + '`interactive: false` for a watch-only link. '
+            description: 'Put the attached browser\'s live view behind a PUBLIC HTTPS URL (a '
+                + 'cloudflared quick tunnel) so someone elsewhere can watch it and '
+                + 'act in it. Use it to hand a login or a 2FA step to the person '
+                + 'who holds the credentials, or to let a colleague watch a '
+                + 'capture. Returns the URL — relay it to the developer VERBATIM, '
+                + 'on its own line. '
+                + 'ONLY for `container` mode, whose browser runs its own viewer. '
+                + 'A `builder` browser already has a hosted live view: use the '
+                + '`liveViewUrl` attach_browser returned. A local browser '
+                + '(`dedicated`, `attach`, `custom`) cannot be shared at all — no '
+                + 'tunnel can fix that, because there is no viewer behind it. Tell '
+                + 'them so, and offer to re-attach: `container` is free and needs '
+                + 'Docker, `builder` needs no install but is chargeable. '
+                + 'THE URL IS THE ONLY CREDENTIAL: the random hostname is the whole '
+                + 'secret, with no token or login behind it, so anyone who learns '
+                + 'it can see and drive this browser as the signed-in user. Share '
+                + 'it only with the person who needs it, and call stop_browser_view '
+                + 'the moment they are done. '
                 + 'Needs cloudflared: an existing install on PATH is used as-is, '
                 + 'otherwise it is downloaded once to ~/.reclaim/bin on first '
                 + 'share (never at install time). Set RECLAIM_CLOUDFLARED_PATH to '
                 + 'point at your own copy instead.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    tabId: {
-                        type: 'string',
-                        description: 'Tab to stream, from list_tabs. Defaults to the tab the '
-                            + 'active capture is on, else the first tab.',
-                    },
-                    interactive: {
-                        type: 'boolean',
-                        description: 'Let the viewer click and type in the page. Default true. '
-                            + 'Set false to stream a read-only view.',
-                    },
-                },
-            },
-        }, async ({ tabId, interactive }) => {
+            inputSchema: { type: 'object', properties: {} },
+        }, async () => {
             const attached = attachRef.current;
             assert(attached, badRequest('No browser attached. Call attach_browser first.'));
             assert(SHAREABLE_MODES.has(attached.mode), badRequest(`share_browser_view does not apply to \`${attached.mode}\` mode. `
-                + 'That browser already has a hosted live view — use the '
-                + '`liveViewUrl` from attach_browser'
-                + (attached.liveViewUrl ? `: ${attached.liveViewUrl}` : '')
+                + (attached.liveViewUrl
+                    ? 'That browser already has a hosted live view — use the '
+                        + `\`liveViewUrl\` from attach_browser: ${attached.liveViewUrl}`
+                    : 'That browser has no live view to put behind a URL. To let '
+                        + 'someone else in, re-attach with mode "container" (the '
+                        + 'Reclaim runtime in Docker — free, needs Docker) or '
+                        + '"builder" (hosted, no install, chargeable)')
                 + '.'));
             assert(!shareRef.current, conflict('A live view is already running at '
                 + `${shareRef.current?.url}. Call stop_browser_view first, or `
                 + 'reuse that URL.'));
-            const tabs = tabId || captures.activeTab
-                ? []
-                : await attached.handles.listTabs();
-            const target = tabId ?? captures.activeTab ?? tabs[0]?.tabId;
-            assert(target, badRequest('No tab to stream. Open a tab, or call list_tabs to pick one.'));
-            const tab = await attached.handles.attachToTab(target);
-            const wantsInput = interactive !== false;
-            const view = await startLiveView({
-                tab,
-                interactive: wantsInput,
-                title: `Reclaim — ${attached.mode} browser`,
-            });
-            let tunnel;
-            try {
-                tunnel = await startTunnel(view.port);
-            }
-            catch (err) {
-                // Don't leave the loopback server behind if the tunnel failed.
-                await view.stop().catch(() => { });
-                throw err;
-            }
-            const url = `${tunnel.url}${view.path}`;
+            // The container publishes its viewer on loopback and its full CDP
+            // port beside it. Only the VIEWER is ever tunnelled: the CDP port is
+            // unauthenticated, total control of the browser, and putting it on a
+            // public URL would hand that to anyone with the link.
+            const viewerPort = attached.viewerPort;
+            assert(viewerPort, badRequest('This browser reports no live-view port. Re-attach with mode '
+                + '"container".'));
+            const tunnel = await startTunnel(viewerPort);
+            // The path is the runtime's own viewer page; `magnify=1` is what makes
+            // it lay out for the device that opens it.
+            const url = `${tunnel.url}/liveview.html?magnify=1`;
             const share = {
-                view, tunnel, url, interactive: wantsInput, startedAt: Date.now(),
+                tunnel, url,
             };
             shareRef.current = share;
-            LOGGER.info({ mode: attached.mode, interactive: wantsInput }, 'live view shared');
+            LOGGER.info({ mode: attached.mode }, 'live view shared');
             return {
                 url,
-                interactive: wantsInput,
-                tabId: target,
                 ...(share.tunnel.binary.source === 'downloaded'
                     ? { cloudflaredInstalled: true }
                     : {}),
-                ...(share.tunnel.ready ? {} : { propagating: true }),
+                ...(share.tunnel.ready
+                    ? {}
+                    : {
+                        propagating: true,
+                        // cloudflared's own last words. Without them, "the URL does
+                        // not connect" is unactionable: the tunnel, the local server
+                        // and this machine's egress all look identical from outside.
+                        ...(share.tunnel.diagnostics
+                            ? { cloudflaredLog: share.tunnel.diagnostics }
+                            : {}),
+                    }),
                 _notes: [
                     ...(share.tunnel.binary.source === 'downloaded'
                         ? ['cloudflared was not installed, so it was downloaded once '
@@ -129,24 +115,31 @@ export function liveViewTools(attachRef, captures, shareRef) {
                         : []),
                     ...(share.tunnel.ready
                         ? []
-                        : ['The tunnel had not started routing yet — if the URL '
-                                + 'errors, wait a few seconds and reload.']),
+                        : ['The tunnel never confirmed a connection to Cloudflare, so '
+                                + 'the URL may not resolve yet. Give it ~10s and reload '
+                                + 'first. If it still fails, say so and offer to retry '
+                                + '(stop_browser_view then share_browser_view) — a quick '
+                                + 'tunnel does sometimes fail to register. '
+                                + '`cloudflaredLog` has its output if it keeps happening.']),
                     'Relay `url` to the developer verbatim, on its own line.',
-                    'The URL is a credential: it needs no login, and anyone with '
-                        + 'it can see this tab'
-                        + (wantsInput ? ' and act in it as the signed-in user.' : '.'),
-                    'Call stop_browser_view when they are done — the tunnel stays '
-                        + 'open until you do.',
+                    'The URL is a credential: it needs no login, and anyone with it '
+                        + 'can see this browser and act in it as the signed-in user.',
+                    'It shows the whole browser, so a sign-in that opens a separate '
+                        + 'window is visible too — unlike a single-tab stream.',
+                    'Opening it on a phone lays the page out for that phone, with '
+                        + 'touch, pinch-zoom and the soft keyboard.',
+                    'Call stop_browser_view when they are done. That closes the '
+                        + 'tunnel only — the browser keeps running.',
                 ],
             };
         }),
         defineTool({
             name: 'stop_browser_view',
-            description: 'Close the public live view opened by share_browser_view: stops '
-                + 'the screen stream and shuts the tunnel down, so the URL stops '
-                + 'resolving. Call it as soon as the person you shared with is '
-                + 'finished. The browser itself stays attached and the capture '
-                + 'keeps running.',
+            description: 'Close the public URL opened by share_browser_view: shuts the '
+                + 'tunnel down, so the URL stops resolving for whoever still has '
+                + 'it. Call it as soon as the person you shared with is finished. '
+                + 'Nothing else changes — the browser stays attached, its own live '
+                + 'view keeps serving locally, and any capture keeps running.',
             inputSchema: { type: 'object', properties: {} },
         }, async () => ({ stopped: await stopLiveShare(shareRef) })),
     ];

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

@@ -7,3 +7,17 @@ export declare function sessionTools(attachRef: {
     current?: AttachState;
     config: ConfigStore;
 }, captures: CaptureStore, liveShare: LiveShareRef): RegisteredTool[];
+/**
+ * Release everything a session holds: the public tunnel, the captures, and the
+ * browser itself.
+ *
+ * Exported because a session can end WITHOUT anyone calling `dispose_browser` —
+ * the developer closes their agent, the client kills the server, the transport
+ * drops. Nothing runs on its own then, so `start.ts` runs this. Without it a
+ * container keeps running and, worse, a public URL to a live browser outlives
+ * the session that created it.
+ */
+export declare function resetAll(attachRef: {
+    current?: AttachState;
+    config: ConfigStore;
+}, captures: CaptureStore, liveShare: LiveShareRef): Promise<void>;

package/lib/mcp/tools/agent/session.js

@@ -24,11 +24,7 @@ export function sessionTools(attachRef, captures, liveShare) {
             // URL can recover it instead of opening a second tunnel.
             ...(liveShare.current
                 ? {
-                    sharedView: {
-                        url: liveShare.current.url,
-                        interactive: liveShare.current.interactive,
-                        viewers: liveShare.current.view.viewers(),
-                    },
+                    sharedView: { url: liveShare.current.url },
                 }
                 : {}),
         })),
@@ -55,9 +51,19 @@ export function sessionTools(attachRef, captures, liveShare) {
         }),
     ];
 }
-async function resetAll(attachRef, captures, liveShare) {
-    // Before the captures: the live view holds a tab session of its own, and a
-    // public URL must never outlive the browser it points at.
+/**
+ * Release everything a session holds: the public tunnel, the captures, and the
+ * browser itself.
+ *
+ * Exported because a session can end WITHOUT anyone calling `dispose_browser` —
+ * the developer closes their agent, the client kills the server, the transport
+ * drops. Nothing runs on its own then, so `start.ts` runs this. Without it a
+ * container keeps running and, worse, a public URL to a live browser outlives
+ * the session that created it.
+ */
+export async function resetAll(attachRef, captures, liveShare) {
+    // Before the captures: a public URL must never outlive the browser it points
+    // at.
     await stopLiveShare(liveShare);
     await resetCaptures(captures);
     await disposeAttached(attachRef);

package/lib/old/client.d.ts

@@ -94,6 +94,70 @@ export interface LinkNonce {
     nonce: string;
     expiresInSeconds: number;
 }
+/** Log-level filter accepted by the devtools backend's session-logs route.
+ *  It validates against this exact list and rejects anything else with a 400,
+ *  including the comma-separated lists the log-stream service itself would
+ *  accept. Each value is hierarchical at the log-stream end: `fine` means
+ *  FINE+CONFIG+INFO+WARNING+SEVERE, `info` means INFO+WARNING+SEVERE, and so
+ *  on. `finer`/`finest` (the PII tiers) are not reachable through this route
+ *  at all. */
+export type SessionLogLevel = 'fine' | 'config' | 'info' | 'warning' | 'severe' | 'unknown';
+/** Filters for {@link ReclaimOldClient.getSessionLogs}. Every one is optional
+ *  and forwarded verbatim; the session id itself is the route's path param, so
+ *  `providerId`/`deviceId` narrow WITHIN one session rather than searching
+ *  across sessions. */
+export interface SessionLogsQuery {
+    deviceId?: string;
+    source?: string;
+    /** The client-side logger NAME (log-stream's `log_type` column, the SDK's
+     *  `LogEntry.type`) — not the event type. */
+    logType?: string;
+    logLevel?: SessionLogLevel;
+    providerId?: string;
+    /** ISO-8601. Omitting BOTH bounds makes the log-stream service default to
+     *  the last 3 days. */
+    startTime?: string;
+    endTime?: string;
+    /** Substring match against the log line (`LIKE %…%`). */
+    logLine?: string;
+    /** Exact `LogEventType` name, for example `REQUEST_MATCHED`. */
+    eventType?: string;
+    /** Capped at 1000 by the log-stream service. */
+    limit?: number;
+    offset?: number;
+    includeCount?: boolean;
+}
+/** One raw log line, in the log-stream service's snake_case ClickHouse shape,
+ *  passed through unchanged by the devtools backend. `event_type` is the SDK's
+ *  `LogEventType` milestone marker (`REQUEST_MATCHED`,
+ *  `CLAIM_CREATION_STARTED`, `PROOF_GENERATED`, …); it is `''` on the majority
+ *  of lines, which carry no event. */
+export interface SessionLogRow {
+    timestamp: string;
+    request_id: string;
+    session_id: string;
+    device_id: string;
+    source: string;
+    app_id: string;
+    provider_id: string;
+    log_type: string;
+    log_level: string;
+    log_line: string;
+    event_type?: string;
+    metadata?: string;
+}
+/** `GET /api/logger/:sessionId`'s `data` envelope. The backend queries every
+ *  region that holds the session, concatenates the pages, sorts them
+ *  newest-first and re-slices to `limit`, so `data` is one page and
+ *  `totalCount` is the match count across all of them. */
+export interface SessionLogsPage {
+    data: SessionLogRow[];
+    count: number;
+    totalCount?: number;
+    /** Regions whose log-stream query failed — the page is INCOMPLETE when
+     *  this is present. */
+    failedRegions?: string[];
+}
 /**
  * Minimal REST client for the OLD devtools Express backend (base `/api`).
  * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
@@ -133,6 +197,25 @@ export declare class ReclaimOldClient {
      *  `#request`). Attaches the caller identity when one is set; queried
      *  anonymously otherwise. */
     getSessionAnalyticsLogs(sessionId: string): Promise<unknown>;
+    /**
+     * Raw log LINES for a verification session — the SDK's own diagnostic
+     * logging, the thing the dashboard's session "logs" tab renders, and a
+     * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+     *
+     * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+     * analytics-logs host — hence `#request`, and hence the same identity and
+     * ownership rules as every other authed call here: the session's app must
+     * be one you created (admins excepted), or the route 404s.
+     *
+     * The backend fans the query out to the per-region log-stream services,
+     * which read the ClickHouse `logs` table. Two defaults applied down there
+     * bite hard if you don't override them:
+     *   - no `startTime`/`endTime` → only the last 3 days are searched;
+     *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+     *     invisible.
+     * Entries are dropped entirely after 30 days (table TTL).
+     */
+    getSessionLogs(sessionId: string, query?: SessionLogsQuery): Promise<SessionLogsPage>;
     /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
      *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
      *  use it as-is within the sandbox session limit. */

package/lib/old/client.js

@@ -89,6 +89,52 @@ export class ReclaimOldClient {
         }
         return json;
     }
+    /**
+     * Raw log LINES for a verification session — the SDK's own diagnostic
+     * logging, the thing the dashboard's session "logs" tab renders, and a
+     * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+     *
+     * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+     * analytics-logs host — hence `#request`, and hence the same identity and
+     * ownership rules as every other authed call here: the session's app must
+     * be one you created (admins excepted), or the route 404s.
+     *
+     * The backend fans the query out to the per-region log-stream services,
+     * which read the ClickHouse `logs` table. Two defaults applied down there
+     * bite hard if you don't override them:
+     *   - no `startTime`/`endTime` → only the last 3 days are searched;
+     *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+     *     invisible.
+     * Entries are dropped entirely after 30 days (table TTL).
+     */
+    async getSessionLogs(sessionId, query = {}) {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/logger/${encodeURIComponent(sessionId)}`, {
+            auth: true,
+            query: {
+                deviceId: query.deviceId,
+                source: query.source,
+                logType: query.logType,
+                logLevel: query.logLevel,
+                providerId: query.providerId,
+                startTime: query.startTime,
+                endTime: query.endTime,
+                logLine: query.logLine,
+                eventType: query.eventType,
+                limit: query.limit,
+                offset: query.offset,
+                includeCount: query.includeCount === undefined
+                    ? undefined
+                    : String(query.includeCount),
+            },
+        });
+        const page = res.data;
+        return {
+            data: page?.data ?? [],
+            count: page?.count ?? page?.data?.length ?? 0,
+            totalCount: page?.totalCount,
+            failedRegions: page?.failedRegions,
+        };
+    }
     /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
      *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
      *  use it as-is within the sandbox session limit. */

package/lib/old/tools/build.js

@@ -8,6 +8,7 @@ import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { scaffoldDemoServerTool } from "./scaffold-demo-server.js";
 import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
+import { sessionLogsTool } from "./session-logs.js";
 import { updateProviderMetadataTool } from "./update-provider-metadata.js";
 import { verifySdkSetupTool } from "./verify-sdk-setup.js";
 /**
@@ -32,6 +33,7 @@ export function buildOldBackendTools(client, sdkClient, attachRef) {
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),
         sessionAnalyticsLogsTool(client),
+        sessionLogsTool(client),
         issueAppCredentialsTool(client),
         linkAppTool(client),
         checkAppStatusTool(client),

package/lib/old/tools/session-logs.d.ts

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+export declare function sessionLogsTool(client: ReclaimOldClient): RegisteredTool;