@zackbart/connecta 0.24.2 → 0.24.4

package/dist/meta-tools.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPolicyError, groupedSearchResult, MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, } from "./catalog-service.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
-import { msg } from "./errors.js";
+import { boundedEchoText, msg } from "./errors.js";
 import { serializeResultText } from "./executor-result.js";
 import { InvocationService, } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
@@ -37,7 +37,12 @@ async function discoveryResult(operation, hint) {
     try {
         const value = await operation();
         const text = boundedDiscoveryText(value, hint);
-        return jsonResult(value, text);
+        const result = jsonResult(value, text);
+        const bytes = enc.encode(JSON.stringify(result)).length;
+        if (bytes > MAX_DISCOVERY_RESULT_BYTES) {
+            throw new DiscoveryPolicyError("result_too_large", `Discovery result is ${bytes} UTF-8 bytes, over the ${MAX_DISCOVERY_RESULT_BYTES}-byte ceiling. ${hint}`);
+        }
+        return result;
     }
     catch (err) {
         if (err instanceof DiscoveryPolicyError) {
@@ -94,29 +99,78 @@ export function alignEndToCharBoundary(bytes, offset, end, total) {
     }
     return e;
 }
-// --- result-size guard + get_result (feature 1) ---------------------------
+/** Prefix of the chunked paging envelope; `v1`'s single inline key still reads. */
+const RESULT_ENVELOPE_V2 = "connecta-result-v2:";
+/** `<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+):`);
 /**
- * The one serialization every result guard measures, stashes, and pages: JSON
- * text for whatever JSON can represent, and `String(value)` for the returns
- * JSON renders as `undefined` — a handler that returns nothing, a function, or
- * a Symbol. `JSON.stringify` is *typed* as returning `string` while actually
- * returning `undefined` for those, which is how a handler returning `undefined`
- * reached clients as a `{"type":"text"}` block carrying no `text` at all: the
- * size guard measured `enc.encode(undefined)` — the empty string, per the
- * WebIDL default — and emitted the non-string unchanged (issue #42). `null`
- * needs no special case; JSON renders it as `"null"`.
- *
- * Shared by `guardText`, `guardValue`, and execute_code's `guardResultValue` so
- * the three give one answer to the same question. A value JSON cannot serialize
- * at all (a BigInt) still throws, as before, and is reported as a failure.
+ * Smallest chunk of result text stored under one key. A multiple of three so
+ * every chunk's base64 stands alone and a byte offset inside it lands on a
+ * whole quad, and a little under the 50,000-byte default page so a default page
+ * reads two or three chunks rather than dozens.
+ */
+const RESULT_CHUNK_BYTES = 49_152;
+/**
+ * Keys one stashed result may occupy. Chunking trades write count for read
+ * count, and both are real: every chunk is a storage write at stash time, and
+ * `fileStorage` rewrites its whole file per write. Above roughly 1.5 MB the
+ * chunks widen instead of multiplying, so a result costs a bounded number of
+ * writes and a page still reads a small fraction of it.
  */
+const RESULT_MAX_CHUNKS = 32;
+/** Chunk width for a result of `totalBytes`, always a multiple of three. */
+function resultChunkBytes(totalBytes) {
+    return Math.max(RESULT_CHUNK_BYTES, Math.ceil(totalBytes / RESULT_MAX_CHUNKS / 3) * 3);
+}
 /**
- * Stash `text` under `result:<uuid>` (ttl 900s) and describe it as the
- * truncation notice every over-cap path hands back.
+ * Base64 of `bytes`, in three-byte-aligned batches so the argument list of one
+ * spread never grows with the result. Alignment matters: an unaligned batch
+ * would pad mid-stream and the concatenation would no longer decode.
  */
-async function stashResult(text, results, totalBytes) {
+function base64Of(bytes) {
+    let out = "";
+    for (let offset = 0; offset < bytes.length; offset += 12_288) {
+        out += btoa(String.fromCharCode(...bytes.subarray(offset, offset + 12_288)));
+    }
+    return out;
+}
+/** Stash a completed result, or return a notice without a paging route. */
+async function stashResult(bytes, results) {
+    const totalBytes = bytes.length;
     const id = crypto.randomUUID();
-    await results.set(`result:${id}`, text, { ttlSeconds: RESULT_TTL_SECONDS });
+    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
+        // reader below maps a byte offset back to chunk index and base64 quad.
+        const chunkBytes = resultChunkBytes(totalBytes);
+        const chunks = [`${RESULT_ENVELOPE_V2}${totalBytes}:${chunkBytes}:`];
+        for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
+            const chunk = base64Of(bytes.subarray(offset, offset + chunkBytes));
+            if (offset === 0)
+                chunks[0] += chunk;
+            else
+                chunks.push(chunk);
+        }
+        if (!await results.set(`result:${id}`, chunks, RESULT_TTL_SECONDS)) {
+            throw new Error("Result stash capacity exhausted");
+        }
+    }
+    catch {
+        // Paging is advisory after a completed call, including an approved write.
+        // Neither backend prose nor a retry hint belongs in this successful result.
+        try {
+            results.warn();
+        }
+        catch {
+            // Logging cannot change the call either.
+        }
+        return {
+            truncated: true,
+            totalBytes,
+            hint: "Paging is unavailable. Use execute_code to reduce read-only results before returning them. Do not repeat a completed write to recover its result.",
+        };
+    }
     return {
         truncated: true,
         resultId: id,
@@ -141,7 +195,7 @@ async function guardEncoded(text, bytes, results, cap) {
             truncated: false,
         };
     }
-    const notice = await stashResult(text, results, bytes.length);
+    const notice = await stashResult(bytes, results);
     const head = dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length)));
     return {
         result: {
@@ -166,8 +220,12 @@ async function guardValue(value, results, cap) {
     const bytes = enc.encode(text);
     if (bytes.length <= cap)
         return { result: value, truncated: false };
+    const notice = await stashResult(bytes, results);
     return {
-        result: await stashResult(text, results, bytes.length),
+        result: notice.resultId ? notice : {
+            ...notice,
+            preview: dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length))),
+        },
         truncated: true,
     };
 }
@@ -210,7 +268,7 @@ async function guardContent(content, results, cap) {
     if (content.every((b) => b.type === "text")) {
         return guardEncoded(text, bytes, results, cap);
     }
-    const notice = await stashResult(text, results, bytes.length);
+    const notice = await stashResult(bytes, results);
     return {
         result: { content: [{ type: "text", text: JSON.stringify(notice) }] },
         truncated: true,
@@ -259,7 +317,6 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     const invocation = new InvocationService(registry, catalog, opts.activity);
     /** MCP adapter: shared invocation semantics plus MCP-only result shaping. */
     async function runCall(call, source, options = {}) {
-        const results = registry.resultsStorage();
         const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
         const outcome = await invocation.invoke(call.address, call.args ?? {}, {
             source,
@@ -272,6 +329,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 : {}),
             unwrapResult: call.resultMode === "value",
             processResult: async (result, resolved) => {
+                const results = {
+                    set: (key, value, ttlSeconds) => registry.stashResult(key, value, ttlSeconds),
+                    warn: () => registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger.warn("[connecta] result paging unavailable", {
+                        connector: resolved.connector.id,
+                        tool: resolved.toolName,
+                    }),
+                };
                 // Result-size cap for THIS call: the connector's own override wins,
                 // then the deployment-wide value, then the built-in default (already
                 // folded into `globalCap`). Resolved per call so one request can
@@ -292,7 +356,14 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 }
                 if (resolved.connector.kind === "mcp") {
                     const mcpResult = result;
-                    const content = mcpResult?.content ?? [];
+                    let content = mcpResult?.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);
                     return processed(guarded.result, guarded.truncated);
                 }
@@ -305,12 +376,15 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         if (!outcome.ok) {
             const structuredRecovery = outcome.error.nextAction !== undefined;
             const recoveryRequired = structuredRecovery ||
+                // Sanitized `unavailable` diagnostics ride the structured shape too;
+                // the plain-text path would drop them (#539).
+                outcome.error.details !== undefined ||
                 [
                     "auth_required",
                     "invalid_args",
                     "input_required_unsupported",
                 ].includes(outcome.error.code);
-            const failedResult = recoveryRequired ||
+            const makeFailedResult = () => recoveryRequired ||
                 call.resultMode === "value"
                 ? jsonResult({
                     ok: false,
@@ -320,6 +394,18 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     ...(call.diagnostics ? { timing: outcome.timing } : {}),
                 })
                 : errorResult(outcome.error.message);
+            let failedResult = makeFailedResult();
+            // Value mode repeats the error 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);
+                let budget = 512;
+                while (enc.encode(JSON.stringify(failedResult)).length > cap && budget > 0) {
+                    budget = Math.floor(budget / 2);
+                    outcome.error.message = boundedEchoText(outcome.error.message, budget);
+                    failedResult = makeFailedResult();
+                }
+            }
             if (recoveryRequired) {
                 failedResult.isError = true;
             }
@@ -372,6 +458,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             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({
                 ...args,
                 includeSchemaKeys: args.includeSchemas !== undefined,
@@ -401,29 +490,95 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
             const results = registry.resultsStorage();
-            const stored = await results.get(`result:${args.id}`);
-            if (stored === null || stored === undefined) {
-                return errorResult(`Unknown or expired result id "${args.id}"`);
+            const unavailableResult = () => ({
+                ...jsonResult({
+                    error: {
+                        code: "unavailable",
+                        message: "Result paging storage is unavailable.",
+                        retryable: true,
+                    },
+                }),
+                isError: true,
+            });
+            // `false` is a storage failure — retryable, and distinct from an id that
+            // is simply gone. Every key a page touches answers the same way, so a
+            // backend that dies halfway through a multi-chunk page says so.
+            const read = async (key) => {
+                try {
+                    return await results.get(key) ?? null;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const stored = await read(`result:${args.id}`);
+            if (stored === false)
+                return unavailableResult();
+            if (stored === null) {
+                return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+            }
+            const requestedOffset = args.offset ?? 0;
+            const maxBytes = args.maxBytes ?? globalCap;
+            // Read and decode only the chunks this page covers, plus a few bytes of
+            // UTF-8 boundary lookaround. Pre-upgrade entries stay readable for their
+            // short TTL: v1 inlined the whole envelope under one key, which is this
+            // format with a single chunk as wide as the result, and raw text before
+            // that still pays one full encode per page.
+            const chunked = RESULT_ENVELOPE_V2_HEADER.exec(stored.slice(0, 80));
+            const inline = chunked ? null : /^connecta-result-v1:(\d+):/.exec(stored.slice(0, 64));
+            const header = chunked ?? inline;
+            let bytes;
+            let total;
+            let start = 0;
+            if (header) {
+                total = Number(header[1]);
+                const chunkBytes = chunked ? Number(chunked[2]) : Math.max(total, 1);
+                start = Math.floor(Math.max(0, Math.min(requestedOffset, total) - 3) / 3) * 3;
+                const end = Math.min(total, requestedOffset + maxBytes + 4);
+                bytes = new Uint8Array(Math.max(0, end - start));
+                const lastChunk = Math.floor(Math.max(end - 1, start) / chunkBytes);
+                for (let index = Math.floor(start / chunkBytes); index <= lastChunk; index++) {
+                    const encoded = index === 0
+                        ? stored.slice(header[0].length)
+                        : await read(`result:${args.id}#${index}`);
+                    if (encoded === false)
+                        return unavailableResult();
+                    if (encoded === null) {
+                        // A chunk expired or was evicted under its own header; the id can no
+                        // longer serve this range, and inventing U+0000 filler would be worse.
+                        return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                    }
+                    const chunkStart = index * chunkBytes;
+                    // Both bounds are chunk-local. `from` inherits `start`'s three-byte
+                    // alignment because every chunk boundary is a multiple of three.
+                    const from = Math.max(start, chunkStart) - chunkStart;
+                    const to = Math.min(end, chunkStart + chunkBytes, total) - chunkStart;
+                    const binary = atob(encoded.slice(from / 3 * 4, Math.ceil(to / 3) * 4));
+                    for (let at = from; at < to; at++) {
+                        bytes[chunkStart + at - start] = binary.charCodeAt(at - from);
+                    }
+                }
+            }
+            else {
+                bytes = enc.encode(stored);
+                total = bytes.length;
             }
-            const bytes = enc.encode(stored);
-            const 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
             // the boundary at or before it, and it is what the response reports back
             // as `offset` (issue #38).
-            const offset = alignStartToCharBoundary(bytes, args.offset ?? 0);
+            const offset = start + alignStartToCharBoundary(bytes, requestedOffset - start);
             // Page size only: a stashed result carries no connector identity, so
             // get_result keeps the deployment-wide default when none is requested.
             // Both sides are validated by now — the argument above, `globalCap` at
             // intake — so `offset + maxBytes` always reaches past `offset`.
-            const maxBytes = args.maxBytes ?? globalCap;
             // Align the slice end to a codepoint boundary so a multi-byte char is
             // never split across pages (which would emit U+FFFD on both sides).
             // `nextOffset` is this aligned end, so it is a valid boundary for the
             // next call and paging reassembles the original byte-for-byte.
-            const end = alignEndToCharBoundary(bytes, offset, offset + maxBytes, total);
-            const slice = dec.decode(bytes.slice(offset, end));
+            const end = start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start);
+            const slice = dec.decode(bytes.subarray(offset - start, end - start));
             const nextOffset = end < total ? end : undefined;
             return jsonResult({
                 offset,
@@ -435,7 +590,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         async authorizeConnector(args) {
             const connector = registry.getConnector(args.connector);
             if (!connector) {
-                return errorResult(`Unknown connector "${args.connector}"`);
+                return errorResult(`Unknown connector "${boundedEchoText(args.connector)}"`);
             }
             if (!connector.startAuth) {
                 if (!connector.credential) {