@zackbart/connecta 0.28.0 → 0.29.0

package/dist/meta-tools.js

@@ -1,16 +1,21 @@
+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 { 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, CALL_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";
+export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
 const dec = new TextDecoder();
 export function jsonResult(obj, text = JSON.stringify(obj)) {
@@ -21,7 +26,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 +62,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 +106,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 +119,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.
  */
@@ -161,13 +158,13 @@ function pagingHint(results, totalBytes, preview) {
             : 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}`;
 }
 /**
@@ -182,14 +179,21 @@ function pagingHint(results, totalBytes, preview) {
  */
 async function stashResult(bytes, results, preview) {
     const totalBytes = bytes.length;
+    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 +201,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,9 +227,14 @@ 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)} })`,
+            },
         },
     };
 }
@@ -235,11 +244,14 @@ 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}` }],
+        structuredContent: { ...notice, format: "text" },
+    };
 }
 /**
  * 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
@@ -266,21 +278,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 +333,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 +350,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
@@ -385,40 +403,53 @@ 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 ?? {};
+    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 +458,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 +483,27 @@ 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);
+                    guarded.result.structuredContent = { ...guarded.result.structuredContent, format };
                     return processed(guarded.result, guarded.truncated);
                 }
                 const value = result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
+                guarded.result.structuredContent = { ...guarded.result.structuredContent, format };
                 return processed(guarded.result, guarded.truncated, { value });
             },
             activityFriction: (processed) => processed.friction,
@@ -473,23 +516,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 +537,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 +550,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 +561,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 +602,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.`);
             }
@@ -598,52 +630,90 @@ 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 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 ||
+                typeof binding.connector !== "string" ||
+                typeof binding.tool !== "string" ||
+                !["read", "write"].includes(binding.classification))
+                return denied();
+            const allowed = async () => {
+                options.signal?.throwIfAborted();
+                try {
+                    const address = `${binding.connector}.${binding.tool}`;
+                    if (!(await registry.recheckResultAccess(address, binding.classification, options.signal)))
+                        return false;
+                    if (!registry.getConnector(binding.connector))
+                        return false;
+                    const tools = await registry.getTools(binding.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
+                    const tool = tools.find((tool) => tool.name === binding.tool);
+                    return Boolean(tool && ((binding.classification === "read" && tool.classification === "read") || opts.trust === "trusted"));
+                }
+                catch {
+                    options.signal?.throwIfAborted();
+                    return false;
+                }
+            };
+            if (!(await allowed()))
+                return denied();
             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 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();
                 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 +726,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
@@ -685,16 +751,19 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             // 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);
@@ -727,8 +796,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 })) ?? [
                     {
                         name: "value",
-                        guidance: connector.credential.description ??
-                            connector.credential.label,
+                        guidance: connector.credential.description ?? connector.credential.label,
                     },
                 ];
                 return jsonResult({
@@ -746,49 +814,40 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                             : "Shared credential mutation requires a signed-in human with access to this connector."),
                 });
             }
+            if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
+                return jsonResult({
+                    connector: connector.id,
+                    recovery: "unavailable",
+                    message: opts.oauthConnectUnavailable ??
+                        "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
+                });
             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);
+                return jsonResult({
+                    connector: connector.id,
+                    recovery: "unavailable",
+                    message: "Your identity is not permitted to manage authentication for this connection.",
+                });
             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 } : {}),
+                    status: "auth_required",
+                    authorizationUrl: await opts.oauthConnectUrl(connector.id, args.force),
+                    instructions: "Open authorizationUrl in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
+                        oauthFollowUp(connector.id),
                 });
             }
             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 +863,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 +884,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 +917,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,53 +927,81 @@ 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,
+        outputSchema: CALL_OUTPUT,
         // 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,
+        outputSchema: CALL_OUTPUT,
         annotations: {
             destructiveHint: true,
             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 +1009,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);
+    });
 }