@reclaimprotocol/agent 0.1.22 → 0.1.24

package/lib/live/tunnel.js

@@ -0,0 +1,120 @@
+/**
+ * Public HTTPS front door for the local live-view server, via a `cloudflared`
+ * quick tunnel.
+ *
+ * A quick tunnel needs no Cloudflare account and no DNS: `cloudflared` dials
+ * out, Cloudflare hands back a throwaway `*.trycloudflare.com` hostname, and
+ * traffic arrives on the loopback port we pass in. That is the whole reason it
+ * is used here — the developer's machine keeps no inbound port open.
+ *
+ * The tunnel itself carries NO authorization. Anyone holding the hostname can
+ * reach the local server, so the server is the thing that must authenticate
+ * (see `viewer.ts`, which puts an unguessable token in every path).
+ */
+import { spawn } from 'node:child_process';
+import { LOGGER } from "../logger.js";
+import { resolveCloudflared } from "./cloudflared.js";
+/** How long to wait for cloudflared to report its hostname before giving up. */
+const URL_TIMEOUT_MS = 30000;
+/** After the hostname is printed, Cloudflare needs a moment before the edge
+ *  routes to it — measured at ~3s. Poll until it answers so the caller never
+ *  hands out a URL that errors, but don't fail the share if it's slow. */
+const READY_TIMEOUT_MS = 20000;
+const READY_POLL_MS = 1000;
+/** `https://<something>.trycloudflare.com`, as printed on cloudflared's log
+ *  stream. Anchored to the scheme so a hostname inside prose can't match. */
+const QUICK_TUNNEL_URL = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+/**
+ * Poll the public origin until Cloudflare's edge routes to it. ANY HTTP
+ * response counts, including a 404: the live-view server 404s unknown paths,
+ * so a status code at all proves the hop is live.
+ */
+async function waitUntilRouted(url) {
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            await fetch(url, {
+                method: 'GET',
+                redirect: 'manual',
+                signal: AbortSignal.timeout(READY_POLL_MS * 4),
+            });
+            return true;
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, READY_POLL_MS));
+        }
+    }
+    return false;
+}
+/**
+ * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
+ * Cloudflare has assigned a hostname.
+ *
+ * Rejects with an actionable message when `cloudflared` is not installed,
+ * exits early, or never reports a hostname.
+ */
+export async function startTunnel(port, { autoInstall = true } = {}) {
+    // Resolves an existing cloudflared, or fetches one on first use. Throws
+    // with an actionable message when neither is possible.
+    const binary = await resolveCloudflared({ autoInstall });
+    const child = spawn(binary.path, [
+        'tunnel',
+        '--no-autoupdate',
+        '--url', `http://127.0.0.1:${port}`,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const stop = async () => {
+        if (!child.killed) {
+            child.kill('SIGTERM');
+        }
+    };
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            void stop();
+            reject(new Error('cloudflared did not report a tunnel hostname within '
+                + `${URL_TIMEOUT_MS / 1000}s. Check network egress to Cloudflare, `
+                + 'or run `cloudflared tunnel --url http://127.0.0.1:'
+                + `${port}` + '` by hand to see its output.'));
+        }, URL_TIMEOUT_MS);
+        let settled = false;
+        const finish = (fn) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        // cloudflared logs the assigned hostname to stderr, not stdout. Watch
+        // both so a future version that switches streams still works.
+        const onChunk = (chunk) => {
+            const text = chunk.toString();
+            const match = QUICK_TUNNEL_URL.exec(text);
+            if (match) {
+                const url = match[0];
+                finish(() => {
+                    void waitUntilRouted(url).then((ready) => {
+                        if (!ready) {
+                            LOGGER.warn({ url }, 'tunnel not routed yet; returning anyway');
+                        }
+                        resolve({ url, ready, stop, binary });
+                    });
+                });
+            }
+        };
+        child.stdout?.on('data', onChunk);
+        child.stderr?.on('data', onChunk);
+        child.on('error', (err) => {
+            // `resolveCloudflared` already proved the binary runs, so an ENOENT
+            // here means it vanished between resolving and spawning.
+            finish(() => reject(err.code === 'ENOENT'
+                ? new Error(`cloudflared disappeared from ${binary.path} before it could `
+                    + 'start. Retry — the agent will fetch it again if needed.')
+                : err));
+        });
+        child.on('exit', (code) => {
+            LOGGER.debug({ code }, 'cloudflared exited');
+            finish(() => reject(new Error(`cloudflared exited with code ${code} before reporting a `
+                + 'hostname.')));
+        });
+    });
+}

package/lib/live/viewer.d.ts

@@ -0,0 +1,28 @@
+import type { CdpTabClient } from '../cdp/client.ts';
+export interface LiveViewOptions {
+    /** The tab to stream. */
+    tab: CdpTabClient;
+    /** Forward viewer input into the page. */
+    interactive: boolean;
+    /** Shown in the viewer's header. */
+    title?: string;
+}
+export interface LiveView {
+    /** Loopback origin the tunnel should point at. */
+    localUrl: string;
+    /** Port the server bound to. */
+    port: number;
+    /** Unguessable path segment guarding every route. */
+    token: string;
+    /** Path prefix, `/v/<token>`. Append this to the public origin. */
+    path: string;
+    /** Number of viewers currently streaming. */
+    viewers: () => number;
+    stop: () => Promise<void>;
+}
+/**
+ * Start the loopback live-view server for `tab`. Resolves once it is
+ * listening; the screencast starts with the first viewer and stops with the
+ * last, so an idle share costs the page nothing.
+ */
+export declare function startLiveView(opts: LiveViewOptions): Promise<LiveView>;

package/lib/live/viewer.js

@@ -0,0 +1,232 @@
+/**
+ * Interactive live view of one attached tab, over a public URL.
+ *
+ * Two halves:
+ *  - OUT: CDP `Page.startScreencast` pushes JPEG frames; each is forwarded to
+ *    every connected browser as a Server-Sent Event and acked back to CDP.
+ *  - IN: the viewer POSTs pointer and key events, which are replayed into the
+ *    page with `Input.dispatch*`.
+ *
+ * Only ever bound to 127.0.0.1. Reaching it from outside is the tunnel's job
+ * (see `tunnel.ts`), and because a quick tunnel is unauthenticated, EVERY
+ * route sits behind an unguessable token in the path. A request without it
+ * gets a flat 404 — not a 401, which would confirm the server exists.
+ *
+ * Interactivity is the caller's choice. `interactive: false` still streams,
+ * but the input route refuses, which is the right setting for showing someone
+ * a run rather than handing them the wheel.
+ */
+import { randomBytes } from 'node:crypto';
+import { createServer, } from 'node:http';
+import { LOGGER } from "../logger.js";
+import { renderViewerPage } from "./page.js";
+/** JPEG quality for streamed frames. 60 keeps a text-heavy page readable
+ *  while staying small enough for a tunnel's uplink. */
+const FRAME_QUALITY = 60;
+/** Cap the streamed frame size. Screencast scales to fit, so this bounds
+ *  bandwidth without changing the page's own layout viewport. */
+const MAX_FRAME_WIDTH = 1280;
+const MAX_FRAME_HEIGHT = 800;
+/** Bytes accepted on an input POST. Events are tiny; anything larger is
+ *  either a bug or someone probing. */
+const MAX_INPUT_BYTES = 4096;
+/**
+ * Start the loopback live-view server for `tab`. Resolves once it is
+ * listening; the screencast starts with the first viewer and stops with the
+ * last, so an idle share costs the page nothing.
+ */
+export async function startLiveView(opts) {
+    const token = randomBytes(24).toString('base64url');
+    const path = `/v/${token}`;
+    const clients = new Set();
+    let streaming = false;
+    let unsubscribe;
+    const startScreencast = async () => {
+        if (streaming) {
+            return;
+        }
+        streaming = true;
+        unsubscribe = opts.tab.subscribe('Page.screencastFrame', (frame) => {
+            // Ack first: CDP sends at most one un-acked frame, so a slow or failed
+            // write must not stall the stream.
+            void opts.tab
+                .send('Page.screencastFrameAck', { sessionId: frame.sessionId })
+                .catch(() => { });
+            const payload = JSON.stringify({ data: frame.data });
+            for (const res of clients) {
+                res.write(`event: frame\ndata: ${payload}\n\n`);
+            }
+        });
+        await opts.tab.send('Page.enable');
+        await opts.tab.send('Page.startScreencast', {
+            format: 'jpeg',
+            quality: FRAME_QUALITY,
+            maxWidth: MAX_FRAME_WIDTH,
+            maxHeight: MAX_FRAME_HEIGHT,
+            everyNthFrame: 1,
+        });
+    };
+    const stopScreencast = async () => {
+        if (!streaming) {
+            return;
+        }
+        streaming = false;
+        unsubscribe?.();
+        unsubscribe = undefined;
+        await opts.tab.send('Page.stopScreencast').catch(() => { });
+    };
+    const server = createServer((req, res) => {
+        const url = req.url ?? '/';
+        // Constant prefix check: everything is scoped under the token, so an
+        // unmatched path is indistinguishable from a server that isn't there.
+        if (!url.startsWith(path)) {
+            res.writeHead(404).end('not found');
+            return;
+        }
+        const route = url.slice(path.length) || '/';
+        if (req.method === 'GET' && (route === '/' || route.startsWith('/?'))) {
+            const body = renderViewerPage({
+                base: path,
+                interactive: opts.interactive,
+                title: opts.title ?? 'Attached tab',
+            });
+            res.writeHead(200, {
+                'content-type': 'text/html; charset=utf-8',
+                // A share URL must never be cached or indexed by anything between
+                // the viewer and here.
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+            }).end(body);
+            return;
+        }
+        if (req.method === 'GET' && route === '/stream') {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-store',
+                connection: 'keep-alive',
+                // Defeat proxy buffering, which would otherwise hold frames back.
+                'x-accel-buffering': 'no',
+            });
+            res.write(': connected\n\n');
+            clients.add(res);
+            void startScreencast().catch((err) => {
+                LOGGER.warn({ err }, 'live view: screencast failed to start');
+            });
+            req.on('close', () => {
+                clients.delete(res);
+                if (!clients.size) {
+                    void stopScreencast();
+                }
+            });
+            return;
+        }
+        if (req.method === 'POST' && route === '/input') {
+            if (!opts.interactive) {
+                res.writeHead(403).end('view only');
+                return;
+            }
+            readJson(req, MAX_INPUT_BYTES)
+                .then((body) => dispatchInput(opts.tab, body))
+                .then(() => res.writeHead(204).end())
+                .catch((err) => {
+                LOGGER.debug({ err }, 'live view: input rejected');
+                res.writeHead(400).end('bad input');
+            });
+            return;
+        }
+        res.writeHead(404).end('not found');
+    });
+    await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const port = server.address().port;
+    return {
+        localUrl: `http://127.0.0.1:${port}`,
+        port,
+        token,
+        path,
+        viewers: () => clients.size,
+        stop: async () => {
+            await stopScreencast();
+            for (const res of clients) {
+                res.end();
+            }
+            clients.clear();
+            await closeServer(server);
+        },
+    };
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+        // A held-open SSE response would otherwise keep the server alive.
+        server.closeAllConnections?.();
+    });
+}
+function readJson(req, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new Error('input too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error('bad json'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+/** Replay one viewer event into the page. Unknown shapes throw, so the route
+ *  answers 400 rather than forwarding something arbitrary to CDP. */
+async function dispatchInput(tab, body) {
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v)
+        ? v
+        : 0);
+    if (body.kind === 'mouse') {
+        const type = String(body.type);
+        if (!['mousePressed', 'mouseReleased', 'mouseMoved', 'mouseWheel']
+            .includes(type)) {
+            throw new Error(`unsupported mouse type ${type}`);
+        }
+        await tab.send('Input.dispatchMouseEvent', {
+            type,
+            x: num(body.x),
+            y: num(body.y),
+            button: type === 'mouseWheel' ? 'none' : 'left',
+            clickCount: type === 'mouseWheel' ? 0 : 1,
+            ...(type === 'mouseWheel'
+                ? { deltaX: num(body.deltaX), deltaY: num(body.deltaY) }
+                : {}),
+        });
+        return;
+    }
+    if (body.kind === 'key') {
+        const type = String(body.type);
+        if (type !== 'keyDown' && type !== 'keyUp') {
+            throw new Error(`unsupported key type ${type}`);
+        }
+        const key = String(body.key ?? '');
+        // A single printable character needs `text` as well, or the page sees the
+        // keypress but no character is inserted.
+        const text = key.length === 1 ? key : undefined;
+        await tab.send('Input.dispatchKeyEvent', {
+            type,
+            key,
+            code: String(body.code ?? ''),
+            ...(text && type === 'keyDown' ? { text } : {}),
+        });
+        return;
+    }
+    throw new Error('unknown event kind');
+}

package/lib/mcp/api/operations.gen.js

@@ -440,7 +440,7 @@ export const MCP_TOOLS = {
         }),
     },
     "CreateProvider": {
-        description: "Create a provider\n\nCreate a new Reclaim provider. Use this only after `providers` returned nothing useful for the domain. The caller must be an active member of the target organization.\nCreates a new provider in the specified organization. `visibility` is coerced to `PRIVATE` at creation regardless of what's sent; the author may toggle to `PUBLIC` later via `PATCH /providers/{id}`. While `PRIVATE`, versions go to the go live freely; once `PUBLIC`, non-admin versions need admin review. See `Provider.visibility`.\nThe server also seeds an initial `0.1.0` version on the `draft` branch in the same transaction so the provider is immediately editable. Its `initialUrl` defaults to `https://<domain>`; all other version fields fall back to their schema-declared defaults (a `structured` verificationType, empty requests, empty web settings). `Provider.latestVersion` stays `null` until the draft is promoted to the live channel.",
+        description: "Create a provider\n\nCreate a new Reclaim provider. Use this only after `providers` returned nothing useful for the domain. The caller must be an active member of the target organization.\nCreates a new provider in the specified organization. `visibility` is coerced to `PRIVATE` at creation regardless of what's sent; the author may toggle to `PUBLIC` later via `PATCH /providers/{id}`. While `PRIVATE`, versions go live freely; once `PUBLIC`, non-admin versions need admin review. See `Provider.visibility`.\nThe server also seeds an initial `0.1.0` version on the `draft` branch in the same transaction so the provider is immediately editable. Its `initialUrl` defaults to `https://<domain>`; all other version fields fall back to their schema-declared defaults (a `structured` verificationType, empty requests, empty web settings). `Provider.latestVersion` stays `null` until the draft is promoted to the live channel.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -467,7 +467,7 @@ export const MCP_TOOLS = {
                             "format": "uuid"
                         },
                         "domain": {
-                            "description": "Canonical root domain (e.g. `github.com`). No scheme, no port, no path.",
+                            "description": "Canonical root domain (for example, `github.com`). No scheme, no port, no path.",
                             "type": "string",
                             "format": "hostname",
                             "minLength": 1,
@@ -526,12 +526,12 @@ export const MCP_TOOLS = {
                                 "brandUrl": {
                                     "type": "string",
                                     "format": "uri",
-                                    "description": "Canonical homepage of the brand (e.g. `https://google.com`). Used in brand-link cards and JSON-LD.",
+                                    "description": "Canonical homepage of the brand (for example, `https://google.com`). Used in brand-link cards and JSON-LD.",
                                     "maxLength": 2000
                                 },
                                 "primaryDataPoint": {
                                     "type": "string",
-                                    "description": "Headline data point — the single most-important variable this provider can verify (e.g. `subscriber count`). Used in the provider's SEO title.",
+                                    "description": "Headline data point — the single most-important variable this provider can verify (for example, `subscriber count`). Used in the provider's SEO title.",
                                     "maxLength": 200
                                 },
                                 "dataPoints": {
@@ -636,10 +636,11 @@ export const MCP_TOOLS = {
                                 },
                                 "branch": {
                                     "type": "string",
-                                    "description": "Branch (lifecycle stage) of this provider version.\n\n- `ai`: changes authored by the AI assistant live on this branch.\n\n- `draft`: a human is actively editing the version.\n\n- `in_review`: the author has submitted the version to be made\n  public and it is awaiting review. On approval the branch tag\n  is cleared (the version is promoted to the live channel and becomes\n  public).\n\n- `rejected`: review concluded with a rejection. When the author\n  addresses the feedback the branch transitions back to\n  `in_review`.",
+                                    "description": "Branch (lifecycle stage) of this provider version.\n\n- `ai`: changes authored by the AI assistant live on this branch.\n\n- `draft`: a human is actively editing the version.\n\n- `fixed`: a proven AI repair. It remains pinned to its explicit\n  version and does not replace the live trunk version.\n\n- `in_review`: the author has submitted the version to be made\n  public and it is awaiting review. On approval the branch tag\n  is cleared (the version is promoted to the live channel and becomes\n  public).\n\n- `rejected`: review concluded with a rejection. When the author\n  addresses the feedback the branch transitions back to\n  `in_review`.",
                                     "enum": [
                                         "ai",
                                         "draft",
+                                        "fixed",
                                         "in_review",
                                         "rejected"
                                     ]
@@ -775,7 +776,7 @@ export const MCP_TOOLS = {
                                         "items": {
                                             "type": "object",
                                             "additionalProperties": false,
-                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
                                             "properties": {
                                                 "xPath": {
                                                     "type": "string",
@@ -783,7 +784,7 @@ export const MCP_TOOLS = {
                                                 },
                                                 "jsonPath": {
                                                     "type": "string",
-                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
                                                 },
                                                 "regex": {
                                                     "type": "string",
@@ -926,7 +927,7 @@ export const MCP_TOOLS = {
                                         "items": {
                                             "type": "object",
                                             "additionalProperties": false,
-                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
                                             "properties": {
                                                 "xPath": {
                                                     "type": "string",
@@ -934,7 +935,7 @@ export const MCP_TOOLS = {
                                                 },
                                                 "jsonPath": {
                                                     "type": "string",
-                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
                                                 },
                                                 "regex": {
                                                     "type": "string",
@@ -991,8 +992,8 @@ export const MCP_TOOLS = {
                             "properties": {
                                 "geoLocation": {
                                     "type": "string",
-                                    "description": "Geographic location (e.g. ISO country code or {{DYNAMIC_GEO}} to use user's geo location) the verification should appear to originate from.",
-                                    "maxLength": 15,
+                                    "description": "Geographic location the verification should appear to originate from: a 2-letter ISO country code, or a parameter the attestor resolves at proof time. `{{DYNAMIC_GEO}}` and `{{DYNAMIC_GEO_SECRET}}` are the Verification Client's standard names for the end-user's own country — the `_SECRET` one is delivered as a secret param, so the attestor never learns which country the proof egressed from.",
+                                    "maxLength": 64,
                                     "default": "{{DYNAMIC_GEO}}"
                                 },
                                 "clientOptions": {
@@ -1386,7 +1387,7 @@ export const MCP_TOOLS = {
         }),
     },
     "DeleteProviderVersion": {
-        description: "Delete a provider version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. Trunk (live) and `in_review` versions cannot be archived this way; archive the parent provider instead. Supports optimistic concurrency via `If-Match`.",
+        description: "Delete a provider version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. `fixed`, trunk (live), and `in_review` versions cannot be archived this way; archive the parent provider instead. Supports optimistic concurrency via `If-Match`.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -1706,7 +1707,7 @@ export const MCP_TOOLS = {
         }),
     },
     "GetProviderVersion": {
-        description: "Get a specific provider version",
+        description: "Get a specific provider version\n\nFetches one exact canonical version. Trunk is public when the provider is public. Non-trunk versions are visible to admins and members of the provider's organization. A member of the organization that paid for a successful AI repair may also read only the exact `fixed` version created by that repair.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2061,7 +2062,7 @@ export const MCP_TOOLS = {
         }),
     },
     "ListProviderVersions": {
-        description: "List a provider's versions\n\nLists versions visible to the caller. Non-public branches (`ai`, `draft`, `in_review`, `rejected`) are only visible to members of the provider's owning organization.",
+        description: "List a provider's versions\n\nLists versions visible to the caller. Non-public branches (`ai`, `draft`, `fixed`, `in_review`, `rejected`) are only visible to members of the provider's owning organization.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2210,7 +2211,7 @@ export const MCP_TOOLS = {
         }),
     },
     "Providers": {
-        description: "Search providers\n\nSearch published Reclaim providers by domain or data point. A provider is the recipe an end-user follows to prove something about themselves (e.g. \"I have N followers on Twitter\"). Returns a list of matches. Call this BEFORE `create_provider` — most popular domains already have a public provider you can reuse.\nCatalog page listing all providers. Returns a paginated list of providers the caller can see. Public providers are visible to everyone; private providers are only visible to org members.",
+        description: "Search providers\n\nSearch Reclaim providers by domain or data point. A provider is the recipe an end-user follows to prove something about themselves, such as \"I have N followers on Twitter\".\nCall this BEFORE `create_provider` — most popular domains already have a public provider you can reuse, and creating another one just stacks duplicates.\nReturns a paginated list of the providers the caller can see: public providers to everyone, private providers only to members of the owning organization.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2567,7 +2568,7 @@ export const MCP_TOOLS = {
                     "properties": {
                         "notes": {
                             "type": "string",
-                            "description": "Optional note from the author to reviewers (changelog, areas to focus on, etc.).",
+                            "description": "Optional note from the author to reviewers (changelog, areas to focus on, and so on).",
                             "maxLength": 10000
                         }
                     }
@@ -2724,6 +2725,13 @@ export const MCP_TOOLS = {
                             "minLength": 1,
                             "maxLength": 200
                         },
+                        "region": {
+                            "type": "string",
+                            "nullable": true,
+                            "description": "Confirm or override the provider's region. Send `null` to clear it so the provider applies to every region. See `Provider.region`.",
+                            "pattern": "^[a-z]{2}(-[a-z]{2})?$",
+                            "maxLength": 5
+                        },
                         "title": {
                             "type": "string",
                             "minLength": 1,
@@ -2776,12 +2784,12 @@ export const MCP_TOOLS = {
                                 "brandUrl": {
                                     "type": "string",
                                     "format": "uri",
-                                    "description": "Canonical homepage of the brand (e.g. `https://google.com`). Used in brand-link cards and JSON-LD.",
+                                    "description": "Canonical homepage of the brand (for example, `https://google.com`). Used in brand-link cards and JSON-LD.",
                                     "maxLength": 2000
                                 },
                                 "primaryDataPoint": {
                                     "type": "string",
-                                    "description": "Headline data point — the single most-important variable this provider can verify (e.g. `subscriber count`). Used in the provider's SEO title.",
+                                    "description": "Headline data point — the single most-important variable this provider can verify (for example, `subscriber count`). Used in the provider's SEO title.",
                                     "maxLength": 200
                                 },
                                 "dataPoints": {
@@ -2817,7 +2825,7 @@ export const MCP_TOOLS = {
         }),
     },
     "UpdateProviderVersion": {
-        description: "Update a provider version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `in_review` or the live channel reject all writes here. Caller must be a member of the provider's owning organization. Supports optimistic concurrency via `If-Match`.",
+        description: "Update a provider version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `fixed`, `in_review`, or the live channel reject all writes here. Caller must be a member of the provider's owning organization. Supports optimistic concurrency via `If-Match`.",
         inputSchema: toZod({
             "type": "object",
             "properties": {
@@ -2857,7 +2865,7 @@ export const MCP_TOOLS = {
                 "body": {
                     "type": "object",
                     "additionalProperties": false,
-                    "description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `in_review` or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` and `prompt` may be updated; omit either to carry the prior build's value forward.",
+                    "description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `fixed`, `in_review`, or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` and `prompt` may be updated; omit either to carry the prior build's value forward.",
                     "properties": {
                         "initialUrl": {
                             "type": "string",
@@ -2996,7 +3004,7 @@ export const MCP_TOOLS = {
                                         "items": {
                                             "type": "object",
                                             "additionalProperties": false,
-                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
                                             "properties": {
                                                 "xPath": {
                                                     "type": "string",
@@ -3004,7 +3012,7 @@ export const MCP_TOOLS = {
                                                 },
                                                 "jsonPath": {
                                                     "type": "string",
-                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
                                                 },
                                                 "regex": {
                                                     "type": "string",
@@ -3146,7 +3154,7 @@ export const MCP_TOOLS = {
                                         "items": {
                                             "type": "object",
                                             "additionalProperties": false,
-                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+                                            "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
                                             "properties": {
                                                 "xPath": {
                                                     "type": "string",
@@ -3154,7 +3162,7 @@ export const MCP_TOOLS = {
                                                 },
                                                 "jsonPath": {
                                                     "type": "string",
-                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+                                                    "description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
                                                 },
                                                 "regex": {
                                                     "type": "string",
@@ -3211,8 +3219,8 @@ export const MCP_TOOLS = {
                             "properties": {
                                 "geoLocation": {
                                     "type": "string",
-                                    "description": "Geographic location (e.g. ISO country code or {{DYNAMIC_GEO}} to use user's geo location) the verification should appear to originate from.",
-                                    "maxLength": 15,
+                                    "description": "Geographic location the verification should appear to originate from: a 2-letter ISO country code, or a parameter the attestor resolves at proof time. `{{DYNAMIC_GEO}}` and `{{DYNAMIC_GEO_SECRET}}` are the Verification Client's standard names for the end-user's own country — the `_SECRET` one is delivered as a secret param, so the attestor never learns which country the proof egressed from.",
+                                    "maxLength": 64,
                                     "default": "{{DYNAMIC_GEO}}"
                                 },
                                 "clientOptions": {

package/lib/mcp/api/to-zod.d.ts

@@ -5,7 +5,7 @@ import type { JSONSchema } from 'zod/v4/core';
  *
  * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
  * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
- * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (for example,
  * `RequestSelectionTemplate =
  * allOf[ RequestSelection, { multiple, required } ]`,
  * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling

package/lib/mcp/api/to-zod.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
  *
  * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
  * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
- * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (for example,
  * `RequestSelectionTemplate =
  * allOf[ RequestSelection, { multiple, required } ]`,
  * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling

package/lib/mcp/api/tools.js

@@ -2,7 +2,7 @@ import { remapErrorAsResponse } from "../remap_errors.js";
 import { MCP_TOOLS } from "./operations.gen.js";
 /**
  * The generated `MCP_TOOLS` are keyed by OpenAPI `operationId` (PascalCase,
- * e.g. `GetMe`). MCP tools are conventionally snake_case, matching the
+ * For example, `GetMe`). MCP tools are conventionally snake_case, matching the
  * hand-written tools in this server. Convert the public tool name here while
  * still dispatching to the API with the original operationId — doing this in
  * the (non-generated) registration keeps it from being reverted on regen.