@reclaimprotocol/agent 0.1.24 → 0.1.25

package/src/live/tunnel.ts

@@ -1,15 +1,22 @@
 /**
- * Public HTTPS front door for the local live-view server, via a `cloudflared`
- * quick tunnel.
+ * Public HTTPS front door for a local port, via a `cloudflared` quick tunnel.
  *
  * A quick tunnel needs no Cloudflare account and no DNS: `cloudflared` dials
  * out, Cloudflare hands back a throwaway `*.trycloudflare.com` hostname, and
  * traffic arrives on the loopback port we pass in. That is the whole reason it
  * is used here — the developer's machine keeps no inbound port open.
  *
- * The tunnel itself carries NO authorization. Anyone holding the hostname can
- * reach the local server, so the server is the thing that must authenticate
- * (see `viewer.ts`, which puts an unguessable token in every path).
+ * **The hostname IS the secret, and it is the only one.** The tunnel carries no
+ * authorization of its own, and the browser runtime's viewer behind it has no
+ * login either — so whoever learns the URL has the browser. Cloudflare's
+ * hostnames are randomly generated, which is what makes that tolerable for a
+ * short, deliberate hand-off, and `stop_browser_view` is how it ends.
+ *
+ * That is weaker than what this file used to front. The agent's own screencast
+ * viewer added a 24-byte token to every path, so the hostname alone was not
+ * enough; the container's viewer has no equivalent. Callers must say plainly
+ * what the URL grants, and it must never front the container's CDP port, which
+ * is unauthenticated total control of the browser.
  */
 import { spawn } from 'node:child_process'
 import { LOGGER } from '../logger.ts'
@@ -18,8 +25,8 @@ import { type CloudflaredBinary, resolveCloudflared } from './cloudflared.ts'
 /** How long to wait for cloudflared to report its hostname before giving up. */
 const URL_TIMEOUT_MS = 30_000
 /** After the hostname is printed, Cloudflare needs a moment before the edge
- *  routes to it — measured at ~3s. Poll until it answers so the caller never
- *  hands out a URL that errors, but don't fail the share if it's slow. */
+ *  routes to it — measured at ~3s. Wait for it so the caller never hands out a
+ *  URL that errors, but don't fail the share if it's slow. */
 const READY_TIMEOUT_MS = 20_000
 const READY_POLL_MS = 1_000
 
@@ -27,13 +34,32 @@ const READY_POLL_MS = 1_000
  *  stream. Anchored to the scheme so a hostname inside prose can't match. */
 const QUICK_TUNNEL_URL = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i
 
+/**
+ * cloudflared says this once per edge connection it establishes, and until it
+ * does, the hostname resolves but routes nowhere.
+ *
+ * This is the signal to trust, because it is LOCAL. Asking whether we can fetch
+ * the public URL ourselves conflates two questions — is the tunnel up, and does
+ * this machine have egress to Cloudflare's edge — and reports "not ready" when
+ * only the second fails. Observed: a tunnel printed its hostname and registered
+ * nothing for 12s, which is indistinguishable from a blocked fetch unless you
+ * read cloudflared's own account of it.
+ */
+const REGISTERED = /Registered tunnel connection|connIndex=/i
+
+/** Tail of cloudflared's log kept for error messages. */
+const LOG_TAIL_BYTES = 4096
+
 export interface Tunnel {
 	/** The public HTTPS origin Cloudflare assigned. */
 	url: string
-	/** Whether the edge answered before {@link READY_TIMEOUT_MS} elapsed. False
-	 *  means the tunnel is probably still propagating rather than broken — tell
-	 *  the viewer to retry rather than treating the share as failed. */
+	/** Whether the tunnel was carrying traffic before {@link READY_TIMEOUT_MS}
+	 *  elapsed. False means it may still be propagating rather than broken — say
+	 *  so rather than treating the share as failed. */
 	ready: boolean
+	/** cloudflared's own last words, for when `ready` is false and someone has
+	 *  to work out why. Absent when the tunnel came up normally. */
+	diagnostics?: string
 	/** Terminate the tunnel. Safe to call more than once. */
 	stop: () => Promise<void>
 	/** Which cloudflared ran, and whether we had to fetch it. */
@@ -41,18 +67,31 @@ export interface Tunnel {
 }
 
 /**
- * Poll the public origin until Cloudflare's edge routes to it. ANY HTTP
- * response counts, including a 404: the live-view server 404s unknown paths,
- * so a status code at all proves the hop is live.
+ * Wait until the tunnel is actually carrying traffic.
+ *
+ * Two independent signals, either of which is proof:
+ *  - cloudflared reported an edge registration (see {@link REGISTERED}). Local,
+ *    so it works regardless of this machine's own egress.
+ *  - the public origin answered. ANY HTTP response counts, including a 404:
+ *    the live-view server 404s unknown paths, so a status code at all proves
+ *    the hop is live. Kept as a second opinion in case a cloudflared release
+ *    rewords its log.
  */
-async function waitUntilRouted(url: string): Promise<boolean> {
+async function waitUntilRouted(
+	url: string,
+	isRegistered: () => boolean,
+): Promise<boolean> {
 	const deadline = Date.now() + READY_TIMEOUT_MS
 	while(Date.now() < deadline) {
+		if(isRegistered()) {
+			return true
+		}
+
 		try {
 			await fetch(url, {
 				method: 'GET',
 				redirect: 'manual',
-				signal: AbortSignal.timeout(READY_POLL_MS * 4),
+				signal: AbortSignal.timeout(READY_POLL_MS * 2),
 			})
 			return true
 		} catch{
@@ -60,7 +99,7 @@ async function waitUntilRouted(url: string): Promise<boolean> {
 		}
 	}
 
-	return false
+	return isRegistered()
 }
 
 /**
@@ -100,6 +139,8 @@ export async function startTunnel(
 			))
 		}, URL_TIMEOUT_MS)
 
+		let registered = false
+		let tail = ''
 		let settled = false
 		const finish = (fn: () => void) => {
 			if(settled) {
@@ -115,16 +156,26 @@ export async function startTunnel(
 		// both so a future version that switches streams still works.
 		const onChunk = (chunk: Buffer) => {
 			const text = chunk.toString()
+			// Keep watching after the hostname: registration lands a beat later, and
+			// on a bad run it never lands at all, which is the case worth reporting.
+			tail = (tail + text).slice(-LOG_TAIL_BYTES)
+			if(REGISTERED.test(text)) {
+				registered = true
+			}
+
 			const match = QUICK_TUNNEL_URL.exec(text)
 			if(match) {
 				const url = match[0]
 				finish(() => {
-					void waitUntilRouted(url).then((ready) => {
-						if(!ready) {
-							LOGGER.warn({ url }, 'tunnel not routed yet; returning anyway')
+					void waitUntilRouted(url, () => registered).then((ready) => {
+						if(ready) {
+							resolve({ url, ready, stop, binary })
+							return
 						}
 
-						resolve({ url, ready, stop, binary })
+						LOGGER.warn({ url, tail },
+							'tunnel never registered with an edge; returning anyway')
+						resolve({ url, ready, stop, binary, diagnostics: tail })
 					})
 				})
 			}

package/src/mcp/instructions.ts

@@ -71,7 +71,8 @@ const SHARED_TOPIC_FILES: Record<string, string> = {
 const TOPIC_SUMMARIES: Record<string, string> = {
 	'overview': 'Terminology, your stance, and the whole loop at a glance.',
 	'auth': 'Signing in to the backend, and which token authorizes what.',
-	'browser': 'Choosing a browser source (local / remote / custom CDP), '
+	'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
+		+ 'Docker, a remote Popcorn browser, or a custom CDP endpoint), '
 		+ 'geolocation, live view, and launch troubleshooting.',
 	'capture': 'Tabs, login detection, driving the page, and picking an '
 		+ 'authenticated request to prove.',

package/src/mcp/start.ts

@@ -11,6 +11,7 @@ import {
 	resolveOldMode,
 	sdkApiUrl,
 } from '../consts.ts'
+import { LOGGER } from '../logger.ts'
 import { ReclaimOldClient } from '../old/client.ts'
 import { resolveInitialIdentity } from '../old/identity.ts'
 import { OLD_MODE_INSTRUCTIONS } from '../old/instructions.ts'
@@ -19,6 +20,7 @@ import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
 import {
+	type AgentState,
 	buildAgentState,
 	buildAgentTools,
 	buildBuilderAuthenticationTools,
@@ -27,6 +29,7 @@ import {
 	buildLocalCredentialTools,
 	buildModeTools,
 	buildVerificationTools,
+	disposeAgentState,
 	readSession,
 } from './tools/index.ts'
 import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
@@ -52,6 +55,8 @@ export async function startMcpServer() {
 	// deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
 	// surface.
 	const agentToolsEnabled = !agentDisabled()
+	/** The agent state this server registered, for shutdown to release. */
+	let agentState: AgentState | undefined
 	const builderClient = new ReclaimClient({
 		baseUrl: apiUrl(),
 		// Builder access is orthogonal to publishing mode. A legacy-devtools
@@ -77,7 +82,7 @@ export async function startMcpServer() {
 		// Shared with buildAgentTools below so the old-mode publish tool can see
 		// the live attach state (for example, to flag a still-open browser
 		// session).
-		const agentState = buildAgentState()
+		agentState = buildAgentState()
 
 		registerToolList(server, buildBuilderAuthenticationTools(builderClient))
 		registerToolList(server, buildBuilderOrganizationTools(builderClient))
@@ -115,10 +120,68 @@ export async function startMcpServer() {
 		registerTools(server, client)
 
 		if(agentToolsEnabled) {
-			registerToolList(server, buildAgentTools(client))
+			agentState = buildAgentState()
+			registerToolList(server, buildAgentTools(client, client, agentState))
 		}
 	}
 
+	// Anything the session holds has to be released when the session ends, and
+	// the session can end without a single tool call: the developer closes their
+	// agent, the client kills the server, stdin drops. Nothing ran here before,
+	// which left a container up and — worse — a public tunnel still pointing at a
+	// live browser after the session that made it was gone.
+	if(agentToolsEnabled) {
+		installShutdownHooks(() => agentState)
+	}
+
 	const transport = new StdioServerTransport()
 	await server.connect(transport)
 }
+
+/** How long teardown gets before the process leaves anyway. */
+const SHUTDOWN_GRACE_MS = 10_000
+
+/**
+ * Release the browser on every way out we can observe.
+ *
+ * `SIGTERM`/`SIGINT` is how a client stops us; stdin ending is how a stdio
+ * transport says the other side is gone. A `SIGKILL` cannot be caught at all,
+ * which is why `reapOrphanedContainers` exists as the backstop.
+ */
+function installShutdownHooks(state: () => AgentState | undefined): void {
+	let shuttingDown = false
+	const shutdown = (reason: string) => {
+		if(shuttingDown) {
+			return
+		}
+
+		shuttingDown = true
+		const current = state()
+		if(!current) {
+			process.exit(0)
+		}
+
+		LOGGER.info({ reason }, 'releasing the browser before exit')
+		// Bounded: a wedged `docker stop` must not keep the process alive, but
+		// nor should we skip cleanup that would have finished in a second.
+		const timer = setTimeout(() => {
+			LOGGER.warn({ reason }, 'teardown timed out; exiting anyway')
+			process.exit(0)
+		}, SHUTDOWN_GRACE_MS)
+		timer.unref()
+		void disposeAgentState(current)
+			.catch((err: unknown) => {
+				LOGGER.warn({ err }, 'teardown failed')
+			})
+			.finally(() => {
+				clearTimeout(timer)
+				process.exit(0)
+			})
+	}
+
+	process.once('SIGTERM', () => shutdown('SIGTERM'))
+	process.once('SIGINT', () => shutdown('SIGINT'))
+	// The transport's own end of the conversation.
+	process.stdin.once('end', () => shutdown('stdin ended'))
+	process.stdin.once('close', () => shutdown('stdin closed'))
+}