@zackbart/connecta 0.24.4 → 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();
@@ -101,13 +103,20 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
 }
 /** 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 a little under the 50,000-byte default page so a default page
- * reads two or three chunks rather than dozens.
+ * 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;
 /**
@@ -134,8 +143,44 @@ function base64Of(bytes) {
     }
     return out;
 }
-/** Stash a completed result, or return a notice without a paging route. */
-async function stashResult(bytes, results) {
+/** 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 {
@@ -144,7 +189,7 @@ async function stashResult(bytes, results) {
         // 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_V2}${totalBytes}:${chunkBytes}:`];
+        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)
@@ -168,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) {
@@ -195,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) {
@@ -220,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`.
  *
- * 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
+ * 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.
+ *
+ * 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);
@@ -266,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,
@@ -311,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.
     });
@@ -329,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
@@ -343,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,
@@ -518,15 +609,24 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
             }
             const requestedOffset = args.offset ?? 0;
-            const maxBytes = args.maxBytes ?? globalCap;
             // 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: v1 inlined the whole envelope under one key, which is this
-            // format with a single chunk as wide as the result, and raw text before
-            // that still pays one full encode per page.
-            const chunked = RESULT_ENVELOPE_V2_HEADER.exec(stored.slice(0, 80));
+            // 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;
@@ -569,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);
@@ -677,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.';
 /**
@@ -724,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
@@ -745,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,
@@ -796,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: {
@@ -810,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));
 }

package/dist/oauth-callback-outcome.js

@@ -0,0 +1,94 @@
+import { renderFixPrompt } from "./fix-prompt.js";
+const OUTCOMES = {
+    connected: { status: 200, message: "Connected. You can close this window." },
+    denied: {
+        status: 400,
+        message: "Authorization was declined at the provider. Nothing was stored; start authorization again when you are ready.",
+        fix: {
+            problem: "Consent for a downstream OAuth connector was declined at the provider, so no grant was stored.",
+            steps: [
+                "If consent was declined on purpose, nothing in code needs to change: restart authorization from the operator page or authorize_connector when ready.",
+                "If the consent screen asked for more than the connector needs, narrow the scopes the connector's OAuth configuration requests.",
+                "If the provider refused the account or organization, check the OAuth app's allowed users or install policy in the provider's console.",
+            ],
+        },
+    },
+    provider_error: {
+        status: 400,
+        message: "The provider returned an error instead of an authorization code. Nothing was stored.",
+        fix: {
+            problem: "A provider redirected back to the OAuth callback with an OAuth error instead of an authorization code.",
+            steps: [
+                "Compare the provider's OAuth client registration with the connector's configuration: client id, requested scopes, and the redirect URI, which is the deployment's public URL followed by /oauth/callback/<connector id>.",
+                "Check that the deployment's publicUrl is the origin the provider redirects to; a different origin yields a redirect URI the provider does not recognize.",
+                "Retry once before changing code: a provider outage answers with the same kind of error.",
+            ],
+        },
+    },
+    invalid_callback: {
+        status: 400,
+        message: "Authorization could not be completed. The link may be expired, already used, or replaced by a newer attempt. Re-run authorization from connecta and try again.",
+        fix: {
+            problem: "An OAuth callback arrived that the deployment could not match to an authorization flow it started: stale, already used, replaced by a newer attempt, or finished in a different session.",
+            steps: [
+                "Restart authorization from the operator page or authorize_connector and finish consent in one pass; restarting invalidates the previous link.",
+                "If it fails every time, confirm the connector implements both finishAuth and verifyState, and that the storage holding OAuth state is shared by every instance serving the deployment (memoryStorage is per-process).",
+                "For personal-auth connectors, finish consent signed in as the same operator who started it.",
+            ],
+        },
+    },
+    handoff_failed: {
+        status: 500,
+        message: "Authorization could not be completed. Nothing was exchanged; try again shortly.",
+        namesConnector: true,
+        fix: {
+            problem: "The deployment could not consume the stored principal handoff for a personal-auth OAuth flow, so no authorization code was exchanged.",
+            steps: [
+                "Check the deployment's storage adapter: that it is reachable, writable, and consistent across every instance serving the deployment.",
+                "Find the [connecta] warning for this callback in the deployment logs; it records the storage error the page withholds.",
+            ],
+        },
+    },
+    exchange_failed: {
+        status: 500,
+        message: "Authorization failed: the provider did not accept the authorization code exchange. Nothing was stored.",
+        namesConnector: true,
+        fix: {
+            problem: "A provider returned an authorization code, but exchanging it for tokens failed.",
+            steps: [
+                "Check the OAuth client credentials the connector uses — client id and secret in the deployment's environment — and that they belong to the same OAuth app that showed the consent screen.",
+                "Check that the token endpoint and redirect URI the connector uses match the provider's registration exactly.",
+                "Find the [connecta] warning for this callback in the deployment logs; it records the exchange error the page withholds.",
+            ],
+        },
+    },
+};
+const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
+/**
+ * RFC 6749 names `access_denied` for a declined consent (section 4.1.2.1). Every other
+ * value, standard or invented, is the provider refusing the request itself —
+ * and is never echoed, because the callback cannot tell a provider's code from
+ * one an attacker typed into the URL.
+ */
+export function providerErrorReason(error) {
+    return error === "access_denied" ? "denied" : "provider_error";
+}
+/** Page copy and fix prompt for one reason. Nothing here reads the request. */
+export function oauthCallbackOutcome(reason, connectorId) {
+    const outcome = OUTCOMES[reason];
+    // Success is reached only after the state check proved the id configured,
+    // so it is the one page that may name the connector in its copy.
+    const message = reason === "connected" && connectorId && CONNECTOR_ID_RE.test(connectorId)
+        ? `Connected "${connectorId}". You can close this window.`
+        : outcome.message;
+    return {
+        reason,
+        status: outcome.status,
+        message,
+        ...(outcome.fix
+            ? {
+                fixPrompt: renderFixPrompt(outcome.fix, outcome.namesConnector ? connectorId : undefined),
+            }
+            : {}),
+    };
+}

package/dist/oauth-sealing.js

@@ -0,0 +1,29 @@
+/**
+ * Contexts the registry built with a sealing vault. Internal on purpose: the
+ * public ConnectorContext type does not change, and a connector cannot hand
+ * itself a sealer another connector's context carries.
+ */
+const sealers = new WeakMap();
+/** A sealer over the vault, or undefined when the vault cannot seal. */
+export function vaultOAuthSealer(vault, connectorId, owner, logger) {
+    const { seal, open } = vault;
+    if (typeof seal !== "function" || typeof open !== "function")
+        return undefined;
+    return {
+        seal: (physicalKey, plaintext) => seal.call(vault, connectorId, physicalKey, plaintext, owner),
+        open: (physicalKey, sealed) => open.call(vault, connectorId, physicalKey, sealed, owner),
+        warn: (message) => logger.warn(message),
+    };
+}
+export function attachOAuthSealer(ctx, sealer) {
+    if (sealer)
+        sealers.set(ctx, sealer);
+    return ctx;
+}
+export function oauthSealerFor(ctx) {
+    return sealers.get(ctx);
+}
+/** Carry the sealer onto a context derived by spreading another. */
+export function inheritOAuthSealer(from, to) {
+    return attachOAuthSealer(to, sealers.get(from));
+}