@reclaimprotocol/agent 0.1.24 → 0.1.25

package/lib/mcp/start.js

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ReclaimClient } from '@reclaimprotocol/client';
 import { ConfigStore } from "../config/store.js";
 import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, resolveOldMode, sdkApiUrl, } from "../consts.js";
+import { LOGGER } from "../logger.js";
 import { ReclaimOldClient } from "../old/client.js";
 import { resolveInitialIdentity } from "../old/identity.js";
 import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
@@ -10,7 +11,7 @@ import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, readSession, } from "./tools/index.js";
+import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
@@ -28,6 +29,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;
     const builderClient = new ReclaimClient({
         baseUrl: apiUrl(),
         // Builder access is orthogonal to publishing mode. A legacy-devtools
@@ -52,7 +55,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));
         registerToolList(server, buildLocalCredentialTools());
@@ -79,9 +82,61 @@ export async function startMcpServer() {
         // for every MCP-tagged operation.
         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 = 10000;
+/**
+ * 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) {
+    let shuttingDown = false;
+    const shutdown = (reason) => {
+        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) => {
+            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'));
+}

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

@@ -1,8 +1,18 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
 import { type CdpHandles, connectCdp, connectCdpUrl } from '../../../cdp/client.ts';
+import { dockerAvailable, startContainer } from '../../../cdp/container.ts';
 import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
-export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom';
+export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom' | 'container';
+/**
+ * Modes with a live view that `share_browser_view` can put behind a public URL.
+ *
+ * Only `container`: it runs the Reclaim browser runtime, whose viewer already
+ * serves on loopback, so sharing is a tunnel in front of it. `builder` gives a
+ * hosted `liveViewUrl` instead, and a plain local browser has nothing to
+ * show — one on this machine is watched by looking at it.
+ */
+export declare const SHAREABLE_MODES: Set<BrowserMode>;
 export interface AttachState {
     handles: CdpHandles;
     mode: BrowserMode;
@@ -17,6 +27,13 @@ export interface AttachState {
     apiUrl?: string;
     /** The exit country this remote browser was allocated with, if any. */
     countryCode?: string;
+    /** Docker's name for a `container`-mode browser, for diagnostics. */
+    containerName?: string;
+    /** Loopback port the container's own live viewer serves on, which is what
+     *  `share_browser_view` tunnels. Never the CDP port. */
+    viewerPort?: number;
+    /** Whether the runtime image had to be downloaded on this attach. */
+    imagePulled?: boolean;
     disposeRemote?: () => Promise<void>;
 }
 export interface AttachRef {
@@ -26,7 +43,10 @@ export interface AttachRef {
 interface AttachDependencies {
     connectLocal: typeof connectCdp;
     connectRemote: typeof connectCdpUrl;
+    /** Injected so container mode is testable without Docker installed. */
+    dockerAvailable: typeof dockerAvailable;
+    startContainer: typeof startContainer;
 }
-export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, beforeReplace?: () => Promise<void>, dependencies?: AttachDependencies): RegisteredTool;
+export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, beforeReplace?: () => Promise<void>, dependencies?: Partial<AttachDependencies>): RegisteredTool;
 export declare function disposeAttached(state: AttachRef): Promise<void>;
 export {};

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

@@ -1,10 +1,20 @@
 import { badRequest } from '@hapi/boom';
 import assert from 'node:assert';
 import { connectCdp, connectCdpUrl, } from "../../../cdp/client.js";
+import { dockerAvailable, dockerMissingMessage, startContainer, } from "../../../cdp/container.js";
 import { suggestCountryFromIp } from "../../../cdp/geo.js";
 import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../../cdp/launcher.js";
 import { defaultConfigPath } from "../../../config/store.js";
 import { defineTool } from "../../server.js";
+/**
+ * Modes with a live view that `share_browser_view` can put behind a public URL.
+ *
+ * Only `container`: it runs the Reclaim browser runtime, whose viewer already
+ * serves on loopback, so sharing is a tunnel in front of it. `builder` gives a
+ * hosted `liveViewUrl` instead, and a plain local browser has nothing to
+ * show — one on this machine is watched by looking at it.
+ */
+export const SHAREABLE_MODES = new Set(['container']);
 /**
  * The browser sources, written once and used twice: rendered into this tool's
  * DESCRIPTION (so an agent can put the choice to the developer straight from
@@ -15,92 +25,145 @@ import { defineTool } from "../../server.js";
  * reads in the description but that disagrees with what the tool returns is
  * worse than either alone.
  *
- * `liveView` is here for the same reason. How a developer watches the browser
- * differs per mode — Popcorn hands back a hosted URL, a local Chrome needs
- * `share_browser_view` to tunnel one — and nobody discovers that by guessing.
- * Advertising it alongside the mode is the only place it lands BEFORE the
- * choice is made.
+ * Ordered and labelled BY USE CASE, because that is the question a developer
+ * can actually answer. "Which CDP transport?" is not; "does anyone else need to
+ * get into this browser?" is, and it decides two of the four. `useCase` is the
+ * grouping key, so the rendered list reads as two pairs rather than four
+ * unrelated transports.
  */
 const BROWSER_OPTIONS = [
     {
         mode: 'dedicated',
+        useCase: 'Working on your own machine',
         label: 'Local Chrome, launched for you',
         detail: 'Launches Chrome with a dedicated profile under '
-            + '~/.reclaim/chrome-profile. Easiest local option; nothing to set up.',
+            + '~/.reclaim/chrome-profile. Nothing to set up, and the profile '
+            + 'persists, so a site you sign in to stays signed in. The easiest '
+            + 'choice when you are doing the work yourself.',
         requires: [],
-        liveView: 'On this machine only, until you share it: share_browser_view puts the '
-            + 'tab behind a public URL (needs cloudflared) so someone elsewhere can '
-            + 'watch, and by default click and type.',
+        liveView: 'None, and none needed — the browser is on your screen.',
     },
     {
         mode: 'attach',
-        label: 'Local Chrome the developer is already running',
-        detail: 'Connects to an existing Chrome debugging port. That Chrome must have '
-            + 'been started with BOTH --remote-debugging-port AND a non-default '
-            + '--user-data-dir: since Chrome 136 the debug flag is silently ignored '
-            + 'on the default profile.',
+        useCase: 'Working on your own machine',
+        label: 'The Chrome you already have open',
+        detail: 'Connects to a Chrome you started yourself, keeping the tabs, '
+            + 'extensions and logins already in it. That Chrome must have been '
+            + 'started with BOTH --remote-debugging-port AND a non-default '
+            + '--user-data-dir: since Chrome 136 the debug flag is silently '
+            + 'ignored on the default profile.',
         requires: ['port (default 9222)'],
-        liveView: 'On this machine only, until you share it: share_browser_view puts the '
-            + 'tab behind a public URL (needs cloudflared) so someone elsewhere can '
-            + 'watch, and by default click and type.',
+        liveView: 'None, and none needed — the browser is on your screen.',
+    },
+    {
+        mode: 'container',
+        useCase: 'Someone else has to sign in, or you need a phone',
+        label: 'Reclaim runtime in Docker — free, runs on your machine',
+        detail: 'Runs the Reclaim browser runtime (the same image the remote browser '
+            + 'uses) as a container on this machine, and gives you a link you can '
+            + 'send to whoever holds the account. They open it in any browser, '
+            + 'including a phone, and can see and click in it. Free — it is your '
+            + 'Docker and your bandwidth. Costs a 432 MB first-run download and '
+            + 'about 2 GB of RAM. The image is amd64, so Apple Silicon runs it '
+            + 'translated. OrbStack handles that itself; Docker Desktop needs '
+            + 'Rosetta enabled.',
+        requires: ['Docker running'],
+        liveView: 'Built in. This call returns a local `viewerUrl`, and '
+            + 'share_browser_view turns that into a public link for the person '
+            + 'helping you.',
     },
     {
         mode: 'builder',
-        label: 'Remote Builder browser (Popcorn), with a shareable live view',
-        detail: 'Quota-accounted remote browser; returns a liveViewUrl the developer '
-            + 'can open or share. The only way to browse a site from a SPECIFIC '
-            + 'COUNTRY — its whole egress is routed there. Geolocation is '
-            + 'optional: '
-            + 'omit countryCode to be offered a suggestion, or pass skipCountry '
-            + 'to allocate without geo-routing.',
+        useCase: 'Someone else has to sign in, or you need a phone',
+        label: 'Remote browser, hosted by Reclaim — CHARGEABLE',
+        detail: 'A browser allocated in Reclaim\'s cloud, billed against the '
+            + 'organization\'s quota. Nothing to install, and the shareable link '
+            + 'comes back immediately. It is also the only way to browse a site '
+            + 'from a SPECIFIC COUNTRY — its whole egress is routed there. '
+            + 'Geolocation is optional: omit countryCode to be offered a '
+            + 'suggestion, or pass skipCountry to allocate without geo-routing.',
         requires: [
             'Builder authentication',
             'orgId (auto-resolved when you have only one)',
+            'quota — this one costs money',
         ],
-        liveView: 'Included — this call returns a hosted liveViewUrl straight from '
-            + 'Popcorn. Nothing to start, and share_browser_view does not apply.',
+        liveView: 'Included. This call returns a hosted liveViewUrl to pass on; '
+            + 'share_browser_view does not apply.',
     },
     {
         mode: 'custom',
-        label: 'A CDP endpoint the developer supplies',
-        detail: 'Connects to any ws:// or wss:// CDP websocket. The URL is treated as '
-            + 'a credential — it is never logged, persisted, or returned.',
+        useCase: 'Advanced',
+        label: 'A CDP endpoint you supply',
+        detail: 'Connects to any ws:// or wss:// CDP websocket — a browser you run '
+            + 'elsewhere, or another tool\'s. The URL is treated as a credential: '
+            + 'never logged, persisted, or returned. Only pick this if you were '
+            + 'given an endpoint and know why.',
         requires: ['cdpUrl'],
-        liveView: 'Shareable on request: share_browser_view puts the tab behind a public '
-            + 'URL (needs cloudflared). The developer\'s own cdpUrl is never '
-            + 'exposed by it.',
+        liveView: 'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
     },
 ];
-/** Flatten {@link BROWSER_OPTIONS} into the tool description. */
+/**
+ * The options as prose, grouped by use case.
+ *
+ * The grouping is the useful part: it turns "pick one of five transports" into
+ * "answer one question, then pick one of two".
+ */
 function renderBrowserOptions() {
-    return BROWSER_OPTIONS
-        .map((option) => {
+    const seen = new Set();
+    const lines = [];
+    for (const option of BROWSER_OPTIONS) {
+        if (!seen.has(option.useCase)) {
+            seen.add(option.useCase);
+            lines.push(`— ${option.useCase.toUpperCase()} —`);
+        }
         const needs = option.requires.length
             ? ` Needs: ${option.requires.join('; ')}.`
             : '';
-        return `(${option.mode}) ${option.label}. ${option.detail}${needs}`
-            + ` Live view: ${option.liveView}`;
-    })
-        .join(' ');
+        lines.push(`(${option.mode}) ${option.label}. ${option.detail}${needs}`
+            + ` Live view: ${option.liveView}`);
+    }
+    return lines.join(' ');
 }
 const DEFAULT_DEPENDENCIES = {
     connectLocal: connectCdp,
     connectRemote: connectCdpUrl,
+    dockerAvailable,
+    startContainer,
 };
-export function attachTool(state, builderClient, beforeReplace, dependencies = DEFAULT_DEPENDENCIES) {
+export function attachTool(state, builderClient, beforeReplace, 
+// Partial so a caller can stub one thing without restating the rest — the
+// tests only ever care about a couple of these at a time.
+dependencies = {}) {
+    const deps = {
+        ...DEFAULT_DEPENDENCIES, ...dependencies,
+    };
     return defineTool({
         name: 'attach_browser',
-        description: 'Connect the provider-authoring tools to a browser. ASK THE '
-            + 'DEVELOPER which of the four options below they want, then call '
-            + 'this ONCE with their chosen `mode` — never choose for them, and '
-            + 'never assume a previous session\'s choice still applies. You do '
-            + 'not need a discovery call: the options are listed here. '
-            + '(Calling with no `mode` returns the same list as structured '
-            + '`options`, if you\'d rather relay it verbatim.) '
-            + 'When you put the choice to them, INCLUDE each option\'s live-view '
-            + 'line: how they watch the browser differs per mode, and nobody '
-            + 'discovers share_browser_view on their own. '
+        description: 'Connect the provider-authoring tools to a browser. Never choose '
+            + 'for them, never assume a previous session\'s choice still '
+            + 'applies, and call this ONCE with the `mode` they pick. '
+            + 'ASK THIS FIRST, before listing anything: "Will you be doing this '
+            + 'yourself, or does someone else need to sign in — for example the '
+            + 'person whose account it is?" That answer decides half the list, '
+            + 'and a developer can answer it without knowing what CDP is. '
+            + 'THEMSELVES → offer `dedicated` or `attach`. SOMEONE ELSE, or the '
+            + 'site only works on a phone → offer `container` or `builder`, '
+            + 'which are the only two that produce a link another person can '
+            + 'open. Say which of those two costs money: `container` is free '
+            + 'but needs Docker, `builder` needs no install but is billed '
+            + 'against the org\'s quota. '
+            + 'Then relay the matching options with their live-view lines. You '
+            + 'do not need a discovery call — the full list is here, and calling '
+            + 'with no `mode` returns it as structured `options` if you would '
+            + 'rather read it back verbatim. '
             + 'OPTIONS — ' + renderBrowserOptions() + ' '
+            + 'A `container` browser returns a local `viewerUrl`; relay it. When '
+            + 'someone remote needs in, call share_browser_view and relay the '
+            + 'FULL public url verbatim, on its own line. `builder` returns a '
+            + 'hosted `liveViewUrl` — relay that the same way. `dedicated`, '
+            + '`attach` and `custom` cannot be shared at all: if they ask for a '
+            + 'link after picking one, say so and offer to re-attach with '
+            + '`container`. '
             + 'Builder and custom CDP credentials are held in memory and are '
             + 'never returned. '
             + 'More: how_it_works({ topic: "browser" }).',
@@ -109,7 +172,9 @@ export function attachTool(state, builderClient, beforeReplace, dependencies = D
             properties: {
                 mode: {
                     type: 'string',
-                    enum: ['dedicated', 'attach', 'builder', 'custom'],
+                    enum: [
+                        'dedicated', 'attach', 'container', 'builder', 'custom',
+                    ],
                 },
                 attachMode: {
                     type: 'string',
@@ -120,6 +185,14 @@ export function attachTool(state, builderClient, beforeReplace, dependencies = D
                 orgId: { type: 'string', format: 'uuid' },
                 cdpUrl: { type: 'string', maxLength: 4000 },
                 liveViewUrl: { type: 'string', format: 'uri', maxLength: 4000 },
+                viewerPort: {
+                    type: 'number',
+                    minimum: 1024,
+                    maximum: 60000,
+                    description: '`container` mode only. Loopback port for the built-in live '
+                        + 'viewer. Change it only to avoid a clash; the CDP port and '
+                        + 'the container name are derived from it.',
+                },
                 countryCode: {
                     type: 'string',
                     pattern: '^[A-Za-z]{2}$',
@@ -148,9 +221,14 @@ export function attachTool(state, builderClient, beforeReplace, dependencies = D
         if (!mode) {
             return {
                 needsChoice: true,
-                message: 'Ask the developer which browser to use, then call '
-                    + 'attach_browser again with their chosen `mode`. Present all '
-                    + 'the options below — do not pick one for them.',
+                message: 'Ask FIRST whether they will be doing this themselves or '
+                    + 'someone else has to sign in — that answer decides half the '
+                    + 'list. Themselves: `dedicated` or `attach`. Someone else, or '
+                    + 'a phone-only site: `container` (free, needs Docker) or '
+                    + '`builder` (no install, chargeable) — the only two that give '
+                    + 'you a link to send. Then present the matching options and '
+                    + 'call attach_browser again with the `mode` they pick. Do not '
+                    + 'pick one for them.',
                 options: BROWSER_OPTIONS,
                 ...(persisted?.attachMode
                     ? { previouslyUsed: persisted.attachMode }
@@ -219,7 +297,7 @@ export function attachTool(state, builderClient, beforeReplace, dependencies = D
                 ...(suggestion.city ? { city: suggestion.city } : {}),
             };
         }
-        const next = await connect(mode, { ...parsed, orgId }, persisted, builderClient, dependencies);
+        const next = await connect(mode, { ...parsed, orgId }, persisted, builderClient, deps);
         try {
             await beforeReplace?.();
             await disposeAttached(state);
@@ -234,6 +312,11 @@ export function attachTool(state, builderClient, beforeReplace, dependencies = D
                 browser_agent: { attachMode: mode, port: next.port },
             });
         }
+        // How the developer watches this browser differs per mode, and none of
+        // it is guessable, so every mode says its own piece here.
+        const localView = mode === 'container';
+        const hostedView = Boolean(next.liveViewUrl) && !localView;
+        const canShare = SHAREABLE_MODES.has(mode);
         return {
             attached: true,
             mode,
@@ -243,6 +326,37 @@ export function attachTool(state, builderClient, beforeReplace, dependencies = D
                 : {}),
             ...(next.liveViewUrl ? { liveViewUrl: next.liveViewUrl } : {}),
             ...(next.countryCode ? { countryCode: next.countryCode } : {}),
+            ...(next.containerName ? { containerName: next.containerName } : {}),
+            ...(canShare ? { liveViewAvailable: true } : {}),
+            _notes: [
+                ...(next.imagePulled
+                    ? ['The browser runtime image was downloaded just now (about '
+                            + '432 MB, about 1.3 GB on disk). Mention it — later attaches '
+                            + 'reuse it. RECLAIM_BROWSER_RUNTIME_IMAGE points at a '
+                            + 'different or locally built image.']
+                    : []),
+                ...(localView
+                    ? ['This browser has its own live view, already running on this '
+                            + 'machine: relay `liveViewUrl` to the developer verbatim, on '
+                            + 'its own line, so they can watch and drive it. It is '
+                            + 'loopback-only, so only they can reach it. If someone ELSE '
+                            + 'needs to — a login only they can complete — call '
+                            + 'share_browser_view to put that same viewer behind a public '
+                            + 'URL.']
+                    : []),
+                ...(hostedView
+                    ? ['This browser has a hosted live view already. Relay '
+                            + '`liveViewUrl` to the developer verbatim, on its own line, '
+                            + 'so they can watch the run — share_browser_view does not '
+                            + 'apply here.']
+                    : []),
+                ...(!localView && !hostedView
+                    ? ['This browser has no live view: it runs on the developer\'s '
+                            + 'own machine, so they watch it by looking at it. If someone '
+                            + 'ELSE needs to see or drive it, say that `container` mode '
+                            + 'runs a browser with a shareable live view built in.']
+                    : []),
+            ],
         };
     });
 }
@@ -304,6 +418,34 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
             ...(parsed.liveViewUrl ? { liveViewUrl: parsed.liveViewUrl } : {}),
         };
     }
+    if (mode === 'container') {
+        assert(await dependencies.dockerAvailable(), badRequest(dockerMissingMessage()));
+        // Ports are allocated per session unless the caller names one. A fixed
+        // default would give two concurrent sessions the SAME container — the
+        // name derives from the viewer port — so session two would silently
+        // drive session one's browser.
+        const container = await dependencies.startContainer({
+            ...(parsed.viewerPort ? { viewerPort: parsed.viewerPort } : {}),
+            image: process.env.RECLAIM_BROWSER_RUNTIME_IMAGE?.trim() || undefined,
+        });
+        try {
+            return {
+                handles: await dependencies.connectRemote(container.cdpUrl),
+                mode,
+                liveViewUrl: container.viewerUrl,
+                containerName: container.name,
+                viewerPort: container.viewerPort,
+                imagePulled: container.pulled,
+                disposeRemote: container.stop,
+            };
+        }
+        catch (err) {
+            // Never leave a 1.3 GB container running for a browser we could not
+            // talk to.
+            await container.stop().catch(() => { });
+            throw err;
+        }
+    }
     const port = parsed.port ?? persisted?.port ?? 9222;
     if (mode === 'dedicated') {
         try {

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

@@ -39,3 +39,8 @@ export declare function buildAgentState(): AgentState;
  *  registered elsewhere (for example, old mode's publish tool) instead of
  *  building a fresh one. */
 export declare function buildAgentTools(client?: ReclaimClient, builderClient?: ReclaimClient | undefined, externalState?: AgentState): RegisteredTool[];
+/**
+ * Tear down an agent state on the way out. Safe to call more than once, and
+ * safe when nothing was ever attached.
+ */
+export declare function disposeAgentState(state: AgentState): Promise<void>;

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

@@ -19,7 +19,7 @@ import { howItWorksTool } from "./how-it-works.js";
 import { liveViewTools } from "./live-view.js";
 import { podProofTools } from "./pod-proof.js";
 import { createVersionFromCaptureTool } from "./publish.js";
-import { sessionTools } from "./session.js";
+import { resetAll, sessionTools } from "./session.js";
 import { sharedAuthoringTools } from "./shared.js";
 /** Exported so a mode (for example, old-devtools) that supplies its own
  *  publish tool can build the attach/capture state up front and share the SAME
@@ -58,7 +58,7 @@ export function buildAgentTools(client, builderClient = client, externalState) {
         tools.push(t);
     }
     // Local-CDP only: a builder-mode browser already has a hosted live view.
-    for (const t of liveViewTools(state.attach, state.captures, state.liveShare)) {
+    for (const t of liveViewTools(state.attach, state.liveShare)) {
         tools.push(t);
     }
     for (const t of podProofTools(state.attach, state.captures)) {
@@ -76,3 +76,10 @@ export function buildAgentTools(client, builderClient = client, externalState) {
     }
     return tools;
 }
+/**
+ * Tear down an agent state on the way out. Safe to call more than once, and
+ * safe when nothing was ever attached.
+ */
+export async function disposeAgentState(state) {
+    await resetAll(state.attach, state.captures, state.liveShare);
+}

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

@@ -1,2 +1 @@
-export { buildAgentState, buildAgentTools } from './build.ts';
-export type { AgentState } from './build.ts';
+export { type AgentState, buildAgentState, buildAgentTools, disposeAgentState, } from './build.ts';

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

@@ -1,3 +1,3 @@
 // Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
 // replay, zkTLS proof). Import from here, not the individual files.
-export { buildAgentState, buildAgentTools } from "./build.js";
+export { buildAgentState, buildAgentTools, disposeAgentState, } from "./build.js";

package/lib/mcp/tools/agent/live-view.d.ts

@@ -1,14 +1,10 @@
 import { type Tunnel } from '../../../live/tunnel.ts';
-import { type LiveView } from '../../../live/viewer.ts';
 import { type RegisteredTool } from '../../server.ts';
-import type { AttachState } from './attach.ts';
-import type { CaptureStore } from './capture.ts';
+import { type AttachState } 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 {
     current?: LiveShare;
@@ -18,4 +14,4 @@ export interface LiveShareRef {
 export declare function stopLiveShare(ref: LiveShareRef): Promise<boolean>;
 export declare function liveViewTools(attachRef: {
     current?: AttachState;
-}, captures: CaptureStore, shareRef: LiveShareRef): RegisteredTool[];
+}, shareRef: LiveShareRef): RegisteredTool[];