@zackbart/connecta 0.28.1 → 0.30.0

package/dist/meta-tools.js

@@ -1,18 +1,26 @@
+import { authorizationHandoff, bindAuthorizationHandoffs } from "./authorization-handoff.js";
+import { bindMcpClient } from "./mcp-client-context.js";
+import { CONFIG_DEFAULTS } from "./config-defaults.js";
 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 { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPolicyError, flatSearchResult, 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";
-import { serializeResultText } from "./executor-result.js";
-import { InvocationService, } from "./invocation.js";
+import { boundedEchoText, ConnectorCallError, msg } from "./errors.js";
+import { failureRecord, logFailure } from "./operator-record.js";
+import { guardExecuteResultValue, MAX_EXECUTE_RESULT_CHARS, serializeResultText } from "./executor-result.js";
+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;
+import { hasConnectorGuides, SkillsRegistry } from "./skills.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
+import { AUTHORIZE_OUTPUT, SEARCH_OUTPUT, SKILLS_OUTPUT } from "./meta-output.js";
+import { RESULT_TTL_SECONDS, resultKeys } from "./storage/keys.js";
+import { agentOutputOperations, sentSecretsForRequest } from "./sent-secrets.js";
+import { captureDownstreamInput } from "./downstream-input.js";
+import { PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
+export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
-const dec = new TextDecoder();
+// Each page is a slice of payload bytes, so a leading U+FEFF is data.
+const dec = new TextDecoder("utf-8", { ignoreBOM: true, fatal: false });
 export function jsonResult(obj, text = JSON.stringify(obj)) {
     return {
         content: [{ type: "text", text }],
@@ -21,7 +29,7 @@ export function jsonResult(obj, text = JSON.stringify(obj)) {
             : {}),
     };
 }
-export function errorResult(message) {
+function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
 function discoveryErrorResult(error) {
@@ -57,7 +65,7 @@ async function discoveryResult(operation, hint) {
 function isContinuationByte(b) {
     return b !== undefined && (b & 0xc0) === 0x80;
 }
-/** Smallest accepted `get_result` byte offset. */
+/** Smallest accepted `connecta.result` byte offset. */
 const MIN_RESULT_OFFSET = 0;
 /** Whole-byte offset accepted by the result representation documented in
  * documentation/meta-tools.md#result-representation. */
@@ -101,17 +109,9 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
     }
     return e;
 }
-/** 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+):`);
+/** Every readable stash carries host-admitted bindings; older entries fail closed. */
+const RESULT_ENVELOPE_V4 = "connecta-result-v4:";
+const RESULT_ENVELOPE_V4_HEADER = /^connecta-result-v4:([A-Za-z0-9+/=]+):(\d+):(\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
@@ -122,7 +122,7 @@ 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
+ * a SQL store commits one row 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.
  */
@@ -145,6 +145,23 @@ function base64Of(bytes) {
 }
 /** 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.";
+/** UTF-8 cannot represent lone UTF-16 surrogates without changing them. */
+function isWellFormedText(text) {
+    const native = String.prototype.isWellFormed;
+    if (native)
+        return native.call(text);
+    for (let at = 0; at < text.length; at++) {
+        const unit = text.charCodeAt(at);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = text.charCodeAt(++at);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            return false;
+    }
+    return true;
+}
 /**
  * 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,
@@ -156,18 +173,20 @@ const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see i
 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) {
+        if (results.binding.program)
+            return "filter/map/slice data inside execute_code and return only what you need; page this completed return with connecta.result using nextAction.";
         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.`;
+        return `${shown} ${READ_REDUCE_FIRST}; ${full} with connecta.result using nextAction.`;
     }
     const body = preview.kind === "prefix"
-        ? `Bytes 0-${preview.bytes} of ${totalBytes} follow; page the rest with get_result using nextAction.`
+        ? `Bytes 0-${preview.bytes} of ${totalBytes} follow; page the rest with connecta.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.`;
+            ? `Its text follows; page the full ${totalBytes}-byte content array as JSON with connecta.result using nextAction.`
+            : `Page all ${totalBytes} bytes with connecta.result using nextAction.`;
     return `${WRITE_ALREADY_RAN} ${body}`;
 }
 /**
@@ -180,16 +199,32 @@ function pagingHint(results, totalBytes, preview) {
  * 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) {
+async function stashResult(bytes, results, preview, rawText) {
     const totalBytes = bytes.length;
+    // Direct pages promise offsets into the original UTF-8 text. JSON-escaping
+    // raw text would change that contract; never stash the encoder's replacement
+    // characters as if they were the completed call's output.
+    if (rawText !== undefined && !isWellFormedText(rawText))
+        return {
+            truncated: true,
+            totalBytes,
+            hint: `${results.write ? WRITE_ALREADY_RAN + " " : ""}Paging is unavailable: text contains unpaired surrogates and can't be paged as text; request the value as JSON (value mode or a JSON-returning call) to recover it.`,
+        };
+    if (!results.pageable)
+        return {
+            truncated: true,
+            totalBytes,
+            hint: `${WRITE_ALREADY_RAN} Paging is unavailable for write results on read-only pools.`,
+        };
     const id = crypto.randomUUID();
     try {
         // 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
+        // the whole result (issue #540). Chunk 0 carries the header; the connecta.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}:`];
+        const binding = base64Of(enc.encode(JSON.stringify(results.binding)));
+        const chunks = [`${RESULT_ENVELOPE_V4}${binding}:${totalBytes}:${chunkBytes}:${results.cap}:`];
         for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
             const chunk = base64Of(bytes.subarray(offset, offset + chunkBytes));
             if (offset === 0)
@@ -197,7 +232,7 @@ async function stashResult(bytes, results, preview) {
             else
                 chunks.push(chunk);
         }
-        if (!await results.set(`result:${id}`, chunks, RESULT_TTL_SECONDS)) {
+        if (!(await results.set(id, chunks, RESULT_TTL_SECONDS))) {
             throw new Error("Result stash capacity exhausted");
         }
     }
@@ -223,11 +258,84 @@ async function stashResult(bytes, results, preview) {
         resultId: id,
         totalBytes,
         hint: pagingHint(results, totalBytes, preview),
+        nextOffset: preview.kind === "prefix" ? preview.bytes : 0,
         nextAction: {
-            tool: "get_result",
-            arguments: { id, offset: preview.kind === "prefix" ? preview.bytes : 0 },
+            tool: "execute_code",
+            // A byte may cost six JSON characters when escaped. Leave room for the
+            // result id, page counters, and continuation metadata in the returned page.
+            arguments: {
+                code: `async () => await connecta.result(${JSON.stringify(id)}, { offset: ${preview.kind === "prefix" ? preview.bytes : 0}, maxBytes: ${Math.floor((MAX_EXECUTE_RESULT_CHARS - 1024) / 6)} })`,
+            },
+        },
+    };
+}
+/** Program calls use the direct-call envelope, ledger, expiry and authority. */
+export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, trust, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
+    const data = secrets.redact(value);
+    const wire = JSON.stringify({ data, format });
+    if (enc.encode(wire).length <= wireBytes)
+        return { data, format };
+    const text = secrets.text(format === "text" ? String(data) : serializeResultText(data));
+    const bytes = enc.encode(text);
+    const write = resolved.definition.classification !== "read";
+    const notice = await stashResult(bytes, {
+        pageable: !write || trust === "trusted",
+        binding: {
+            identity: registry.resultIdentity(),
+            baseUrl,
+            connector: resolved.connector.id,
+            tool: resolved.definition.name,
+            classification: write ? "write" : "read",
+        },
+        write,
+        cap: resolveMaxResultBytes(resolved.connector.maxResultBytes, registry.maxResultBytes),
+        set: (id, chunks, ttl) => registry.stashResult(id, chunks, ttl),
+        warn: () => logFailure(registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger, "result paging unavailable", failureRecord({ connector: resolved.connector.id, tool: resolved.definition })),
+    }, { kind: "none" }, format === "text" ? text : undefined);
+    return {
+        format: "paged",
+        valueFormat: format,
+        ...(notice.resultId ? { resultId: notice.resultId } : {}),
+        totalBytes: bytes.length,
+        truncated: true,
+        hint: notice.resultId
+            ? `${write ? WRITE_ALREADY_RAN + " " : ""}Page this result with connecta.result(handle); do not repeat the call for output.`
+            : notice.hint,
+    };
+}
+/** Program returns share the direct stash, with all host-admitted call dependencies. */
+export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, trust, logger, maxChars, completedWrite) {
+    const serialized = serializeResultText(value);
+    if (serialized.length <= maxChars)
+        return value;
+    const text = secrets.text(serialized);
+    const bytes = enc.encode(text);
+    const write = dependencies.some((dependency) => dependency.classification === "write");
+    const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
+    const results = {
+        secrets,
+        pageable: !write || trust === "trusted",
+        binding: {
+            identity: registry.resultIdentity(),
+            baseUrl,
+            classification: write ? "write" : "read",
+            program: dependencies,
         },
+        write: completedWrite,
+        cap,
+        set: (id, chunks, ttl) => registry.stashResult(id, chunks, ttl),
+        warn: () => logFailure(logger, "result paging unavailable", failureRecord({})),
     };
+    const notice = await stashResult(bytes, results, { kind: "none" }, text);
+    // Put the entire recovery route ahead of the preview in both response forms.
+    // A client retaining only the first 2,000 characters still sees the action.
+    if (notice.resultId) {
+        const base = { ...notice, totalChars: text.length, preview: "" };
+        const budget = Math.max(0, maxChars - JSON.stringify(base).length);
+        return { ...base, preview: escapedHeadOf(bytes, Math.min(512, budget)) };
+    }
+    const fallback = guardExecuteResultValue(secrets.redact(value), maxChars, notice.hint);
+    return { truncated: true, totalChars: fallback.totalChars, hint: fallback.hint, preview: fallback.preview };
 }
 /** The first `cap` bytes of `bytes`, ending on a character boundary. */
 function headOf(bytes, cap) {
@@ -235,11 +343,13 @@ function headOf(bytes, cap) {
 }
 /** One text block: the notice line, then the preview. */
 function noticeFirst(notice, preview) {
-    return { content: [{ type: "text", text: `${JSON.stringify(notice)}\n${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 a JSON truncation notice pointing at get_result,
+ * full text and return a JSON truncation notice pointing at connecta.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
@@ -252,6 +362,10 @@ async function guardEncoded(text, bytes, results, cap) {
             truncated: false,
         };
     }
+    if (!isWellFormedText(text)) {
+        const notice = await stashResult(bytes, results, { kind: "none" }, text);
+        return { result: noticeFirst(notice, ""), truncated: true };
+    }
     const head = headOf(bytes, cap);
     const notice = await stashResult(bytes, results, {
         kind: "prefix",
@@ -266,21 +380,25 @@ async function guardText(text, results, cap) {
     // Normalizing at the door means the size check below always measures exactly
     // the text that is emitted, and no future caller can launder a non-string
     // through it the way issue #42 describes.
-    const body = typeof text === "string" ? text : serializeResultText(text);
+    const serialized = typeof text === "string" ? text : serializeResultText(text);
+    const body = results.secrets?.text(serialized) ?? serialized;
     return guardEncoded(body, enc.encode(body), results, cap);
 }
 /** Store an oversized JSON value and replace it with a page handle. */
 async function guardValue(value, results, cap) {
-    const text = serializeResultText(value);
+    const serialized = serializeResultText(value);
+    const text = results.secrets?.text(serialized) ?? serialized;
     const bytes = enc.encode(text);
     if (bytes.length <= cap)
-        return { result: value, truncated: false };
+        return { result: results.secrets?.redact(value) ?? value, truncated: false };
     const notice = await stashResult(bytes, results, { kind: "none" });
     return {
-        result: notice.resultId ? notice : {
-            ...notice,
-            preview: escapedHeadOf(bytes, cap),
-        },
+        result: notice.resultId
+            ? notice
+            : {
+                ...notice,
+                preview: escapedHeadOf(bytes, cap),
+            },
         truncated: true,
     };
 }
@@ -317,12 +435,13 @@ function escapedHeadOf(bytes, cap) {
  *
  * 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
+ * connecta.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`.
+ * the full envelope is stashed and pages through `connecta.result`.
  */
 async function guardContent(content, results, cap) {
+    content = results.secrets?.redact({ content }).content ?? content;
     const only = content.length === 1 ? content[0] : undefined;
     if (only?.type === "text" && typeof only.text === "string") {
         const bytes = enc.encode(only.text);
@@ -333,7 +452,8 @@ async function guardContent(content, results, cap) {
     }
     let text;
     try {
-        text = JSON.stringify(content);
+        const serialized = JSON.stringify(content);
+        text = results.secrets?.text(serialized) ?? serialized;
     }
     catch {
         // A block carrying a BigInt or a cycle cannot be serialized, so it cannot
@@ -362,13 +482,6 @@ async function guardContent(content, results, cap) {
         truncated: true,
     };
 }
-/**
- * The sentence that closes the OAuth handoff, telling the operator's agent how
- * to confirm the flow landed through the one surface it can call.
- */
-function oauthFollowUp(connectorId) {
-    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
-}
 /**
  * Every meta-tool handler over a registry, one per registered tool. Exported for
  * direct testing; registerMetaTools() wires the six explicit tools onto an
@@ -385,40 +498,56 @@ function oauthFollowUp(connectorId) {
  * override each have one runtime source of truth.
  */
 export function createMetaTools(registry, baseUrl, opts = {}) {
+    return agentOutputOperations((requestScope) => metaToolsForRequest(registry, baseUrl, { ...opts, requestScope }), opts.requestScope);
+}
+function metaToolsForRequest(registry, baseUrl, opts = {}) {
     // Already normalized and warned about at registry construction.
     const globalCap = registry.maxResultBytes;
-    const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
+    const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs) ?? CONFIG_DEFAULTS.execute.hostCallTimeoutMs;
     const probeTimeoutMs = normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
     const discoveryConcurrency = resolveDiscoveryConcurrency(opts.discoveryConcurrency);
     // createMetaTools() is called once per inbound MCP request. Sharing this
     // identity lets remote connectors reuse one downstream client inside that
     // request without leaking request-bound I/O into the next one.
-    const requestScope = {};
+    const requestScope = opts.requestScope ?? {};
+    if (opts.canManageAuth || opts.oauthConnectUrl || opts.credentialHandoffUrl || opts.oauthConnectUnavailable) {
+        bindAuthorizationHandoffs(requestScope, (connector) => authorizationHandoff(registry, baseUrl, requestScope, opts, { connector }));
+    }
+    const sentSecrets = sentSecretsForRequest(requestScope);
+    const skills = new SkillsRegistry(registry, baseUrl, {
+        requestScope,
+        requestSignal: opts.requestSignal,
+        probeTimeoutMs,
+        defer: opts.defer,
+    });
     const catalog = new CatalogService(registry, baseUrl, {
         requestScope,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
         defer: opts.defer,
         requestSignal: opts.requestSignal,
-        approval: opts.approval,
         // searchRoute keeps its top-level default. In-program callers use a
         // separate CatalogService configured for connecta.search.
     });
     const invocation = new InvocationService(registry, catalog, opts.activity);
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
-    async function runCall(call, source, options = {}) {
+    async function runCall(call, source) {
         const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
         const outcome = await invocation.invoke(call.address, call.args ?? {}, {
             source,
-            ...(options.allowDestructive !== undefined
-                ? { allowDestructive: options.allowDestructive }
-                : {}),
+            sentSecrets,
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            ...(opts.requestSignal !== undefined
-                ? { requestSignal: opts.requestSignal }
-                : {}),
+            ...(opts.requestSignal !== undefined ? { requestSignal: opts.requestSignal } : {}),
             unwrapResult: call.resultMode === "value",
-            processResult: async (result, resolved) => {
+            ...(opts.downstreamInput
+                ? {
+                    processInputRequired: async (result, resolved, secrets) => {
+                        await captureDownstreamInput(requestScope, resolved.connector.id, `${resolved.connector.id}.${resolved.toolName}`, result, secrets);
+                        return { toolResult: { content: [] } };
+                    },
+                }
+                : {}),
+            processResult: async (result, resolved, secrets, format) => {
                 // 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
@@ -427,13 +556,21 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 // 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", {
+                    secrets,
+                    pageable: resolved.definition.classification === "read" || opts.trust === "trusted",
+                    binding: {
+                        identity: registry.resultIdentity(),
+                        baseUrl,
                         connector: resolved.connector.id,
-                        tool: resolved.toolName,
-                    }),
+                        tool: resolved.definition.name,
+                        classification: resolved.definition.classification === "read" ? "read" : "write",
+                    },
+                    write: resolved.definition.classification !== "read",
+                    cap,
+                    set: (id, value, ttlSeconds) => registry.stashResult(id, value, ttlSeconds),
+                    // The catalog entry, never `toolName`: a record names a tool
+                    // only through the grammar check (src/operator-record.ts).
+                    warn: () => logFailure(registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger, "result paging unavailable", failureRecord({ connector: resolved.connector.id, tool: resolved.definition })),
                 };
                 const processed = (toolResult, truncated, value) => ({
                     toolResult,
@@ -444,23 +581,29 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     let value = result;
                     const guarded = await guardValue(value, results, cap);
                     value = guarded.result;
-                    return processed(jsonResult({ ok: true, data: value }), guarded.truncated, { value });
+                    return processed(jsonResult({ ok: true, data: value, format }), guarded.truncated, { value });
                 }
                 if (resolved.connector.kind === "mcp") {
                     const mcpResult = result;
                     let content = mcpResult?.content ?? [];
-                    if (!content.some((block) => block.type === "text") &&
-                        mcpResult?.structuredContent !== undefined) {
-                        content = [...content, {
+                    if (!content.some((block) => block.type === "text") && mcpResult?.structuredContent !== undefined) {
+                        content = [
+                            ...content,
+                            {
                                 type: "text",
                                 text: JSON.stringify(mcpResult.structuredContent),
-                            }];
+                            },
+                        ];
                     }
                     const guarded = await guardContent(content, results, cap);
+                    // Native blocks and bounded previews are the result. A format-only
+                    // structuredContent hides them in clients that prefer that field.
+                    guarded.result._meta = { "dev.connecta/format": format };
                     return processed(guarded.result, guarded.truncated);
                 }
                 const value = result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
+                guarded.result._meta = { "dev.connecta/format": format };
                 return processed(guarded.result, guarded.truncated, { value });
             },
             activityFriction: (processed) => processed.friction,
@@ -473,23 +616,17 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 outcome.error.details !== undefined ||
                 // So does a conflict's `current`: where things stand is the retry.
                 outcome.error.current !== undefined ||
-                [
-                    "auth_required",
-                    "invalid_args",
-                    "input_required_unsupported",
-                ].includes(outcome.error.code);
-            const makeFailedResult = () => recoveryRequired ||
-                call.resultMode === "value"
-                ? jsonResult({
-                    ok: false,
-                    error: outcome.error,
-                    durationMs: outcome.durationMs,
-                    attempts: outcome.attempts,
-                    ...(call.diagnostics ? { timing: outcome.timing } : {}),
-                })
-                : errorResult(outcome.error.message);
+                ["auth_required", "invalid_args", "input_required_unsupported"].includes(outcome.error.code);
+            // Every mode carries the complete repair envelope in both MCP forms.
+            const makeFailedResult = () => jsonResult({
+                ok: false,
+                error: outcome.error,
+                durationMs: outcome.durationMs,
+                attempts: outcome.attempts,
+                ...(call.diagnostics ? { timing: outcome.timing } : {}),
+            });
             let failedResult = makeFailedResult();
-            // Value mode repeats the error in text and structuredContent. Account for
+            // Errors repeat in text and structuredContent. Account for
             // both copies and JSON escaping when the bounded provider reason is large.
             if (!recoveryRequired) {
                 const cap = resolveMaxResultBytes(outcome.resolved?.connector.maxResultBytes, globalCap);
@@ -500,9 +637,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     failedResult = makeFailedResult();
                 }
             }
-            if (recoveryRequired) {
-                failedResult.isError = true;
-            }
+            failedResult.isError = true;
             return {
                 toolResult: failedResult,
                 durationMs: outcome.durationMs,
@@ -515,6 +650,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             ? jsonResult({
                 ok: true,
                 data: outcome.value.value,
+                format: outcome.format,
                 durationMs: outcome.durationMs,
                 attempts: outcome.attempts,
                 ...(call.diagnostics ? { timing: outcome.timing } : {}),
@@ -525,37 +661,37 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             durationMs: outcome.durationMs,
             attempts: outcome.attempts,
             timing: outcome.timing,
-            ...(Object.prototype.hasOwnProperty.call(outcome.value, "value")
-                ? { value: outcome.value.value }
-                : {}),
+            ...(Object.prototype.hasOwnProperty.call(outcome.value, "value") ? { value: outcome.value.value } : {}),
         };
     }
     return {
         async skills(args = {}) {
-            const connectors = registry.listConnectors();
-            if (!args.name) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
-                                listSkills(connectors)
-                                    .map((skill) => `- \`${skill.name}\` — ${skill.description}`)
-                                    .join("\n"),
-                        },
-                    ],
-                };
+            try {
+                if (!args.name) {
+                    const listing = await skills.summaries();
+                    return {
+                        structuredContent: { skills: listing },
+                        content: [
+                            {
+                                type: "text",
+                                text: 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
+                                    listing.map((skill) => `- \`${skill.name}\` — ${skill.description}`).join("\n"),
+                            },
+                        ],
+                    };
+                }
+                const text = await skills.text(args.name);
+                return { content: [{ type: "text", text }], structuredContent: { name: args.name, format: "text", text } };
+            }
+            catch (error) {
+                return errorResult(error instanceof ConnectorCallError ? error.message : "Skills are unavailable.");
             }
-            const skill = resolveSkill(args.name, connectors);
-            if (!skill.found)
-                return errorResult(skill.message);
-            return { content: [{ type: "text", text: skill.content }] };
         },
         async searchTools(args) {
             if (args.connector !== undefined && enc.encode(args.connector).length > 512) {
                 return discoveryErrorResult(new DiscoveryPolicyError("invalid_args", "connector must be at most 512 UTF-8 bytes."));
             }
-            return discoveryResult(async () => groupedSearchResult(await catalog.search({
+            return discoveryResult(async () => flatSearchResult(await catalog.search({
                 ...args,
                 includeSchemaKeys: args.includeSchemas !== undefined,
             })), "Request a smaller limit, omit fullDescriptions, or use compact schemas.");
@@ -566,16 +702,12 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         async callDestructiveTool(args) {
             // `reason` is read by the host's approval view and stops there — runCall
             // forwards only the call arguments, so it never reaches the connector.
-            return (await runCall(args, "call_destructive_tool", { allowDestructive: true })).toolResult;
+            return (await runCall(args, "call_destructive_tool")).toolResult;
         },
-        async getResult(args) {
-            // Client-supplied page size and offset: normal input-validation errors,
-            // not clamps. Callers arriving over MCP are rejected earlier by the
-            // registered zod schema and never reach these branches, so they exist for
-            // in-process callers of createMetaTools — which have no schema in front
-            // of them — and to keep the rules true of the handler on its own terms.
-            if (args.maxBytes !== undefined &&
-                !isValidMaxResultBytes(args.maxBytes)) {
+        async readResult(args, options = {}) {
+            // Defense for in-process callers too: guest paging validates these domains
+            // before calling here, while internal consumers may call readResult directly.
+            if (args.maxBytes !== undefined && !isValidMaxResultBytes(args.maxBytes)) {
                 return errorResult(`Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
                     `>= ${MIN_MAX_RESULT_BYTES}. Omit it to use the deployment default.`);
             }
@@ -583,6 +715,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 return errorResult(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
+            if (args.page !== undefined && (!Number.isSafeInteger(args.page) || args.page < 0 || args.offset !== undefined)) {
+                return errorResult("Use a whole page >= 0, without offset.");
+            }
             const results = registry.resultsStorage();
             const unavailableResult = () => ({
                 ...jsonResult({
@@ -598,52 +733,124 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             // 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) => {
+                options.signal?.throwIfAborted();
+                let value;
                 try {
-                    return await results.get(key) ?? null;
+                    value = (await results.get(key)) ?? null;
                 }
                 catch {
-                    return false;
+                    value = false;
                 }
+                // A storage driver may finish its pending read after cancellation. No
+                // subsequent chunk read or decode may start when that happens (INV-7).
+                options.signal?.throwIfAborted();
+                return value;
             };
-            const stored = await read(`result:${args.id}`);
+            const stored = await read(resultKeys.chunk(args.id, 0));
             if (stored === false)
                 return unavailableResult();
             if (stored === null) {
                 return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
             }
-            const requestedOffset = args.offset ?? 0;
-            // 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 denied = () => errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+            const header = RESULT_ENVELOPE_V4_HEADER.exec(stored);
+            if (!header)
+                return denied();
+            let binding;
+            try {
+                binding = JSON.parse(dec.decode(Uint8Array.from(atob(header[1]), (char) => char.charCodeAt(0))));
+            }
+            catch {
+                return denied();
+            }
+            const identity = registry.resultIdentity();
+            if (!binding ||
+                binding.baseUrl !== baseUrl ||
+                !binding.identity ||
+                binding.identity.subject !== identity.subject ||
+                binding.identity.principal !== identity.principal ||
+                binding.identity.endpoint !== identity.endpoint ||
+                binding.identity.origin !== identity.origin ||
+                (binding.program === undefined
+                    ? typeof binding.connector !== "string" || typeof binding.tool !== "string"
+                    : !Array.isArray(binding.program) ||
+                        binding.program.some((dependency) => !dependency ||
+                            typeof dependency.connector !== "string" ||
+                            (dependency.tool !== undefined && typeof dependency.tool !== "string") ||
+                            (dependency.access !== undefined &&
+                                (dependency.access !== "catalog" || dependency.classification !== "read")) ||
+                            !["read", "write"].includes(dependency.classification))) ||
+                !["read", "write"].includes(binding.classification))
+                return denied();
+            const allowed = async () => {
+                options.signal?.throwIfAborted();
+                try {
+                    if (binding.program &&
+                        !(await registry.recheckResultAccess(undefined, binding.classification, options.signal)))
+                        return false;
+                    if (binding.classification === "write" && opts.trust !== "trusted")
+                        return false;
+                    const dependencies = binding.program ?? [binding];
+                    for (const dependency of dependencies) {
+                        const address = dependency.tool === undefined ? dependency.connector : `${dependency.connector}.${dependency.tool}`;
+                        if (!(await registry.recheckResultAccess(address, dependency.classification, options.signal, dependency.access)))
+                            return false;
+                        if (dependency.tool === undefined) {
+                            if (dependency.access === "catalog"
+                                ? !registry.getConnector(dependency.connector)
+                                : !registry.getResourceConnector(dependency.connector))
+                                return false;
+                            continue;
+                        }
+                        if (!registry.getConnector(dependency.connector))
+                            return false;
+                        const tools = await registry.getTools(dependency.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
+                        const tool = tools.find((tool) => tool.name === dependency.tool);
+                        if (!tool ||
+                            !(dependency.access === "catalog" ||
+                                (dependency.classification === "read" && tool.classification === "read") ||
+                                opts.trust === "trusted"))
+                            return false;
+                    }
+                    return true;
+                }
+                catch {
+                    options.signal?.throwIfAborted();
+                    return false;
+                }
+            };
+            if (!(await allowed()))
+                return denied();
+            opts.onResultRead?.(binding.program ?? [binding]);
+            let requestedOffset = args.offset ?? 0;
+            const cap = Number(header[4]);
+            if (!isValidMaxResultBytes(cap))
+                return denied();
             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);
+            {
+                total = Number(header[2]);
+                const chunkBytes = Number(header[3]);
+                if (!Number.isSafeInteger(total) ||
+                    total < 0 ||
+                    !Number.isSafeInteger(chunkBytes) ||
+                    chunkBytes < 3 ||
+                    chunkBytes % 3 !== 0)
+                    return denied();
+                if (args.page !== undefined) {
+                    // At least one complete UTF-8 codepoint per nominal window. Adjacent
+                    // pages align both edges backwards, so no character repeats or vanishes.
+                    const width = Math.max(4, maxBytes);
+                    requestedOffset = Math.min(total, Math.min(args.page, Math.ceil(total / width)) * width);
+                }
                 start = Math.floor(Math.max(0, Math.min(requestedOffset, total) - 3) / 3) * 3;
                 const end = Math.min(total, requestedOffset + maxBytes + 4);
                 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}`);
+                    const encoded = index === 0 ? stored.slice(header[0].length) : await read(resultKeys.chunk(args.id, index));
                     if (encoded === false)
                         return unavailableResult();
                     if (encoded === null) {
@@ -656,16 +863,12 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     // 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));
+                    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);
-                total = bytes.length;
-            }
             // Validated above, so no coercion is needed here — only alignment. A
             // client that computes its own offsets can land inside a multi-byte
             // character, which would decode as U+FFFD; the offset actually served is
@@ -678,117 +881,45 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             // 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 end = args.page === undefined
+                ? start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start)
+                : start +
+                    alignStartToCharBoundary(bytes, Math.min(total - start, requestedOffset - start + Math.max(4, maxBytes)));
             const slice = dec.decode(bytes.subarray(offset - start, end - start));
             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({
+            const pageHeader = {
                 resultId: args.id,
                 offset,
                 bytes: Math.max(0, end - offset),
                 totalBytes: total,
                 hasMore,
-                ...(hasMore
-                    ? { nextAction: { tool: "get_result", arguments: { id: args.id, offset: end } } }
-                    : {}),
-            }, slice);
+                ...(hasMore ? { nextOffset: end } : {}),
+            };
+            if (!(await allowed()))
+                return denied();
+            const page = noticeFirst(pageHeader, slice);
+            page.structuredContent = { ...pageHeader, text: slice, format: "text" };
+            return page;
         },
         async authorizeConnector(args) {
-            const connector = registry.getConnector(args.connector);
-            if (!connector) {
-                return errorResult(`Unknown connector "${boundedEchoText(args.connector)}"`);
-            }
-            if (!connector.startAuth) {
-                if (!connector.credential) {
-                    return jsonResult({
-                        connector: connector.id,
-                        recovery: "unavailable",
-                        message: `Connector "${connector.id}" declares neither downstream OAuth ` +
-                            "nor an operator-managed credential slot. Update the connector " +
-                            "or deployment configuration before retrying.",
-                    });
-                }
-                const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
-                if (!ctx.credential || !opts.credentialHandoffUrl) {
-                    return jsonResult({
-                        connector: connector.id,
-                        recovery: "unavailable",
-                        message: "Credential recovery needs both a vault and the optional UI. Configure " +
-                            "vault and ui in deployment code, then call " +
-                            "authorize_connector again.",
-                    });
-                }
-                const fields = connector.credential.fields?.map((field) => ({
-                    name: field.name,
-                    guidance: field.description ?? field.label,
-                })) ?? [
-                    {
-                        name: "value",
-                        guidance: connector.credential.description ??
-                            connector.credential.label,
-                    },
-                ];
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "operator_config",
-                    credential: {
-                        label: connector.credential.label,
-                        fields,
-                    },
-                    operatorUrl: opts.credentialHandoffUrl,
-                    instructions: "Have the operator open operatorUrl, set and test the credential, " +
-                        "then retry the original call. No redeploy is needed. " +
-                        (connector.authScope === "personal"
-                            ? "Credential mutation requires the signed-in principal who owns this connection."
-                            : "Shared credential mutation requires a signed-in human with access to this connector."),
-                });
-            }
-            if (!opts.canManageAuth?.(connector.id))
-                return jsonResult({ connector: connector.id, recovery: "unavailable", message: "Your identity is not permitted to manage authentication for this connection." });
-            const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
             try {
-                const status = await connector.startAuth(ctx, args.force !== undefined ? { force: args.force } : {});
-                if (status.authorizationUrl) {
-                    await registry.bindOAuthHandoff(connector.id, status.authorizationUrl);
-                }
-                if (status.state === "auth_required" && !status.authorizationUrl) {
-                    // auth_required with nothing to open is a dead end for the operator.
-                    return errorResult(`Connector "${connector.id}": authorization required but no URL is available — retry authorize_connector.`);
-                }
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "oauth",
-                    status: status.state,
-                    ...(status.authorizationUrl
-                        ? {
-                            authorizationUrl: status.authorizationUrl,
-                            instructions: "Have the operator open authorizationUrl in a browser and complete the consent flow. The provider then redirects back to this server's /oauth/callback/<connector> route, which finishes the flow automatically. " +
-                                oauthFollowUp(connector.id),
-                        }
-                        : {}),
-                    ...(status.message ? { message: status.message } : {}),
-                });
+                return jsonResult(await authorizationHandoff(registry, baseUrl, requestScope, opts, args));
             }
             catch (err) {
                 return errorResult(msg(err));
             }
-            finally {
-                // Auth state may have changed — even on a throw or a half-wiped force —
-                // so don't serve a stale tool list.
-                await registry.invalidateStored(connector.id);
-            }
         },
     };
 }
-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 tools that run unasked; "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 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 tools that run unasked; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses. Returns { catalogErrors, tools, total, offset, limit, hasMore }; read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
+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 connecta.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 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.';
+const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true requests an OAuth restart when the verified user opens the /connect URL; 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.";
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -804,9 +935,7 @@ const GUIDE_NOTES = {
 };
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
 function describedFor(registry, base, note) {
-    return hasConnectorGuides(registry.listConnectors())
-        ? base + GUIDE_NOTES[note]
-        : base;
+    return hasConnectorGuides(registry.listConnectors()) ? base + GUIDE_NOTES[note] : base;
 }
 /**
  * Connecta refuses downstream tools that are not explicitly annotated
@@ -827,7 +956,7 @@ const READ_ONLY_LOCAL = {
     openWorldHint: false,
 };
 const CALL_INPUT_SCHEMA = {
-    address: z.string(),
+    address: z.string().meta({ "x-mcp-header": "Address" }),
     args: z.record(z.string(), z.unknown()).optional(),
     resultMode: z.enum(["mcp", "value"]).optional(),
     timeoutMs: z.number().int().positive().optional(),
@@ -860,18 +989,9 @@ 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
+ * Register the five explicit meta-tools onto an McpServer instance.
+ * `registerExecuteTool` adds the sixth, `execute_code`. Broad discovery and
  * multi-call work uses discovery and ordinary JavaScript promises inside a
  * program, which `execute_code` builds over the same
  * `CatalogService` and `InvocationService` these handlers use — one shared
@@ -879,33 +999,56 @@ const GET_RESULT_INPUT = advertisedSchema(z.object({
  */
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
+        downstreamInput: Boolean(ctx.authElicitation),
+        requestScope: ctx.requestScope,
+        trust: ctx.trust,
         defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
         probeTimeoutMs: ctx.probeTimeoutMs,
         discoveryConcurrency: ctx.discoveryConcurrency,
         activity: ctx.activity,
+        client: ctx.client,
         canManageAuth: ctx.canManageAuth,
         credentialHandoffUrl: ctx.credentialHandoffUrl,
+        oauthConnectUrl: ctx.oauthConnectUrl,
+        oauthConnectUnavailable: ctx.oauthConnectUnavailable,
         requestSignal: ctx.requestSignal,
         defer: ctx.defer,
-        approval: ctx.approval,
     });
+    const bindRequest = (request) => {
+        if (ctx.client)
+            bindMcpClient(request, ctx.client, ctx.activity);
+    };
     server.registerTool("skills", {
         description: describedFor(registry, SKILLS_DESC, "skills"),
         inputSchema: SKILLS_INPUT,
+        outputSchema: SKILLS_OUTPUT,
         annotations: READ_ONLY_LOCAL,
-    }, async (args) => mt.skills(args));
+    }, async (args, request) => {
+        bindRequest(request);
+        return mt.skills(args);
+    });
     server.registerTool("search_tools", {
         description: describedFor(registry, SEARCH_DESC, "search"),
         inputSchema: SEARCH_INPUT,
+        outputSchema: SEARCH_OUTPUT,
         annotations: READ_ONLY_REMOTE,
-    }, async (args) => mt.searchTools(args));
+    }, async (args, request) => {
+        bindRequest(request);
+        return mt.searchTools(args);
+    });
     server.registerTool("call_tool", {
         description: CALL_DESC,
         inputSchema: CALL_INPUT,
+        // Default mode returns native content, so no structured result is promised.
         // 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));
+    }, async (args, request) => {
+        bindRequest(request);
+        return ctx.authElicitation
+            ? ctx.authElicitation.run("call_tool", args, request, () => mt.callTool(args))
+            : mt.callTool(args);
+    });
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
         inputSchema: CALL_DESTRUCTIVE_INPUT,
@@ -914,18 +1057,22 @@ export function registerMetaTools(server, registry, ctx) {
             readOnlyHint: false,
             openWorldHint: true,
         },
-    }, async (args) => {
+    }, async (args, request) => {
+        bindRequest(request);
         // `reason` is the host's to display and connecta's to keep out of the
         // downstream call, so this destructuring is the whole of its handling:
         // nothing below reads it. Dropping it is also what makes an empty or
         // whitespace-only one "absent" rather than a validation failure — there
         // is no field left for it to be absent from.
         const { reason: _hostContext, ...call } = args;
-        return mt.callDestructiveTool(call);
+        return ctx.authElicitation
+            ? ctx.authElicitation.run("call_destructive_tool", call, request, () => mt.callDestructiveTool(call))
+            : mt.callDestructiveTool(call);
     });
     server.registerTool("authorize_connector", {
         description: AUTHORIZE_DESC,
         inputSchema: AUTHORIZE_INPUT,
+        outputSchema: AUTHORIZE_OUTPUT,
         // Starts (or with force, resets) a downstream OAuth flow — it changes
         // stored connector auth state, so it is deliberately not read-only.
         annotations: {
@@ -933,10 +1080,10 @@ export function registerMetaTools(server, registry, ctx) {
             destructiveHint: false,
             openWorldHint: true,
         },
-    }, async (args) => mt.authorizeConnector(args));
-    server.registerTool("get_result", {
-        description: GET_RESULT_DESC,
-        inputSchema: GET_RESULT_INPUT,
-        annotations: READ_ONLY_LOCAL,
-    }, async (args) => mt.getResult(args));
+    }, async (args, request) => {
+        bindRequest(request);
+        return ctx.authElicitation
+            ? ctx.authElicitation.run("authorize_connector", args, request, () => mt.authorizeConnector(args))
+            : mt.authorizeConnector(args);
+    });
 }