@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/mcp/tools.js

@@ -0,0 +1,1381 @@
+/**
+ * MCP tool surface. Phase 1 / §4 of 260604-PLAN-vana-mcp-personal-server.md.
+ *
+ * Read-only, small, and only over scopes that the connection's grants cover.
+ * No write tools. No grant-approval tools. No raw owner/admin status tools.
+ *
+ * Every tool that returns data first picks a covering grant from the
+ * connection's grant list, signs a Web3Signed request as the per-connection
+ * grantee, and uses the bounded sidecar read path — so reads are grant-gated,
+ * access-logged, and safe for large scopes.
+ */
+import { z } from "zod";
+import { MCP_SCOPE_ACCESS_REQUEST_LIMIT, } from "./types.js";
+import { McpDataReadError } from "./read-client.js";
+import { MiniSearchIndex } from "./search/index.js";
+import { MAX_SELECTED_BLOCK_IDS } from "../storage/blocks/index.js";
+import { rawScopeFileInputSchema, rawScopeMetadata, rawScopeResourceUri, } from "./resources.js";
+/** Tool names the read path stamps onto access records. */
+const READ_SCOPE_TOOL = "read_scope";
+const SEARCH_PERSONAL_CONTEXT_TOOL = "search_personal_context";
+const STRUCTURED_CONTENT_TEXT_LIMIT_BYTES = 64 * 1024;
+const resultTextEncoder = new TextEncoder();
+/**
+ * Tool payloads are machine-read, never displayed as-is: pretty-printing them
+ * inflated the wire size 1.37x-1.63x on real scopes for no reader benefit.
+ */
+function textResult(value, isError = false) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const textBytes = resultTextEncoder.encode(text).byteLength;
+    const structuredContent = !isError &&
+        textBytes <= STRUCTURED_CONTENT_TEXT_LIMIT_BYTES &&
+        typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value)
+        ? value
+        : undefined;
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        ...(structuredContent ? { structuredContent } : {}),
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function uniqueScopes(connection) {
+    const set = new Set();
+    for (const grant of connection.grants) {
+        for (const scope of grant.scopes)
+            set.add(scope);
+    }
+    return Array.from(set).sort();
+}
+function uniqueSources(connection) {
+    const set = new Set();
+    for (const grant of connection.grants) {
+        const sourceId = typeof grant.sourceId === "string" ? grant.sourceId.trim() : "";
+        if (sourceId) {
+            set.add(sourceId);
+            continue;
+        }
+        for (const scope of grant.scopes) {
+            const [scopeSourceId] = scope.split(".");
+            if (scopeSourceId && scopeSourceId !== "*") {
+                set.add(scopeSourceId);
+            }
+        }
+    }
+    return Array.from(set).sort();
+}
+/**
+ * Block ids a caller may name in one block-addressed read. Bounded so a model
+ * cannot turn `blockIds` into an unbounded fan-out; `maxBytes` still applies on
+ * top of it.
+ */
+function normalizeBlockIdsInput(value) {
+    if (!Array.isArray(value))
+        return [];
+    const blockIds = [];
+    const seen = new Set();
+    for (const raw of value) {
+        if (typeof raw !== "string")
+            continue;
+        const blockId = raw.trim();
+        if (!blockId || blockId.length > BLOCK_ID_MAX_CHARS || seen.has(blockId)) {
+            continue;
+        }
+        seen.add(blockId);
+        blockIds.push(blockId);
+        if (blockIds.length >= MAX_SELECTED_BLOCK_IDS)
+            break;
+    }
+    return blockIds;
+}
+function normalizeScopeListInput(value) {
+    if (!Array.isArray(value))
+        return [];
+    const scopes = [];
+    const seen = new Set();
+    for (const raw of value) {
+        if (typeof raw !== "string")
+            continue;
+        const scope = raw.trim();
+        if (!scope || scope.length > SEARCH_SCOPE_MAX_CHARS || seen.has(scope)) {
+            continue;
+        }
+        seen.add(scope);
+        scopes.push(scope);
+    }
+    return scopes;
+}
+/**
+ * Hard ceiling the MCP dispatcher enforces on any tool call (see
+ * `clampToolTimeout` in `server.ts`, which imports this).
+ *
+ * Tools must never advertise a larger `timeoutMs` than the dispatcher allows: a
+ * client that trusts the advertised maximum gets killed with a hard
+ * `tool_timeout` instead of the graceful "budget exhausted, here are partial
+ * results plus nextSearchCursor" path the tools implement.
+ */
+export const MAX_MCP_TOOL_TIMEOUT_MS = 90_000;
+const DEFAULT_SEARCH_LIMIT = 5;
+const MAX_SEARCH_LIMIT = 50;
+const MAX_SEARCH_SCOPES = 200;
+const DEFAULT_SEARCH_MAX_SCOPES = MAX_SEARCH_SCOPES;
+const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
+const MAX_SEARCH_TIMEOUT_MS = MAX_MCP_TOOL_TIMEOUT_MS;
+const DEFAULT_SEARCH_DISCOVERY_TIMEOUT_MS = 2_000;
+const MAX_SEARCH_TOTAL_TIMEOUT_MS = MAX_MCP_TOOL_TIMEOUT_MS;
+const DEFAULT_READ_SCOPE_MAX_BYTES = 64 * 1024;
+const MAX_READ_SCOPE_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_READ_SCOPE_TIMEOUT_MS = 60_000;
+const MAX_READ_SCOPE_TIMEOUT_MS = MAX_MCP_TOOL_TIMEOUT_MS;
+const DEFAULT_READ_FILE_TIMEOUT_MS = 60_000;
+const MAX_READ_FILE_TIMEOUT_MS = MAX_MCP_TOOL_TIMEOUT_MS;
+const DEFAULT_READ_FILE_MAX_BYTES = 10 * 1024 * 1024;
+const MAX_READ_FILE_MAX_BYTES = 25 * 1024 * 1024;
+const DEFAULT_SEARCH_MAX_BYTES = 64 * 1024;
+const MAX_SEARCH_MAX_BYTES = 1024 * 1024;
+const DEFAULT_SCOPE_METADATA_TIMEOUT_MS = 2_000;
+const DEFAULT_LIST_BLOCKS_LIMIT = 100;
+const MAX_LIST_BLOCKS_LIMIT = 500;
+const LIST_BLOCKS_TIMEOUT_MS = 15_000;
+/**
+ * Safety net, not a search budget: a scope is scanned page by page until the
+ * result limit or the time budget is hit, and this only stops a pathological
+ * scope from monopolising the run. Pages beyond it are resumable through
+ * `nextSearchCursor`, so raising it costs latency, never correctness.
+ */
+const SEARCH_MAX_PAGES_PER_SCOPE = 256;
+const SEARCH_QUERY_MAX_CHARS = 256;
+const SEARCH_SCOPE_MAX_CHARS = 128;
+const BLOCK_ID_MAX_CHARS = 128;
+const SEARCH_REQUESTED_SCOPES_LIMIT = MAX_SEARCH_SCOPES * 2;
+const SEARCH_SKIPPED_SCOPES_LIMIT = 50;
+const SEARCH_PREVIEW_CHARS = 600;
+const LIST_SCOPES_LIMIT = 200;
+const scopeAccessRequestInputShape = {
+    scopes: z
+        .array(z.string().min(1).max(SEARCH_SCOPE_MAX_CHARS))
+        .min(1)
+        .max(MCP_SCOPE_ACCESS_REQUEST_LIMIT)
+        .describe("Exact scope ids the MCP client wants to read."),
+    reason: z
+        .string()
+        .max(500)
+        .optional()
+        .describe("Brief reason to show the user."),
+};
+export function parseScopeAccessRequestArguments(value) {
+    const parsed = z.object(scopeAccessRequestInputShape).safeParse(value);
+    if (!parsed.success)
+        return null;
+    const scopes = normalizeScopeListInput(parsed.data.scopes);
+    if (scopes.length === 0)
+        return null;
+    const reason = parsed.data.reason?.trim();
+    return { scopes, ...(reason ? { reason } : {}) };
+}
+// Size thresholds for sizeClass classification (raw envelope bytes)
+const SIZE_CLASS_TINY_BYTES = 10_000;
+const SIZE_CLASS_SMALL_BYTES = 100_000;
+const SIZE_CLASS_MEDIUM_BYTES = 1_000_000;
+const SIZE_CLASS_LARGE_BYTES = 10_000_000;
+class OperationTimeoutError extends Error {
+    operation;
+    timeoutMs;
+    constructor(operation, timeoutMs) {
+        super(`${operation} timed out after ${timeoutMs}ms`);
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+        this.name = "OperationTimeoutError";
+    }
+}
+/**
+ * Resolve a concrete requested scope to a covering grant id from the
+ * connection's approved grants. A scope is "covered" when an approved grant's
+ * scopes either contains the exact scope or contains a wildcard like
+ * `instagram.*` that matches a concrete child scope like `instagram.profile`.
+ *
+ * Mirrors `scopeCoveredByGrant` semantics from `policy/data-read.ts` so the
+ * tool surface never offers Claude a scope its grant won't actually pass
+ * server-side.
+ */
+export function resolveGrantForScope(connection, scope) {
+    for (const grant of connection.grants) {
+        for (const granted of grant.scopes) {
+            if (granted === scope) {
+                return { grantId: grant.grantId, scopes: grant.scopes };
+            }
+            if (granted.endsWith(".*")) {
+                const prefix = granted.slice(0, -2);
+                if (scope.startsWith(`${prefix}.`)) {
+                    return { grantId: grant.grantId, scopes: grant.scopes };
+                }
+            }
+            if (granted === "*") {
+                return { grantId: grant.grantId, scopes: grant.scopes };
+            }
+        }
+    }
+    return null;
+}
+function clampInteger(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+function wildcardPrefix(scope) {
+    if (scope === "*")
+        return "";
+    if (scope.endsWith(".*"))
+        return `${scope.slice(0, -2)}.`;
+    return null;
+}
+function truncateLabel(value) {
+    return value.length > SEARCH_SCOPE_MAX_CHARS
+        ? `${value.slice(0, SEARCH_SCOPE_MAX_CHARS)}...`
+        : value;
+}
+function stringifyPreview(value) {
+    if (typeof value === "string") {
+        return value.slice(0, SEARCH_PREVIEW_CHARS);
+    }
+    try {
+        return JSON.stringify(value)?.slice(0, SEARCH_PREVIEW_CHARS) ?? "";
+    }
+    catch {
+        return String(value).slice(0, SEARCH_PREVIEW_CHARS);
+    }
+}
+function collectSearchText(value) {
+    const chunks = [];
+    function visit(node) {
+        if (typeof node === "string") {
+            chunks.push(node);
+            return;
+        }
+        if (typeof node === "number" ||
+            typeof node === "boolean" ||
+            node === null) {
+            chunks.push(String(node));
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (typeof node === "object" && node !== null) {
+            for (const [key, item] of Object.entries(node)) {
+                chunks.push(key);
+                visit(item);
+            }
+        }
+    }
+    visit(value);
+    return chunks.join("\n");
+}
+function blockPageSearchText(blocks) {
+    return blocks
+        .map((block) => `${block.path}\n${collectSearchText(block.value)}`)
+        .join("\n\n");
+}
+function blockPageSearchDocuments(scope, blocks) {
+    const textById = new Map();
+    const documents = blocks.map((block, index) => {
+        const id = `${scope}:${block.id || index}`;
+        const text = `${block.path}\n${collectSearchText(block.value)}`;
+        textById.set(id, text);
+        return {
+            id,
+            scope,
+            title: block.path,
+            text,
+            preview: text.slice(0, SEARCH_PREVIEW_CHARS),
+            blockRef: block.id,
+        };
+    });
+    return { documents, textById };
+}
+function previewMatch(text, matchIndex) {
+    const halfWindow = Math.floor(SEARCH_PREVIEW_CHARS / 2);
+    const start = Math.max(0, matchIndex - halfWindow);
+    const end = Math.min(text.length, start + SEARCH_PREVIEW_CHARS);
+    const prefix = start > 0 ? "..." : "";
+    const suffix = end < text.length ? "..." : "";
+    return `${prefix}${text.slice(start, end)}${suffix}`;
+}
+function miniSearchMatchIndex(text, terms) {
+    const normalized = text.toLowerCase();
+    for (const term of terms) {
+        const index = normalized.indexOf(term.toLowerCase());
+        if (index >= 0)
+            return index;
+    }
+    return 0;
+}
+async function withTimeout(promise, timeoutMs, operation) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new OperationTimeoutError(operation, timeoutMs)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function normalizeRequestedScopes(value, connection) {
+    const input = Array.isArray(value) ? value : uniqueScopes(connection);
+    const requestedScopes = [];
+    const seen = new Set();
+    const skippedScopes = [];
+    const scanned = Math.min(input.length, SEARCH_REQUESTED_SCOPES_LIMIT);
+    let invalidCount = 0;
+    for (let index = 0; index < scanned; index += 1) {
+        const scope = input[index];
+        if (typeof scope !== "string") {
+            invalidCount += 1;
+            continue;
+        }
+        const trimmed = scope.trim();
+        if (!trimmed || trimmed.length > SEARCH_SCOPE_MAX_CHARS) {
+            invalidCount += 1;
+            continue;
+        }
+        if (seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        requestedScopes.push(trimmed);
+    }
+    if (input.length > SEARCH_REQUESTED_SCOPES_LIMIT) {
+        skippedScopes.push(`${input.length - SEARCH_REQUESTED_SCOPES_LIMIT} requested scopes omitted by input cap`);
+    }
+    if (invalidCount > 0) {
+        skippedScopes.push(`${invalidCount} invalid requested scopes omitted`);
+    }
+    return { requestedScopes, skippedScopes };
+}
+function classifySizeBytes(sizeBytes) {
+    if (sizeBytes === undefined)
+        return "unknown";
+    if (sizeBytes < SIZE_CLASS_TINY_BYTES)
+        return "tiny";
+    if (sizeBytes < SIZE_CLASS_SMALL_BYTES)
+        return "small";
+    if (sizeBytes < SIZE_CLASS_MEDIUM_BYTES)
+        return "medium";
+    if (sizeBytes < SIZE_CLASS_LARGE_BYTES)
+        return "large";
+    return "huge";
+}
+// Directive guidance the MCP client (e.g. Claude) uses to pick read_scope vs
+// search_personal_context for a scope WITHOUT operator intervention. The signal
+// must be unambiguous: a misnamed flag here (the old `searchRecommended: false`
+// on large scopes) reads to a model as "don't search → read the whole thing",
+// which is exactly the slow path — a full read of a large scope returns many
+// pages it must walk via nextCursor and tends to stall the agent loop.
+function recommendAccessForScope(sizeClass, hasBlocks) {
+    if (!hasBlocks) {
+        return {
+            recommendedAccess: "wait",
+            reason: "bounded block data is still indexing or unavailable; retry shortly before reading or searching",
+        };
+    }
+    if (sizeClass === "large" || sizeClass === "huge") {
+        return {
+            recommendedAccess: "search",
+            reason: `scope is ${sizeClass}; prefer search_personal_context and name this scope explicitly. A full read_scope returns many pages you must walk via nextCursor.`,
+        };
+    }
+    if (sizeClass === "unknown") {
+        return {
+            recommendedAccess: "search",
+            reason: "scope size is unknown; prefer search_personal_context and name this scope explicitly",
+        };
+    }
+    return {
+        recommendedAccess: "read",
+        reason: `scope is ${sizeClass}; read_scope returns it in one or few pages. search_personal_context also works for targeted lookups.`,
+    };
+}
+async function resolveSearchScopes({ connection, maxScopes, discoveryTimeoutMs, readClient, requestedScopes, }) {
+    const scopes = new Set();
+    const skippedScopes = [];
+    let skippedScopeOverflow = 0;
+    const errors = [];
+    let wildcardDiscoveries = 0;
+    function skipScope(scope) {
+        if (skippedScopes.length < SEARCH_SKIPPED_SCOPES_LIMIT) {
+            skippedScopes.push(truncateLabel(scope));
+            return;
+        }
+        skippedScopeOverflow += 1;
+    }
+    function addScope(scope) {
+        if (scopes.has(scope))
+            return;
+        if (scopes.size >= maxScopes) {
+            skipScope(scope);
+            return;
+        }
+        scopes.add(scope);
+    }
+    for (const requested of requestedScopes) {
+        if (scopes.size >= maxScopes) {
+            skipScope(requested);
+            continue;
+        }
+        const grant = resolveGrantForScope(connection, requested);
+        if (!grant) {
+            errors.push({ scope: requested, error: "scope_not_granted" });
+            continue;
+        }
+        const prefix = wildcardPrefix(requested);
+        if (prefix === null) {
+            addScope(requested);
+            continue;
+        }
+        if (wildcardDiscoveries >= maxScopes) {
+            skipScope(`${requested} (wildcard discovery cap reached)`);
+            continue;
+        }
+        wildcardDiscoveries += 1;
+        try {
+            const listed = await withTimeout(readClient.listScopes({
+                scopePrefix: prefix,
+                limit: LIST_SCOPES_LIMIT,
+            }), discoveryTimeoutMs, `list scopes for ${requested}`);
+            for (const summary of listed.scopes) {
+                if (resolveGrantForScope(connection, summary.scope)) {
+                    addScope(summary.scope);
+                }
+            }
+            if (listed.total > listed.scopes.length) {
+                skipScope(`${requested} (more than ${listed.scopes.length})`);
+            }
+        }
+        catch (err) {
+            errors.push({
+                scope: requested,
+                error: err instanceof OperationTimeoutError
+                    ? "scope_list_timeout"
+                    : "scope_list_failed",
+                status: err instanceof McpDataReadError ? err.status : undefined,
+                bodyPreview: stringifyPreview(err instanceof McpDataReadError
+                    ? err.body
+                    : err instanceof OperationTimeoutError
+                        ? err.message
+                        : "unexpected scope list failure"),
+            });
+        }
+    }
+    if (skippedScopeOverflow > 0) {
+        skippedScopes.push(`${skippedScopeOverflow} additional skipped scopes omitted`);
+    }
+    return {
+        scopes: Array.from(scopes),
+        skippedScopes: Array.from(new Set(skippedScopes)),
+        errors,
+    };
+}
+const listGrantedSources = {
+    name: "list_granted_sources",
+    title: "List granted sources",
+    description: "List granted data source ids. Use list_granted_scopes for scope readiness and size.",
+    inputSchema: {},
+    async handler(_args, { connection }) {
+        return textResult({ sources: uniqueSources(connection) });
+    },
+};
+const listGrantedScopes = {
+    name: "list_granted_scopes",
+    title: "List granted scopes",
+    description: "List granted scopes, readiness, size, and recommendedAccess. Call first.",
+    inputSchema: {},
+    async handler(_args, { connection, readClient }) {
+        const grantedScopes = uniqueScopes(connection);
+        const scopeEntries = await Promise.all(grantedScopes.map(async (scope) => {
+            let meta = null;
+            if (typeof readClient.getScopeMetadata === "function") {
+                try {
+                    meta = await withTimeout(readClient.getScopeMetadata(scope), DEFAULT_SCOPE_METADATA_TIMEOUT_MS, `scope metadata for ${scope}`);
+                }
+                catch {
+                    return {
+                        scope,
+                        source: scope.split(".")[0],
+                        dataStatus: "indexing",
+                        sizeClass: "unknown",
+                        recommendedAccess: "wait",
+                        reason: "scope metadata is still indexing or temporarily unavailable; retry shortly",
+                    };
+                }
+            }
+            if (!meta) {
+                return {
+                    scope,
+                    dataStatus: "needs_refresh",
+                    sizeClass: "unknown",
+                    recommendedAccess: "wait",
+                    reason: "no local data found; refresh your data connection",
+                };
+            }
+            const sizeClass = classifySizeBytes(meta.sizeBytes);
+            const { recommendedAccess, reason } = recommendAccessForScope(sizeClass, meta.hasBlocks);
+            return {
+                scope,
+                source: scope.split(".")[0],
+                collectedAt: meta.collectedAt,
+                dataStatus: meta.hasBlocks
+                    ? "ready"
+                    : "indexing",
+                sizeBytes: meta.sizeBytes,
+                sizeClass,
+                recommendedAccess,
+                reason,
+            };
+        }));
+        return textResult({ scopes: scopeEntries });
+    },
+};
+const requestScopeAccess = {
+    name: "request_scope_access",
+    title: "Request scope access",
+    description: "Record missing scopes on this MCP connection for explicit owner approval in Vana.",
+    inputSchema: scopeAccessRequestInputShape,
+    async handler(args, { connection, requestScopeAccess }) {
+        const requestedScopes = normalizeScopeListInput(args.scopes);
+        let effectiveConnection = connection;
+        let grantedRequestedScopes = requestedScopes.filter((scope) => Boolean(resolveGrantForScope(effectiveConnection, scope)));
+        let missingScopes = requestedScopes.filter((scope) => !resolveGrantForScope(connection, scope));
+        const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+        const approvalRequired = missingScopes.length > 0;
+        const alreadyRecorded = approvalRequired &&
+            missingScopes.every((scope) => connection.scopeAccessRequest?.scopes.includes(scope));
+        let requestRecorded = alreadyRecorded;
+        if (approvalRequired && requestScopeAccess) {
+            const outcome = await requestScopeAccess({
+                scopes: missingScopes,
+                ...(reason ? { reason } : {}),
+            });
+            effectiveConnection = outcome.connection;
+            requestRecorded = outcome.requestRecorded;
+            grantedRequestedScopes = requestedScopes.filter((scope) => Boolean(resolveGrantForScope(effectiveConnection, scope)));
+            missingScopes = requestedScopes.filter((scope) => !resolveGrantForScope(effectiveConnection, scope));
+        }
+        const finalApprovalRequired = missingScopes.length > 0;
+        return textResult({
+            approvalRequired: finalApprovalRequired,
+            client: {
+                id: connection.id,
+                displayName: connection.displayName,
+                status: connection.status,
+            },
+            requestedScopes,
+            grantedRequestedScopes,
+            missingScopes,
+            grantedScopes: uniqueScopes(effectiveConnection),
+            reason: reason || undefined,
+            requestRecorded: finalApprovalRequired && requestRecorded,
+            nextAction: finalApprovalRequired
+                ? requestRecorded
+                    ? "The request is waiting for owner approval in Vana. Access remains unchanged until the owner approves it."
+                    : "Ask the user to open Vana's Personal Server page and add the missing scopes to this MCP client. This tool cannot grant access by itself."
+                : "No new grant is needed for the requested scopes.",
+        });
+    },
+};
+const readScope = {
+    name: READ_SCOPE_TOOL,
+    title: "Read scope",
+    description: "Read approved scope blocks. Pass blockIds to fetch exact blocks; otherwise page with nextCursor.",
+    inputSchema: {
+        scope: z.string().min(1).describe("Exact scope id."),
+        cursor: z.string().min(1).optional(),
+        blockIds: z
+            .array(z.string().min(1).max(BLOCK_ID_MAX_CHARS))
+            .min(1)
+            .max(MAX_SELECTED_BLOCK_IDS)
+            .optional()
+            .describe("Block ids from a search hit's blockRef or list_scope_blocks. Ignores cursor; maxBytes still applies."),
+        maxBytes: z.number().int().min(1).max(MAX_READ_SCOPE_MAX_BYTES).optional(),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1000)
+            .max(MAX_READ_SCOPE_TIMEOUT_MS)
+            .optional(),
+        payment: z
+            .string()
+            .optional()
+            .describe("Base64 X-PAYMENT proof (x402). Provide it after a prior call returned payment_required."),
+    },
+    async handler(args, { connection, readClient }) {
+        const scope = typeof args.scope === "string" ? args.scope : null;
+        if (!scope) {
+            return textResult({ error: "scope is required and must be a string" }, true);
+        }
+        const grant = resolveGrantForScope(connection, scope);
+        if (!grant) {
+            return textResult({
+                error: "scope_not_granted",
+                message: `Scope '${scope}' is not covered by any grant on this MCP connection.`,
+                grantedScopes: uniqueScopes(connection),
+            }, true);
+        }
+        const cursor = typeof args.cursor === "string" ? args.cursor : undefined;
+        const blockIds = normalizeBlockIdsInput(args.blockIds);
+        const maxBytes = typeof args.maxBytes === "number"
+            ? clampInteger(args.maxBytes, DEFAULT_READ_SCOPE_MAX_BYTES, 1, MAX_READ_SCOPE_MAX_BYTES)
+            : DEFAULT_READ_SCOPE_MAX_BYTES;
+        const timeoutMs = clampInteger(args.timeoutMs, DEFAULT_READ_SCOPE_TIMEOUT_MS, 1000, MAX_READ_SCOPE_TIMEOUT_MS);
+        // In-band steer: the model may call read_scope on a large scope without
+        // first consulting list_granted_scopes. Fetch lightweight planning metadata
+        // (storage-index only, no network/auth) opportunistically so we can attach a
+        // `guidance` hint when it is already available. This is advisory only: it
+        // must never delay the read or consume the read timeout budget.
+        let guidance;
+        if (typeof readClient.getScopeMetadata === "function") {
+            void withTimeout(readClient.getScopeMetadata(scope), DEFAULT_SCOPE_METADATA_TIMEOUT_MS, `scope metadata for ${scope}`)
+                .then((meta) => {
+                if (!meta)
+                    return;
+                const sizeClass = classifySizeBytes(meta.sizeBytes);
+                const recommendation = recommendAccessForScope(sizeClass, meta.hasBlocks);
+                // Only steer when search is the better tool; a normal small read gets
+                // no extra noise.
+                if (recommendation.recommendedAccess === "search") {
+                    guidance = {
+                        sizeClass,
+                        sizeBytes: meta.sizeBytes,
+                        recommendedAccess: recommendation.recommendedAccess,
+                        reason: recommendation.reason,
+                    };
+                }
+            })
+                .catch(() => {
+                // Advisory only — serve the read without guidance.
+            });
+        }
+        const payment = typeof args.payment === "string" ? args.payment : undefined;
+        try {
+            const result = await withTimeout(readClient.readScopeBlocks({
+                scope,
+                grantId: grant.grantId,
+                cursor,
+                maxBytes,
+                payment,
+                tool: READ_SCOPE_TOOL,
+                ...(blockIds.length > 0 ? { blockIds } : {}),
+            }), timeoutMs, `read blocks for ${scope}`);
+            const nextCursor = result.nextCursor ?? null;
+            return textResult({
+                scope,
+                grantId: grant.grantId,
+                collectedAt: result.collectedAt,
+                contentKind: result.contentKind,
+                blocks: result.blocks,
+                ...(result.nextCursor ? { nextCursor: result.nextCursor } : {}),
+                ...(guidance ? { guidance } : {}),
+                warnings: result.warnings,
+                page: {
+                    cursor: cursor ?? null,
+                    nextCursor,
+                    hasMore: Boolean(result.nextCursor),
+                    maxBytes,
+                    timeoutMs,
+                    returnedBlocks: result.blocks.length,
+                    ...(blockIds.length > 0 ? { requestedBlockIds: blockIds } : {}),
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof OperationTimeoutError) {
+                return textResult({
+                    error: "scope_read_timeout",
+                    message: err.message,
+                    timeoutMs: err.timeoutMs,
+                }, true);
+            }
+            if (err instanceof McpDataReadError) {
+                if (err.status === 402) {
+                    const body = err.body;
+                    const challenge = body?.error?.details?.challenge;
+                    // Only a genuine PAYMENT_REQUIRED with a challenge is signable. A
+                    // gateway failure that also surfaces as 402 (e.g. PAYMENT_GATEWAY_ERROR
+                    // — insufficient escrow balance) is NOT signable; presenting it as a
+                    // challenge would make the client sign an error envelope in a loop.
+                    if (body?.error?.errorCode === "PAYMENT_REQUIRED" && challenge) {
+                        return textResult({
+                            payment_required: true,
+                            status: 402,
+                            challenge,
+                            message: "This read requires payment. Sign the x402 challenge and call read_scope again with the `payment` argument.",
+                        }, true);
+                    }
+                    // Gateway-side payment failure — surface the real error + remediation.
+                    return textResult({
+                        error: "payment_failed",
+                        status: 402,
+                        errorCode: body?.error?.errorCode ?? "PAYMENT_ERROR",
+                        message: body?.error?.message ??
+                            "Payment could not be completed (e.g. insufficient escrow balance). This is not a signable challenge; resolve the gateway error and retry.",
+                    }, true);
+                }
+                if (err.status === 503) {
+                    return textResult({
+                        error: "bounded_data_unavailable",
+                        status: err.status,
+                        body: err.body,
+                    }, true);
+                }
+                return textResult({ error: "data_read_failed", status: err.status, body: err.body }, true);
+            }
+            return textResult({
+                error: "tool_handler_error",
+                message: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    },
+};
+const listScopeBlocks = {
+    name: "list_scope_blocks",
+    title: "List scope blocks",
+    description: "Scope table of contents: block ids, paths, sizes. Feed ids to read_scope blockIds.",
+    inputSchema: {
+        scope: z.string().min(1).describe("Exact scope id."),
+        offset: z.number().int().min(0).optional(),
+        limit: z.number().int().min(1).max(MAX_LIST_BLOCKS_LIMIT).optional(),
+    },
+    async handler(args, { connection, readClient }) {
+        const scope = typeof args.scope === "string" ? args.scope : null;
+        if (!scope) {
+            return textResult({ error: "scope is required and must be a string" }, true);
+        }
+        const grant = resolveGrantForScope(connection, scope);
+        if (!grant) {
+            return textResult({
+                error: "scope_not_granted",
+                message: `Scope '${scope}' is not covered by any grant on this MCP connection.`,
+                grantedScopes: uniqueScopes(connection),
+            }, true);
+        }
+        if (typeof readClient.readBlockManifest !== "function") {
+            return textResult({
+                scope,
+                blocks: [],
+                manifestAvailable: false,
+                reason: "this server build does not expose block manifests",
+                nextStep: "Use read_scope with nextCursor, or search_personal_context.",
+            });
+        }
+        const offset = clampInteger(args.offset, 0, 0, Number.MAX_SAFE_INTEGER);
+        const limit = clampInteger(args.limit, DEFAULT_LIST_BLOCKS_LIMIT, 1, MAX_LIST_BLOCKS_LIMIT);
+        try {
+            const manifest = await withTimeout(readClient.readBlockManifest({ scope, grantId: grant.grantId }), LIST_BLOCKS_TIMEOUT_MS, `read block manifest for ${scope}`);
+            // Scopes stored before block sidecars existed, and scopes still
+            // indexing, simply have no manifest. That is not an error.
+            if (!manifest) {
+                return textResult({
+                    scope,
+                    grantId: grant.grantId,
+                    blocks: [],
+                    manifestAvailable: false,
+                    reason: "no block manifest for this scope yet; it may still be indexing",
+                    nextStep: "Use read_scope with nextCursor, or search_personal_context.",
+                });
+            }
+            const page = manifest.blocks.slice(offset, offset + limit);
+            const nextOffset = offset + page.length;
+            return textResult({
+                scope,
+                grantId: grant.grantId,
+                collectedAt: manifest.collectedAt,
+                contentKind: manifest.contentKind,
+                manifestAvailable: true,
+                totalBlocks: manifest.blocks.length,
+                blocks: page.map((block) => ({
+                    id: block.id,
+                    path: block.path,
+                    sizeBytes: block.sizeBytes,
+                    ...(block.itemCount === undefined
+                        ? {}
+                        : { itemCount: block.itemCount }),
+                })),
+                warnings: manifest.warnings,
+                page: {
+                    offset,
+                    limit,
+                    returnedBlocks: page.length,
+                    ...(nextOffset < manifest.blocks.length ? { nextOffset } : {}),
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof OperationTimeoutError) {
+                return textResult({
+                    error: "scope_blocks_timeout",
+                    message: err.message,
+                    timeoutMs: err.timeoutMs,
+                }, true);
+            }
+            if (err instanceof McpDataReadError) {
+                return textResult({ error: "data_read_failed", status: err.status, body: err.body }, true);
+            }
+            return textResult({
+                error: "tool_handler_error",
+                message: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    },
+};
+function encodeSearchCursor(payload) {
+    const json = JSON.stringify(payload);
+    // TextEncoder + Uint8Array → base64url without Node.js Buffer dependency
+    const bytes = new TextEncoder().encode(json);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function decodeSearchCursor(raw) {
+    try {
+        const base64 = raw.replace(/-/g, "+").replace(/_/g, "/");
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        const json = new TextDecoder().decode(bytes);
+        const payload = JSON.parse(json);
+        if (typeof payload === "object" &&
+            payload !== null &&
+            typeof payload.scopeIndex === "number") {
+            return {
+                scopeIndex: payload.scopeIndex,
+                blockCursor: typeof payload.blockCursor === "string"
+                    ? payload.blockCursor
+                    : undefined,
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const searchPersonalContext = {
+    name: SEARCH_PERSONAL_CONTEXT_TOOL,
+    title: "Search personal context",
+    description: "Search approved scopes. Omit scopes for default sweep; name scopes for targeted search. Continue with nextSearchCursor. Free discovery/preview — it does not settle payments; chargeable scopes are returned in paymentRequiredScopes, fetch those via read_scope with a `payment` proof.",
+    inputSchema: {
+        query: z.string().min(1).max(SEARCH_QUERY_MAX_CHARS),
+        scopes: z
+            .array(z.string().min(1).max(SEARCH_SCOPE_MAX_CHARS))
+            .max(SEARCH_REQUESTED_SCOPES_LIMIT)
+            .optional(),
+        cursor: z.string().min(1).optional(),
+        maxResults: z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional(),
+        limit: z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional(),
+        maxScopes: z.number().int().min(1).max(MAX_SEARCH_SCOPES).optional(),
+        timeoutMs: z.number().int().min(1000).max(MAX_SEARCH_TIMEOUT_MS).optional(),
+        maxBytes: z.number().int().min(1).max(MAX_SEARCH_MAX_BYTES).optional(),
+    },
+    async handler(args, { connection, readClient }) {
+        const query = typeof args.query === "string" ? args.query.trim() : "";
+        if (!query) {
+            return textResult({ error: "query is required and must be a non-empty string" }, true);
+        }
+        if (query.length > SEARCH_QUERY_MAX_CHARS) {
+            return textResult({
+                error: "query_too_long",
+                maxQueryChars: SEARCH_QUERY_MAX_CHARS,
+            }, true);
+        }
+        const normalizedScopes = normalizeRequestedScopes(args.scopes, connection);
+        const requestedScopes = normalizedScopes.requestedScopes;
+        // maxResults takes precedence over deprecated limit for forward compat
+        const limit = clampInteger(args.maxResults ?? args.limit, DEFAULT_SEARCH_LIMIT, 1, MAX_SEARCH_LIMIT);
+        const maxScopes = clampInteger(args.maxScopes, DEFAULT_SEARCH_MAX_SCOPES, 1, MAX_SEARCH_SCOPES);
+        const timeoutMs = clampInteger(args.timeoutMs, DEFAULT_SEARCH_TIMEOUT_MS, 1000, MAX_SEARCH_TIMEOUT_MS);
+        const maxBytes = clampInteger(args.maxBytes, DEFAULT_SEARCH_MAX_BYTES, 1, MAX_SEARCH_MAX_BYTES);
+        const totalTimeoutMs = Math.min(MAX_SEARCH_TOTAL_TIMEOUT_MS, timeoutMs);
+        const startedAt = Date.now();
+        const deadline = startedAt + totalTimeoutMs;
+        const discoveryTimeoutMs = Math.min(totalTimeoutMs, DEFAULT_SEARCH_DISCOVERY_TIMEOUT_MS);
+        // Decode continuation cursor if provided
+        const resumeCursor = typeof args.cursor === "string" ? decodeSearchCursor(args.cursor) : null;
+        const resolved = await resolveSearchScopes({
+            connection,
+            maxScopes,
+            discoveryTimeoutMs,
+            readClient,
+            requestedScopes,
+        });
+        const matches = [];
+        const searchedScopes = [];
+        const truncatedScopes = [];
+        // Chargeable scopes hit on a paid (self-signing) session. Search is a free
+        // discovery/preview surface and does not settle x402 payments — it surfaces
+        // these explicitly so the client retrieves them via read_scope with a
+        // `payment` proof, instead of burying the 402 as an opaque scope error.
+        const paymentRequiredScopes = [];
+        const errors = [...resolved.errors];
+        // When resuming, start from the scope index encoded in the cursor
+        const startScopeIndex = resumeCursor
+            ? Math.max(0, Math.min(resumeCursor.scopeIndex, resolved.scopes.length))
+            : 0;
+        const initialBlockCursor = resumeCursor?.blockCursor ?? undefined;
+        let nextSearchCursor;
+        for (let scopeIndex = startScopeIndex; scopeIndex < resolved.scopes.length; scopeIndex += 1) {
+            const scope = resolved.scopes[scopeIndex];
+            const remainingBeforeScope = deadline - Date.now();
+            if (remainingBeforeScope <= 0) {
+                // Budget exhausted — offer cursor to continue from this scope
+                nextSearchCursor = encodeSearchCursor({ scopeIndex });
+                errors.push({ scope, error: "search_total_timeout" });
+                break;
+            }
+            const grant = resolveGrantForScope(connection, scope);
+            if (!grant)
+                continue;
+            // The index preview path bypasses the data API auth port (and thus
+            // x402). Skip it when reads are payment-enforced so paid content is never
+            // previewed for free — search falls back to the paid bounded block read.
+            if (!resumeCursor &&
+                !readClient.enforcesPayment &&
+                typeof readClient.searchScopeIndex === "function") {
+                const remainingMs = deadline - Date.now();
+                if (remainingMs <= 0) {
+                    nextSearchCursor = encodeSearchCursor({ scopeIndex });
+                    errors.push({ scope, error: "search_total_timeout" });
+                    break;
+                }
+                const remainingScopes = resolved.scopes.length - scopeIndex;
+                const perScopeTimeoutMs = Math.min(Math.max(250, Math.floor(remainingMs / Math.max(1, remainingScopes))), remainingMs);
+                try {
+                    const indexed = await withTimeout(readClient.searchScopeIndex({
+                        scope,
+                        grantId: grant.grantId,
+                        query,
+                        maxResults: limit - matches.length,
+                    }), perScopeTimeoutMs, `search index for ${scope}`);
+                    if (indexed.status === "hit") {
+                        searchedScopes.push(scope);
+                        for (const hit of indexed.hits) {
+                            if (matches.length >= limit)
+                                break;
+                            matches.push({
+                                scope,
+                                grantId: grant.grantId,
+                                preview: hit.preview ?? hit.title ?? "",
+                                searchedChars: 0,
+                                truncated: false,
+                                blockRef: hit.blockRef,
+                                score: hit.score,
+                                terms: hit.terms,
+                            });
+                        }
+                        if (matches.length >= limit) {
+                            const nextScopeIndex = scopeIndex + 1;
+                            if (nextScopeIndex < resolved.scopes.length) {
+                                nextSearchCursor = encodeSearchCursor({
+                                    scopeIndex: nextScopeIndex,
+                                });
+                            }
+                            break;
+                        }
+                        continue;
+                    }
+                }
+                catch (err) {
+                    errors.push({
+                        scope,
+                        error: err instanceof OperationTimeoutError
+                            ? "scope_index_timeout"
+                            : "scope_index_failed",
+                        bodyPreview: stringifyPreview(err instanceof OperationTimeoutError
+                            ? err.message
+                            : "unexpected scope index failure"),
+                    });
+                }
+            }
+            // Use block cursor from resume only for the first scope we process
+            let cursor = scopeIndex === startScopeIndex ? initialBlockCursor : undefined;
+            let pageCount = 0;
+            let scopeTruncated = false;
+            let scopeSearched = false;
+            try {
+                while (pageCount < SEARCH_MAX_PAGES_PER_SCOPE) {
+                    const remainingMs = deadline - Date.now();
+                    if (remainingMs <= 0) {
+                        // Budget hit mid-scope — encode cursor pointing at this scope + block
+                        nextSearchCursor = encodeSearchCursor({
+                            scopeIndex,
+                            blockCursor: cursor,
+                        });
+                        errors.push({ scope, error: "search_total_timeout" });
+                        scopeTruncated = Boolean(cursor);
+                        break;
+                    }
+                    pageCount += 1;
+                    if (!scopeSearched) {
+                        searchedScopes.push(scope);
+                        scopeSearched = true;
+                    }
+                    const remainingScopes = resolved.scopes.length - scopeIndex;
+                    const perScopeTimeoutMs = Math.min(Math.max(250, Math.floor(remainingMs / Math.max(1, remainingScopes))), remainingMs);
+                    const result = await withTimeout(readClient.readScopeBlocks({
+                        scope,
+                        grantId: grant.grantId,
+                        cursor,
+                        maxBytes,
+                        tool: SEARCH_PERSONAL_CONTEXT_TOOL,
+                    }), perScopeTimeoutMs, `read blocks for ${scope}`);
+                    const pageText = blockPageSearchText(result.blocks);
+                    const { documents, textById } = blockPageSearchDocuments(scope, result.blocks);
+                    // Every hit the page can still contribute, not one per page: the
+                    // index is thrown away with the page, so a discarded hit is a block
+                    // the caller can never reach again.
+                    const pageHits = documents.length > 0
+                        ? MiniSearchIndex.build(documents).search({
+                            query,
+                            limit: limit - matches.length,
+                        })
+                        : [];
+                    for (const pageHit of pageHits) {
+                        if (matches.length >= limit)
+                            break;
+                        const hitText = textById.get(pageHit.id) ?? pageText;
+                        matches.push({
+                            scope,
+                            grantId: grant.grantId,
+                            collectedAt: result.collectedAt,
+                            preview: previewMatch(hitText, miniSearchMatchIndex(hitText, pageHit.terms)),
+                            searchedChars: pageText.length,
+                            truncated: Boolean(result.nextCursor),
+                            // The id of the block that matched, so the caller can fetch it
+                            // with read_scope({ blockIds }) instead of walking cursors.
+                            ...(pageHit.blockRef ? { blockRef: pageHit.blockRef } : {}),
+                            score: pageHit.score,
+                            terms: pageHit.terms,
+                        });
+                    }
+                    if (result.nextCursor) {
+                        cursor = result.nextCursor;
+                        if (pageCount >= SEARCH_MAX_PAGES_PER_SCOPE ||
+                            matches.length >= limit) {
+                            scopeTruncated = true;
+                            // More pages remain in this scope — cursor points here
+                            nextSearchCursor = encodeSearchCursor({
+                                scopeIndex,
+                                blockCursor: cursor,
+                            });
+                            break;
+                        }
+                        continue;
+                    }
+                    break;
+                }
+                if (scopeTruncated) {
+                    truncatedScopes.push(scope);
+                }
+            }
+            catch (err) {
+                const paymentChallenge = err instanceof McpDataReadError &&
+                    err.status === 402 &&
+                    err.body?.error?.errorCode ===
+                        "PAYMENT_REQUIRED";
+                if (paymentChallenge) {
+                    // Paid session hit a chargeable scope. Surface it as payment-required
+                    // (retrieve via read_scope with `payment`) rather than a scope error.
+                    // A gateway 402 (PAYMENT_GATEWAY_ERROR) falls through to `errors`.
+                    if (!paymentRequiredScopes.includes(scope)) {
+                        paymentRequiredScopes.push(scope);
+                    }
+                }
+                else {
+                    errors.push({
+                        scope,
+                        error: err instanceof OperationTimeoutError
+                            ? "scope_search_timeout"
+                            : "scope_read_failed",
+                        status: err instanceof McpDataReadError ? err.status : undefined,
+                        bodyPreview: stringifyPreview(err instanceof McpDataReadError
+                            ? err.body
+                            : err instanceof OperationTimeoutError
+                                ? err.message
+                                : "unexpected scope read failure"),
+                    });
+                }
+            }
+            if (matches.length >= limit) {
+                // Result limit hit — if more scopes remain, offer cursor for next scope.
+                // A cursor set inside the scope wins: it still has unread pages, and
+                // pointing past it would silently drop them.
+                const nextScopeIndex = scopeIndex + 1;
+                if (!nextSearchCursor && nextScopeIndex < resolved.scopes.length) {
+                    nextSearchCursor = encodeSearchCursor({
+                        scopeIndex: nextScopeIndex,
+                    });
+                }
+                break;
+            }
+        }
+        const elapsedMs = Date.now() - startedAt;
+        // Matches accumulate in page order, so a weak early hit would otherwise
+        // outrank a strong later one. Scores are only comparable within one page's
+        // index, but best-first is still strictly better than page order for the
+        // caller. Unscored matches (budget-exhausted fallback path) keep their
+        // relative order at the end.
+        matches.sort((a, b) => (b.score ?? -1) - (a.score ?? -1));
+        return textResult({
+            query,
+            results: matches,
+            // Backward-compatible alias for existing clients/tests. `results` is the
+            // canonical field, but removing `matches` is a separate migration.
+            matches,
+            searchedScopes,
+            skippedScopes: [
+                ...normalizedScopes.skippedScopes,
+                ...resolved.skippedScopes,
+            ],
+            truncatedScopes,
+            errors,
+            ...(paymentRequiredScopes.length > 0
+                ? {
+                    payment_required: true,
+                    paymentRequiredScopes,
+                    paymentHint: "These scopes are chargeable; search does not settle x402 payments. Retrieve each with read_scope (it returns a payment_required challenge; sign it and re-call read_scope with the `payment` argument).",
+                }
+                : {}),
+            ...(nextSearchCursor ? { nextSearchCursor } : {}),
+            elapsedMs,
+            limits: {
+                maxResults: limit,
+                maxScopes,
+                maxRequestedScopes: SEARCH_REQUESTED_SCOPES_LIMIT,
+                timeoutMs,
+                discoveryTimeoutMs,
+                queryChars: SEARCH_QUERY_MAX_CHARS,
+                scopeChars: SEARCH_SCOPE_MAX_CHARS,
+                previewChars: SEARCH_PREVIEW_CHARS,
+                requestedBytesPerPage: maxBytes,
+                maxPagesPerScope: SEARCH_MAX_PAGES_PER_SCOPE,
+                totalTimeoutMs,
+            },
+        });
+    },
+};
+const getScopeFile = {
+    name: "get_scope_file",
+    title: "Get scope file",
+    description: "Fetch an approved file/PDF scope. Defaults to metadata plus a resource link; set includeContent=true only when the client supports inline resource blobs. Use search_personal_context for extracted text.",
+    inputSchema: {
+        ...rawScopeFileInputSchema,
+        // x402 proof (see read_scope's `payment`); provide after a payment_required.
+        payment: z.string().optional(),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1000)
+            .max(MAX_READ_FILE_TIMEOUT_MS)
+            .optional(),
+    },
+    async handler(args, { connection, readClient }) {
+        const scope = typeof args.scope === "string" ? args.scope : null;
+        if (!scope) {
+            return textResult({ error: "scope is required and must be a string" }, true);
+        }
+        const grant = resolveGrantForScope(connection, scope);
+        if (!grant) {
+            return textResult({
+                error: "scope_not_granted",
+                message: `Scope '${scope}' is not covered by any grant on this MCP connection.`,
+                grantedScopes: uniqueScopes(connection),
+            }, true);
+        }
+        const at = typeof args.at === "string" ? args.at : undefined;
+        const fileId = typeof args.fileId === "string" ? args.fileId : undefined;
+        const includeContent = typeof args.includeContent === "boolean" ? args.includeContent : false;
+        const maxBytes = clampInteger(args.maxBytes, DEFAULT_READ_FILE_MAX_BYTES, 1, MAX_READ_FILE_MAX_BYTES);
+        const timeoutMs = clampInteger(args.timeoutMs, DEFAULT_READ_FILE_TIMEOUT_MS, 1000, MAX_READ_FILE_TIMEOUT_MS);
+        const resourceUri = rawScopeResourceUri({ scope, at, fileId });
+        const payment = typeof args.payment === "string" ? args.payment : undefined;
+        try {
+            const raw = await withTimeout(readClient.readRawScopeFile({
+                scope,
+                grantId: grant.grantId,
+                at,
+                fileId,
+                payment,
+            }), timeoutMs, `read raw file for ${scope}`);
+            const metadata = rawScopeMetadata(raw);
+            const base = {
+                ...metadata,
+                grantId: grant.grantId,
+                resourceUri,
+                includeContent,
+                maxBytes,
+                timeoutMs,
+            };
+            // A paid read settles a SINGLE-USE x402 payment for this fetch. A resource
+            // link would force a second, unpaid resources/read → another 402 that
+            // cannot be satisfied, so a paid read returns the bytes inline (regardless
+            // of includeContent) — BUT the hard size cap is still enforced to protect
+            // server/client memory and the MCP transport. An oversized paid file
+            // returns a structured error, never an inline dump; clients size maxBytes
+            // from the payment challenge's `sizeBytes` before paying.
+            const paidRead = Boolean(payment);
+            if (paidRead && raw.sizeBytes > maxBytes) {
+                return textResult({
+                    error: "paid_file_exceeds_max_bytes",
+                    status: 413,
+                    sizeBytes: raw.sizeBytes,
+                    maxBytes,
+                    message: "Payment settled, but the file exceeds maxBytes and is not returned inline. Retry with a larger maxBytes (and a fresh payment); files above the inline ceiling cannot be delivered over MCP.",
+                }, true);
+            }
+            if (!paidRead && (!includeContent || raw.sizeBytes > maxBytes)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ...base,
+                                contentIncluded: false,
+                                reason: !includeContent
+                                    ? "includeContent=false"
+                                    : "file exceeds maxBytes for inline MCP tool response",
+                                nextStep: "Use resources/read with resourceUri if your MCP client supports resources, or retry with a higher maxBytes if appropriate.",
+                            }),
+                        },
+                        {
+                            type: "resource_link",
+                            uri: resourceUri,
+                            name: raw.filename ?? scope,
+                            title: raw.filename ?? scope,
+                            description: `Raw file for ${scope}`,
+                            mimeType: raw.mimeType,
+                            size: raw.sizeBytes,
+                        },
+                    ],
+                    structuredContent: {
+                        ...base,
+                        contentIncluded: false,
+                    },
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ...base,
+                            contentIncluded: true,
+                            resourceType: "blob",
+                        }),
+                    },
+                    {
+                        type: "resource",
+                        resource: {
+                            uri: resourceUri,
+                            mimeType: raw.mimeType,
+                            blob: raw.contentBase64,
+                            _meta: metadata,
+                        },
+                    },
+                ],
+                structuredContent: {
+                    ...base,
+                    contentIncluded: true,
+                    resourceType: "blob",
+                },
+            };
+        }
+        catch (err) {
+            if (err instanceof OperationTimeoutError) {
+                return textResult({
+                    error: "scope_file_timeout",
+                    message: err.message,
+                    timeoutMs: err.timeoutMs,
+                }, true);
+            }
+            if (err instanceof McpDataReadError) {
+                if (err.status === 402) {
+                    const body = err.body;
+                    const challenge = body?.error?.details?.challenge;
+                    // Only a genuine PAYMENT_REQUIRED with a challenge is signable; a
+                    // gateway 402 (e.g. insufficient escrow) is surfaced as an error.
+                    if (body?.error?.errorCode === "PAYMENT_REQUIRED" && challenge) {
+                        // Surface the file size so the client can set maxBytes >= sizeBytes
+                        // BEFORE paying — a paid read must fit the inline size cap (the
+                        // single-use payment can't fund a second resources/read).
+                        let meta = null;
+                        try {
+                            meta = await readClient.getScopeMetadata(scope);
+                        }
+                        catch {
+                            meta = null;
+                        }
+                        const sizeBytes = meta?.sizeBytes;
+                        return textResult({
+                            payment_required: true,
+                            status: 402,
+                            challenge,
+                            ...(typeof sizeBytes === "number"
+                                ? { sizeBytes, recommendedMaxBytes: sizeBytes }
+                                : {}),
+                            message: "This file requires payment. Sign the x402 challenge and call get_scope_file again with the `payment` argument" +
+                                (typeof sizeBytes === "number"
+                                    ? ` and maxBytes >= ${sizeBytes}.`
+                                    : "."),
+                        }, true);
+                    }
+                    return textResult({
+                        error: "payment_failed",
+                        status: 402,
+                        errorCode: body?.error?.errorCode ?? "PAYMENT_ERROR",
+                        message: body?.error?.message ??
+                            "Payment could not be completed. This is not a signable challenge; resolve the gateway error and retry.",
+                    }, true);
+                }
+                return textResult({
+                    error: err.status === 404
+                        ? "scope_file_not_found"
+                        : "scope_file_read_failed",
+                    status: err.status,
+                    body: err.body,
+                }, true);
+            }
+            return textResult({
+                error: "tool_handler_error",
+                message: err instanceof Error ? err.message : String(err),
+            }, true);
+        }
+    },
+};
+export const MCP_TOOLS = [
+    listGrantedSources,
+    listGrantedScopes,
+    requestScopeAccess,
+    readScope,
+    listScopeBlocks,
+    getScopeFile,
+    searchPersonalContext,
+];
+//# sourceMappingURL=tools.js.map