@reclaimprotocol/agent 0.1.25 → 0.1.26

package/README.md

@@ -113,6 +113,8 @@ The MCP server targets one of two backends, selected by `USE_OLD_DEVTOOLS`:
   - `reclaim_authenticate` — by default opens the dashboard in Chrome via CDP, waits for sign-in, reads the Firebase token from page storage, and closes the tab (or pass a `token` / `ethAddress` to skip the browser).
   - `create_provider_version_from_capture` — registers a new provider, or adds a version to an existing one when given a `providerId`.
   - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
+  - `session_analytics_logs` — the milestone events for a verification session, which show how far it got.
+  - `session_logs` — the log entries the in-app SDK emitted during that session, each with its event type, log level, and logger name. Filter by event type, level, or substring, page with `limit` and `offset`, or set `saveTo` to write every matching entry to an NDJSON file. The backend searches only the last 3 days unless you pass `startTime` and `endTime`, and it deletes entries after 30 days.
 - **Builder (`USE_OLD_DEVTOOLS=false`).** Registers the auto-generated HTTP-API tools plus the authentication/credential tools (`authenticate` device-pairing login, `issue_credentials` / `import_credentials` to set up the local eth proof-owner key, `resolve_owner_key`) and a verification-result helper (`get_verification_result`).
 
 Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotocol.org`), `RECLAIM_OLD_API_TOKEN` / `RECLAIM_OLD_ETH_UID` (headless identity), `RECLAIM_OLD_LOGIN_URL` (default `https://dev.reclaimprotocol.org`); builder mode uses `RECLAIM_API_URL` / `RECLAIM_API_TOKEN`.

package/lib/old/client.d.ts

@@ -94,6 +94,70 @@ export interface LinkNonce {
     nonce: string;
     expiresInSeconds: number;
 }
+/** Log-level filter accepted by the devtools backend's session-logs route.
+ *  It validates against this exact list and rejects anything else with a 400,
+ *  including the comma-separated lists the log-stream service itself would
+ *  accept. Each value is hierarchical at the log-stream end: `fine` means
+ *  FINE+CONFIG+INFO+WARNING+SEVERE, `info` means INFO+WARNING+SEVERE, and so
+ *  on. `finer`/`finest` (the PII tiers) are not reachable through this route
+ *  at all. */
+export type SessionLogLevel = 'fine' | 'config' | 'info' | 'warning' | 'severe' | 'unknown';
+/** Filters for {@link ReclaimOldClient.getSessionLogs}. Every one is optional
+ *  and forwarded verbatim; the session id itself is the route's path param, so
+ *  `providerId`/`deviceId` narrow WITHIN one session rather than searching
+ *  across sessions. */
+export interface SessionLogsQuery {
+    deviceId?: string;
+    source?: string;
+    /** The client-side logger NAME (log-stream's `log_type` column, the SDK's
+     *  `LogEntry.type`) — not the event type. */
+    logType?: string;
+    logLevel?: SessionLogLevel;
+    providerId?: string;
+    /** ISO-8601. Omitting BOTH bounds makes the log-stream service default to
+     *  the last 3 days. */
+    startTime?: string;
+    endTime?: string;
+    /** Substring match against the log line (`LIKE %…%`). */
+    logLine?: string;
+    /** Exact `LogEventType` name, for example `REQUEST_MATCHED`. */
+    eventType?: string;
+    /** Capped at 1000 by the log-stream service. */
+    limit?: number;
+    offset?: number;
+    includeCount?: boolean;
+}
+/** One raw log line, in the log-stream service's snake_case ClickHouse shape,
+ *  passed through unchanged by the devtools backend. `event_type` is the SDK's
+ *  `LogEventType` milestone marker (`REQUEST_MATCHED`,
+ *  `CLAIM_CREATION_STARTED`, `PROOF_GENERATED`, …); it is `''` on the majority
+ *  of lines, which carry no event. */
+export interface SessionLogRow {
+    timestamp: string;
+    request_id: string;
+    session_id: string;
+    device_id: string;
+    source: string;
+    app_id: string;
+    provider_id: string;
+    log_type: string;
+    log_level: string;
+    log_line: string;
+    event_type?: string;
+    metadata?: string;
+}
+/** `GET /api/logger/:sessionId`'s `data` envelope. The backend queries every
+ *  region that holds the session, concatenates the pages, sorts them
+ *  newest-first and re-slices to `limit`, so `data` is one page and
+ *  `totalCount` is the match count across all of them. */
+export interface SessionLogsPage {
+    data: SessionLogRow[];
+    count: number;
+    totalCount?: number;
+    /** Regions whose log-stream query failed — the page is INCOMPLETE when
+     *  this is present. */
+    failedRegions?: string[];
+}
 /**
  * Minimal REST client for the OLD devtools Express backend (base `/api`).
  * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
@@ -133,6 +197,25 @@ export declare class ReclaimOldClient {
      *  `#request`). Attaches the caller identity when one is set; queried
      *  anonymously otherwise. */
     getSessionAnalyticsLogs(sessionId: string): Promise<unknown>;
+    /**
+     * Raw log LINES for a verification session — the SDK's own diagnostic
+     * logging, the thing the dashboard's session "logs" tab renders, and a
+     * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+     *
+     * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+     * analytics-logs host — hence `#request`, and hence the same identity and
+     * ownership rules as every other authed call here: the session's app must
+     * be one you created (admins excepted), or the route 404s.
+     *
+     * The backend fans the query out to the per-region log-stream services,
+     * which read the ClickHouse `logs` table. Two defaults applied down there
+     * bite hard if you don't override them:
+     *   - no `startTime`/`endTime` → only the last 3 days are searched;
+     *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+     *     invisible.
+     * Entries are dropped entirely after 30 days (table TTL).
+     */
+    getSessionLogs(sessionId: string, query?: SessionLogsQuery): Promise<SessionLogsPage>;
     /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
      *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
      *  use it as-is within the sandbox session limit. */

package/lib/old/client.js

@@ -89,6 +89,52 @@ export class ReclaimOldClient {
         }
         return json;
     }
+    /**
+     * Raw log LINES for a verification session — the SDK's own diagnostic
+     * logging, the thing the dashboard's session "logs" tab renders, and a
+     * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+     *
+     * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+     * analytics-logs host — hence `#request`, and hence the same identity and
+     * ownership rules as every other authed call here: the session's app must
+     * be one you created (admins excepted), or the route 404s.
+     *
+     * The backend fans the query out to the per-region log-stream services,
+     * which read the ClickHouse `logs` table. Two defaults applied down there
+     * bite hard if you don't override them:
+     *   - no `startTime`/`endTime` → only the last 3 days are searched;
+     *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+     *     invisible.
+     * Entries are dropped entirely after 30 days (table TTL).
+     */
+    async getSessionLogs(sessionId, query = {}) {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/logger/${encodeURIComponent(sessionId)}`, {
+            auth: true,
+            query: {
+                deviceId: query.deviceId,
+                source: query.source,
+                logType: query.logType,
+                logLevel: query.logLevel,
+                providerId: query.providerId,
+                startTime: query.startTime,
+                endTime: query.endTime,
+                logLine: query.logLine,
+                eventType: query.eventType,
+                limit: query.limit,
+                offset: query.offset,
+                includeCount: query.includeCount === undefined
+                    ? undefined
+                    : String(query.includeCount),
+            },
+        });
+        const page = res.data;
+        return {
+            data: page?.data ?? [],
+            count: page?.count ?? page?.data?.length ?? 0,
+            totalCount: page?.totalCount,
+            failedRegions: page?.failedRegions,
+        };
+    }
     /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
      *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
      *  use it as-is within the sandbox session limit. */

package/lib/old/tools/build.js

@@ -8,6 +8,7 @@ import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { scaffoldDemoServerTool } from "./scaffold-demo-server.js";
 import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
+import { sessionLogsTool } from "./session-logs.js";
 import { updateProviderMetadataTool } from "./update-provider-metadata.js";
 import { verifySdkSetupTool } from "./verify-sdk-setup.js";
 /**
@@ -32,6 +33,7 @@ export function buildOldBackendTools(client, sdkClient, attachRef) {
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),
         sessionAnalyticsLogsTool(client),
+        sessionLogsTool(client),
         issueAppCredentialsTool(client),
         linkAppTool(client),
         checkAppStatusTool(client),

package/lib/old/tools/session-logs.d.ts

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+export declare function sessionLogsTool(client: ReclaimOldClient): RegisteredTool;

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.25",
+	"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.25",
+		"@reclaimprotocol/client": "0.1.26",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

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/old-mode.md

@@ -52,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

package/src/old/client.ts

@@ -99,6 +99,80 @@ export interface LinkNonce {
 	expiresInSeconds: number
 }
 
+/** Log-level filter accepted by the devtools backend's session-logs route.
+ *  It validates against this exact list and rejects anything else with a 400,
+ *  including the comma-separated lists the log-stream service itself would
+ *  accept. Each value is hierarchical at the log-stream end: `fine` means
+ *  FINE+CONFIG+INFO+WARNING+SEVERE, `info` means INFO+WARNING+SEVERE, and so
+ *  on. `finer`/`finest` (the PII tiers) are not reachable through this route
+ *  at all. */
+export type SessionLogLevel =
+	| 'fine'
+	| 'config'
+	| 'info'
+	| 'warning'
+	| 'severe'
+	| 'unknown'
+
+/** Filters for {@link ReclaimOldClient.getSessionLogs}. Every one is optional
+ *  and forwarded verbatim; the session id itself is the route's path param, so
+ *  `providerId`/`deviceId` narrow WITHIN one session rather than searching
+ *  across sessions. */
+export interface SessionLogsQuery {
+	deviceId?: string
+	source?: string
+	/** The client-side logger NAME (log-stream's `log_type` column, the SDK's
+	 *  `LogEntry.type`) — not the event type. */
+	logType?: string
+	logLevel?: SessionLogLevel
+	providerId?: string
+	/** ISO-8601. Omitting BOTH bounds makes the log-stream service default to
+	 *  the last 3 days. */
+	startTime?: string
+	endTime?: string
+	/** Substring match against the log line (`LIKE %…%`). */
+	logLine?: string
+	/** Exact `LogEventType` name, for example `REQUEST_MATCHED`. */
+	eventType?: string
+	/** Capped at 1000 by the log-stream service. */
+	limit?: number
+	offset?: number
+	includeCount?: boolean
+}
+
+/** One raw log line, in the log-stream service's snake_case ClickHouse shape,
+ *  passed through unchanged by the devtools backend. `event_type` is the SDK's
+ *  `LogEventType` milestone marker (`REQUEST_MATCHED`,
+ *  `CLAIM_CREATION_STARTED`, `PROOF_GENERATED`, …); it is `''` on the majority
+ *  of lines, which carry no event. */
+export interface SessionLogRow {
+	timestamp: string
+	request_id: string
+	session_id: string
+	device_id: string
+	source: string
+	app_id: string
+	provider_id: string
+	log_type: string
+	log_level: string
+	log_line: string
+	event_type?: string
+	metadata?: string
+}
+
+/** `GET /api/logger/:sessionId`'s `data` envelope. The backend queries every
+ *  region that holds the session, concatenates the pages, sorts them
+ *  newest-first and re-slices to `limit`, so `data` is one page and
+ *  `totalCount` is the match count across all of them. */
+export interface SessionLogsPage {
+	data: SessionLogRow[]
+	count: number
+	totalCount?: number
+	/** Regions whose log-stream query failed — the page is INCOMPLETE when
+	 *  this is present. */
+	failedRegions?: string[]
+}
+
 interface RequestOpts {
 	query?: Record<string, string | number | undefined>
 	body?: unknown
@@ -212,6 +286,60 @@ export class ReclaimOldClient {
 		return json
 	}
 
+	/**
+	 * Raw log LINES for a verification session — the SDK's own diagnostic
+	 * logging, the thing the dashboard's session "logs" tab renders, and a
+	 * strictly richer signal than `getSessionAnalyticsLogs`'s milestone events.
+	 *
+	 * This is the devtools backend (`GET /api/logger/:sessionId`), NOT the
+	 * analytics-logs host — hence `#request`, and hence the same identity and
+	 * ownership rules as every other authed call here: the session's app must
+	 * be one you created (admins excepted), or the route 404s.
+	 *
+	 * The backend fans the query out to the per-region log-stream services,
+	 * which read the ClickHouse `logs` table. Two defaults applied down there
+	 * bite hard if you don't override them:
+	 *   - no `startTime`/`endTime` → only the last 3 days are searched;
+	 *   - no `logLevel` → INFO and above only, so every FINE/CONFIG line is
+	 *     invisible.
+	 * Entries are dropped entirely after 30 days (table TTL).
+	 */
+	async getSessionLogs(
+		sessionId: string,
+		query: SessionLogsQuery = {},
+	): Promise<SessionLogsPage> {
+		const res = await this.#request(
+			'GET',
+			`/logger/${encodeURIComponent(sessionId)}`,
+			{
+				auth: true,
+				query: {
+					deviceId: query.deviceId,
+					source: query.source,
+					logType: query.logType,
+					logLevel: query.logLevel,
+					providerId: query.providerId,
+					startTime: query.startTime,
+					endTime: query.endTime,
+					logLine: query.logLine,
+					eventType: query.eventType,
+					limit: query.limit,
+					offset: query.offset,
+					includeCount: query.includeCount === undefined
+						? undefined
+						: String(query.includeCount),
+				},
+			},
+		)
+		const page = (res as { data?: Partial<SessionLogsPage> }).data
+		return {
+			data: page?.data ?? [],
+			count: page?.count ?? page?.data?.length ?? 0,
+			totalCount: page?.totalCount,
+			failedRegions: page?.failedRegions,
+		}
+	}
+
 	/** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
 	 *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
 	 *  use it as-is within the sandbox session limit. */

package/src/old/tools/build.ts

@@ -12,6 +12,7 @@ import { getMeProvidersTool } from './me-providers.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
 import { scaffoldDemoServerTool } from './scaffold-demo-server.ts'
 import { sessionAnalyticsLogsTool } from './session-analytics-logs.ts'
+import { sessionLogsTool } from './session-logs.ts'
 import { updateProviderMetadataTool } from './update-provider-metadata.ts'
 import { verifySdkSetupTool } from './verify-sdk-setup.ts'
 
@@ -41,6 +42,7 @@ export function buildOldBackendTools(
 		getProviderInfoTool(sdkClient),
 		updateProviderMetadataTool(client),
 		sessionAnalyticsLogsTool(client),
+		sessionLogsTool(client),
 		issueAppCredentialsTool(client),
 		linkAppTool(client),
 		checkAppStatusTool(client),

package/src/old/tools/session-logs.ts

@@ -0,0 +1,395 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import { findProjectRoot } from '../../paths.ts'
+import type {
+	ReclaimOldClient,
+	SessionLogRow,
+	SessionLogsQuery,
+} from '../client.ts'
+
+/** 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 = 20_000
+
+interface Args extends SessionLogsQuery {
+	sessionId: string
+	/** Substring match on the log line — `logLine` under its dashboard name. */
+	contains?: string
+	/** Keep only entries that carry an `event_type`. Applied here rather than
+	 *  server-side: the devtools route has no `eventTypeOnly` passthrough. */
+	eventsOnly?: boolean
+	saveTo?: string
+	maxEntries?: number
+}
+
+/** An entry's fields minus the ones hoisted into `context`. `event` and
+ *  `metadata` drop out when empty; `device` and `source` appear only on an
+ *  entry that disagrees with a single-valued context. */
+interface CompactEntry {
+	ts: string
+	level: string
+	event?: string
+	logger: string
+	line: string
+	device?: string
+	source?: string
+	metadata?: string
+}
+
+export function sessionLogsTool(client: ReclaimOldClient): RegisteredTool {
+	return defineTool<Args>(
+		{
+			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: SessionLogsQuery = {
+				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: ReclaimOldClient,
+	args: Args,
+	query: SessionLogsQuery,
+) {
+	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: ReclaimOldClient,
+	args: Args,
+	query: SessionLogsQuery,
+	saveTo: string,
+) {
+	const maxEntries = Math.max(args.maxEntries ?? DEFAULT_MAX_ENTRIES, 1)
+	const all: SessionLogRow[] = []
+	const failedRegions = new Set<string>()
+	let total: number | undefined
+	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: Args,
+	failedRegions: string[] | undefined,
+	entries: SessionLogRow[],
+	total: number | undefined,
+) {
+	const events: Record<string, number> = {}
+	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: SessionLogRow[]) {
+	const uniq = (pick: (entry: SessionLogRow) => string | undefined) => {
+		const set = new Set(entries.map(pick).filter(Boolean) as string[])
+		return [...set]
+	}
+
+	const one = (values: string[]) => (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: SessionLogRow[]): CompactEntry[] {
+	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: SessionLogRow): boolean {
+	return !!entry.event_type
+}
+
+function clampLimit(limit: number): number {
+	return Math.min(Math.max(Math.trunc(limit), 1), MAX_PAGE)
+}