@reclaimprotocol/agent 0.1.23 → 0.1.25

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

@@ -1,36 +1,180 @@
 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
+ * the tool list, without a discovery round-trip) and returned verbatim as
+ * structured `options` when the tool is called without a `mode` anyway.
+ *
+ * Being the single source for both is the point — an option list that a model
+ * reads in the description but that disagrees with what the tool returns is
+ * worse than either alone.
+ *
+ * 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. 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: 'None, and none needed — the browser is on your screen.',
+    },
+    {
+        mode: 'attach',
+        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: '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',
+        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 to pass on; '
+            + 'share_browser_view does not apply.',
+    },
+    {
+        mode: 'custom',
+        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: 'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
+    },
+];
+/**
+ * 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() {
+    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('; ')}.`
+            : '';
+        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, name = 'attach_browser', 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,
-        description: 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). '
-                + 'For builder mode, orgId may be omitted: it auto-resolves to '
-                + 'the account\'s only organization, or — if there is more '
-                + 'than one — returns needsChoice with the full list so the '
-                + 'caller can ask the developer which to use and re-call with '
-                + 'that orgId. '
-                + 'Builder and custom CDP credentials are held in memory and never '
-                + 'returned.',
+        name: 'attach_browser',
+        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" }).',
         inputSchema: {
             type: 'object',
             properties: {
                 mode: {
                     type: 'string',
-                    enum: ['dedicated', 'attach', 'builder', 'custom'],
+                    enum: [
+                        'dedicated', 'attach', 'container', 'builder', 'custom',
+                    ],
                 },
                 attachMode: {
                     type: 'string',
@@ -41,19 +185,54 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
                 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}$',
+                    description: 'Builder mode only. ISO 3166-1 alpha-2 country the remote '
+                        + 'browser browses from, fixed for the whole session. Omit to '
+                        + 'get a suggested country back (needsChoice) instead of '
+                        + 'allocating a browser.',
+                },
+                skipCountry: {
+                    type: 'boolean',
+                    description: 'Builder mode only. Allocate without geo-routing, skipping '
+                        + 'the country prompt. Pass this once the developer has said '
+                        + 'they don\'t need a specific country.',
+                },
             },
         },
     }, async (parsed) => {
         const persisted = state.config.read()?.browser_agent;
-        const mode = parsed.mode ?? parsed.attachMode ?? persisted?.attachMode;
+        // Deliberately NOT falling back to the persisted mode: which browser
+        // to drive is the developer's call every time (a remote one costs
+        // quota, a local one exposes their own profile), and silently reusing
+        // last session's answer takes that decision away from them. The
+        // persisted choice is offered back as a default to suggest, not
+        // applied.
+        const mode = parsed.mode ?? parsed.attachMode;
         if (!mode) {
             return {
                 needsChoice: true,
-                message: '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.',
+                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 }
+                    : {}),
                 configPath: defaultConfigPath(),
             };
         }
@@ -80,7 +259,45 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
             }
             orgId = orgs[0].id;
         }
-        const next = await connect(mode, { ...parsed, orgId }, persisted, builderClient, dependencies);
+        // A remote browser's exit country is fixed for the whole session —
+        // Popcorn applies it at allocation and it can't be changed later. So
+        // confirm it with the developer BEFORE spending a quota-accounted
+        // browser on the wrong one, the same way orgId is confirmed above.
+        // Geo-routing is OPTIONAL though, so this asks rather than demands:
+        // `skipCountry` is the "no particular country" answer, and it must be
+        // as reachable as naming one.
+        if (mode === 'builder' && !parsed.countryCode && !parsed.skipCountry) {
+            const suggestion = await suggestCountryFromIp();
+            return {
+                needsChoice: true,
+                message: 'Ask the developer which country this browser should browse '
+                    + 'from — its egress is routed through that country for the '
+                    + 'whole session and cannot be changed afterwards. Geolocation '
+                    + 'is optional; offer all three answers below. Nothing has been '
+                    + 'allocated yet, so this costs nothing.',
+                choices: [
+                    {
+                        answer: 'The suggested country',
+                        howToCall: `attach_browser({ mode: "builder", countryCode: "${suggestion.countryCode}" })`,
+                    },
+                    {
+                        answer: 'A specific country the site must be seen from',
+                        howToCall: 'attach_browser({ mode: "builder", countryCode: "<ISO '
+                            + '3166-1 alpha-2>" })',
+                    },
+                    {
+                        answer: 'No particular country',
+                        howToCall: 'attach_browser({ mode: "builder", skipCountry: true })',
+                    },
+                ],
+                suggestedCountryCode: suggestion.countryCode,
+                suggestionSource: 'caller-ip',
+                ...(suggestion.country ? { country: suggestion.country } : {}),
+                ...(suggestion.region ? { region: suggestion.region } : {}),
+                ...(suggestion.city ? { city: suggestion.city } : {}),
+            };
+        }
+        const next = await connect(mode, { ...parsed, orgId }, persisted, builderClient, deps);
         try {
             await beforeReplace?.();
             await disposeAttached(state);
@@ -95,6 +312,11 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
                 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,
@@ -103,6 +325,38 @@ export function attachTool(state, builderClient, name = 'attach_browser', before
                 ? { browserSessionId: next.browserSessionId }
                 : {}),
             ...(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.']
+                    : []),
+            ],
         };
     });
 }
@@ -118,8 +372,10 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
     if (mode === 'builder') {
         assert(builderClient, badRequest('Builder browser service is unavailable'));
         assert(parsed.orgId, badRequest('orgId is required for builder mode'));
+        const countryCode = parsed.countryCode?.trim().toUpperCase();
         const { data } = await builderClient.call('CreateAgentBrowserSession', {
             params: { orgId: parsed.orgId },
+            body: countryCode ? { countryCode } : {},
         });
         let handles;
         try {
@@ -140,6 +396,8 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
             liveViewUrl: data.liveViewUrl,
             browserSessionId: data.id,
             orgId: parsed.orgId,
+            ...(data.apiUrl ? { apiUrl: data.apiUrl } : {}),
+            ...(countryCode ? { countryCode } : {}),
             disposeRemote: async () => {
                 await builderClient.call('DisposeAgentBrowserSession', {
                     params: {
@@ -160,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

@@ -14,23 +14,33 @@ import { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
 import { type AttachState } from './attach.ts';
 import { type CaptureStore } from './capture.ts';
+import { type LiveShareRef } from './live-view.ts';
 export interface AgentState {
     attach: {
         current?: AttachState;
         config: ConfigStore;
     };
     captures: CaptureStore;
+    /** The one public live view, when `share_browser_view` has opened it. */
+    liveShare: LiveShareRef;
 }
-/** 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). */
+/** 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
+ *  instance with `buildAgentTools` — letting that publish tool see the live
+ *  attach state (for example, to remind the caller about a still-open browser
+ *  session). */
 export declare function buildAgentState(): AgentState;
 /** Build the flat list of `RegisteredTool` entries, ready for
  *  `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.
- *  Pass `externalState` to share attach/capture state with tools registered
- *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+ *  omit it (for example, OLD-devtools mode) to register only the
+ *  backend-independent capture/proof tools — old mode supplies its own publish
+ *  tool. Pass `externalState` to share attach/capture state with tools
+ *  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

@@ -16,26 +16,31 @@ import { attachTool } from "./attach.js";
 import { captureTools, resetCaptures } from "./capture.js";
 import { listTabsTool } from "./eval.js";
 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 (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). */
+/** 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
+ *  instance with `buildAgentTools` — letting that publish tool see the live
+ *  attach state (for example, to remind the caller about a still-open browser
+ *  session). */
 export function buildAgentState() {
     return {
         attach: { config: new ConfigStore() },
         captures: { sessions: new Map() },
+        liveShare: {},
     };
 }
 /** Build the flat list of `RegisteredTool` entries, ready for
  *  `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.
- *  Pass `externalState` to share attach/capture state with tools registered
- *  elsewhere (e.g. old mode's publish tool) instead of building a fresh one. */
+ *  omit it (for example, OLD-devtools mode) to register only the
+ *  backend-independent capture/proof tools — old mode supplies its own publish
+ *  tool. Pass `externalState` to share attach/capture state with tools
+ *  registered elsewhere (for example, old mode's publish tool) instead of
+ *  building a fresh one. */
 export function buildAgentTools(client, builderClient = client, externalState) {
     const state = externalState ?? buildAgentState();
     ensureAttestorCrypto();
@@ -44,13 +49,19 @@ export function buildAgentTools(client, builderClient = client, externalState) {
     // client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
     tools.push(howItWorksTool(!client));
     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(attachTool(state.attach, builderClient, beforeReplace));
     tools.push(listTabsTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {
         tools.push(t);
     }
-    for (const t of sessionTools(state.attach, state.captures)) {
+    for (const t of sessionTools(state.attach, state.captures, state.liveShare)) {
+        tools.push(t);
+    }
+    // Local-CDP only: a builder-mode browser already has a hosted live view.
+    for (const t of liveViewTools(state.attach, state.liveShare)) {
+        tools.push(t);
+    }
+    for (const t of podProofTools(state.attach, state.captures)) {
         tools.push(t);
     }
     tools.push(analyzeTool(state.captures));
@@ -65,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/capture.js

@@ -54,7 +54,11 @@ export function captureTools(attachRef, captures) {
     });
     const getTool = defineTool({
         name: 'get_request',
-        description: 'Return full headers + bodies for a specific captured request.',
+        description: 'Return the full headers and bodies of one captured request. Use it '
+            + 'to inspect a candidate that find_requests_containing ranked. '
+            + 'Unlike every other tool here, the headers are RAW — cookie and '
+            + 'authorization values are visible. Read them; never repeat them to '
+            + 'the developer or write them to a file.',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -5,7 +5,9 @@ import { defineTool } from "../../server.js";
 export function listTabsTool(attachRef) {
     return defineTool({
         name: 'list_tabs',
-        description: 'List open Chrome tabs.',
+        description: 'List the open tabs in the attached browser, with their tabId, title '
+            + 'and URL. Call it after attach_browser to pick the tabId to pass to '
+            + 'start_capture.',
         inputSchema: { type: 'object', properties: {} },
     }, async () => {
         if (!attachRef.current) {

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

@@ -15,9 +15,10 @@ export function findTool(resolveBackend) {
             + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
             + 'the matched variant, score, and a short snippet — used to locate '
             + 'the request that returns a target. Also finds SPLIT matches: when '
-            + '`value` is multi-word (e.g. a full name), a response that carries '
-            + 'every word SEPARATELY (a JSON profile API with first/last name in '
-            + 'distinct fields) is returned with `splitMatch:true` — prove those '
+            + '`value` is multi-word (for example, a full name), a response '
+            + 'that carries every word SEPARATELY (a JSON profile API with '
+            + 'first and last name in distinct fields) is returned with '
+            + '`splitMatch:true` — prove those '
             + 'per-field (a redaction per part) rather than as one string. '
             + 'Server-side; bodies stay here.',
         inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
@@ -60,8 +61,8 @@ export function findTool(resolveBackend) {
                 });
                 continue;
             }
-            // Split match: every word present separately (e.g. first/last name
-            // in distinct JSON fields). Requires ≥2 tokens so it's specific.
+            // Split match: every word present separately (for example, first/last
+            // name in distinct JSON fields). Requires ≥2 tokens so it's specific.
             if (tokens.length >= 2 && tokens.every((t) => body.includes(t))) {
                 ranked.push({
                     ...publicRequest(r),

package/lib/mcp/tools/agent/how-it-works.d.ts

@@ -1,11 +1,19 @@
 import { type RegisteredTool } from '../../server.ts';
 /**
- * Serves the full provider-authoring guide on demand. The MCP server's
- * always-on `instructions` are a terse tool-flow reference; this tool returns
- * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
- * 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_browser`.
+ * Serves the provider-authoring guide on demand, ONE TOPIC AT A TIME. The
+ * server's always-on `instructions` are a terse tool-flow reference; this tool
+ * is the deep version, so any MCP client — not just Claude Code, which alone
+ * auto-loads skills — can pull it.
+ *
+ * Topic-scoped rather than all-at-once because the full guide is ~7k tokens:
+ * paying that to answer "how do I mark a header secret?" crowds out the actual
+ * task, which is exactly what makes an agent slow and prone to inventing
+ * details. Every response carries the topic index, so a caller that guessed
+ * wrong (or called with no topic at all) always learns what else is available
+ * without a second round-trip.
+ *
+ * `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_browser`.
  */
 export declare function howItWorksTool(oldMode: boolean): RegisteredTool;