@zackbart/connecta 0.40.0 → 0.42.0

package/dist/meta-tools.js

@@ -1,28 +1,35 @@
+import { Effect } from "effect";
+import { operationActivity } from "./operation-activity.js";
+import { SkillLookupError } from "./skills.js";
+import { skillLookupRecovery, utilityRecovery } from "./utility-recovery.js";
 import { META_ROUTES } from "./agent-routes.js";
 import { toolError } from "./tool-error.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, authMethod, authStorage, registerAuth } from "./auth/native.js";
 import { registryProgram } from "./runtime/registry.js";
-import { runEdge } from "./runtime/run.js";
+import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 import { authorizationHandoff, authorizeConnector, bindAuthorizationHandoffs } from "./authorization-handoff.js";
 import { bindMcpClient } from "./mcp-client-context.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import * as z from "zod";
 import { advertisedSchema } from "./advertised-schema.js";
-import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPolicyError, flatSearchResult, MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, } from "./catalog-service.js";
+import { boundedDiscoveryText, CatalogService, DiscoveryPolicyError, flatSearchResult, MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT, } from "./catalog-service.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
-import { boundedEchoText, ConnectorCallError, msg } from "./errors.js";
+import { boundedEchoText, clipText, ConnectorCallError, MAX_TOOL_ERROR_BYTES, msg, } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
+import { RESULT_ENVELOPE_V4 } from "./result-seal.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, 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 { isWriteLike } from "./tool-safety.js";
+import { AUTHORIZE_OUTPUT, SEARCH_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_PAGE_BYTES, PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
+import { previewResult } from "./result-preview.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
 // Each page is a slice of payload bytes, so a leading U+FEFF is data.
@@ -38,6 +45,9 @@ export function jsonResult(obj, text = JSON.stringify(obj)) {
 function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+function resultError(message) {
+    return toolError(utilityRecovery("invalid_args", message));
+}
 function discoveryErrorResult(error) {
     return toolError({ code: error.code, message: error.message, retryable: false });
 }
@@ -110,8 +120,8 @@ function alignEndToCharBoundary(bytes, offset, end, total) {
     return e;
 }
 /** 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+):/;
+const RESULT_REFUSED_V4_HEADER = /^connecta-result-refused-v4:([A-Za-z0-9+/=]+):$/;
 /**
  * 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
@@ -131,6 +141,30 @@ const RESULT_MAX_CHUNKS = 32;
 function resultChunkBytes(totalBytes) {
     return Math.max(RESULT_CHUNK_BYTES, Math.ceil(totalBytes / RESULT_MAX_CHUNKS / 3) * 3);
 }
+const isBinary = (item) => ArrayBuffer.isView(item) || item instanceof ArrayBuffer;
+/**
+ * JSON text, and whether a binary value went into it: as written (the holder's value, before
+ * any toJSON) or as a toJSON returned it. Whatever JSON makes of one, redaction checks its bytes
+ * only while they are binary. Text results have no binary values to lose.
+ */
+function serializedWithBinary(value) {
+    let binary = false;
+    const text = JSON.stringify(value, function (key, item) {
+        binary ||= isBinary(this[key]) || isBinary(item);
+        return item;
+    });
+    return { text: text === undefined ? String(value) : text, binary };
+}
+/**
+ * Give back a stash nothing can name any more; its layout follows from its size. Sealing
+ * writes a header for whatever the ledger still holds, so the id leaves the ledger first.
+ * Once sealing has begun it owns the entry, which keeps its charge until it expires.
+ */
+export function releaseStashedResult(registry, held, id, totalBytes) {
+    return Effect.suspend(() => held && !held.discard(id)
+        ? Effect.void
+        : registryProgram(registry, "releaseResult", id, Math.max(1, Math.ceil(totalBytes / resultChunkBytes(totalBytes)))));
+}
 /**
  * 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
@@ -143,6 +177,26 @@ function base64Of(bytes) {
     }
     return out;
 }
+/** Calls a whole-result loop leaves the program, so it can also act on what it finds. */
+const LOOP_SPARE_HOST_CALLS = 2;
+/**
+ * Host calls to read every page of a retained result at the default page size.
+ * A page can stop up to three bytes short to keep a character whole, so the
+ * count assumes every one does.
+ */
+const resultPages = (cap, totalBytes) => Math.ceil(totalBytes / Math.max(1, Math.min(cap, PROGRAM_RESULT_PAGE_BYTES) - 3));
+/** Whether a program with this many calls left can walk every page of a retained result. */
+const loopFits = (cap, totalBytes, calls) => resultPages(cap, totalBytes) + LOOP_SPARE_HOST_CALLS <= calls;
+/**
+ * A read handle's advice, sized to the calls its program has left. Overrunning
+ * them ends the run and discards everything it read, so a result that can't fit
+ * pages across programs, which carry the offset and reduction between them.
+ */
+function readHandleHint(id, cap, totalBytes, calls) {
+    if (loopFits(cap, totalBytes, calls.left))
+        return "Loop connecta.result(handle, { offset }) until !hasMore, setting offset to nextOffset.";
+    return `Needs up to ${resultPages(cap, totalBytes)} host calls; this program has ${calls.left} left, and overrunning returns nothing. Call connecta.result(${JSON.stringify(id)}, { offset }) at most ${Math.max(0, calls.left - LOOP_SPARE_HOST_CALLS)} times here and ${Math.max(1, calls.max - LOOP_SPARE_HOST_CALLS)} per new program, return your reduction and nextOffset, and continue from both within ${RESULT_TTL_SECONDS / 60} minutes.`;
+}
 /**
  * The page a notice's nextAction asks a program to read: it fits the program's
  * return even if every byte escapes to six JSON characters, with room for the
@@ -152,6 +206,28 @@ function programPageBytes(results) {
     const fits = Math.floor(((results.programChars ?? MAX_EXECUTE_RESULT_CHARS) - 1024) / 6);
     return Math.max(4, Math.min(fits, results.cap, PROGRAM_RESULT_PAGE_BYTES));
 }
+/** A retained result its run could not seal: a typed answer, and repeating this page cannot help. */
+function resultNotRetained(write, id) {
+    const label = `"${boundedEchoText(id, 96)}"`;
+    return write
+        ? {
+            code: "result_not_retained",
+            message: `Result ${label} is not retrievable: it was not retained past the run that produced it. ${WRITE_ALREADY_RAN}`,
+            retryable: false,
+            nextAction: {
+                action: "recover_result",
+                purpose: "Read the write's target for its outcome, or report the missing output. Never repeat the write.",
+            },
+        }
+        : {
+            code: "result_not_retained",
+            message: `Result ${label} was not retained past the run that produced it. Rerun the read for a fresh result.`,
+            retryable: false,
+            nextAction: { action: "recover_result", purpose: "Rerun the read in a new call or program." },
+        };
+}
+/** nextAction for a whole read: runs as written, and is meant to be edited first. */
+const reduceWhole = (id, results) => `async () => { const { data } = await connecta.result(${JSON.stringify(id)}, { all: true }); return /* reduce data to what you need */ JSON.stringify(data).slice(0, ${programPageBytes(results)}); }`;
 /** Opens a write's notice, ahead of any paging instruction. */
 const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see its result.";
 /** UTF-8 cannot represent lone UTF-16 surrogates without changing them. */
@@ -180,7 +256,9 @@ function isWellFormedText(text) {
  * it is the one thing its notice forbids.
  */
 const readReduceFirst = (routes) => `To find something specific, repeat this read inside ${routes.program} with connecta.call and filter or search the result there, returning only what matters`;
-function pagingHint(results, totalBytes, preview) {
+function pagingHint(results, id, totalBytes, preview) {
+    if (results.readBytes !== undefined && totalBytes <= results.readBytes)
+        return `${results.write ? WRITE_ALREADY_RAN + " " : ""}Read this completed return with connecta.result(id, { all: true }) inside ${results.routes.program} and reduce it, as nextAction does.`;
     if (results.pagingTool === "read_result") {
         const shown = preview.kind === "prefix"
             ? `Bytes 0-${preview.bytes} of ${totalBytes} follow; page the rest`
@@ -197,6 +275,11 @@ 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"];
+        // Stop fetching again when one program can reach every retained byte: the reduction
+        // still sees the whole value, and the downstream is asked only once. Beyond that the
+        // loop would end in budget_exceeded with nothing returned, so a program repeats the read.
+        if (loopFits(results.cap, totalBytes, results.programHostCalls ?? CONFIG_DEFAULTS.execute.maxHostCalls))
+            return `${shown} The full result is retained for ${RESULT_TTL_SECONDS / 60} minutes. To find something in it, loop connecta.result(${JSON.stringify(id)}, { offset }) from offset 0 until !hasMore, setting offset to nextOffset, in one ${results.routes.program} program; filter there and return the matches. To read on, run nextAction.`;
         return `${shown} ${readReduceFirst(results.routes)}; ${full} with connecta.result using nextAction.`;
     }
     const body = preview.kind === "prefix"
@@ -236,7 +319,8 @@ const stashResult = function (bytes, results, preview, rawText) {
             // reader below maps a byte offset back to chunk index and base64 quad.
             const chunkBytes = resultChunkBytes(totalBytes);
             const binding = base64Of(enc.encode(JSON.stringify(results.binding)));
-            const chunks = [`${RESULT_ENVELOPE_V4}${binding}:${totalBytes}:${chunkBytes}:${results.cap}:`];
+            const head = `${RESULT_ENVELOPE_V4}${binding}:${totalBytes}:${chunkBytes}:${results.cap}:`;
+            const chunks = [head];
             for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
                 const chunk = base64Of(bytes.subarray(offset, offset + chunkBytes));
                 if (offset === 0)
@@ -244,9 +328,30 @@ const stashResult = function (bytes, results, preview, rawText) {
                 else
                     chunks.push(chunk);
             }
-            if (!(yield* upwardStep(authInvoke(results, "set", [id, chunks, RESULT_TTL_SECONDS])))) {
+            const held = results.held;
+            // Taken before the booking, so a held header can never outlive the chunks it describes.
+            const expiresAtMs = Date.now() + RESULT_TTL_SECONDS * 1000;
+            if (held && !held.results.accepts())
+                throw new Error("The run already sealed its results");
+            const stashed = yield* upwardStep(authInvoke(results, "set", [id, chunks, RESULT_TTL_SECONDS, ...(held ? [{ holdFirst: true }] : [])]));
+            if (!stashed)
                 throw new Error("Result stash capacity exhausted");
-            }
+            if (held &&
+                !held.results.add({
+                    id,
+                    binding,
+                    total: totalBytes,
+                    chunkBytes,
+                    cap: results.cap,
+                    first: chunks[0].slice(head.length),
+                    chunks: chunks.length,
+                    passed: held.passed,
+                    format: held.format,
+                    binary: held.binary,
+                    write: results.binding.classification === "write",
+                    expiresAtMs,
+                }))
+                throw new Error("The run already sealed its results");
         }
         catch {
             // Paging is advisory after a completed call, including an approved write.
@@ -271,7 +376,7 @@ const stashResult = function (bytes, results, preview, rawText) {
             truncated: true,
             resultId: id,
             totalBytes,
-            hint: pagingHint(results, totalBytes, preview),
+            hint: pagingHint(results, id, totalBytes, preview),
             nextOffset: preview.kind === "prefix" ? preview.bytes : 0,
             nextAction: results.pagingTool === "read_result"
                 ? {
@@ -279,32 +384,37 @@ const stashResult = function (bytes, results, preview, rawText) {
                     arguments: { id, offset: preview.kind === "prefix" ? preview.bytes : 0 },
                 }
                 : {
-                    tool: "execute_code",
+                    tool: results.routes.program,
                     // 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: ${programPageBytes(results)} })`,
+                        code: results.readBytes !== undefined && totalBytes <= results.readBytes
+                            ? reduceWhole(id, results)
+                            : `async () => await connecta.result(${JSON.stringify(id)}, { offset: ${preview.kind === "prefix" ? preview.bytes : 0}, maxBytes: ${programPageBytes(results)} })`,
                     },
                 },
         };
     });
 };
 /** Program calls use the direct-call envelope, ledger, expiry and authority. */
-export function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
-    return runEdge(pageProgramResultNative(registry, baseUrl, resolved, value, format, secrets, requestScope, wireBytes));
+export function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, requestScope, hostCalls, wireBytes = PROGRAM_RESULT_WIRE_BYTES, routes = META_ROUTES, held, readBytes) {
+    return runEdge(pageProgramResultNative(registry, baseUrl, resolved, value, format, secrets, requestScope, hostCalls, wireBytes, routes, held, readBytes));
 }
-const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult, function (registry, baseUrl, resolved, value, format, secrets, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
+const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult, function (registry, baseUrl, resolved, value, format, secrets, requestScope, hostCalls, wireBytes = PROGRAM_RESULT_WIRE_BYTES, routes = META_ROUTES, held, readBytes) {
     return authFlow(function* () {
+        const passed = held?.secrets.revision ?? 0;
         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 serialized = format === "text" ? { text: String(data), binary: false } : serializedWithBinary(data);
+        const text = secrets.text(serialized.text);
         const bytes = enc.encode(text);
         const write = resolved.definition.classification !== "read";
+        const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, registry.maxResultBytes);
         const notice = yield* upwardStep(stashResult(bytes, {
-            // Program-call pages name only execute_code, listed wherever programs run.
-            routes: META_ROUTES,
+            // Pages name the program route the run is on, listed wherever it runs.
+            routes,
             binding: {
                 identity: registry.resultIdentity(),
                 baseUrl,
@@ -313,8 +423,9 @@ const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult,
                 classification: write ? "write" : "read",
             },
             write,
-            cap: resolveMaxResultBytes(resolved.connector.maxResultBytes, registry.maxResultBytes),
-            set: authMethod((id, chunks, ttl) => registryProgram(registry, "stashResult", id, chunks, ttl)),
+            cap,
+            ...(held ? { held: { results: held, passed, format, binary: serialized.binary } } : {}),
+            set: authMethod((id, chunks, ttl, options) => registryProgram(registry, "stashResult", id, chunks, ttl, options)),
             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 {
@@ -324,28 +435,35 @@ const pageProgramResultNative = /* @__PURE__ */ registerAuth(pageProgramResult,
             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.`
+                ? readBytes !== undefined && bytes.length <= readBytes
+                    ? `${write ? `${WRITE_ALREADY_RAN} ` : ""}Read it whole with connecta.result(handle, { all: true }), then reduce it.`
+                    : write
+                        ? `${WRITE_ALREADY_RAN} Page this result with connecta.result(handle); do not repeat the call for output.`
+                        : readHandleHint(notice.resultId, cap, bytes.length, hostCalls)
                 : notice.hint,
         };
     });
 });
 /** Program returns share the direct stash, with all host-admitted call dependencies. */
-export function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars) {
-    return runEdge(guardProgramReturnNative(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars));
+export function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars, held, storeBy, readBytes, routes) {
+    return runEdge(guardProgramReturnNative(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars, held, storeBy, readBytes, routes));
 }
-const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn, function (value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars) {
+const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn, function (value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite, programChars, held, 
+// Stalled storage costs the paging, never the answer.
+storeBy, readBytes, routes = META_ROUTES) {
     return authFlow(function* () {
-        const serialized = serializeResultText(value);
-        if (serialized.length <= maxChars)
+        if (serializeResultText(value).length <= maxChars)
             return value;
-        const text = secrets.text(serialized);
+        const passed = held?.secrets.revision ?? 0;
+        const serialized = serializedWithBinary(value);
+        const text = secrets.text(serialized.text);
         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,
-            // A program return names only execute_code, which every surface running programs lists.
-            routes: META_ROUTES,
+            // A return names the program route the run is on, listed wherever it runs.
+            routes,
             binding: {
                 identity: registry.resultIdentity(),
                 baseUrl,
@@ -355,7 +473,14 @@ const guardProgramReturnNative = /* @__PURE__ */ registerAuth(guardProgramReturn
             write: completedWrite,
             cap,
             ...(programChars !== undefined ? { programChars } : {}),
-            set: authMethod((id, chunks, ttl) => registryProgram(registry, "stashResult", id, chunks, ttl)),
+            ...(readBytes !== undefined ? { readBytes } : {}),
+            ...(held ? { held: { results: held, passed, format: "json", binary: serialized.binary } } : {}),
+            set: authMethod((id, chunks, ttl, options) => storeBy === undefined
+                ? registryProgram(registry, "stashResult", id, chunks, ttl, options)
+                : withDeadlineEffect(() => registryProgram(registry, "stashResult", id, chunks, ttl, options), {
+                    timeoutMs: Math.max(1, storeBy - Date.now()),
+                    timeoutError: new Error("Result storage did not answer."),
+                })),
             warn: () => logFailure(logger, "result paging unavailable", failureRecord({})),
         };
         const notice = yield* upwardStep(stashResult(bytes, results, { kind: "none" }, text));
@@ -380,6 +505,39 @@ function noticeFirst(notice, preview) {
         content: [{ type: "text", text: `${JSON.stringify(notice)}\n${preview}` }],
     };
 }
+/**
+ * The view of a read past its cap, or undefined for its first bytes. A call that
+ * may have written is never reshaped, whatever a deployment override calls it: its
+ * result is its only copy, and repeating it to look again is forbidden (INV-9).
+ */
+function previewOf(text, bytes, results, format) {
+    if (!results.programTool || results.write)
+        return undefined;
+    // The program this offers has to reach every byte within the run's host calls.
+    if (!loopFits(results.cap, bytes.length, results.programHostCalls ?? CONFIG_DEFAULTS.execute.maxHostCalls))
+        return undefined;
+    return previewResult(text, format, results.cap);
+}
+/**
+ * A preview's notice. It says what the body holds and what it leaves out, and
+ * since a host may prompt for or refuse the program, what to do without it.
+ */
+function previewNotice(view, id, totalBytes, tool) {
+    return {
+        truncated: true,
+        resultId: id,
+        totalBytes,
+        ...view.fields,
+        hint: `${view.shown} All of it is retained for ${RESULT_TTL_SECONDS / 60} minutes: run nextAction in ${tool}, editing its last line to ${view.noun === "rows" ? "filter, join or count the rows" : "search for what you need"}, instead of reading pages by hand. If ${tool} is refused or unavailable, the rest can't be read here: narrow this read with its own filter, limit or fields arguments, or say what was not read.`,
+        nextOffset: 0,
+        nextAction: {
+            tool,
+            arguments: {
+                code: `async () => { let text = "", offset = 0, page; do { page = await connecta.result(${JSON.stringify(id)}, { offset }); text += page.text; offset = page.nextOffset; } while (page.hasMore); ${view.reduce} }`,
+            },
+        },
+    };
+}
 /**
  * Return `text` as a single content block; if it exceeds `cap` bytes, stash the
  * full text and return a JSON truncation notice pointing at connecta.result,
@@ -388,7 +546,7 @@ function noticeFirst(notice, preview) {
  * `text` already encoded, so a caller that had to measure it to make this
  * decision doesn't encode it twice.
  */
-const guardEncoded = function (text, bytes, results, cap) {
+const guardEncoded = function (text, bytes, results, cap, format) {
     return authFlow(function* () {
         if (bytes.length <= cap) {
             return {
@@ -405,11 +563,17 @@ const guardEncoded = function (text, bytes, results, cap) {
             kind: "prefix",
             bytes: head.length,
         }));
+        // A preview needs the retained copy its program reads, so a failed stash keeps the first bytes.
+        const view = notice.resultId === undefined ? undefined : previewOf(text, bytes, results, format);
+        if (view && notice.resultId !== undefined) {
+            const shown = previewNotice(view, notice.resultId, bytes.length, results.programTool);
+            return { result: noticeFirst(shown, view.body), truncated: true };
+        }
         return { result: noticeFirst(notice, dec.decode(head)), truncated: true };
     });
 };
 /** {@link guardEncoded} over a string that has not been measured yet. */
-const guardText = function (text, results, cap) {
+const guardText = function (text, results, cap, format) {
     return authFlow(function* () {
         // `JSON.stringify`'s type says `string` where its behavior says `string |
         // undefined`, so TypeScript alone does not keep a non-string out of here.
@@ -418,7 +582,7 @@ const guardText = function (text, results, cap) {
         // through it the way issue #42 describes.
         const serialized = typeof text === "string" ? text : serializeResultText(text);
         const body = results.secrets?.text(serialized) ?? serialized;
-        return yield* upwardStep(guardEncoded(body, enc.encode(body), results, cap));
+        return yield* upwardStep(guardEncoded(body, enc.encode(body), results, cap, format));
     });
 };
 /** Store an oversized JSON value and replace it with a page handle. */
@@ -474,7 +638,7 @@ function escapedHeadOf(bytes, cap) {
  * the head of a half-written base64 image is of no use to anyone. Either way
  * the full envelope is stashed and pages through `connecta.result`.
  */
-const guardContent = function (content, results, cap) {
+const guardContent = function (content, results, cap, format) {
     return authFlow(function* () {
         content = results.secrets?.redact({ content }).content ?? content;
         const only = content.length === 1 ? content[0] : undefined;
@@ -483,7 +647,7 @@ const guardContent = function (content, results, cap) {
             // Under the cap the block passes through untouched, annotations included.
             if (bytes.length <= cap)
                 return { result: { content }, truncated: false };
-            return yield* upwardStep(guardEncoded(only.text, bytes, results, cap));
+            return yield* upwardStep(guardEncoded(only.text, bytes, results, cap, format));
         }
         let text;
         try {
@@ -540,6 +704,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     // Already normalized and warned about at registry construction.
     const globalCap = registry.maxResultBytes;
     const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs) ?? CONFIG_DEFAULTS.execute.hostCallTimeoutMs;
+    const responseCeilingMs = normalizeTimeoutMs(opts.responseCeilingMs) ?? CONFIG_DEFAULTS.execute.watchdogMs;
     const probeTimeoutMs = normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
     const discoveryConcurrency = resolveDiscoveryConcurrency(opts.discoveryConcurrency);
     // createMetaTools() is called once per inbound MCP request. Sharing this
@@ -558,6 +723,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     }
     const sentSecrets = sentSecretsForRequest(requestScope);
     const skills = new SkillsRegistry(registry, baseUrl, {
+        readOnly: opts.readOnly,
         requestScope,
         requestSignal: opts.requestSignal,
         probeTimeoutMs,
@@ -582,7 +748,22 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     }
     const runCallNative = /* @__PURE__ */ registerAuth(runCall, function (call, source) {
         return authFlow(function* () {
-            const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
+            // A deadline past the client's would trade a typed result for its transport timeout.
+            const now = Date.now();
+            const ceilingAt = (opts.requestStartedAt ?? now) + responseCeilingMs;
+            const remainingMs = ceilingAt - now;
+            const timeoutMs = Math.min(normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs, Math.max(1, remainingMs));
+            const pastCeiling = () => ({
+                code: "timeout",
+                message: `This request used its ${responseCeilingMs}ms response ceiling before ${boundedEchoText(call.address, 512)} started, so it was not sent. Send it again.`,
+                retryable: true,
+                details: {
+                    operation: boundedEchoText(call.address, 512),
+                    stage: "response ceiling",
+                    elapsedMs: responseCeilingMs - (ceilingAt - Date.now()),
+                    deadlineMs: responseCeilingMs,
+                },
+            });
             const outcome = yield* upwardStep(authInvoke(invocation, "invoke", [
                 call.address,
                 call.args ?? {},
@@ -592,7 +773,11 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     sentSecrets,
                     readOnly: opts.readOnly,
                     routes,
-                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    timeoutMs,
+                    // Auth or queueing spent the time, and a 1 ms deadline could still lose
+                    // to a dispatch. A known "not sent" beats an answer the client won't hear.
+                    ...(remainingMs <= 0 ? { refusal: pastCeiling() } : {}),
+                    dispatchDeadline: { at: ceilingAt, refusal: pastCeiling },
                     ...(opts.requestSignal !== undefined ? { requestSignal: opts.requestSignal } : {}),
                     unwrapResult: call.resultMode === "value",
                     ...(opts.downstreamInput
@@ -628,10 +813,12 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                                 tool: resolved.definition.name,
                                 classification: resolved.definition.classification === "read" ? "read" : "write",
                             },
-                            write: resolved.definition.classification !== "read",
+                            write: isWriteLike(resolved.definition),
                             cap,
                             ...(opts.pagingTool ? { pagingTool: opts.pagingTool } : {}),
+                            ...(opts.programTool ? { programTool: opts.programTool } : {}),
                             ...(opts.maxProgramResultChars !== undefined ? { programChars: opts.maxProgramResultChars } : {}),
+                            ...(opts.maxProgramHostCalls !== undefined ? { programHostCalls: opts.maxProgramHostCalls } : {}),
                             set: authMethod((id, value, ttlSeconds) => registryProgram(registry, "stashResult", id, value, ttlSeconds)),
                             // The catalog entry, never `toolName`: a record names a tool
                             // only through the grammar check (src/operator-record.ts).
@@ -660,14 +847,14 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                                     },
                                 ];
                             }
-                            const guarded = yield* upwardStep(guardContent(content, results, cap));
+                            const guarded = yield* upwardStep(guardContent(content, results, cap, format));
                             // 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 = yield* upwardStep(guardText(serializeResultText(value), results, cap));
+                        const guarded = yield* upwardStep(guardText(serializeResultText(value), results, cap, format));
                         guarded.result._meta = { "dev.connecta/format": format };
                         return processed(guarded.result, guarded.truncated, { value });
                     })),
@@ -696,10 +883,11 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 // 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;
+                    const { message } = outcome.error;
+                    let budget = 2 * MAX_TOOL_ERROR_BYTES;
                     while (enc.encode(JSON.stringify(failedResult)).length > cap && budget > 0) {
                         budget = Math.floor(budget / 2);
-                        outcome.error.message = boundedEchoText(outcome.error.message, budget);
+                        outcome.error.message = clipText(message, budget);
                         failedResult = makeFailedResult();
                     }
                 }
@@ -731,7 +919,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             };
         });
     });
-    return {
+    const methods = {
         skills: authMethod((args = {}) => authFlow(function* () {
             try {
                 if (!args.name) {
@@ -748,10 +936,13 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     };
                 }
                 const text = yield* upwardStep(authInvoke(skills, "text", [args.name]));
-                return { content: [{ type: "text", text }], structuredContent: { name: args.name, format: "text", text } };
+                // Guidance is text-only: a structured copy would double every fetch on the wire (result-representation).
+                return { content: [{ type: "text", text }] };
             }
             catch (error) {
-                return errorResult(error instanceof ConnectorCallError ? error.message : "Skills are unavailable.");
+                if (error instanceof SkillLookupError)
+                    return toolError(skillLookupRecovery(error.message));
+                return toolError(utilityRecovery(error instanceof ConnectorCallError ? error.code : "unavailable", "Skills are unavailable.", error instanceof ConnectorCallError && error.retryable));
             }
         })),
         searchTools: authMethod((args) => authFlow(function* () {
@@ -781,25 +972,21 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // 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 ` +
+                return resultError(`Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
                     `>= ${MIN_MAX_RESULT_BYTES}. Omit it to use the deployment default.`);
             }
             if (args.offset !== undefined && !isValidResultOffset(args.offset)) {
-                return errorResult(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
+                return resultError(`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.");
+                return resultError("Use a whole page >= 0, without offset.");
             }
             const results = registry.resultsStorage();
             const unavailableResult = () => ({
                 ...jsonResult({
-                    error: {
-                        code: "unavailable",
-                        message: "Result paging storage is unavailable.",
-                        retryable: true,
-                    },
+                    error: utilityRecovery("unavailable", "Result paging storage is unavailable.", true),
                 }),
                 isError: true,
             });
@@ -821,14 +1008,16 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 options.signal?.throwIfAborted();
                 return value;
             }));
-            const stored = yield* upwardStep(authCall(read, [resultKeys.chunk(args.id, 0)]));
+            const stored = opts.heldResults?.stored(args.id) ??
+                (yield* upwardStep(authCall(read, [resultKeys.chunk(args.id, 0)])));
             if (stored === false)
                 return unavailableResult();
             if (stored === null) {
-                return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                return toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
             }
-            const denied = () => errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
-            const header = RESULT_ENVELOPE_V4_HEADER.exec(stored);
+            const denied = () => toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
+            const refused = RESULT_REFUSED_V4_HEADER.exec(stored);
+            const header = refused ?? RESULT_ENVELOPE_V4_HEADER.exec(stored);
             if (!header)
                 return denied();
             let binding;
@@ -858,6 +1047,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                             !["read", "write"].includes(dependency.classification))) ||
                 !["read", "write"].includes(binding.classification))
                 return denied();
+            if (refused)
+                return toolError(resultNotRetained(binding.classification === "write", args.id));
             const allowed = authMethod(() => authFlow(function* () {
                 options.onStage?.("access validation");
                 options.signal?.throwIfAborted();
@@ -941,7 +1132,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     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)}"`);
+                        return toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
                     }
                     const chunkStart = index * chunkBytes;
                     // Both bounds are chunk-local. `from` inherits `start`'s three-byte
@@ -999,18 +1190,27 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             }
         })),
     };
+    if (!opts.activity?.recordOperation)
+        return methods;
+    const track = (name, method) => authMethod((...args) => operationActivity(opts.activity, registry, name, authCall(method, args)));
+    return {
+        ...methods,
+        skills: track("skill", methods.skills),
+        searchTools: track("search", methods.searchTools),
+        readResult: track("result", methods.readResult),
+    };
 }
 // Each description states only its own tool's scope; the full routing rule
 // lives once in the server instructions. A client that drops instructions
 // still routes correctly from these scopes plus execute_code's terse lead.
 // Only the meta surface lists these tools, so they use its names.
-const SEARCH_DESC = (readOnly) => `${readOnly ? "Catalog inspection; this read-only endpoint omits write tools." : `Catalog inspection, or finding a write before ${META_ROUTES.write}.`} For read work, search inside one ${META_ROUTES.program} program that also 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" selects reads; "approvalRequired" selects the fail-closed write complement; neither grants authority. Empty query browses. Read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
-const CALL_DESC = (readOnly) => `Call one known-address read: a tool explicitly annotated readOnlyHint: true. Other read work: ${META_ROUTES.program}. ${readOnly ? "This endpoint is read-only and refuses every write." : `Unannotated or write-capable tools fail closed to ${META_ROUTES.write}.`} 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 SEARCH_DESC = (readOnly, program) => `${readOnly ? "Inspect the catalog; this read-only endpoint omits write tools." : `Inspect the catalog, or find a write before ${META_ROUTES.write}.`} For read work, search inside one ${program} program that also calls and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; set connector when known; an empty query browses. safety filters by classification and grants nothing. Read catalogErrors and absence before choosing a tool.`;
+const CALL_DESC = (readOnly, program) => `Call one known-address read: a tool explicitly annotated readOnlyHint: true. Other read work: ${program}. ${readOnly ? "This endpoint is read-only and refuses every write." : `Unannotated or write-capable tools fail closed to ${META_ROUTES.write}.`} A truncated result carries nextAction.`;
+const CALL_DESTRUCTIVE_DESC = "Call one tool not explicitly annotated readOnlyHint: true. Check its schema and consequences, then include a short reason for the human reviewer; it grants nothing and is not sent downstream. Sent once: never resend it to see output.";
 /** A read-only endpoint keeps the six-tool surface, so this tool says why it never writes here. */
 const CALL_DESTRUCTIVE_READ_ONLY_DESC = `This endpoint is read-only: search and describe omit write tools, and every write call here is refused. Reads still run; prefer ${META_ROUTES.read} or ${META_ROUTES.program} for them.`;
-const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or required deployment configuration. A configured credential reports presence only: if a call just failed with an authentication or operator-configuration error, give the retained handoff to the operator; otherwise proceed with the call. 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.";
+const AUTHORIZE_DESC = "Use after auth_required when the error has no authorizationUrl or operatorUrl, or for a fresh link; otherwise pass that on. Returns an OAuth or operator-credential handoff, or required deployment configuration. A configured credential reports presence only: if a call just failed on authentication or configuration, give the retained handoff to the operator; otherwise proceed with the call. force=true restarts OAuth when the verified user opens the /connect URL. Never accepts credentials.";
+const SKILLS_DESC = "List or fetch guidance by exact name. Fetch usage only when guidance is missing 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,
@@ -1020,9 +1220,9 @@ const SKILLS_DESC = "List or fetch on-demand guidance. Fetch usage only when the
  * Registration is per connection and reads the configured connector set.
  */
 const GUIDE_NOTES = {
-    skills: " Also lists this deployment's connector guides by exact name.",
-    search: " A result with guideRequired: true requires its exact named connector guide before the call.",
-    destructive: " Fetch any exact connector guide named by discovery before the call.",
+    skills: " Includes connector guides.",
+    search: " guideRequired: true means fetch its named guide before the call.",
+    destructive: " Fetch any connector guide discovery names first.",
 };
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
 function describedFor(registry, base, note) {
@@ -1047,7 +1247,10 @@ const READ_ONLY_LOCAL = {
     openWorldHint: false,
 };
 const CALL_INPUT_SCHEMA = {
-    address: z.string().meta({ "x-mcp-header": "Address" }),
+    // Error text only: neither message reaches the advertised schema or widens what is accepted.
+    address: z
+        .string({ error: 'expected a string such as "connector.tool". Send { address, args }.' })
+        .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(),
@@ -1067,7 +1270,13 @@ const SEARCH_INPUT = advertisedSchema(z.object({
     fullDescriptions: z.boolean().optional(),
     includeSchemas: z.enum(["compact", "json", "typescript"]).optional(),
 }));
-const CALL_INPUT = advertisedSchema(z.strictObject(CALL_INPUT_SCHEMA));
+/** MCP's own `tools/call` spells these `name` and `arguments`; say so at the point of failure. */
+const CALL_SHAPE = {
+    error: (issue) => issue.code === "unrecognized_keys"
+        ? `Unrecognized key${issue.keys?.length === 1 ? "" : "s"}: ${issue.keys?.map((key) => JSON.stringify(key)).join(", ")}. Send { address, args }, with the tool's arguments in args.`
+        : undefined,
+};
+const CALL_INPUT = advertisedSchema(z.strictObject(CALL_INPUT_SCHEMA, CALL_SHAPE));
 const CALL_DESTRUCTIVE_INPUT = advertisedSchema(z.strictObject({
     ...CALL_INPUT_SCHEMA,
     // Bounded above, but with no lower bound: a model that sends `""` or
@@ -1075,8 +1284,8 @@ const CALL_DESTRUCTIVE_INPUT = advertisedSchema(z.strictObject({
     // call over a cosmetic field the host merely displays is the wrong
     // trade. It is normalized to absent in the handler instead.
     reason: z.string().max(500).optional(),
-}));
-const READ_RESULT_DESC = "Page by resultId and nextAction from the truncation notice. UTF-8 byte ranges: continue from nextOffset while hasMore. Never repeat a write for output.";
+}, CALL_SHAPE));
+const READ_RESULT_DESC = "Page a truncated result: run nextAction, then continue from nextOffset while hasMore. Never repeat a write for output.";
 const READ_RESULT_INPUT = advertisedSchema(z.strictObject({
     id: z.string(),
     offset: z.number().int().nonnegative().optional(),
@@ -1098,6 +1307,8 @@ const AUTHORIZE_INPUT = advertisedSchema(z.object({
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
         maxProgramResultChars: ctx.maxProgramResultChars,
+        maxProgramHostCalls: ctx.maxProgramHostCalls,
+        programTool: ctx.programTool,
         routes: ctx.routes,
         ...(ctx.native && !ctx.native.executeCode ? { pagingTool: "read_result" } : {}),
         ...(ctx.native ? { activitySource: "native" } : {}),
@@ -1105,6 +1316,8 @@ export function registerMetaTools(server, registry, ctx) {
         requestScope: ctx.requestScope,
         readOnly: ctx.readOnly,
         defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
+        responseCeilingMs: ctx.responseCeilingMs,
+        requestStartedAt: ctx.requestStartedAt,
         probeTimeoutMs: ctx.probeTimeoutMs,
         discoveryConcurrency: ctx.discoveryConcurrency,
         activity: ctx.activity,
@@ -1116,6 +1329,7 @@ export function registerMetaTools(server, registry, ctx) {
         requestSignal: ctx.requestSignal,
         defer: ctx.defer,
     });
+    const routeProgram = ctx.routes?.program ?? META_ROUTES.program;
     const bindRequest = (request) => {
         if (ctx.client)
             bindMcpClient(request, ctx.client, ctx.activity);
@@ -1124,7 +1338,6 @@ export function registerMetaTools(server, registry, ctx) {
         description: describedFor(registry, SKILLS_DESC, "skills"),
         ...(ctx.native ? { _meta: { "dev.connecta/surface": { surface: "native", ...ctx.native } } } : {}),
         inputSchema: SKILLS_INPUT,
-        outputSchema: SKILLS_OUTPUT,
         annotations: READ_ONLY_LOCAL,
     }, authMethod((args, request) => authFlow(function* () {
         bindRequest(request);
@@ -1179,7 +1392,7 @@ export function registerMetaTools(server, registry, ctx) {
         });
     }
     server.registerTool("search_tools", {
-        description: describedFor(registry, SEARCH_DESC(ctx.readOnly === true), "search"),
+        description: describedFor(registry, SEARCH_DESC(ctx.readOnly === true, routeProgram), "search"),
         inputSchema: SEARCH_INPUT,
         outputSchema: SEARCH_OUTPUT,
         annotations: READ_ONLY_REMOTE,
@@ -1188,7 +1401,7 @@ export function registerMetaTools(server, registry, ctx) {
         return yield* upwardStep(authInvoke(mt, "searchTools", [args]));
     })));
     server.registerTool("call_tool", {
-        description: CALL_DESC(ctx.readOnly === true),
+        description: CALL_DESC(ctx.readOnly === true, routeProgram),
         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;