@zackbart/connecta 0.24.3 → 0.25.0

package/dist/meta-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { advertisedSchema } from "./advertised-schema.js";
 import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPolicyError, groupedSearchResult, MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, } from "./catalog-service.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, msg } from "./errors.js";
@@ -7,6 +8,7 @@ import { InvocationService, } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
 import { hasConnectorGuides, listSkills, resolveSkill, } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, };
 const RESULT_TTL_SECONDS = 900;
 const enc = new TextEncoder();
@@ -99,19 +101,103 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
     }
     return e;
 }
-/** Stash a completed result, or return a notice without a paging route. */
-async function stashResult(bytes, results) {
+/** Prefix of the chunked paging envelope; `v1`'s single inline key still reads. */
+const RESULT_ENVELOPE_V2 = "connecta-result-v2:";
+/**
+ * The current envelope: v2's header plus the inline cap of the call that
+ * stashed it, `<total>:<chunk>:<cap>:`, so get_result can clamp a page to the
+ * connector's own cap without the stash carrying connector identity.
+ */
+const RESULT_ENVELOPE_V3 = "connecta-result-v3:";
+const RESULT_ENVELOPE_V3_HEADER = new RegExp(`^${RESULT_ENVELOPE_V3}(\\d+):(\\d+):(\\d+):`);
+/** `<total bytes>:<bytes per chunk>:` follow the prefix, then chunk 0's base64. */
+const RESULT_ENVELOPE_V2_HEADER = new RegExp(`^${RESULT_ENVELOPE_V2}(\\d+):(\\d+):`);
+/**
+ * Smallest chunk of result text stored under one key. A multiple of three so
+ * every chunk's base64 stands alone and a byte offset inside it lands on a
+ * whole quad, and about twice the 24,000-byte default page so a default page
+ * reads one or two chunks rather than dozens.
+ */
+const RESULT_CHUNK_BYTES = 49_152;
+/**
+ * Keys one stashed result may occupy. Chunking trades write count for read
+ * count, and both are real: every chunk is a storage write at stash time, and
+ * `fileStorage` rewrites its whole file per write. Above roughly 1.5 MB the
+ * chunks widen instead of multiplying, so a result costs a bounded number of
+ * writes and a page still reads a small fraction of it.
+ */
+const RESULT_MAX_CHUNKS = 32;
+/** Chunk width for a result of `totalBytes`, always a multiple of three. */
+function resultChunkBytes(totalBytes) {
+    return Math.max(RESULT_CHUNK_BYTES, Math.ceil(totalBytes / RESULT_MAX_CHUNKS / 3) * 3);
+}
+/**
+ * Base64 of `bytes`, in three-byte-aligned batches so the argument list of one
+ * spread never grows with the result. Alignment matters: an unaligned batch
+ * would pad mid-stream and the concatenation would no longer decode.
+ */
+function base64Of(bytes) {
+    let out = "";
+    for (let offset = 0; offset < bytes.length; offset += 12_288) {
+        out += btoa(String.fromCharCode(...bytes.subarray(offset, offset + 12_288)));
+    }
+    return out;
+}
+/** Opens a write's notice, ahead of any paging instruction. */
+const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see its result.";
+/**
+ * Offers a read the route meta-tools.md prefers for finding something in it:
+ * repeat the call inside a program and reduce it there. Paging comes second,
+ * for reading the whole thing. Led by paging alone, the eval's weakest model
+ * read a 185 KB log in eight pages, skipped the range holding the answer, and
+ * reported the decoy near the top instead. A write never gets this: repeating
+ * it is the one thing its notice forbids.
+ */
+const READ_REDUCE_FIRST = "To find something specific, repeat this read inside execute_code with connecta.call and filter or search the result there, returning only what matters";
+function pagingHint(results, totalBytes, preview) {
+    if (!results.write) {
+        const [shown, full] = preview.kind === "prefix"
+            ? [`Bytes 0-${preview.bytes} of ${totalBytes} follow.`, "to read it in full, page the rest"]
+            : preview.kind === "text-of-envelope"
+                ? ["Its text follows.", `to read the full ${totalBytes}-byte content array as JSON, page it`]
+                : [`The result is ${totalBytes} bytes.`, "to read it in full, page it"];
+        return `${shown} ${READ_REDUCE_FIRST}; ${full} with get_result using nextAction.`;
+    }
+    const body = preview.kind === "prefix"
+        ? `Bytes 0-${preview.bytes} of ${totalBytes} follow; page the rest with get_result using nextAction.`
+        : preview.kind === "text-of-envelope"
+            ? `Its text follows; page the full ${totalBytes}-byte content array as JSON with get_result using nextAction.`
+            : `Page all ${totalBytes} bytes with get_result using nextAction.`;
+    return `${WRITE_ALREADY_RAN} ${body}`;
+}
+/**
+ * Stash a completed result and describe it with a notice that leads whatever
+ * the caller returns, or a notice without a paging route when stashing fails.
+ *
+ * The notice goes first because clients cut oversized results from the end:
+ * Claude Code keeps the first 2,000 characters of a result it spills to disk,
+ * and a notice at the tail never reached the agent (see
+ * documentation/meta-tools.md#result-representation). It is one compact JSON
+ * line with no raw newline, so the preview starts after the first `\n`.
+ */
+async function stashResult(bytes, results, preview) {
     const totalBytes = bytes.length;
     const id = crypto.randomUUID();
     try {
-        // Base64 permits byte-range decoding after a KV read, without scanning or
-        // re-encoding all preceding text. Each chunk is a multiple of three bytes.
-        const chunks = [];
-        for (let offset = 0; offset < bytes.length; offset += 12_288) {
-            chunks.push(btoa(String.fromCharCode(...bytes.subarray(offset, offset + 12_288))));
+        // Base64 permits byte-range decoding, and splitting the envelope across
+        // keys keeps a page's storage read proportional to the page instead of to
+        // the whole result (issue #540). Chunk 0 carries the header; the get_result
+        // reader below maps a byte offset back to chunk index and base64 quad.
+        const chunkBytes = resultChunkBytes(totalBytes);
+        const chunks = [`${RESULT_ENVELOPE_V3}${totalBytes}:${chunkBytes}:${results.cap}:`];
+        for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
+            const chunk = base64Of(bytes.subarray(offset, offset + chunkBytes));
+            if (offset === 0)
+                chunks[0] += chunk;
+            else
+                chunks.push(chunk);
         }
-        const stored = `connecta-result-v1:${totalBytes}:${chunks.join("")}`;
-        if (!await results.set(`result:${id}`, stored, RESULT_TTL_SECONDS)) {
+        if (!await results.set(`result:${id}`, chunks, RESULT_TTL_SECONDS)) {
             throw new Error("Result stash capacity exhausted");
         }
     }
@@ -127,25 +213,37 @@ async function stashResult(bytes, results) {
         return {
             truncated: true,
             totalBytes,
-            hint: "Paging is unavailable. Use execute_code to reduce read-only results before returning them. Do not repeat a completed write to recover its result.",
+            hint: results.write
+                ? `Paging is unavailable. ${WRITE_ALREADY_RAN}`
+                : "Paging is unavailable. Use execute_code to reduce read-only results before returning them.",
         };
     }
     return {
         truncated: true,
         resultId: id,
         totalBytes,
-        hint: "use get_result {id, offset} to page the complete direct-call result",
+        hint: pagingHint(results, totalBytes, preview),
         nextAction: {
             tool: "get_result",
-            arguments: { id, offset: 0 },
+            arguments: { id, offset: preview.kind === "prefix" ? preview.bytes : 0 },
         },
     };
 }
+/** The first `cap` bytes of `bytes`, ending on a character boundary. */
+function headOf(bytes, cap) {
+    return bytes.subarray(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length));
+}
+/** One text block: the notice line, then the preview. */
+function noticeFirst(notice, preview) {
+    return { content: [{ type: "text", text: `${JSON.stringify(notice)}\n${preview}` }] };
+}
 /**
  * Return `text` as a single content block; if it exceeds `cap` bytes, stash the
- * full text and return the first `cap` bytes followed by a JSON truncation
- * notice pointing at get_result. `bytes` is `text` already encoded, so a caller
- * that had to measure it to make this decision doesn't encode it twice.
+ * full text and return a JSON truncation notice pointing at get_result,
+ * followed by the first `cap` bytes. The preview is a byte prefix of what
+ * pages, so the notice's next action continues where it stops. `bytes` is
+ * `text` already encoded, so a caller that had to measure it to make this
+ * decision doesn't encode it twice.
  */
 async function guardEncoded(text, bytes, results, cap) {
     if (bytes.length <= cap) {
@@ -154,14 +252,12 @@ async function guardEncoded(text, bytes, results, cap) {
             truncated: false,
         };
     }
-    const notice = await stashResult(bytes, results);
-    const head = dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length)));
-    return {
-        result: {
-            content: [{ type: "text", text: `${head}\n${JSON.stringify(notice)}` }],
-        },
-        truncated: true,
-    };
+    const head = headOf(bytes, cap);
+    const notice = await stashResult(bytes, results, {
+        kind: "prefix",
+        bytes: head.length,
+    });
+    return { result: noticeFirst(notice, dec.decode(head)), truncated: true };
 }
 /** {@link guardEncoded} over a string that has not been measured yet. */
 async function guardText(text, results, cap) {
@@ -179,34 +275,62 @@ async function guardValue(value, results, cap) {
     const bytes = enc.encode(text);
     if (bytes.length <= cap)
         return { result: value, truncated: false };
-    const notice = await stashResult(bytes, results);
+    const notice = await stashResult(bytes, results, { kind: "none" });
     return {
         result: notice.resultId ? notice : {
             ...notice,
-            preview: dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length))),
+            preview: escapedHeadOf(bytes, cap),
         },
         truncated: true,
     };
 }
 /**
- * Bound a downstream MCP `content` array by `cap`, measuring the serialized
- * envelope — the same string that gets stashed and paged, and the one that
- * counts every block rather than only the text ones.
+ * The longest head of `bytes` whose JSON string form fits `cap` bytes. Value
+ * mode carries an unpageable preview inside its JSON envelope, where escaping
+ * could double a quote-heavy head cut at `cap` bytes; a response that only
+ * exists because paging failed must not be the one that breaks the cap.
+ */
+function escapedHeadOf(bytes, cap) {
+    let limit = cap;
+    for (;;) {
+        const head = limit === 0 ? "" : dec.decode(headOf(bytes, limit));
+        const escaped = enc.encode(JSON.stringify(head)).length;
+        if (escaped <= cap || limit === 0)
+            return head;
+        limit = Math.max(0, Math.min(limit - 1, Math.floor((limit * cap) / escaped)));
+    }
+}
+/**
+ * Bound a downstream MCP `content` array by `cap`.
+ *
+ * A lone text block is measured, stashed, previewed, and paged as its text:
+ * its envelope adds nothing but a wrapper and a second layer of JSON escaping,
+ * which made a JSON payload's preview unreadable and inflated every page.
  *
- * Both halves matter (issue #43). Measuring only text blocks meant an oversized
- * all-image result scored zero bytes and was returned inline unbounded, with no
- * `resultId` to page from; and measuring one string while truncating another
- * left `totalBytes` and the served head describing something the cap was never
+ * Anything else is measured as the serialized envelope — the same string that
+ * gets stashed and paged, and the one that counts every block rather than only
+ * the text ones. Both halves matter (issue #43). Measuring only text blocks
+ * meant an oversized all-image result scored zero bytes and was returned inline
+ * unbounded, with no `resultId` to page from; and measuring one string while
+ * truncating another left `totalBytes` describing something the cap was never
  * compared against.
  *
- * Over the cap, what a client gets depends on whether a prefix is usable. An
- * all-text envelope keeps the historical head + notice — a JSON prefix is still
- * readable. An envelope carrying non-text blocks is replaced by the notice
- * alone: the head of a half-written base64 image is of no use to anyone, and
- * cutting one leaves unparseable block structure behind. Either way the full
- * envelope is stashed and pages through `get_result`.
+ * Over the cap, what a client gets depends on whether a preview is usable.
+ * Several text blocks preview as their text joined by newlines, while
+ * get_result pages the envelope from offset 0, where the block boundaries
+ * live. An envelope carrying non-text blocks is replaced by the notice alone:
+ * the head of a half-written base64 image is of no use to anyone. Either way
+ * the full envelope is stashed and pages through `get_result`.
  */
 async function guardContent(content, results, cap) {
+    const only = content.length === 1 ? content[0] : undefined;
+    if (only?.type === "text" && typeof only.text === "string") {
+        const bytes = enc.encode(only.text);
+        // Under the cap the block passes through untouched, annotations included.
+        if (bytes.length <= cap)
+            return { result: { content }, truncated: false };
+        return guardEncoded(only.text, bytes, results, cap);
+    }
     let text;
     try {
         text = JSON.stringify(content);
@@ -225,9 +349,14 @@ async function guardContent(content, results, cap) {
         return { result: { content }, truncated: false };
     }
     if (content.every((b) => b.type === "text")) {
-        return guardEncoded(text, bytes, results, cap);
+        const joined = enc.encode(content.map((b) => b.text).join("\n"));
+        const notice = await stashResult(bytes, results, { kind: "text-of-envelope" });
+        return {
+            result: noticeFirst(notice, dec.decode(headOf(joined, cap))),
+            truncated: true,
+        };
     }
-    const notice = await stashResult(bytes, results);
+    const notice = await stashResult(bytes, results, { kind: "none" });
     return {
         result: { content: [{ type: "text", text: JSON.stringify(notice) }] },
         truncated: true,
@@ -270,6 +399,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
         defer: opts.defer,
+        requestSignal: opts.requestSignal,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
     });
@@ -288,13 +418,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 : {}),
             unwrapResult: call.resultMode === "value",
             processResult: async (result, resolved) => {
-                const results = {
-                    set: (key, value, ttlSeconds) => registry.stashResult(key, value, ttlSeconds),
-                    warn: () => registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger.warn("[connecta] result paging unavailable", {
-                        connector: resolved.connector.id,
-                        tool: resolved.toolName,
-                    }),
-                };
                 // Result-size cap for THIS call: the connector's own override wins,
                 // then the deployment-wide value, then the built-in default (already
                 // folded into `globalCap`). Resolved per call so one request can
@@ -302,6 +425,15 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 // override the registry already warned about at startup is dropped
                 // here, so the connector simply inherits `globalCap`.
                 const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
+                const results = {
+                    write: !isExplicitlyReadOnly(resolved.definition),
+                    cap,
+                    set: (key, value, ttlSeconds) => registry.stashResult(key, value, ttlSeconds),
+                    warn: () => registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger.warn("[connecta] result paging unavailable", {
+                        connector: resolved.connector.id,
+                        tool: resolved.toolName,
+                    }),
+                };
                 const processed = (toolResult, truncated, value) => ({
                     toolResult,
                     ...value,
@@ -449,39 +581,83 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
             const results = registry.resultsStorage();
-            let stored;
-            try {
-                stored = await results.get(`result:${args.id}`);
-            }
-            catch {
-                return {
-                    ...jsonResult({
-                        error: {
-                            code: "unavailable",
-                            message: "Result paging storage is unavailable.",
-                            retryable: true,
-                        },
-                    }),
-                    isError: true,
-                };
-            }
-            if (stored === null || stored === undefined) {
+            const unavailableResult = () => ({
+                ...jsonResult({
+                    error: {
+                        code: "unavailable",
+                        message: "Result paging storage is unavailable.",
+                        retryable: true,
+                    },
+                }),
+                isError: true,
+            });
+            // `false` is a storage failure — retryable, and distinct from an id that
+            // is simply gone. Every key a page touches answers the same way, so a
+            // backend that dies halfway through a multi-chunk page says so.
+            const read = async (key) => {
+                try {
+                    return await results.get(key) ?? null;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const stored = await read(`result:${args.id}`);
+            if (stored === false)
+                return unavailableResult();
+            if (stored === null) {
                 return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
             }
             const requestedOffset = args.offset ?? 0;
-            const maxBytes = args.maxBytes ?? globalCap;
-            // Decode only this page plus UTF-8 boundary lookaround. Legacy raw-text
-            // entries remain readable for their short TTL after an upgrade.
-            const header = /^connecta-result-v1:(\d+):/.exec(stored.slice(0, 64));
+            // Read and decode only the chunks this page covers, plus a few bytes of
+            // UTF-8 boundary lookaround. Pre-upgrade entries stay readable for their
+            // short TTL: v2 is this format without the recorded cap, v1 inlined the
+            // whole envelope under one key, which is v2 with a single chunk as wide
+            // as the result, and raw text before that still pays one full encode
+            // per page.
+            const current = RESULT_ENVELOPE_V3_HEADER.exec(stored.slice(0, 96));
+            const chunked = current ?? RESULT_ENVELOPE_V2_HEADER.exec(stored.slice(0, 80));
+            const inline = chunked ? null : /^connecta-result-v1:(\d+):/.exec(stored.slice(0, 64));
+            const header = chunked ?? inline;
+            // A page never exceeds the inline cap of the call that stashed it — the
+            // connector's override when it had one — whatever maxBytes asks for.
+            // Clients cut an oversized page exactly as they cut the original result,
+            // so honouring a larger request would hand the agent an error in place
+            // of its data. Entries from before the cap was recorded use the
+            // deployment-wide one.
+            const cap = current ? Number(current[3]) : globalCap;
+            const maxBytes = Math.min(args.maxBytes ?? cap, cap);
             let bytes;
             let total;
             let start = 0;
             if (header) {
                 total = Number(header[1]);
+                const chunkBytes = chunked ? Number(chunked[2]) : Math.max(total, 1);
                 start = Math.floor(Math.max(0, Math.min(requestedOffset, total) - 3) / 3) * 3;
                 const end = Math.min(total, requestedOffset + maxBytes + 4);
-                const binary = atob(stored.slice(header[0].length + start / 3 * 4, header[0].length + Math.ceil(end / 3) * 4));
-                bytes = Uint8Array.from(binary, char => char.charCodeAt(0));
+                bytes = new Uint8Array(Math.max(0, end - start));
+                const lastChunk = Math.floor(Math.max(end - 1, start) / chunkBytes);
+                for (let index = Math.floor(start / chunkBytes); index <= lastChunk; index++) {
+                    const encoded = index === 0
+                        ? stored.slice(header[0].length)
+                        : await read(`result:${args.id}#${index}`);
+                    if (encoded === false)
+                        return unavailableResult();
+                    if (encoded === null) {
+                        // A chunk expired or was evicted under its own header; the id can no
+                        // longer serve this range, and inventing U+0000 filler would be worse.
+                        return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                    }
+                    const chunkStart = index * chunkBytes;
+                    // Both bounds are chunk-local. `from` inherits `start`'s three-byte
+                    // alignment because every chunk boundary is a multiple of three.
+                    const from = Math.max(start, chunkStart) - chunkStart;
+                    const to = Math.min(end, chunkStart + chunkBytes, total) - chunkStart;
+                    const binary = atob(encoded.slice(from / 3 * 4, Math.ceil(to / 3) * 4));
+                    for (let at = from; at < to; at++) {
+                        bytes[chunkStart + at - start] = binary.charCodeAt(at - from);
+                    }
+                }
             }
             else {
                 bytes = enc.encode(stored);
@@ -493,23 +669,29 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             // the boundary at or before it, and it is what the response reports back
             // as `offset` (issue #38).
             const offset = start + alignStartToCharBoundary(bytes, requestedOffset - start);
-            // Page size only: a stashed result carries no connector identity, so
-            // get_result keeps the deployment-wide default when none is requested.
-            // Both sides are validated by now — the argument above, `globalCap` at
-            // intake — so `offset + maxBytes` always reaches past `offset`.
+            // Both sides of `maxBytes` are validated by now — the argument above, the
+            // cap at intake — so `offset + maxBytes` always reaches past `offset`.
             // Align the slice end to a codepoint boundary so a multi-byte char is
             // never split across pages (which would emit U+FFFD on both sides).
             // `nextOffset` is this aligned end, so it is a valid boundary for the
             // next call and paging reassembles the original byte-for-byte.
             const end = start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start);
             const slice = dec.decode(bytes.subarray(offset - start, end - start));
-            const nextOffset = end < total ? end : undefined;
-            return jsonResult({
+            const hasMore = end < total;
+            // The same notice-first shape as a truncated call: one line of header,
+            // then the page as raw text. A JSON `text` field escaped every quote and
+            // newline in the page — a second layer over JSON payloads — which
+            // inflated pages past the size clients accept and made them hard to read.
+            return noticeFirst({
+                resultId: args.id,
                 offset,
-                ...(nextOffset !== undefined ? { nextOffset } : {}),
+                bytes: Math.max(0, end - offset),
                 totalBytes: total,
-                text: slice,
-            });
+                hasMore,
+                ...(hasMore
+                    ? { nextAction: { tool: "get_result", arguments: { id: args.id, offset: end } } }
+                    : {}),
+            }, slice);
         },
         async authorizeConnector(args) {
             const connector = registry.getConnector(args.connector);
@@ -601,7 +783,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
 const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required work before call_destructive_tool. Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses.`;
 const CALL_DESC = 'Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a get_result action.';
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
-const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns text, offset, nextOffset when more remains, and totalBytes.";
+const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns a one-line JSON header (offset, bytes, totalBytes, hasMore, nextAction) and then the page as raw text. maxBytes is an upper bound, clamped to the result's inline cap.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
 const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage only when the always-loaded instructions are insufficient or a program needs repair.';
 /**
@@ -648,6 +830,42 @@ const CALL_INPUT_SCHEMA = {
     timeoutMs: z.number().int().positive().optional(),
     diagnostics: z.boolean().optional(),
 };
+// The six input schemas, built once at module scope so their JSON Schema is
+// derived once per process (see advertisedSchema). Nothing here may read
+// deployment configuration or the request's identity: anything that varies
+// belongs in the per-registration description instead.
+const SKILLS_INPUT = advertisedSchema(z.object({ name: z.string().optional() }));
+const SEARCH_INPUT = advertisedSchema(z.object({
+    query: z.string().optional(),
+    connector: z.string().optional(),
+    safety: z.enum(["readOnly", "approvalRequired", "all"]).optional(),
+    limit: z.number().int().positive().max(MAX_SEARCH_LIMIT).optional(),
+    offset: z.number().int().nonnegative().optional(),
+    fullDescriptions: z.boolean().optional(),
+    includeSchemas: z.enum(["compact", "json", "typescript"]).optional(),
+}));
+const CALL_INPUT = advertisedSchema(z.strictObject(CALL_INPUT_SCHEMA));
+const CALL_DESTRUCTIVE_INPUT = advertisedSchema(z.strictObject({
+    ...CALL_INPUT_SCHEMA,
+    // Bounded above, but with no lower bound: a model that sends `""` or
+    // whitespace has written no reason, and failing an entire consequential
+    // call over a cosmetic field the host merely displays is the wrong
+    // trade. It is normalized to absent in the handler instead.
+    reason: z.string().max(500).optional(),
+}));
+const AUTHORIZE_INPUT = advertisedSchema(z.object({
+    connector: z.string(),
+    force: z.boolean().optional(),
+}));
+const GET_RESULT_INPUT = advertisedSchema(z.object({
+    id: z.string(),
+    // Both bounds are the shared rules (isValidResultOffset,
+    // isValidMaxResultBytes) expressed for the wire: spelling them against
+    // the same constants keeps the schema from drifting away from the
+    // in-handler checks if either floor ever moves.
+    offset: z.number().int().min(MIN_RESULT_OFFSET).optional(),
+    maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
+}));
 /**
  * Register the six explicit meta-tools onto an McpServer instance.
  * `registerExecuteTool` adds the seventh, `execute_code`. Broad discovery and
@@ -669,41 +887,24 @@ export function registerMetaTools(server, registry, ctx) {
     });
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),
-        inputSchema: z.object({ name: z.string().optional() }),
+        inputSchema: SKILLS_INPUT,
         annotations: READ_ONLY_LOCAL,
     }, async (args) => mt.skills(args));
     server.registerTool("search_tools", {
         description: describedFor(registry, SEARCH_DESC, "search"),
-        inputSchema: z.object({
-            query: z.string().optional(),
-            connector: z.string().optional(),
-            safety: z
-                .enum(["readOnly", "approvalRequired", "all"])
-                .optional(),
-            limit: z.number().int().positive().max(MAX_SEARCH_LIMIT).optional(),
-            offset: z.number().int().nonnegative().optional(),
-            fullDescriptions: z.boolean().optional(),
-            includeSchemas: z.enum(["compact", "json"]).optional(),
-        }),
+        inputSchema: SEARCH_INPUT,
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.searchTools(args));
     server.registerTool("call_tool", {
         description: CALL_DESC,
-        inputSchema: z.strictObject(CALL_INPUT_SCHEMA),
+        inputSchema: CALL_INPUT,
         // call_tool admits only tools that are themselves explicitly read-only;
         // anything else is refused and routed to call_destructive_tool.
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.callTool(args));
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
-        inputSchema: z.strictObject({
-            ...CALL_INPUT_SCHEMA,
-            // Bounded above, but with no lower bound: a model that sends `""` or
-            // whitespace has written no reason, and failing an entire consequential
-            // call over a cosmetic field the host merely displays is the wrong
-            // trade. It is normalized to absent below instead.
-            reason: z.string().max(500).optional(),
-        }),
+        inputSchema: CALL_DESTRUCTIVE_INPUT,
         annotations: {
             destructiveHint: true,
             readOnlyHint: false,
@@ -720,10 +921,7 @@ export function registerMetaTools(server, registry, ctx) {
     });
     server.registerTool("authorize_connector", {
         description: AUTHORIZE_DESC,
-        inputSchema: z.object({
-            connector: z.string(),
-            force: z.boolean().optional(),
-        }),
+        inputSchema: AUTHORIZE_INPUT,
         // Starts (or with force, resets) a downstream OAuth flow — it changes
         // stored connector auth state, so it is deliberately not read-only.
         annotations: {
@@ -734,15 +932,7 @@ export function registerMetaTools(server, registry, ctx) {
     }, async (args) => mt.authorizeConnector(args));
     server.registerTool("get_result", {
         description: GET_RESULT_DESC,
-        inputSchema: z.object({
-            id: z.string(),
-            // Both bounds are the shared rules (isValidResultOffset,
-            // isValidMaxResultBytes) expressed for the wire: spelling them against
-            // the same constants keeps the schema from drifting away from the
-            // in-handler checks if either floor ever moves.
-            offset: z.number().int().min(MIN_RESULT_OFFSET).optional(),
-            maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
-        }),
+        inputSchema: GET_RESULT_INPUT,
         annotations: READ_ONLY_LOCAL,
     }, async (args) => mt.getResult(args));
 }