@opendatalabs/personal-server-ts-core 0.0.1-canary.01ca694 → 0.0.1-canary.052d47e

package/dist/mcp/tools.js

@@ -2,7 +2,7 @@
  * 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-management tools. No raw owner/admin status tools.
+ * 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
@@ -12,10 +12,16 @@
 import { z } from "zod";
 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";
 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, null, 2);
+    const text = typeof value === "string" ? value : JSON.stringify(value);
     const textBytes = resultTextEncoder.encode(text).byteLength;
     const structuredContent = !isError &&
         textBytes <= STRUCTURED_CONTENT_TEXT_LIMIT_BYTES &&
@@ -60,24 +66,89 @@ function uniqueSources(connection) {
     }
     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 DEFAULT_SEARCH_MAX_SCOPES = 10;
-const MAX_SEARCH_SCOPES = 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 = 300_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 = 300_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 = 300_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 SEARCH_MAX_PAGES_PER_SCOPE = 16;
+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;
@@ -403,7 +474,7 @@ const listGrantedSources = {
 const listGrantedScopes = {
     name: "list_granted_scopes",
     title: "List granted scopes",
-    description: "List granted scopes with dataStatus, sizeClass, sizeBytes, and recommendedAccess ('read' for small scopes, 'search' for large/huge scopes, 'wait' while indexing). Call first, then follow recommendedAccess.",
+    description: "List granted scopes, readiness, size, and recommendedAccess. Call first.",
     inputSchema: {},
     async handler(_args, { connection, readClient }) {
         const grantedScopes = uniqueScopes(connection);
@@ -451,24 +522,70 @@ const listGrantedScopes = {
         return textResult({ scopes: scopeEntries });
     },
 };
+const requestScopeAccess = {
+    name: "request_scope_access",
+    title: "Request scope access",
+    description: "Check which requested scopes are missing from this MCP grant and tell the user to approve them in Vana.",
+    inputSchema: {
+        scopes: z
+            .array(z.string().min(1).max(SEARCH_SCOPE_MAX_CHARS))
+            .min(1)
+            .max(SEARCH_REQUESTED_SCOPES_LIMIT)
+            .describe("Exact scope ids the MCP client wants to read."),
+        reason: z
+            .string()
+            .max(500)
+            .optional()
+            .describe("Brief reason to show the user."),
+    },
+    async handler(args, { connection }) {
+        const requestedScopes = normalizeScopeListInput(args.scopes);
+        const grantedRequestedScopes = requestedScopes.filter((scope) => Boolean(resolveGrantForScope(connection, scope)));
+        const missingScopes = requestedScopes.filter((scope) => !resolveGrantForScope(connection, scope));
+        const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+        const approvalRequired = missingScopes.length > 0;
+        return textResult({
+            approvalRequired,
+            client: {
+                id: connection.id,
+                displayName: connection.displayName,
+                status: connection.status,
+            },
+            requestedScopes,
+            grantedRequestedScopes,
+            missingScopes,
+            grantedScopes: uniqueScopes(connection),
+            reason: reason || undefined,
+            nextAction: approvalRequired
+                ? "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",
     title: "Read scope",
-    description: "Read one full approved scope as bounded blocks. Best for tiny/small/medium scopes (see sizeClass from list_granted_scopes). For large/huge scopes prefer search_personal_context — a full read returns many pages you must walk via nextCursor and is slow. The response includes a `guidance` hint when a scope is large enough that search is the better tool.",
+    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, e.g. 'instagram.profile'."),
+        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("Wall-clock read budget in ms. Capped at 300000 by the server."),
+            .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;
@@ -484,6 +601,7 @@ const readScope = {
             }, 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;
@@ -516,12 +634,15 @@ const readScope = {
                 // 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,
+                ...(blockIds.length > 0 ? { blockIds } : {}),
             }), timeoutMs, `read blocks for ${scope}`);
             const nextCursor = result.nextCursor ?? null;
             return textResult({
@@ -540,6 +661,7 @@ const readScope = {
                     maxBytes,
                     timeoutMs,
                     returnedBlocks: result.blocks.length,
+                    ...(blockIds.length > 0 ? { requestedBlockIds: blockIds } : {}),
                 },
             });
         }
@@ -552,6 +674,30 @@ const readScope = {
                 }, 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",
@@ -568,6 +714,97 @@ const readScope = {
         }
     },
 };
+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
@@ -610,28 +847,18 @@ function decodeSearchCursor(raw) {
 const searchPersonalContext = {
     name: "search_personal_context",
     title: "Search personal context",
-    description: "Search approved scopes by keyword — the preferred way to pull from large/huge scopes without reading every page. Omit scopes to sweep all small ready data; name scopes (including large ones) to target them. Continue with nextSearchCursor.",
+    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()
-            .describe("Continuation cursor from a prior search response's nextSearchCursor."),
+        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()
-            .describe("Wall-clock budget in ms. Capped at 300000 by the server."),
+        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 }) {
@@ -668,6 +895,11 @@ const searchPersonalContext = {
         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
@@ -687,7 +919,12 @@ const searchPersonalContext = {
             const grant = resolveGrantForScope(connection, scope);
             if (!grant)
                 continue;
-            if (!resumeCursor && typeof readClient.searchScopeIndex === "function") {
+            // 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 });
@@ -746,7 +983,6 @@ const searchPersonalContext = {
             // Use block cursor from resume only for the first scope we process
             let cursor = scopeIndex === startScopeIndex ? initialBlockCursor : undefined;
             let pageCount = 0;
-            let scopeHasMatch = false;
             let scopeTruncated = false;
             let scopeSearched = false;
             try {
@@ -777,11 +1013,18 @@ const searchPersonalContext = {
                     }), 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: 1 })
+                        ? MiniSearchIndex.build(documents).search({
+                            query,
+                            limit: limit - matches.length,
+                        })
                         : [];
-                    const pageHit = pageHits[0];
-                    if (pageHit && matches.length < limit && !scopeHasMatch) {
+                    for (const pageHit of pageHits) {
+                        if (matches.length >= limit)
+                            break;
                         const hitText = textById.get(pageHit.id) ?? pageText;
                         matches.push({
                             scope,
@@ -790,8 +1033,12 @@ const searchPersonalContext = {
                             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,
                         });
-                        scopeHasMatch = true;
                     }
                     if (result.nextCursor) {
                         cursor = result.nextCursor;
@@ -814,23 +1061,39 @@ const searchPersonalContext = {
                 }
             }
             catch (err) {
-                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"),
-                });
+                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
+                // 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 (nextScopeIndex < resolved.scopes.length) {
+                if (!nextSearchCursor && nextScopeIndex < resolved.scopes.length) {
                     nextSearchCursor = encodeSearchCursor({
                         scopeIndex: nextScopeIndex,
                     });
@@ -839,6 +1102,12 @@ const searchPersonalContext = {
             }
         }
         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,
@@ -852,6 +1121,13 @@ const searchPersonalContext = {
             ],
             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: {
@@ -870,10 +1146,201 @@ const searchPersonalContext = {
         });
     },
 };
+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