@reclaimprotocol/agent 0.1.24 → 0.1.26

package/src/mcp/tools/agent/live-view.ts

@@ -16,22 +16,14 @@
 import { badRequest, conflict } from '@hapi/boom'
 import assert from 'node:assert'
 import { startTunnel, type Tunnel } from '../../../live/tunnel.ts'
-import { type LiveView, startLiveView } from '../../../live/viewer.ts'
 import { LOGGER } from '../../../logger.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { AttachState } from './attach.ts'
-import type { CaptureStore } from './capture.ts'
-
-/** 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 { type AttachState, SHAREABLE_MODES } from './attach.ts'
 
 export interface LiveShare {
-	view: LiveView
 	tunnel: Tunnel
+	/** The public URL handed to whoever is watching. */
 	url: string
-	interactive: boolean
-	startedAt: number
 }
 
 export interface LiveShareRef {
@@ -47,9 +39,8 @@ export async function stopLiveShare(ref: LiveShareRef): Promise<boolean> {
 	}
 
 	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')
 	})
@@ -58,61 +49,52 @@ export async function stopLiveShare(ref: LiveShareRef): Promise<boolean> {
 
 export function liveViewTools(
 	attachRef: { current?: AttachState },
-	captures: CaptureStore,
 	shareRef: LiveShareRef,
 ): RegisteredTool[] {
 	return [
-		defineTool<{ tabId?: string, interactive?: boolean }>(
+		defineTool<Record<string, never>>(
 			{
 				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. '
+					'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.',
-						},
-					},
-				},
+				inputSchema: { type: 'object', properties: {} },
 			},
-			async({ tabId, interactive }) => {
+			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(
@@ -121,47 +103,42 @@ export function liveViewTools(
 					+ '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.',
+				// 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 tab = await attached.handles.attachToTab(target)
-				const wantsInput = interactive !== false
-				const view = await startLiveView({
-					tab,
-					interactive: wantsInput,
-					title: `Reclaim — ${attached.mode} browser`,
-				})
-
-				let tunnel: 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}`
+				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: LiveShare = {
-					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 '
@@ -169,14 +146,21 @@ export function liveViewTools(
 							: []),
 						...(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.',
 					],
 				}
 			},
@@ -185,11 +169,11 @@ export function liveViewTools(
 			{
 				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.',
+					'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/src/mcp/tools/agent/session.ts

@@ -33,11 +33,7 @@ export function sessionTools(
 				// 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 },
 					}
 					: {}),
 			}),
@@ -74,13 +70,23 @@ export function sessionTools(
 	]
 }
 
-async function resetAll(
+/**
+ * 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: { current?: AttachState, config: ConfigStore },
 	captures: CaptureStore,
 	liveShare: LiveShareRef,
 ) {
-	// 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.
+	// Before the captures: a public URL must never outlive the browser it points
+	// at.
 	await stopLiveShare(liveShare)
 	await resetCaptures(captures)
 	await disposeAttached(attachRef)

package/src/old/client.ts

@@ -99,6 +99,80 @@ export interface LinkNonce {
 	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[]
+}
+
 interface RequestOpts {
 	query?: Record<string, string | number | undefined>
 	body?: unknown
@@ -212,6 +286,60 @@ 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: string,
+		query: SessionLogsQuery = {},
+	): Promise<SessionLogsPage> {
+		const res = await this.#request(
+			'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 as { data?: Partial<SessionLogsPage> }).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/src/old/tools/build.ts

@@ -12,6 +12,7 @@ import { getMeProvidersTool } from './me-providers.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
 import { scaffoldDemoServerTool } from './scaffold-demo-server.ts'
 import { sessionAnalyticsLogsTool } from './session-analytics-logs.ts'
+import { sessionLogsTool } from './session-logs.ts'
 import { updateProviderMetadataTool } from './update-provider-metadata.ts'
 import { verifySdkSetupTool } from './verify-sdk-setup.ts'
 
@@ -41,6 +42,7 @@ export function buildOldBackendTools(
 		getProviderInfoTool(sdkClient),
 		updateProviderMetadataTool(client),
 		sessionAnalyticsLogsTool(client),
+		sessionLogsTool(client),
 		issueAppCredentialsTool(client),
 		linkAppTool(client),
 		checkAppStatusTool(client),