@reclaimprotocol/agent 0.1.18 → 0.1.21

package/src/mcp/start.ts

@@ -19,7 +19,10 @@ import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
 import {
+	buildAgentState,
 	buildAgentTools,
+	buildBuilderAuthenticationTools,
+	buildBuilderOrganizationTools,
 	buildCredentialTools,
 	buildLocalCredentialTools,
 	buildModeTools,
@@ -49,7 +52,13 @@ export async function startMcpServer() {
 	// deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
 	// surface.
 	const agentToolsEnabled = !agentDisabled()
-
+	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,
+		headers: { 'User-Agent': `${NAME}/${VERSION}` },
+	})
 	// Backend-mode toggle — available in both modes and regardless of whether
 	// the agent tools are enabled, so a user can always switch either direction.
 	registerToolList(server, buildModeTools(config, oldMode))
@@ -65,21 +74,27 @@ export async function startMcpServer() {
 			identity: resolveInitialIdentity(),
 		})
 		const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() })
+		// Shared with buildAgentTools below so the old-mode publish tool can see
+		// the live attach state (e.g. to flag a still-open browser session).
+		const agentState = buildAgentState()
 
+		registerToolList(server, buildBuilderAuthenticationTools(builderClient))
+		registerToolList(server, buildBuilderOrganizationTools(builderClient))
 		registerToolList(server, buildLocalCredentialTools())
-		registerToolList(server, buildOldBackendTools(oldClient, sdkClient))
+		registerToolList(
+			server,
+			buildOldBackendTools(oldClient, sdkClient, agentState.attach),
+		)
 		if(agentToolsEnabled) {
 			// No builder client → no builder publish tool (old mode has its own).
-			registerToolList(server, buildAgentTools())
+			registerToolList(
+				server,
+				buildAgentTools(undefined, builderClient, agentState),
+			)
 		}
 		// NOTE: registerTools() is intentionally NOT called — generated tools off.
 	} else {
-		const client = new ReclaimClient({
-			baseUrl: apiUrl(),
-			// Priority: explicit env var → cached session token → unauthenticated
-			token: apiToken() || readSession()?.token,
-			headers: { 'User-Agent': `${NAME}/${VERSION}` },
-		})
+		const client = builderClient
 
 		// Tool names must stay disjoint across these three groups: hand-written
 		// tools are higher-level orchestrations (multi-call flows, ReclaimProvider

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

@@ -1,4 +1,11 @@
-import { type CdpHandles, connectCdp } from '../../../cdp/client.ts'
+import { badRequest } from '@hapi/boom'
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import assert from 'node:assert'
+import {
+	type CdpHandles,
+	connectCdp,
+	connectCdpUrl,
+} from '../../../cdp/client.ts'
 import {
 	defaultProfileDir,
 	launchChrome,
@@ -8,88 +15,222 @@ import type { ConfigStore } from '../../../config/store.ts'
 import { defaultConfigPath } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
+export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom'
+
 export interface AttachState {
 	handles: CdpHandles
-	port: number
+	mode: BrowserMode
+	port?: number
+	liveViewUrl?: string
+	browserSessionId?: string
+	orgId?: string
+	disposeRemote?: () => Promise<void>
 }
 
-export function attachTool(state: {
+export interface AttachRef {
 	current?: AttachState
 	config: ConfigStore
-}): RegisteredTool {
-	return defineTool<{ attachMode?: 'dedicated' | 'attach', port?: number }>(
+}
+
+interface AttachArgs {
+	mode?: BrowserMode
+	/** Backward-compatible local-mode spelling. */
+	attachMode?: 'dedicated' | 'attach'
+	port?: number
+	orgId?: string
+	cdpUrl?: string
+	liveViewUrl?: string
+}
+
+interface AttachDependencies {
+	connectLocal: typeof connectCdp
+	connectRemote: typeof connectCdpUrl
+}
+
+const DEFAULT_DEPENDENCIES: AttachDependencies = {
+	connectLocal: connectCdp,
+	connectRemote: connectCdpUrl,
+}
+
+export function attachTool(
+	state: AttachRef,
+	builderClient?: ReclaimClient,
+	name: 'attach_browser' | 'attach_chrome' = 'attach_browser',
+	beforeReplace?: () => Promise<void>,
+	dependencies: AttachDependencies = DEFAULT_DEPENDENCIES,
+): RegisteredTool {
+	return defineTool<AttachArgs>(
 		{
-			name: 'attach_chrome',
+			name,
 			description:
-				'Attach to a Chrome instance via CDP. ' +
-				'Auto-launches a dedicated-profile Chrome ' +
-				'on first call if no attachMode is persisted. ' +
-				'Persists the chosen mode in ~/.reclaim/config.json.',
+				name === 'attach_chrome'
+					? 'Backward-compatible alias for attach_browser.'
+					: 'Connect the provider-authoring tools to a browser. Choose '
+						+ 'dedicated (launch local Chrome), attach (existing local CDP '
+						+ 'port), builder (quota-accounted Popcorn browser with a '
+						+ 'shareable live view), or custom (caller-supplied CDP '
+						+ 'websocket). '
+						+ 'Builder and custom CDP credentials are held in memory and never '
+						+ 'returned.',
 			inputSchema: {
 				type: 'object',
 				properties: {
-					attachMode: { type: 'string', enum: ['dedicated', 'attach'] },
-					port: { type: 'number' },
+					mode: {
+						type: 'string',
+						enum: ['dedicated', 'attach', 'builder', 'custom'],
+					},
+					attachMode: {
+						type: 'string',
+						enum: ['dedicated', 'attach'],
+						description: 'Deprecated local-mode alias for mode.',
+					},
+					port: { type: 'number', minimum: 1, maximum: 65535 },
+					orgId: { type: 'string', format: 'uuid' },
+					cdpUrl: { type: 'string', maxLength: 4000 },
+					liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
 				},
 			},
 		},
 		async(parsed) => {
-			let cfg = state.config.read()?.browser_agent
-			if(parsed.attachMode || parsed.port) {
-				cfg = {
-					attachMode: parsed.attachMode ?? cfg?.attachMode ?? 'dedicated',
-					port: parsed.port ?? cfg?.port ?? 9222,
-				}
-				state.config.write({ browser_agent: cfg })
-			}
-
-			if(!cfg) {
+			const persisted = state.config.read()?.browser_agent
+			const mode = parsed.mode ?? parsed.attachMode ?? persisted?.attachMode
+			if(!mode) {
 				return {
 					needsChoice: true,
 					message:
-						'First-run: choose attach mode. ' +
-						'Call attach_chrome again with attachMode="dedicated" ' +
-						'(auto-launch a Chrome profile under ~/.reclaim/chrome-profile) ' +
-						'or attachMode="attach" ' +
-						'(connect to a Chrome you launched yourself with ' +
-						'BOTH --remote-debugging-port=9222 AND ' +
-						'--user-data-dir=<some-non-default-path>; ' +
-						'since Chrome 136 the debug-port flag is silently ' +
-						'ignored if the default profile is in use).',
+						'Choose a browser mode and call attach_browser again: '
+						+ '"dedicated" launches a local dedicated Chrome profile; '
+						+ '"attach" connects to a local Chrome debugging port; '
+						+ '"builder" creates a quota-accounted remote browser and '
+						+ 'requires orgId; "custom" requires a CDP websocket URL.',
 					configPath: defaultConfigPath(),
 				}
 			}
 
-			if(cfg.attachMode === 'dedicated') {
-				try {
-					await waitForCdpReady(cfg.port, 500)
-				} catch{
-					launchChrome({ port: cfg.port, profileDir: defaultProfileDir() })
-					await waitForCdpReady(cfg.port, 10_000)
-				}
-			} else {
-				await waitForCdpReady(cfg.port, 2_000).catch(() => {
-					throw new Error(
-						`attach mode: nothing answering CDP on port ${cfg.port}. ` +
-						'Chrome must be launched with BOTH ' +
-						`--remote-debugging-port=${cfg.port} AND ` +
-						'--user-data-dir=<some-non-default-path>. ' +
-						'Since Chrome 136 (May 2025), the debug-port flag is ' +
-						'silently ignored when the default ' +
-						"user profile is in use — that's why nothing opens the port. " +
-						'Either re-launch Chrome with ' +
-						'a custom --user-data-dir, or switch to attachMode="dedicated".',
-					)
-				})
+			const next = await connect(
+				mode, parsed, persisted, builderClient, dependencies,
+			)
+			try {
+				await beforeReplace?.()
+				await disposeAttached(state)
+			} catch(err) {
+				await disposeState(next).catch(() => {})
+				throw err
 			}
 
-			if(state.current) {
-				await state.current.handles.close().catch(() => {})
+			state.current = next
+			if(mode === 'dedicated' || mode === 'attach') {
+				state.config.write({
+					browser_agent: { attachMode: mode, port: next.port! },
+				})
 			}
 
-			const handles = await connectCdp(cfg.port)
-			state.current = { handles, port: cfg.port }
-			return { attached: true, port: cfg.port, mode: cfg.attachMode }
+			return {
+				attached: true,
+				mode,
+				...(next.port ? { port: next.port } : {}),
+				...(next.browserSessionId
+					? { browserSessionId: next.browserSessionId }
+					: {}),
+				...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
+			}
 		},
 	)
 }
+
+export async function disposeAttached(state: AttachRef) {
+	const current = state.current
+	if(!current) {
+		return
+	}
+
+	delete state.current
+	await disposeState(current)
+}
+
+async function connect(
+	mode: BrowserMode,
+	parsed: AttachArgs,
+	persisted: { attachMode: 'dedicated' | 'attach', port: number } | undefined,
+	builderClient: ReclaimClient | undefined,
+	dependencies: AttachDependencies,
+): Promise<AttachState> {
+	if(mode === 'builder') {
+		assert(builderClient, badRequest('Builder browser service is unavailable'))
+		assert(parsed.orgId, badRequest('orgId is required for builder mode'))
+		const { data } = await builderClient.call('CreateAgentBrowserSession', {
+			params: { orgId: parsed.orgId },
+		})
+		let handles: CdpHandles
+		try {
+			handles = await dependencies.connectRemote(data.cdpUrl)
+		} catch(err) {
+			await builderClient.call('DisposeAgentBrowserSession', {
+				params: {
+					orgId: parsed.orgId,
+					browserSessionId: data.id,
+				},
+			}).catch(() => {})
+			throw err
+		}
+
+		return {
+			handles,
+			mode,
+			liveViewUrl: data.liveViewUrl,
+			browserSessionId: data.id,
+			orgId: parsed.orgId,
+			disposeRemote: async() => {
+				await builderClient.call('DisposeAgentBrowserSession', {
+					params: {
+						orgId: parsed.orgId!,
+						browserSessionId: data.id,
+					},
+				})
+			},
+		}
+	}
+
+	if(mode === 'custom') {
+		assert(parsed.cdpUrl, badRequest('cdpUrl is required for custom mode'))
+		const url = new URL(parsed.cdpUrl)
+		assert(
+			url.protocol === 'ws:' || url.protocol === 'wss:',
+			badRequest('cdpUrl must use ws:// or wss://'),
+		)
+		return {
+			handles: await dependencies.connectRemote(parsed.cdpUrl),
+			mode,
+			...(parsed.liveViewUrl ? { liveViewUrl: parsed.liveViewUrl } : {}),
+		}
+	}
+
+	const port = parsed.port ?? persisted?.port ?? 9222
+	if(mode === 'dedicated') {
+		try {
+			await waitForCdpReady(port, 500)
+		} catch{
+			launchChrome({ port, profileDir: defaultProfileDir() })
+			await waitForCdpReady(port, 10_000)
+		}
+	} else {
+		await waitForCdpReady(port, 2_000).catch(() => {
+			throw new Error(
+				`attach mode: nothing answering CDP on port ${port}. Chrome must `
+				+ `be launched with --remote-debugging-port=${port} AND `
+				+ '--user-data-dir=<some-non-default-path>. Chrome 136+ ignores '
+				+ 'the debugging flag for the default profile.',
+			)
+		})
+	}
+
+	return { handles: await dependencies.connectLocal(port), mode, port }
+}
+
+async function disposeState(state: AttachState) {
+	try {
+		await state.handles.close()
+	} finally {
+		await state.disposeRemote?.()
+	}
+}

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

@@ -16,7 +16,7 @@ import { ensureAttestorCrypto } from '../../../proof/proof-core.ts'
 import { type RegisteredTool } from '../../server.ts'
 import { analyzeTool } from './analyze.ts'
 import { type AttachState, attachTool } from './attach.ts'
-import { type CaptureStore, captureTools } from './capture.ts'
+import { type CaptureStore, captureTools, resetCaptures } from './capture.ts'
 import { listTabsTool } from './eval.ts'
 import { howItWorksTool } from './how-it-works.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
@@ -28,7 +28,11 @@ export interface AgentState {
 	captures: CaptureStore
 }
 
-function buildAgentState(): AgentState {
+/** Exported so a mode (e.g. old-devtools) that supplies its own publish tool
+ *  can build the attach/capture state up front and share the SAME instance
+ *  with `buildAgentTools` — letting that publish tool see the live attach
+ *  state (e.g. to remind the caller about a still-open browser session). */
+export function buildAgentState(): AgentState {
 	return {
 		attach: { config: new ConfigStore() },
 		captures: { sessions: new Map() },
@@ -39,17 +43,27 @@ function buildAgentState(): AgentState {
  *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
- *  capture/proof tools — old mode supplies its own publish tool. */
+ *  capture/proof tools — old mode supplies its own publish tool.
+ *  Pass `externalState` to share attach/capture state with tools registered
+ *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
 export function buildAgentTools(
 	client?: ReclaimClient,
+	builderClient: ReclaimClient | undefined = client,
+	externalState?: AgentState,
 ): RegisteredTool[] {
-	const state = buildAgentState()
+	const state = externalState ?? buildAgentState()
 	ensureAttestorCrypto()
 	const tools: RegisteredTool[] = []
 	// Stateless docs tool — serve the mode-specific authoring guide to any
 	// client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
 	tools.push(howItWorksTool(!client))
-	tools.push(attachTool(state.attach))
+	const beforeReplace = () => resetCaptures(state.captures)
+	tools.push(attachTool(
+		state.attach, builderClient, 'attach_browser', beforeReplace,
+	))
+	tools.push(attachTool(
+		state.attach, builderClient, 'attach_chrome', beforeReplace,
+	))
 	tools.push(listTabsTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {
 		tools.push(t)
@@ -68,7 +82,7 @@ export function buildAgentTools(
 	}
 
 	if(client) {
-		tools.push(createVersionFromCaptureTool(client))
+		tools.push(createVersionFromCaptureTool(client, state.attach))
 	}
 
 	return tools

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

@@ -20,13 +20,22 @@ export interface CaptureStore {
 	activeTab?: string
 }
 
+export async function resetCaptures(captures: CaptureStore) {
+	for(const entry of captures.sessions.values()) {
+		await entry.session.stop().catch(() => {})
+	}
+
+	captures.sessions.clear()
+	delete captures.activeTab
+}
+
 export function captureTools(
 	attachRef: { current?: AttachState },
 	captures: CaptureStore,
 ): RegisteredTool[] {
 	const requireAttached = (): AttachState => {
 		if(!attachRef.current) {
-			throw new Error('Not attached. Call attach_chrome first.')
+			throw new Error('Not attached. Call attach_browser first.')
 		}
 
 		return attachRef.current

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

@@ -1,4 +1,3 @@
-import { listTabs } from '../../../cdp/tabs.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
 
@@ -16,10 +15,10 @@ export function listTabsTool(attachRef: {
 		},
 		async() => {
 			if(!attachRef.current) {
-				throw new Error('Not attached. Call attach_chrome first.')
+				throw new Error('Not attached. Call attach_browser first.')
 			}
 
-			return { tabs: await listTabs(attachRef.current.port) }
+			return { tabs: await attachRef.current.handles.listTabs() }
 		},
 	)
 }

package/src/mcp/tools/agent/how-it-works.ts

@@ -11,7 +11,7 @@ import { defineTool, type RegisteredTool } from '../../server.ts'
  * so any MCP client — not just Claude Code, which alone auto-loads skills — can
  * pull it. `oldMode` selects the backend-specific guide so the agent is never
  * told to call auth/publish tools that aren't registered in its mode.
- * Stateless: callable before `attach_chrome`.
+ * Stateless: callable before `attach_browser`.
  */
 export function howItWorksTool(oldMode: boolean): RegisteredTool {
 	const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER

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

@@ -1,4 +1,4 @@
 // Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
 // replay, zkTLS proof). Import from here, not the individual files.
-export { buildAgentTools } from './build.ts'
+export { buildAgentState, buildAgentTools } from './build.ts'
 export type { AgentState } from './build.ts'

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

@@ -12,6 +12,7 @@ import {
 	providerToCreateVersionRequest,
 } from '../../../provider/to-version.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
 
 /** Schemas shared by the top-level `provider`/`providers` and the lighter
  *  `allowedJsRequests` drafts — keeps the request shape from drifting between
@@ -142,6 +143,7 @@ interface PublishArgs {
 
 export function createVersionFromCaptureTool(
 	client: ReclaimClient,
+	attachRef?: { current?: AttachState },
 ): RegisteredTool {
 	return defineTool<PublishArgs>(
 		{
@@ -172,7 +174,11 @@ export function createVersionFromCaptureTool(
 				'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.',
+				'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.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -234,7 +240,28 @@ export function createVersionFromCaptureTool(
 						description:
 							'Extra requests the injection script is allowed to fire ' +
 							'(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-							'`multiple`/`required` default to true.',
+							'`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.',
 						items: ALLOWED_JS_REQUEST_SCHEMA,
 					},
 					interceptorOptions: {
@@ -307,6 +334,23 @@ export function createVersionFromCaptureTool(
 			]
 			notes.push(...matchRedactionWarnings(requestCounts))
 
+			// A browser session left attached after a successful publish is easy
+			// to forget about — surface it so the caller asks the developer
+			// before closing it (a builder-mode session is quota-accounted and
+			// otherwise just sits until its TTL expires).
+			const attached = attachRef?.current
+			if(attached) {
+				notes.push(
+					`A "${attached.mode}" browser session is still attached` +
+					(attached.browserSessionId
+						? ` (browserSessionId: ${attached.browserSessionId})`
+						: '') +
+					'. Ask the developer whether they want to keep it open for ' +
+					'further edits — only call dispose_browser once they confirm ' +
+					'they\'re done with it.',
+				)
+			}
+
 			// Let the dev know how/when the script runs (and the window.Reclaim gap).
 			if(args.jsUserScripts?.trim()) {
 				notes.push(

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

@@ -1,7 +1,7 @@
 import type { ConfigStore } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
-import type { AttachState } from './attach.ts'
-import type { CaptureStore } from './capture.ts'
+import { type AttachState, disposeAttached } from './attach.ts'
+import { type CaptureStore, resetCaptures } from './capture.ts'
 
 export function sessionTools(
 	attachRef: { current?: AttachState, config: ConfigStore },
@@ -18,11 +18,29 @@ export function sessionTools(
 			async() => ({
 				config: attachRef.config.read()?.browser_agent,
 				attached: Boolean(attachRef.current),
+				mode: attachRef.current?.mode,
 				port: attachRef.current?.port,
+				liveViewUrl: attachRef.current?.liveViewUrl,
+				browserSessionId: attachRef.current?.browserSessionId,
+				orgId: attachRef.current?.orgId,
 				captures: [...captures.sessions.keys()],
 				activeTab: captures.activeTab,
 			}),
 		),
+		defineTool<Record<string, never>>(
+			{
+				name: 'dispose_browser',
+				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.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => {
+				await resetAll(attachRef, captures)
+				return { disposed: true }
+			},
+		),
 		defineTool<Record<string, never>>(
 			{
 				name: 'reset_session',
@@ -32,14 +50,17 @@ export function sessionTools(
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
-				for(const entry of captures.sessions.values()) {
-					await entry.session.stop().catch(() => {})
-				}
-
-				captures.sessions.clear()
-				delete captures.activeTab
+				await resetAll(attachRef, captures)
 				return { reset: true }
 			},
 		),
 	]
 }
+
+async function resetAll(
+	attachRef: { current?: AttachState, config: ConfigStore },
+	captures: CaptureStore,
+) {
+	await resetCaptures(captures)
+	await disposeAttached(attachRef)
+}

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

@@ -54,19 +54,14 @@ function withLocalOprfMode(provider: ReclaimProvider): ReclaimProvider {
  *  captured requests, prove via the in-process attestor, replay by re-fetch. */
 function localBackend(entry: CaptureEntry): AuthoringBackend {
 	const { tabClient, session, drafts } = entry
-	// The per-tab CDP client is strongly typed to `keyof Commands`; the shared
-	// tools drive it with dynamic method/event names, so view it as string-keyed.
-	const client = tabClient as unknown as {
-		send: (method: string, params: object) => Promise<unknown>
-		once: (e: string, cb: () => void) => void
-		removeListener: (e: string, cb: () => void) => void
-	}
 
 	return {
 		capture: session,
 		drafts,
-		sendCdp: (method, params) => client.send(method, params ?? {}),
+		sendCdp: (method, params) => tabClient.send(method, params ?? {}),
 		waitForEvent: (method, timeoutMs) => new Promise((resolve) => {
+			let stopListening = () => {}
+
 			const onEvent = () => {
 				cleanup()
 				resolve('fired')
@@ -78,10 +73,10 @@ function localBackend(entry: CaptureEntry): AuthoringBackend {
 			}, timeoutMs)
 			const cleanup = () => {
 				clearTimeout(timer)
-				client.removeListener(method, onEvent)
+				stopListening()
 			}
 
-			client.once(method, onEvent)
+			stopListening = tabClient.subscribeOnce(method, onEvent)
 		}),
 		replay: async(draft, opts) => {
 			// Auth-bound check: re-fetch with the secrets dropped. replayProvider