@reclaimprotocol/agent 0.1.24 → 0.1.26

package/lib/old/tools/session-logs.js

@@ -0,0 +1,310 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { defineTool } from "../../mcp/server.js";
+import { findProjectRoot } from "../../paths.js";
+/** The log-stream service caps a page at 1000 entries however large a
+ *  `limit` asks for, so paging is the only way past it. */
+const MAX_PAGE = 1000;
+/** Inline default. Small enough to stay readable in a tool result; a bigger
+ *  pull belongs in `saveTo`. */
+const DEFAULT_LIMIT = 200;
+/** Ceiling on a `saveTo` dump, so a chatty session can't page forever. */
+const DEFAULT_MAX_ENTRIES = 20000;
+export function sessionLogsTool(client) {
+    return defineTool({
+        name: 'session_logs',
+        description: 'Fetch the raw log entries the in-app SDK emitted during a '
+            + 'verification session, each with its event type (for example '
+            + 'REQUEST_MATCHED, CLAIM_CREATION_STARTED, or PROOF_GENERATED), '
+            + 'log level, and logger name. This is the data behind the '
+            + 'dashboard session-logs tab, and it is far more detailed than '
+            + 'session_analytics_logs, which returns only the coarse milestone '
+            + 'events. Use it to diagnose a session that stalled, matched '
+            + 'nothing, or produced no claim. Narrow the result with eventType, '
+            + 'logLevel, or contains; page through it with limit and offset; or '
+            + 'set saveTo to write every matching entry to an NDJSON file and '
+            + 'read that file with your own tools. Old-devtools mode only. You '
+            + 'must own the app the session belongs to, so call '
+            + 'reclaim_authenticate first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    description: 'Id of the verification session to read log entries for.',
+                },
+                eventType: {
+                    type: 'string',
+                    description: 'Keep only entries that carry this exact event type, for '
+                        + 'example REQUEST_MATCHED or PROOF_GENERATION_FAILED_'
+                        + 'EXCEPTION. Most entries carry no event type at all, so '
+                        + 'prefer eventsOnly when you want the milestone timeline '
+                        + 'rather than guessing a name.',
+                },
+                eventsOnly: {
+                    type: 'boolean',
+                    description: 'Keep only entries that carry an event type, which gives you '
+                        + 'a compact milestone timeline for the session. This tool '
+                        + 'applies the filter after fetching, so it narrows what you '
+                        + 'read rather than what it fetches.',
+                },
+                logLevel: {
+                    type: 'string',
+                    enum: ['fine', 'config', 'info', 'warning', 'severe', 'unknown'],
+                    description: 'Lowest severity to include. Each value is hierarchical: '
+                        + '`fine` includes FINE, CONFIG, INFO, WARNING, and SEVERE; '
+                        + '`info` drops FINE and CONFIG; `severe` keeps only '
+                        + 'failures. Defaults to `fine`, which is wider than the '
+                        + 'backend default of `info`. The FINER and FINEST tiers '
+                        + 'contain PII, and this route rejects them.',
+                },
+                logType: {
+                    type: 'string',
+                    description: 'Exact client-side logger name, which the SDK calls `type` — '
+                        + 'for example reclaim_flutter_sdk.ClaimCreation. This is not '
+                        + 'the event type.',
+                },
+                contains: {
+                    type: 'string',
+                    description: 'Substring that an entry\'s log line must contain.',
+                },
+                providerId: {
+                    type: 'string',
+                    description: 'Keep only entries for this provider. A session can touch '
+                        + 'more than one provider, so this narrows within the '
+                        + 'session; it cannot search across sessions.',
+                },
+                deviceId: {
+                    type: 'string',
+                    description: 'Keep only entries for this device id, which is the claimant '
+                        + 'id.',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Keep only entries from this client build. The source string '
+                        + 'carries the SDK, platform, and version, so it is the field '
+                        + 'to compare a working run against a broken one.',
+                },
+                startTime: {
+                    type: 'string',
+                    description: 'Lower bound, as an ISO-8601 timestamp. If you set neither '
+                        + 'bound, the backend searches only the last 3 days.',
+                },
+                endTime: {
+                    type: 'string',
+                    description: 'Upper bound, as an ISO-8601 timestamp.',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Log entries per page. Defaults to ${DEFAULT_LIMIT} and is `
+                        + `capped at ${MAX_PAGE}. Ignored when you set saveTo.`,
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Entries to skip, counting back from the newest match. '
+                        + 'Ignored when you set saveTo.',
+                },
+                saveTo: {
+                    type: 'string',
+                    description: 'Path to write every matching entry to, as NDJSON: one raw '
+                        + 'entry per line, oldest first. When you set this, the tool '
+                        + 'returns a summary instead of the entries. Relative paths '
+                        + 'resolve against the project root. Use it when a session '
+                        + 'has more entries than you want to read inline.',
+                },
+                maxEntries: {
+                    type: 'number',
+                    description: 'Maximum entries a saveTo dump collects. Defaults to '
+                        + `${DEFAULT_MAX_ENTRIES}.`,
+                },
+            },
+            required: ['sessionId'],
+        },
+    }, async (args) => {
+        // The backend's own default is `info`, which silently hides every
+        // FINE and CONFIG entry — the ones that say what the interceptor
+        // actually saw. Debugging is the whole point of this tool, so widen
+        // the default here.
+        const query = {
+            logLevel: (args.logLevel ?? 'fine'),
+            logType: args.logType,
+            eventType: args.eventType,
+            providerId: args.providerId,
+            deviceId: args.deviceId,
+            source: args.source,
+            startTime: args.startTime,
+            endTime: args.endTime,
+            logLine: args.contains,
+        };
+        return args.saveTo
+            ? await dump(client, args, query, args.saveTo)
+            : await page(client, args, query);
+    });
+}
+/** One page, returned inline. */
+async function page(client, args, query) {
+    const limit = clampLimit(args.limit ?? DEFAULT_LIMIT);
+    const offset = Math.max(args.offset ?? 0, 0);
+    const res = await client.getSessionLogs(args.sessionId, {
+        ...query,
+        limit,
+        offset,
+        includeCount: true,
+    });
+    // Newest-first off the wire; a debugger reads a session forwards.
+    const chronological = [...res.data].reverse();
+    const entries = args.eventsOnly
+        ? chronological.filter(hasEvent)
+        : chronological;
+    const fetched = res.data.length;
+    const total = res.totalCount;
+    return {
+        ...summarize(args, res.failedRegions, entries, total),
+        page: {
+            limit,
+            offset,
+            fetched,
+            ...(args.eventsOnly ? { keptWithEvent: entries.length } : {}),
+            hasMore: total === undefined
+                ? fetched === limit
+                : offset + fetched < total,
+            nextOffset: offset + fetched,
+        },
+        entries: compact(entries),
+    };
+}
+/** Every match, paged out to an NDJSON file. */
+async function dump(client, args, query, saveTo) {
+    const maxEntries = Math.max(args.maxEntries ?? DEFAULT_MAX_ENTRIES, 1);
+    const all = [];
+    const failedRegions = new Set();
+    let total;
+    let offset = 0;
+    while (all.length < maxEntries) {
+        const res = await client.getSessionLogs(args.sessionId, {
+            ...query,
+            limit: Math.min(MAX_PAGE, maxEntries - all.length),
+            offset,
+            // Only the first page pays for the count; it does not move.
+            includeCount: offset === 0,
+        });
+        for (const region of res.failedRegions ?? []) {
+            failedRegions.add(region);
+        }
+        if (offset === 0) {
+            total = res.totalCount;
+        }
+        all.push(...res.data);
+        offset += res.data.length;
+        // A short page means the match set is exhausted.
+        if (!res.data.length || res.data.length < MAX_PAGE) {
+            break;
+        }
+        if (total !== undefined && offset >= total) {
+            break;
+        }
+    }
+    all.reverse();
+    const entries = args.eventsOnly ? all.filter(hasEvent) : all;
+    const path = isAbsolute(saveTo)
+        ? saveTo
+        : join(findProjectRoot(process.cwd()), saveTo);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+    return {
+        ...summarize(args, [...failedRegions], entries, total),
+        file: {
+            path,
+            format: 'ndjson',
+            entries: entries.length,
+            order: 'oldest first',
+            note: 'Each line holds one raw log entry with all of its columns: '
+                + 'timestamp, log_level, event_type, log_type, log_line, '
+                + 'session_id, app_id, provider_id, device_id, source, and '
+                + 'metadata.',
+            truncated: entries.length >= maxEntries
+                ? `Stopped at maxEntries=${maxEntries}. Narrow the filters, or `
+                    + 'raise the limit.'
+                : undefined,
+        },
+    };
+}
+/** The header both modes share: what was asked for, what came back, and the
+ *  event-type histogram — usually enough on its own to see where a session
+ *  died. */
+function summarize(args, failedRegions, entries, total) {
+    const events = {};
+    for (const entry of entries) {
+        if (entry.event_type) {
+            events[entry.event_type] = (events[entry.event_type] ?? 0) + 1;
+        }
+    }
+    return {
+        sessionId: args.sessionId,
+        context: contextOf(entries),
+        totalMatching: total,
+        span: entries.length
+            ? {
+                from: entries[0].timestamp,
+                to: entries[entries.length - 1].timestamp,
+            }
+            : undefined,
+        eventTypes: Object.keys(events).length ? events : undefined,
+        ...(failedRegions?.length
+            ? {
+                warning: 'The log-stream query failed in region '
+                    + `${failedRegions.join(', ')}, so this result is incomplete.`,
+            }
+            : {}),
+        ...(entries.length
+            ? {}
+            : {
+                hint: 'No entries matched. Check these causes in order: the '
+                    + 'search window defaults to the last 3 days, so pass startTime '
+                    + 'and endTime for an older session; the backend deletes entries '
+                    + 'after 30 days; the backend picks which regions to query from '
+                    + 'the analytics table, so a session that never recorded an '
+                    + 'analytics event reads as empty here even when entries exist; '
+                    + 'or the filters are too narrow. Cross-check with '
+                    + 'session_analytics_logs.',
+            }),
+    };
+}
+/** Fields that are identical on every entry, hoisted out so they are not
+ *  repeated hundreds of times. */
+function contextOf(entries) {
+    const uniq = (pick) => {
+        const set = new Set(entries.map(pick).filter(Boolean));
+        return [...set];
+    };
+    const one = (values) => (values.length === 1 ? values[0] : values);
+    return entries.length
+        ? {
+            appId: one(uniq(e => e.app_id)),
+            providerId: one(uniq(e => e.provider_id)),
+            deviceId: one(uniq(e => e.device_id)),
+            source: one(uniq(e => e.source)),
+        }
+        : undefined;
+}
+function compact(entries) {
+    const devices = new Set(entries.map(e => e.device_id));
+    const sources = new Set(entries.map(e => e.source));
+    return entries.map(e => ({
+        ts: e.timestamp,
+        level: e.log_level,
+        ...(e.event_type ? { event: e.event_type } : {}),
+        logger: e.log_type,
+        line: e.log_line,
+        // Only worth repeating per entry once the page actually mixes them.
+        ...(devices.size > 1 ? { device: e.device_id } : {}),
+        ...(sources.size > 1 ? { source: e.source } : {}),
+        ...(e.metadata && e.metadata !== '{}' ? { metadata: e.metadata } : {}),
+    }));
+}
+function hasEvent(entry) {
+    return !!entry.event_type;
+}
+function clampLimit(limit) {
+    return Math.min(Math.max(Math.trunc(limit), 1), MAX_PAGE);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.24",
+	"version": "0.1.26",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "0.1.24",
+		"@reclaimprotocol/client": "0.1.26",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/SKILL.common.md

@@ -22,24 +22,45 @@ already names it.
 <!-- section: browser -->
 ## Choosing a browser
 
-**Ask the developer which browser they want, then call `attach_browser` ONCE
-with their chosen `mode`.** Never pick for them, and never assume last session's
-choice still applies. You don't need a discovery call — the four options are
-spelled out in the tool's own description (and summarized below). Calling with
-no `mode` returns the same list as `needsChoice: true` + `options`, if you'd
-rather relay it verbatim.
-
-| mode | what it is | needs | live view |
+- Choosing one — ask who signs in, then offer the matching pair
+- Sharing the container's live view with someone remote
+- What happens when the session ends
+- When the container will not start
+
+**Ask one question first, before you list anything:**
+
+> Will you be doing this yourself, or does someone else need to sign in — the
+> person whose account it is, say?
+
+That answer decides half the list, and a developer can answer it without knowing
+what CDP is. Only then offer the matching pair, call `attach_browser` ONCE with
+the `mode` they pick, and never pick for them or assume last session's choice
+still applies.
+
+**They're doing it themselves** — no link, no Docker, nothing to install:
+
+| mode | what it is | needs |
+| --- | --- | --- |
+| `dedicated` | Chrome the agent launches with its own profile (`~/.reclaim/chrome-profile`), which persists, so a site stays signed in. The default choice. | nothing |
+| `attach` | The Chrome they already have open, with its tabs, extensions and logins. | `port` (default 9222) |
+
+Neither can be shared, and neither needs to be: the browser is on their screen.
+
+**Someone else has to sign in, or the site only works on a phone** — these two
+are the only modes that produce a link another person can open:
+
+| mode | what it is | needs | costs |
 | --- | --- | --- | --- |
-| `dedicated` | Local Chrome the agent launches with its own profile (`~/.reclaim/chrome-profile`). Easiest local path. | nothing | `share_browser_view` on request |
-| `attach` | A Chrome the developer is already running. | `port` (default 9222) | `share_browser_view` on request |
-| `builder` | Quota-accounted remote Popcorn browser. Only way to browse from a **specific country**. | Builder auth, `orgId` | hosted `liveViewUrl`, returned by `attach_browser` |
-| `custom` | Any CDP websocket the developer supplies. | `cdpUrl` | `share_browser_view` on request |
+| `container` | The Reclaim runtime in Docker, on their machine. `share_browser_view` turns its viewer into a public link. | Docker running | free — their Docker, their bandwidth. 432 MB the first time, about 2 GB of RAM, 7 to 17 seconds to start |
+| `builder` | A browser in Reclaim's cloud. The link comes back immediately, with nothing to install. Also the only way to browse from a **specific country**. | Builder auth, `orgId` | **chargeable** — billed against the org's quota |
 
-**Say the live-view column out loud when you offer the choice.** How the
-developer watches the browser is part of picking one, and a local browser looks
-like it can't be shared at all unless you tell them `share_browser_view`
-exists.
+**Say which one costs money.** They are otherwise interchangeable from the
+developer's point of view, so price and "do you have Docker" are the whole
+decision. Do not quietly pick the billed one.
+
+`custom` (any `ws://`/`wss://` CDP endpoint they supply) exists for someone who
+was handed an endpoint and knows why. Don't offer it unprompted; it cannot be
+shared either.
 
 **`attach` gotcha (Chrome 136+, May 2025):** the developer's Chrome must be
 started with BOTH `--remote-debugging-port=9222` AND
@@ -72,31 +93,87 @@ default profile. If `attach` fails, say this verbatim and offer `dedicated`.
 **`custom` specifics:** the `cdpUrl` is a credential — never repeat, log, or
 persist it. If a `liveViewUrl` comes back, share it full and verbatim.
 
-### Sharing a local browser (`share_browser_view`)
-
-A `dedicated`, `attach`, or `custom` browser runs on the developer's machine,
-so only they can see it. `share_browser_view` puts the tab behind a public
-HTTPS URL through a cloudflared quick tunnel — use it when the person who has
-to act is not at that machine: a login or 2FA only they can complete, or a
-colleague watching a capture.
-
-- **`builder` mode already has one.** The Popcorn browser returns a hosted
-  `liveViewUrl` from `attach_browser`; share that instead. The tool refuses
-  here rather than opening a second tunnel.
-- **The URL is a credential.** It carries an unguessable token and needs no
-  login, so whoever holds it can see the tab — and, by default, click and type
-  in it as the signed-in user. Give it to one person, and say plainly what it
-  grants.
-- **Return it verbatim, on its own line**, exactly as with `liveViewUrl`.
-- `interactive: false` streams a watch-only view. Prefer it when the developer
-  only needs to see progress.
-- **Call `stop_browser_view` as soon as they're done.** The tunnel stays open
-  until you do. `dispose_browser` and `reset_session` also close it.
+### Sharing the container's live view (`share_browser_view`)
+
+A `container` browser serves its own viewer on loopback, so the developer can
+open it the moment `attach_browser` returns. `share_browser_view` puts that same
+viewer behind a public HTTPS URL through a cloudflared quick tunnel — for when
+the person who has to act is not at that machine: a login or 2FA only they can
+complete, or a colleague watching a capture.
+
+**Offer it whenever a login is coming and the developer is not the one holding
+the credentials.** Nobody asks for a feature they have no way of knowing exists.
+Ask plainly:
+
+> Do you want a link to this browser? You can open it yourself, or send it to
+> whoever holds the login — they can watch and click in it, including from a
+> phone.
+
+If they say yes, call `share_browser_view` and **relay the full URL verbatim, on
+its own line.**
+
+- **`container` is the only mode this applies to.** `builder` returns a hosted
+  `liveViewUrl` from `attach_browser` — relay that instead, full and verbatim.
+  `dedicated`, `attach`, and `custom` have no view to share at all; if someone
+  else needs to see the browser, say so and offer `container`.
+- **The URL is the ONLY credential.** The hostname Cloudflare hands out is the
+  whole secret: there is no token and no login behind it, so whoever learns the
+  URL has the browser, as the signed-in user. Give it to one person, say plainly
+  what it grants, and stop the share when they are done rather than leaving it
+  open. Tell them the watcher sees everything typed into that browser, including
+  a password — so if the point is for the DEVELOPER to log in, they should do it
+  before you share, not after.
+- **It shows the whole browser, not one tab.** A sign-in that opens a separate
+  window is visible too.
+- **Opening it on a phone lays the page out for that phone**, with touch,
+  pinch-zoom and the soft keyboard. That is the reason to reach for `container`
+  when a site only works on mobile.
+- **Call `stop_browser_view` as soon as they're done.** That closes the tunnel
+  only — the browser keeps running. `dispose_browser` and `reset_session` stop
+  the container itself.
+- **If the URL will not load**, the tunnel may not have registered with
+  Cloudflare — the hostname exists before the route does. Have them reload after
+  10 seconds; if it still fails, `stop_browser_view` then `share_browser_view`
+  again, since a quick tunnel does occasionally fail to come up. A
+  `propagating: true` in the result is that case, and `cloudflaredLog` carries
+  the reason.
 - **cloudflared is handled for you.** An existing install on PATH wins;
-  otherwise it's fetched once into `~/.reclaim/bin` on the first share, never
-  at install time. Say so when it happens — it's a ~37 MB download onto their
+  otherwise it's fetched once into `~/.reclaim/bin` on the first share, never at
+  install time. Say so when it happens — it's a 37 MB download onto their
   machine. `RECLAIM_CLOUDFLARED_PATH` points at their own copy instead.
 
+### How containers are shared, and when they close
+
+- **Closing the agent releases the browser.** The server stops the container and
+  the tunnel when its connection drops, so a public URL never outlives the
+  session that made it. `dispose_browser` does the same on demand.
+- **Re-attaching in one session reuses the same browser** — under a second,
+  rather than the twenty a fresh one costs — so whatever it is signed into is
+  still there.
+- **A second session working at the same time gets its own container.** They
+  cannot share one: the live view streams the whole screen, so two sessions in
+  one container would see each other's browsing, and two browsers on one profile
+  corrupt the cookie jar they share. Each concurrent session therefore has its
+  own profile, and starts out signed in to nothing.
+- **Four at once is the ceiling**, because each is about 2 GB of RAM. Past that,
+  `attach_browser` says so and points at `dedicated`.
+- **A crash cannot strand one for long.** A killed session runs no cleanup, so
+  the next `container` attach removes any container whose owning process is gone.
+  One belonging to a session that is still alive is never touched.
+
+### When the container will not start
+
+- **Docker is not running.** The error says so and names the other browser
+  modes. Docker is not something you can install for them.
+- **Apple Silicon.** The image is amd64 and cannot be built for arm64, so it
+  runs translated. OrbStack does this itself; Docker Desktop needs "Use Rosetta
+  for x86/amd64 emulation" turned on. Under QEMU instead of Rosetta, Chromium
+  crashes on launch.
+- **First run looks stuck.** It is downloading 432 MB. Say that rather than
+  letting it look hung.
+- A container left over from a crashed run is **reused if it is still serving**,
+  and replaced if it is not — a second attach does not need a different port.
+
 **When a local attach errors or `waitForCdpReady` reports a dead port**, walk
 these before retrying:
 

package/skill/SKILL.old.md

@@ -37,8 +37,9 @@ workflow — the narrow `authenticate_builder` / `list_builder_organizations`
 exception exists only to allocate Builder-hosted authoring browsers.
 `get_me_providers` is the only provider-listing tool here.
 
-**Diagnosing a session:** `session_analytics_logs` fetches a verification
-session's analytics logs by id (matches, claims, failures).
+**Diagnosing a session:** `session_analytics_logs` returns a session's
+milestone events; `session_logs` returns the log entries the SDK itself
+emitted. Read both from topic `troubleshooting`.
 
 <!-- topic: auth -->
 ## Getting authenticated
@@ -357,6 +358,31 @@ breaks the page, and it's the smallest change. Only if that doesn't help, turn
 interception off entirely (`injectionType: NONE`, or omit
 `interceptorOptions`). Full checklist and remedies: topic `interception`.
 
+**A session stalled, matched nothing, or produced no claim.** Read it with
+two tools, coarse to fine. `session_analytics_logs` returns the milestone
+events for a session id — SESSION_STARTED, PROOF_GENERATION_FAILED, and so on
+— which tells you how far the session got. `session_logs` returns the log
+entries the SDK emitted, each with its event type, log level, and logger name,
+which tells you why it stopped: the request it intercepted, the match or
+redaction that failed, and what the attestor answered. Work through it in this
+order:
+
+1. Call `session_analytics_logs({ sessionId })` to place the failure on the
+   timeline.
+2. Call `session_logs({ sessionId, eventsOnly: true })` for the same timeline
+   at entry level, then drop `eventsOnly` and add `contains` or `eventType` to
+   read around the entry that failed.
+3. To compare a working run against a broken one, filter by `source` — it
+   carries the SDK, platform, and version, which is usually the variable that
+   differs.
+
+Two defaults decide whether you see anything: the backend searches only the
+last 3 days unless you pass `startTime` and `endTime`, and it deletes entries
+after 30 days. An empty result is more often one of those than a genuinely
+silent session, so read the `hint` the tool returns before concluding
+anything. When a session is too large to read inline, pass `saveTo` to write
+every entry to an NDJSON file and grep that file instead.
+
 **Proof failures / attestor errors** → topic `prove`.
 **Browser won't launch or attach** → topic `browser`.
 **Missing signing key** → topic `credentials`.

package/skill/builder-mode.md

@@ -18,15 +18,17 @@ device-pairing `code` + `attachUrl` — give the user the URL, then poll
 `authenticate({ code })` until LINKED. Tokens cache ~2 days.
 (→ `how_it_works({ topic: "auth" })`)
 
-**Browser choice is the developer's, and so is watching it.** `attach_browser`
-advertises all four sources in its own description — relay them, including each
-one's live-view line. A `builder` browser returns a hosted `liveViewUrl`; a
-local or custom CDP browser is private until you call `share_browser_view`,
-which tunnels a public URL with cloudflared. Say that option exists: nobody
-guesses it.
+**Ask who is doing the signing in, then offer a browser.** "Yourself, or does
+someone else need to log in?" decides half of `attach_browser`'s list. Doing it
+themselves → `dedicated` or `attach`, both local, neither shareable. Someone
+else, or a phone-only site → `container` (the Reclaim runtime in Docker, free,
+shareable with `share_browser_view`) or `builder` (hosted, no install,
+**chargeable**). Say which costs money, and say `container` exists at all:
+nobody guesses it.
 
 **The flow:** `attach_browser` (ask the developer which browser source — local
-Chrome, a CDP URL they supply, or a remote Builder browser) → `start_capture`
+Chrome, the Reclaim runtime in Docker, a remote Builder browser, or a CDP URL
+they supply) → `start_capture`
 ⇒ **`captureId`** (the handle every browser/inspect tool takes first) → drive
 the page (`navigate`, `wait_for_page`, `eval_in_page`, `get_cookies`) → inspect
 (`list_requests`, `get_request`, `find_requests_containing`) →

package/skill/interception.md

@@ -96,7 +96,7 @@ to detect and nothing to disable — and `builder` never delivers intercepted
 traffic to the page at all (topic `user-script`). A verification on those that
 won't load or won't sign in is almost always a CAPTCHA or bot challenge
 instead: check `analyze_request_constraints` for a `botChallenge` concern, and
-treat it as a site that needs a human through the live view rather than a
+treat it as a site that needs a human through a live view rather than a
 provider to fix.
 
 ### Then bisect, cheapest change first
@@ -232,4 +232,5 @@ oversight.
   `window.Reclaim` is inert on Builder's own client.
 - `hash-validation` — declaring script-fired requests without breaking
   `verifyProof({ providerId })`.
-- `browser` — live view, for handing a stuck sign-in to a human.
+- `browser` — the modes with a live view (`container`, `builder`), for handing
+  a stuck sign-in to a human.

package/skill/old-mode.md

@@ -12,16 +12,18 @@ topic at a time — call `how_it_works({})` for the topic index. Topics:
 `user-script`, `interception`, `hash-validation`, `credentials`, `never-do`,
 `troubleshooting`.
 
-**Browser choice is the developer's, and so is watching it.** `attach_browser`
-advertises all four sources in its own description — relay them, including each
-one's live-view line. A `builder` browser returns a hosted `liveViewUrl`; a
-local or custom CDP browser is private until you call `share_browser_view`,
-which tunnels a public URL with cloudflared. Say that option exists: nobody
-guesses it.
+**Ask who is doing the signing in, then offer a browser.** "Yourself, or does
+someone else need to log in?" decides half of `attach_browser`'s list. Doing it
+themselves → `dedicated` or `attach`, both local, neither shareable. Someone
+else, or a phone-only site → `container` (the Reclaim runtime in Docker, free,
+shareable with `share_browser_view`) or `builder` (hosted, no install,
+**chargeable**). Say which costs money, and say `container` exists at all:
+nobody guesses it.
 
 **The flow:** `reclaim_authenticate` once → `attach_browser` (ask the developer
-which browser source — local Chrome, a CDP URL they supply, or a remote Builder
-browser) → `start_capture` ⇒ **`captureId`** → drive the page (`navigate`,
+which browser source — local Chrome, the Reclaim runtime in Docker, a remote
+Builder browser, or a CDP URL they supply) → `start_capture` ⇒ **`captureId`** →
+drive the page (`navigate`,
 `wait_for_page`, `eval_in_page`) → inspect (`list_requests`, `get_request`,
 `find_requests_containing`) → `propose_provider` ⇒ **`draftId`** →
 `replay_request(captureId, draftId)` → `run_proof(captureId, draftId,
@@ -50,8 +52,10 @@ and the proof binds to nobody — find an auth-bound request instead.
 Values the CONSUMER supplies at verification time use `{{context_<name>}}` —
 this backend does NOT support the builder's dotted `{{context.<name>}}` form.
 
-**Diagnosing a session:** `session_analytics_logs` fetches a verification
-session's analytics logs by id (matches, claims, failures).
+**Diagnosing a session:** `session_analytics_logs` returns a session's
+milestone events; `session_logs` returns the log entries the SDK emitted, each
+with its event type — that is where a failed match, redaction, or claim shows
+up. Both take a `sessionId`; see topic `troubleshooting` for how to read them.
 
 **Backend mode:** the BUILDER backend (generated API tools, orgs, verification
 sessions, public review) is one switch away. `get_devtools_mode` reports the