@reclaimprotocol/agent 0.1.23 → 0.1.24

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

@@ -0,0 +1,198 @@
+/**
+ * `share_browser_view` / `stop_browser_view` — put the LOCAL attached tab
+ * behind a public URL so someone who is not at this machine can watch it, and
+ * optionally drive it.
+ *
+ * Scoped to the CDP-attached modes (`dedicated`, `attach`, `custom`) on
+ * purpose. A `builder`-mode browser is a Popcorn pod that already ships its
+ * own hosted live view on `attach_browser`'s `liveViewUrl`; tunnelling a
+ * second one would duplicate it and burn a share URL for nothing, so this
+ * refuses and points at the one that exists.
+ *
+ * The share is deliberately explicit and single-instance: one live view per
+ * attached browser, started only when asked for, and torn down by
+ * `stop_browser_view`, `dispose_browser`, or `reset_session`.
+ */
+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'])
+
+export interface LiveShare {
+	view: LiveView
+	tunnel: Tunnel
+	url: string
+	interactive: boolean
+	startedAt: number
+}
+
+export interface LiveShareRef {
+	current?: LiveShare
+}
+
+/** 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: LiveShareRef): Promise<boolean> {
+	const share = ref.current
+	if(!share) {
+		return false
+	}
+
+	ref.current = undefined
+	await share.view.stop().catch((err) => {
+		LOGGER.warn({ err }, 'live view: server stop failed')
+	})
+	await share.tunnel.stop().catch((err) => {
+		LOGGER.warn({ err }, 'live view: tunnel stop failed')
+	})
+	return true
+}
+
+export function liveViewTools(
+	attachRef: { current?: AttachState },
+	captures: CaptureStore,
+	shareRef: LiveShareRef,
+): RegisteredTool[] {
+	return [
+		defineTool<{ tabId?: string, interactive?: boolean }>(
+			{
+				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. '
+					+ '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 }) => {
+				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}` : '')
+					+ '.',
+				))
+				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: 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 share: LiveShare = {
+					view, tunnel, url, interactive: wantsInput, startedAt: Date.now(),
+				}
+				shareRef.current = share
+				LOGGER.info({ mode: attached.mode, interactive: wantsInput },
+					'live view shared')
+
+				return {
+					url,
+					interactive: wantsInput,
+					tabId: target,
+					...(share.tunnel.binary.source === 'downloaded'
+						? { cloudflaredInstalled: true }
+						: {}),
+					...(share.tunnel.ready ? {} : { propagating: true }),
+					_notes: [
+						...(share.tunnel.binary.source === 'downloaded'
+							? ['cloudflared was not installed, so it was downloaded once '
+								+ 'to ~/.reclaim/bin. Mention that; later shares reuse it.']
+							: []),
+						...(share.tunnel.ready
+							? []
+							: ['The tunnel had not started routing yet — if the URL '
+								+ 'errors, wait a few seconds and reload.']),
+						'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.',
+					],
+				}
+			},
+		),
+		defineTool<Record<string, never>>(
+			{
+				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.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => ({ stopped: await stopLiveShare(shareRef) }),
+		),
+	]
+}

package/src/mcp/tools/agent/pod-proof.ts

@@ -0,0 +1,90 @@
+/**
+ * Prove a drafted recipe through the Popcorn pod's OWN `/reclaim/prove` — the
+ * remote browser session's own API for creating a proof from that same
+ * session — instead of the local in-process attestor SDK (`run_proof`).
+ * Recommended for any `builder`-mode attach: the pod is the SAME enclave that
+ * holds the browser's TLS session, so proving there reaches the target from
+ * the identical exit IP the browser used — including the country-routed egress
+ * Popcorn applies when the session was allocated with a country. A local SDK
+ * proof runs from the agent's own network instead, which won't match a
+ * country-locked / IP-allowlisted target the remote browser could reach.
+ *
+ * Builder mode only (needs the attach's pod `apiUrl`, from
+ * `CreateAgentBrowserSession`) — throws a clear error otherwise rather than
+ * silently falling back to the local path.
+ */
+import { badRequest } from '@hapi/boom'
+import assert from 'node:assert'
+import type { ConfigStore } from '../../../config/store.ts'
+import { popcornProve } from '../../../proof/pod-prover.ts'
+import { buildHttpParams } from '../../../proof/proof-core.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
+import type { CaptureStore } from './capture.ts'
+import { shapeRichProofResult } from './proof.ts'
+
+export function podProofTools(
+	attachRef: { current?: AttachState, config: ConfigStore },
+	captures: CaptureStore,
+): RegisteredTool[] {
+	const tool = defineTool<{ captureId: string, draftId: string }>(
+		{
+			name: 'run_proof_via_pod',
+			description:
+				'Prove the drafted recipe through the Popcorn pod\'s own TEE '
+				+ '(/reclaim/prove) instead of the local attestor SDK — this is '
+				+ 'the remote browser session\'s own api for creating a proof '
+				+ 'from that same session. Use this instead of run_proof '
+				+ 'whenever this capture\'s '
+				+ 'attach mode is "builder": the pod is the same enclave that '
+				+ 'held the browser\'s TLS session (and its country-routed egress, '
+				+ 'if any), so '
+				+ 'the proof reaches the target from the browser\'s own exit IP. '
+				+ 'No ownerAddress needed — the pod signs with the attestor\'s '
+				+ 'own TEE key, not a local credential.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					captureId: { type: 'string' },
+					draftId: { type: 'string' },
+				},
+				required: ['captureId', 'draftId'],
+			},
+		},
+		async({ captureId, draftId }) => {
+			const apiUrl = attachRef.current?.apiUrl
+			assert(
+				apiUrl,
+				badRequest(
+					'No pod api available for this attach — run_proof_via_pod needs '
+					+ 'mode "builder" (attach_browser), not local/custom CDP.',
+				),
+			)
+
+			const entry = captures.sessions.get(captureId)
+			assert(
+				entry,
+				badRequest(
+					`no capture ${captureId} — call start_capture first `
+					+ '(it has been reset or never started).',
+				),
+			)
+
+			const draft = entry.drafts.get(draftId)
+			assert(draft, badRequest(`no draft ${draftId} in capture ${captureId}`))
+
+			const result = await popcornProve({
+				apiUrl,
+				params: buildHttpParams(draft.provider),
+				secretParams: { headers: draft.secrets },
+			})
+
+			return shapeRichProofResult(result, {
+				provider: draft.provider,
+				hasSecrets: Object.keys(draft.secrets).length > 0,
+			})
+		},
+	)
+
+	return [tool]
+}

package/src/mcp/tools/agent/propose.ts

@@ -25,13 +25,15 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				+ 'Single-value shorthand: `target` + `name`. Per-target `hash` '
 				+ 'OPRF-hashes that value. BY DEFAULT each `name` is shortened to '
 				+ 'its last alphanumeric token, lowercased, to form the param key '
-				+ '(e.g. "employer_name" → "name") — pick names that stay distinct '
+				+ '(for example, "employer_name" → "name") — pick names that stay '
+				+ 'distinct '
 				+ 'after shortening ("firstName"/"surname", not "first_name"/'
 				+ '"last_name"). Pass `shortenNames: false` to use each `name` '
 				+ 'VERBATIM as the param key instead — it becomes both a regex '
 				+ 'capture-group name and a paramValues key, so it must be a plain '
 				+ 'identifier (letters/digits/underscore, not starting with a '
-				+ 'digit); we recommend lower_snake_case (e.g. "employer_name"), '
+				+ 'digit); we recommend lower_snake_case (for example, '
+				+ '"employer_name"), '
 				+ 'but you choose the exact name.',
 			inputSchema: objectSchema(
 				{

package/src/mcp/tools/agent/publish.ts

@@ -1,6 +1,9 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
 import type { JSONSchema } from 'zod/v4/core'
-import { INJECTION_GUIDE } from '../../../provider/injection-doc.ts'
+import {
+	ALLOWED_REQUESTS_HINT,
+	USER_SCRIPT_HINT,
+} from '../../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
@@ -82,7 +85,8 @@ const PROVIDER_SCHEMA: JSONSchema.Schema = {
 	type: 'object',
 	description:
 		'A `provider` object from propose_provider, passed through verbatim — ' +
-		'the tool builds the version body (the requests[] entry etc.) for you.',
+		'the tool builds the version body (the requests[] entry and so on) ' +
+		'for you.',
 	properties: {
 		name: { type: 'string', description: 'Verification name.' },
 		...REQUEST_DRAFT_PROPERTIES,
@@ -95,7 +99,7 @@ const PROVIDER_SCHEMA: JSONSchema.Schema = {
 		paramValues: {
 			type: 'object',
 			description:
-				'Real values for the {{param}} placeholders, e.g. ' +
+				'Real values for the {{param}} placeholders, for example, ' +
 				'{ "username": "Syed" }.',
 		},
 	},
@@ -111,8 +115,8 @@ const ALLOWED_JS_REQUEST_SCHEMA: JSONSchema.Schema = {
 		multiple: {
 			type: 'boolean',
 			description:
-				'Allow the template to match many requests (e.g. pagination). ' +
-				'Default true.',
+				'Allow the template to match many requests (for example, ' +
+				'pagination). Default true.',
 		},
 		required: {
 			type: 'boolean',
@@ -137,6 +141,7 @@ interface PublishArgs {
 	interceptorOptions?: {
 		interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP'
 		interceptorSettings?: string
+		isDocumentRequestReplayEnabled?: boolean
 	}
 }
 
@@ -148,36 +153,21 @@ export function createVersionFromCaptureTool(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Persist drafted ReclaimProvider(s) as a provider version. ' +
-				'Call this after run_proof succeeds, passing the `provider` ' +
-				'object(s) from propose_provider VERBATIM. This tool builds the ' +
-				'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
-				'hand-construct that shape or call create_provider_version directly. ' +
-				'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-				'proven draft) — every entry becomes one request in the version, and ' +
-				'all are required at verification time. Pass a single `provider` ' +
-				'for the one-request case (exactly one of `provider`/`providers`). ' +
-				'For data gated behind login/navigation, supply `jsUserScripts` (a ' +
-				'page-injection script that drives the page to where the request ' +
-				'fires) and/or `allowedJsRequests` (extra requests the script may ' +
-				'fire, e.g. pagination). ' +
-				'Omit `version` to have the tool auto-select the next available ' +
-				'version (it lists existing versions and bumps past the highest). ' +
-				'The version lands on the draft branch — to go live, call ' +
-				'`publish_provider_version` (PRIVATE) or ' +
-				'`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+				'Persist drafted ReclaimProvider(s) as a provider version, after ' +
+				'run_proof succeeds. Pass the `provider` object(s) from ' +
+				'propose_provider VERBATIM — this tool builds the version body ' +
+				'(requests[], webSettings, …) for you; do NOT hand-construct that ' +
+				'shape or call create_provider_version directly. Exactly one of ' +
+				'`provider` (one request) or `providers` (a multi-request provider — ' +
+				'every entry is required at verification time). Omit `version` to ' +
+				'auto-bump past the highest existing one. The version lands on the ' +
+				'draft branch: call `publish_provider_version` (PRIVATE) or ' +
+				'`submit_provider_version_for_review` (PUBLIC) to go live. ' +
 				'`requiredContext` is derived from any {{context.<name>}} ' +
-				'placeholders across ALL requests (plus injected requests / script) ' +
-				'and returned on the created version — when present, tell the dev ' +
-				'verbatim which context fields consumers MUST send when creating ' +
-				'sessions (verification matches those values exactly; a missing ' +
-				'field is a 400 at session create). ' +
-				'Refine types/descriptions via `update_provider_version` while ' +
-				'still on draft. ' +
-				'On success, if a browser is still attached, the response\'s ' +
-				'`_notes` reminds you to confirm with the developer before ' +
-				'calling `dispose_browser` — never close it unprompted, they ' +
-				'may want it for further edits.',
+				'placeholders and returned on the created version — relay it to the ' +
+				'dev verbatim, since a session missing those fields is a 400. Always ' +
+				'read the response\'s `_notes`. ' +
+				'Full walkthrough: how_it_works({ topic: "publish" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -199,13 +189,15 @@ export function createVersionFromCaptureTool(
 						type: 'string',
 						description:
 							'The website URL the user landed on to trigger the request ' +
-							'(e.g. https://github.com/Syed). The URL the verification ' +
-							'flow opens for end-users — NOT the API URL inside the provider.',
+							'(for example, https://github.com/Syed). The URL the ' +
+							'verification flow opens for end-users — NOT the API URL ' +
+							'inside the provider.',
 					},
 					notes: {
 						type: 'string',
 						description:
-							'Short change note (e.g. "Initial draft from browser capture").',
+							'Short change note (for example, "Initial draft from ' +
+							'browser capture").',
 					},
 					version: {
 						type: 'object',
@@ -222,45 +214,22 @@ export function createVersionFromCaptureTool(
 					jsUserScripts: {
 						type: 'string',
 						description:
-							'Plain JavaScript injected into the provider page before every ' +
-							'page load (stored as webSettings.jsUserScripts). Use standard ' +
-							'browser APIs (window.location, element.click(), forms) to ' +
-							'drive login/navigation so the target request fires — the ' +
-							'client already intercepts page requests, and window.Reclaim ' +
-							'is only for rare edge cases, not navigation. The Builder ' +
-							'verification client installs this to run before every page ' +
-							'load (before navigating to initialUrl), matching old-devtool ' +
-							'customInjection; window.Reclaim itself is not yet exposed ' +
-							'there, so prefer plain browser JS. Guide:\n\n' +
-							INJECTION_GUIDE,
+							USER_SCRIPT_HINT +
+							' Stored as webSettings.jsUserScripts; the Builder ' +
+							'verification client runs it before every page load ' +
+							'(including before navigating to initialUrl), matching ' +
+							'old-devtools customInjection. window.Reclaim is not exposed ' +
+							'there yet, so prefer plain browser JS.',
 					},
 					allowedJsRequests: {
 						type: 'array',
 						description:
-							'Extra requests the injection script is allowed to fire ' +
-							'(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-							'`multiple`/`required` default to true. ' +
-							'⚠️ BEFORE populating this to gate ' +
-							'`verifyProof(proof, { providerId })` (old-devtools calls the ' +
-							'same concept `allowedInjectedRequestData` — same mechanics, ' +
-							'different field name): this whole entry (url, method, body, ' +
-							'responseMatches, responseRedactions) feeds a client-side ' +
-							'hash-equality check, and `url` is hashed VERBATIM — no regex/ ' +
-							'template resolution, even with `urlType: REGEX` or ' +
-							'`TEMPLATE`. If the real captured URL contains ANY per-session ' +
-							'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
-							'no declared spec can EVER hash-match a real proof — populating' +
-							' this for such a provider makes verifyProof reject every real ' +
-							'proof, which is worse than leaving it empty. Diff the same ' +
-							'endpoint\'s captured URL across two separate sessions before ' +
-							'wiring this up. If provider-hash validation keeps causing ' +
-							'problems (unstable url, or any other persistent mismatch), ' +
-							'the fallback on the verifying side is `verifyProof(proof, { ' +
-							'dangerouslyDisableContentValidation: true })` — trusts only ' +
-							'the attestor\'s signature, skips the hash-equality check ' +
-							'entirely; see the "Provider-hash validation" section of the ' +
-							'injection script\'s guide for the full mechanics and when to ' +
-							'reach for it.',
+							'Extra requests the user script is allowed to fire (for ' +
+							'example, paginated API calls), as ' +
+							'RequestSelectionTemplates. ' +
+							'`multiple`/`required` default to true. Old-devtools calls the ' +
+							'same concept `allowedInjectedRequestData`. ' +
+							ALLOWED_REQUESTS_HINT,
 						items: ALLOWED_JS_REQUEST_SCHEMA,
 					},
 					interceptorOptions: {
@@ -269,11 +238,7 @@ export function createVersionFromCaptureTool(
 							'In-app interception settings, stored as ' +
 							'webSettings.clientOptions.inapp.interceptorOptions — only ' +
 							'needed for a genuine live-interception provider (a real ' +
-							'HAWKEYE/MSWJS script, not the standard capture→replay flow). ' +
-							'Document replay (webSettings.clientOptions.inapp' +
-							'.interceptorOptions.isDocumentRequestReplayEnabled) is ' +
-							'ALWAYS published disabled regardless of this field — there ' +
-							'is no way to enable it here.',
+							'HAWKEYE/MSWJS script, not the standard capture→replay flow).',
 						properties: {
 							interceptorType: {
 								type: 'string',
@@ -285,6 +250,16 @@ export function createVersionFromCaptureTool(
 								description:
 									'Free-form JSON config for the chosen interceptor.',
 							},
+							isDocumentRequestReplayEnabled: {
+								type: 'boolean',
+								description:
+									'Whether the page\'s own document/navigation request is ' +
+									'genuinely replayed through the interceptor, rather than ' +
+									'constructed locally. Defaults to `false` (disabled) when ' +
+									'omitted. Only meaningful for HAWKEYE/MSWJS — pass `true` ' +
+									'when the target value is embedded in the page\'s own HTML ' +
+									'rather than a separate API call. Inert for CDP.',
+							},
 						},
 						required: ['interceptorType'],
 					},

package/src/mcp/tools/agent/session.ts

@@ -2,17 +2,21 @@ import type { ConfigStore } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { type AttachState, disposeAttached } from './attach.ts'
 import { type CaptureStore, resetCaptures } from './capture.ts'
+import { type LiveShareRef, stopLiveShare } from './live-view.ts'
 
 export function sessionTools(
 	attachRef: { current?: AttachState, config: ConfigStore },
 	captures: CaptureStore,
+	liveShare: LiveShareRef,
 ): RegisteredTool[] {
 	return [
 		defineTool<Record<string, never>>(
 			{
 				name: 'get_session',
 				description:
-					'Return current attach state, active captures, and persisted config.',
+					'Report the current attach state, the live captureIds, and the '
+					+ 'persisted browser config. Call it to check whether a browser is '
+					+ 'still attached before reattaching, or to recover a captureId.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => ({
@@ -25,6 +29,17 @@ export function sessionTools(
 				orgId: attachRef.current?.orgId,
 				captures: [...captures.sessions.keys()],
 				activeTab: captures.activeTab,
+				// The public share, when one is open — so a caller that lost the
+				// 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(),
+						},
+					}
+					: {}),
 			}),
 		),
 		defineTool<Record<string, never>>(
@@ -33,11 +48,12 @@ export function sessionTools(
 				description:
 					'Stop captures, disconnect the current browser, and immediately '
 					+ 'delete a Builder-hosted Popcorn session. Custom CDP sessions '
-					+ 'are disconnected but never deleted by Reclaim.',
+					+ 'are disconnected but never deleted by Reclaim. Also closes a '
+					+ 'public live view opened by share_browser_view.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
-				await resetAll(attachRef, captures)
+				await resetAll(attachRef, captures, liveShare)
 				return { disposed: true }
 			},
 		),
@@ -46,11 +62,12 @@ export function sessionTools(
 				name: 'reset_session',
 				description:
 					'Stop all captures and clear capture state — drops every '
-					+ 'session\'s drafts and their in-memory secrets.',
+					+ 'session\'s drafts and their in-memory secrets, and closes a '
+					+ 'public live view opened by share_browser_view.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
-				await resetAll(attachRef, captures)
+				await resetAll(attachRef, captures, liveShare)
 				return { reset: true }
 			},
 		),
@@ -60,7 +77,11 @@ export function sessionTools(
 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.
+	await stopLiveShare(liveShare)
 	await resetCaptures(captures)
 	await disposeAttached(attachRef)
 }

package/src/mcp/tools/authenticate/authenticate.ts

@@ -18,17 +18,12 @@ export function authenticateTool(
 			name,
 			description:
 				(name === 'authenticate_builder'
-					? 'This tool only exists in OLD-DEVTOOLS mode — Builder mode has '
-					+ 'no separate version of it; its own reclaim_authenticate '
-					+ 'already covers everything below. In old-devtools mode, this '
-					+ 'authenticates with Builder for exactly two Builder-exclusive '
-					+ 'features: allocating a Popcorn remote browser (attach_browser '
-					+ 'mode="builder") and listing Builder organizations '
-					+ '(list_builder_organizations — old-devtools has no generated '
-					+ 'org tool of its own). It does NOT authorize '
-					+ 'create_provider_version_from_capture or get_me_providers, '
-					+ 'which need their OWN, separate login via the old-devtools '
-					+ 'reclaim_authenticate tool. Check both with get_devtools_mode. '
+					? 'OLD-DEVTOOLS MODE ONLY, and narrow: it authorizes exactly two '
+					+ 'Builder-exclusive features — allocating a remote browser '
+					+ '(attach_browser mode="builder") and list_builder_organizations. '
+					+ 'It does NOT authorize create_provider_version_from_capture or '
+					+ 'get_me_providers; those need the separate old-devtools login, '
+					+ 'reclaim_authenticate. Check both with get_devtools_mode. '
 					: '')
 				+ 'Authorize the CLI / MCP to make authenticated API calls. Opens '
 				+ 'the '
@@ -37,8 +32,9 @@ export function authenticateTool(
 				'the user to sign in and approve. On success the access token is ' +
 				'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
 				'Call with no arguments. This bearer token authenticates ' +
-				'dashboard/org-management calls (e.g. list_orgs, issuing an org ' +
-				'secret). Programmatic verification calls use a separate org secret ' +
+				'dashboard/org-management calls (for example, list_orgs, or ' +
+				'issuing an org secret). Programmatic verification calls use a ' +
+				'separate org secret ' +
 				'(rorg_…, set as RECLAIM_ORG_SECRET).',
 			inputSchema: { type: 'object', properties: {} },
 		},
@@ -85,6 +81,18 @@ export async function runOAuthLoopback(
 	const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier)
 	const state = oauth.randomState()
 
+	// openid-client/oauth4webapi refuse any non-HTTPS issuer by default
+	// ("only requests to HTTPS are allowed"). Better Auth's own dev default
+	// (`canonicalOrigin()`, packages/app/src/consts.ts) is plain
+	// `http://localhost:4001` — the server side has no HTTPS requirement at
+	// all — so a local `RECLAIM_API_URL=http://localhost:...` would otherwise
+	// always fail here. Loosen it ONLY for loopback hosts, matching what the
+	// server already trusts (`authTrustedOrigins()` defaults to
+	// localhost:4000/4001 outside production); a non-loopback http:// origin
+	// still gets the strict check.
+	const isLoopbackAuthBase =
+		['localhost', '127.0.0.1', '[::1]'].includes(new URL(authBase).hostname)
+
 	// Bind the callback port first: the client is registered for this exact
 	// loopback redirect.
 	const callback = await listenForCallback()
@@ -119,6 +127,13 @@ export async function runOAuthLoopback(
 				// `authorizationCodeGrant` fails instead (confirmed by hitting
 				// exactly that when this only checked method === 'POST').
 				[oauth.customFetch]: _customFetchForOauth,
+				// Applies to the `Configuration` this call returns, so the later
+				// `buildAuthorizationUrl`/`authorizationCodeGrant` calls below (which
+				// reuse that same `config`) stop enforcing HTTPS too — no separate
+				// opt-in needed for them.
+				...(isLoopbackAuthBase
+					? { execute: [oauth.allowInsecureRequests] }
+					: {}),
 			},
 		)
 		openBrowserFn(