@zackbart/connecta 0.40.0 → 0.42.0

package/dist/executor-admission.js

@@ -335,6 +335,8 @@ export function executorName(executor) {
  */
 export function withExecutorAdmission(executor, admission) {
     return {
+        ...(executor.deadlineMs !== undefined ? { deadlineMs: executor.deadlineMs } : {}),
+        ...(executor.maxReadBytes !== undefined ? { maxReadBytes: executor.maxReadBytes } : {}),
         async acquire(options = {}) {
             const token = await admission.acquire(options);
             let released = false;

package/dist/executor-contract.js

@@ -12,6 +12,10 @@ export function brandExecutor(executor, lifecycle) {
     return executor;
 }
 export function assertExecutor(executor) {
+    const { deadlineMs } = executor;
+    if (deadlineMs !== undefined && (!Number.isSafeInteger(deadlineMs) || deadlineMs < 1)) {
+        throw new Error("ConnectaConfig.executor.deadlineMs must be a positive whole number of milliseconds.");
+    }
     const descriptor = Object.getOwnPropertyDescriptor(executor, EXECUTOR_BRAND);
     const brand = descriptor?.value;
     if (typeof executor.execute === "function" &&
@@ -35,6 +39,8 @@ export function customExecutor(executor, options) {
     const name = executorName(executor);
     const wrapper = {
         ...(name ? { name } : {}),
+        ...(executor.deadlineMs !== undefined ? { deadlineMs: executor.deadlineMs } : {}),
+        ...(executor.maxReadBytes !== undefined ? { maxReadBytes: executor.maxReadBytes } : {}),
         execute: executor.execute.bind(executor),
         ...(executor.close ? { close: executor.close.bind(executor) } : {}),
         ...(isAdmittingExecutor(executor)

package/dist/executor-result.js

@@ -1,6 +1,6 @@
-import { META_ROUTES } from "./agent-routes.js";
+import { META_ROUTES } from "./route-names.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
-import { msg } from "./errors.js";
+import { msg, tokenPrefix } from "./errors.js";
 /** ~6k tokens. Sandbox code should filter data down before returning. */
 export const MAX_EXECUTE_RESULT_CHARS = CONFIG_DEFAULTS.execute.maxResultChars;
 export const MAX_EXECUTE_LOG_CHARS = 4_000;
@@ -64,7 +64,7 @@ export function guardExecuteResultValue(value, maxChars = MAX_EXECUTE_RESULT_CHA
 export function truncateExecuteText(text, max) {
     if (text.length <= max)
         return text;
-    return `${text.slice(0, max)}\n--- TRUNCATED (${text.length} chars total) — filter/map/slice data inside your code and return only what you need ---`;
+    return `${tokenPrefix(text, max)}\n--- TRUNCATED (${text.length} chars total) — filter/map/slice data inside your code and return only what you need ---`;
 }
 /**
  * Validate serialization before IPC without discarding the program return.

package/dist/executors/quickjs-child.js

@@ -1,11 +1,18 @@
 import { prepareExecuteResultForTransport } from "../executor-result.js";
-import { InvocationFailure } from "../invocation.js";
+import { InvocationFailure } from "../invocation-failure.js";
 import { msg } from "../errors.js";
 import { MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_RESULT_BYTES, QUICKJS_RESULT_CHUNK_CHARS, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
 import { executeQuickJs, prepareQuickJs } from "./quickjs-runtime.js";
 let activeJobId;
 let nextCallId = 1;
 const pending = new Map();
+/** Host calls still open will never hear back; settling them lets their handles go. */
+function settlePending() {
+    for (const request of pending.values()) {
+        request.reject(new Error("Execution ended before the host call settled."));
+    }
+    pending.clear();
+}
 function send(message) {
     if (!process.send)
         throw new Error("QuickJS child IPC channel is unavailable.");
@@ -70,9 +77,14 @@ async function run(payload) {
             jobId: payload.id,
             payloadJson: stringifyBounded(entry, "QuickJS log entry"),
         }));
+        // Answer only once the runtime is freed, so the parent knows whether this child can take the
+        // next run before it could send one. Only the settled stragglers stand in the way.
+        settlePending();
+        const tornDown = await raw.tornDown;
         const prepared = {
             outcome: prepareExecuteResultForTransport(raw),
             ...(raw.timedOut ? { timedOut: true } : {}),
+            ...(tornDown === false ? { retire: true } : {}),
         };
         let payloadJson;
         try {
@@ -85,10 +97,7 @@ async function run(payload) {
     }
     finally {
         activeJobId = undefined;
-        for (const request of pending.values()) {
-            request.reject(new Error("Execution ended before the host call settled."));
-        }
-        pending.clear();
+        settlePending();
     }
 }
 process.on("message", (message) => {

package/dist/executors/quickjs-runtime.d.ts

@@ -16,6 +16,8 @@ export declare function normalizeCode(code: string): string;
  */
 export interface QuickJsExecutionResult extends ExecuteResult {
     timedOut?: boolean;
+    /** Settles once the run's runtime is freed; false when freeing it failed. */
+    tornDown?: Promise<boolean>;
 }
 /**
  * Execute one program inside the child. Wall time includes host waits; guest

package/dist/executors/quickjs-runtime.js

@@ -9,8 +9,8 @@ import { utf8Length } from "../bytes.js";
 // continuations from a host-side loop. Values cross the boundary as JSON, so
 // provider args/results must be JSON-serializable.
 import { getQuickJS } from "quickjs-emscripten";
-import { InvocationFailure } from "../invocation.js";
-import { msg } from "../errors.js";
+import { InvocationFailure } from "../invocation-failure.js";
+import { msg, tokenPrefix } from "../errors.js";
 import { withoutProgramTerminator } from "../program-source.js";
 import { hostCallLabel, MAX_QUICKJS_LOG_TRANSPORT_BYTES, serializedBytes } from "./quickjs-protocol.js";
 /** Load and compile the shared QuickJS WASM module before a run budget starts. */
@@ -28,10 +28,8 @@ const MAX_LOG_TOTAL_CHARS = 256_000;
 const LOG_ENTRY_LIMIT_MARKER = `[log truncated after ${MAX_LOG_ENTRIES} entries]`;
 const LOG_SIZE_LIMIT_MARKER = "[log truncated: size budget exceeded]";
 const MAX_LOG_MARKER_TRANSPORT_BYTES = Math.max(logTransportBytes(LOG_ENTRY_LIMIT_MARKER), logTransportBytes(LOG_SIZE_LIMIT_MARKER));
-// Keep one host result below the range where quickjs-emscripten@0.32.0 can
-// nondeterministically fail during runtime disposal under concurrent load.
-// This still lets guest code reduce data more than ten times larger than
-// connecta's final response budget.
+// Bounds what one host result puts in the guest. This still lets guest code
+// reduce data more than ten times larger than connecta's final response budget.
 const MAX_HOST_RESULT_BYTES = 256 * 1024;
 function logTransportBytes(entry) {
     // The log is encoded into ExecutionPayload, then that payloadJson string is
@@ -159,7 +157,7 @@ function installBridge(ctx, providers, logs, onLog) {
         // but slicing here keeps only a bounded string alive in `logs`.
         let entry = ctx.getString(h);
         if (entry.length > MAX_LOG_ENTRY_CHARS) {
-            entry = `${entry.slice(0, MAX_LOG_ENTRY_CHARS)}…[entry truncated]`;
+            entry = `${tokenPrefix(entry, MAX_LOG_ENTRY_CHARS)}…[entry truncated]`;
         }
         const entryTransportBytes = logTransportBytes(entry);
         if (logTotalChars + entry.length > MAX_LOG_TOTAL_CHARS ||
@@ -222,7 +220,7 @@ function installBridge(ctx, providers, logs, onLog) {
                 }
                 else {
                     const error = ctx.newError();
-                    const message = ctx.unwrapResult(ctx.evalCode(JSON.stringify(msg(reply.error).slice(0, 4_000))));
+                    const message = ctx.unwrapResult(ctx.evalCode(JSON.stringify(tokenPrefix(msg(reply.error), 4_000))));
                     ctx.setProp(error, "message", message);
                     message.dispose();
                     if (reply.error instanceof InvocationFailure) {
@@ -262,6 +260,13 @@ export async function executeQuickJs(code, providers, options, onLog) {
     const { timeoutMs, cpuTimeMs, memoryLimitBytes, maxStackSizeBytes } = options;
     const QuickJS = await getQuickJS();
     const ctx = QuickJS.newContext();
+    // quickjs-emscripten-core 0.32.0's executePendingJobs reads its context out-pointer through a
+    // typed array, which detaches when WASM memory grows during the job pass. It then reads
+    // undefined and calls newContext({ contextPointer: undefined }), which creates a context
+    // nothing frees, and freeing the runtime aborts. A run has this one context, and that lookup
+    // is the only thing here that reaches newContext, so it always means this one.
+    // Remove once a release fixes it: justjake/quickjs-emscripten#240, fix in PR #248.
+    ctx.runtime.newContext = () => ctx;
     const deadline = Date.now() + timeoutMs;
     const timeoutError = `Execution timed out after ${timeoutMs}ms.`;
     const cpuTimeoutError = `Execution exceeded the ${cpuTimeMs}ms guest CPU budget.`;
@@ -293,6 +298,16 @@ export async function executeQuickJs(code, providers, options, onLog) {
     let describeError;
     const logs = [];
     const bridge = installBridge(ctx, providers, logs, onLog);
+    // A failed free leaves this child's WASM module unusable, but the answer is already in host memory.
+    const dispose = () => {
+        try {
+            ctx.dispose();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
     const finish = (r) => {
         bridge.aborted = true;
         describeError?.dispose();
@@ -307,19 +322,17 @@ export async function executeQuickJs(code, providers, options, onLog) {
         // stragglers are waiting on. Arming before the pending check (and
         // synchronously, before the first await) closes the settle-before-arm
         // window: any settle after this point resolves the promise we await.
-        if (bridge.pending === 0)
-            ctx.dispose();
-        else {
-            void (async () => {
+        const tornDown = bridge.pending === 0
+            ? Promise.resolve(dispose())
+            : (async () => {
                 armWake(bridge);
                 while (bridge.pending > 0) {
                     await bridge.waitForSettle;
                     armWake(bridge);
                 }
-                ctx.dispose();
+                return dispose();
             })();
-        }
-        return logs.length > 0 ? { ...r, logs } : r;
+        return { ...r, ...(logs.length > 0 ? { logs } : {}), tornDown };
     };
     const rejected = (error) => {
         // Interrupt/deadline facts are host state, never inferred by inspecting
@@ -332,7 +345,7 @@ export async function executeQuickJs(code, providers, options, onLog) {
         let description = { name: "Error", message: "Program threw a value." };
         const type = ctx.typeof(error);
         if (type === "string")
-            description = ctx.getString(error).slice(0, 4000);
+            description = tokenPrefix(ctx.getString(error), 4000);
         else if (type === "number")
             description = ctx.getNumber(error);
         else if (type === "undefined")
@@ -347,7 +360,10 @@ export async function executeQuickJs(code, providers, options, onLog) {
             if (described.error)
                 described.error.dispose();
             else {
-                description = JSON.parse(ctx.getString(described.value)) ?? description;
+                const parsed = JSON.parse(ctx.getString(described.value));
+                if (typeof parsed?.name === "string")
+                    parsed.name = tokenPrefix(parsed.name, 64);
+                description = parsed ?? description;
                 described.value.dispose();
             }
             if (wallInterrupted || Date.now() >= deadline)
@@ -364,7 +380,7 @@ export async function executeQuickJs(code, providers, options, onLog) {
         const location = /:(\d+)(?::\d+)?\)?(?:\n|$)/.exec(stack);
         return {
             result: undefined,
-            error: formatGuestError(description).slice(0, 4000),
+            error: tokenPrefix(formatGuestError(description), 4000),
             failure: {
                 name,
                 ...(call ? { call } : {}),
@@ -410,8 +426,9 @@ export async function executeQuickJs(code, providers, options, onLog) {
           for (let i = 0; i < prototypes.length; i++) {
             if (prototype === prototypes[i][0]) { name = prototypes[i][1]; break; }
           }
-          return stringify({ __proto__: null, name: text("name", name, 64),
-            message: text("message", "Program threw a value.", 4000), stack: text("stack", "", 1000) });
+          // One unit past the host's cuts, which read it to tell a finished token from an open one.
+          return stringify({ __proto__: null, name: text("name", name, 65),
+            message: text("message", "Program threw a value.", 4001), stack: text("stack", "", 1000) });
         };
       })()`));
     if (described.error) {

package/dist/executors/quickjs.js

@@ -17,9 +17,10 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Deferred, Duration, Effect, Exit, Schedule, Scope } from "effect";
 import { AdmissionController, ExecutorAdmissionError, ExecutorExecutionError } from "../executor-admission.js";
-import { msg } from "../errors.js";
-import { InvocationFailure } from "../invocation.js";
+import { msg, tokenPrefix } from "../errors.js";
+import { InvocationFailure } from "../invocation-failure.js";
 import { brandExecutor } from "../executor-contract.js";
+import { PROGRAM_RESULT_READ_BYTES } from "../program-result.js";
 import { MAX_EXECUTE_LOG_CHARS } from "../executor-result.js";
 import { admit } from "../runtime/admission.js";
 import { awaitExecutorLease, executorProgram, provideExecutorProgram } from "../runtime/executor.js";
@@ -77,7 +78,7 @@ function nonNegativeWhole(value, fallback, name) {
 function errorPayload(error) {
     return JSON.stringify({
         ok: false,
-        error: msg(error).slice(0, MAX_ERROR_CHARS),
+        error: tokenPrefix(msg(error), MAX_ERROR_CHARS),
         ...(error instanceof InvocationFailure ? { call: error.details } : {}),
     });
 }
@@ -121,10 +122,12 @@ let providePoolProgram;
 class QuickJsChildPool {
     /** What `/health` and `connecta doctor` call this sandbox. */
     name = "QuickJS";
+    deadlineMs;
     admission;
     slots;
     available;
     runtimeOptions;
+    maxReadBytes;
     // Scope closes still in flight, so close() can wait out every child rather
     // than only the ones it retired itself.
     retiring = new Set();
@@ -145,6 +148,10 @@ class QuickJsChildPool {
             memoryLimitBytes: positiveWhole(options.memoryLimitBytes, DEFAULT_MEMORY_LIMIT_BYTES, "memoryLimitBytes"),
             maxStackSizeBytes: positiveWhole(options.maxStackSizeBytes, DEFAULT_STACK_LIMIT_BYTES, "maxStackSizeBytes"),
         };
+        this.deadlineMs = this.runtimeOptions.timeoutMs;
+        // Parsing and then using a value costs CPU and heap in proportion to its size,
+        // so a tighter budget reads less, and no budget reads past the fixed cap.
+        this.maxReadBytes = Math.min(Math.floor((PROGRAM_RESULT_READ_BYTES * this.runtimeOptions.cpuTimeMs) / DEFAULT_CPU_TIME_MS), 2 * 1024 * 1024, Math.floor(this.runtimeOptions.memoryLimitBytes / 16));
         this.slots = Array.from({ length: concurrency }, () => ({
             crashes: [],
             notBefore: 0,
@@ -475,9 +482,16 @@ class QuickJsChildPool {
                 if (typeof entry !== "string")
                     return;
                 const separator = active.logs.length > 0 ? 1 : 0;
-                const retained = entry.slice(0, MAX_EXECUTE_LOG_CHARS + 1 - active.logChars - separator);
-                active.logs.push(retained);
-                active.logChars += separator + retained.length;
+                const room = MAX_EXECUTE_LOG_CHARS + 1 - active.logChars - separator;
+                if (entry.length > room) {
+                    // A cut between tokens can stop short of the bound, so its marker signals the loss.
+                    active.logs.push(`${tokenPrefix(entry, room)}…[entry truncated]`);
+                    active.logChars = MAX_EXECUTE_LOG_CHARS + 1;
+                }
+                else {
+                    active.logs.push(entry);
+                    active.logChars += separator + entry.length;
+                }
             }
             catch {
                 /* Malformed log messages carry no output. */
@@ -519,7 +533,10 @@ class QuickJsChildPool {
             slot.backoff = undefined;
             slot.notBefore = 0;
             this.resolveActive(slot, payload.outcome);
-            if (payload.timedOut) {
+            if (payload.retire) {
+                console.warn("[connecta] QuickJS could not free a finished run's runtime. Its answer stands; replacing the child.");
+            }
+            if (payload.timedOut || payload.retire) {
                 // A timed-out host call may still retain QuickJS handles. A fresh child
                 // is cheaper and safer than reusing a context with unknown stragglers.
                 // The runtime sets this flag itself: matching error text here would let

package/dist/guarded-transport.js

@@ -1,6 +1,8 @@
 // The plain runtime slot keeps the HTTP kit and Node sender off the root
 // and Worker graphs. /node installs its sender when listen() starts serving.
 import { ConnectorCallError } from "./errors.js";
+/** Internal request marker: only downstream-learned URL fetches set this. */
+export const learnedDestination = Symbol("connecta.learnedDestination");
 let owned;
 /** Runtime configuration, never request data. Returns the previous slot for isolated fixtures. */
 export function configureGuardedTransport(transport) {

package/dist/guest-functions.js

@@ -13,7 +13,7 @@ export const GUEST_FUNCTIONS = [
     {
         name: "search",
         budget: "hostCall",
-        declaration: "search(args?: { query?: string; connector?: string; limit?: number; offset?: number; includeSchemas?: Schemas }): Promise<{ tools: Tool[]; catalogErrors: { connector: string; code: string; message: string }[]; hasMore: boolean; nextOffset?: number }>;",
+        declaration: "search(args?: { query?: string; connector?: string; limit?: number; offset?: number; includeSchemas?: Schemas; fullDescriptions?: boolean }): Promise<{ tools: Tool[]; catalogErrors: { connector: string; code: string; message: string; stale?: true }[]; absence?: { message: string }; readyCalls?: { address: string; args: { path: string } }[]; hasMore: boolean; nextOffset?: number }>;",
     },
     /** Describes exact addresses, one entry per address in order. */
     {
@@ -34,10 +34,11 @@ export const GUEST_FUNCTIONS = [
         budget: "hostCall",
         declaration: "read(uri: string): Promise<{ contents: { uri: string; text?: string; blob?: string }[] }>;",
     },
-    /** Pages a retained result by page or UTF-8 byte offset. */
+    /** Reads a retained result whole, or pages it by page or UTF-8 byte offset. */
     {
         name: "result",
         budget: "hostCall",
+        wrapped: true,
         deadline: "result storage",
         declaration: "result(id: string | Paged, options?: { page?: number; offset?: number; maxBytes?: number }): Promise<{ text: string; hasMore: boolean; nextOffset?: number }>;",
     },
@@ -55,7 +56,7 @@ export const GUEST_FUNCTIONS = [
         budget: "emission",
         declaration: "emit(block: Block | Native | Exclude<Result, Paged>): PromiseLike<void>;",
     },
-    /** Tells the host a failed program read a result field off an unawaited call. */
+    /** Tells the host a program read a result field off an unawaited call. */
     {
         name: "unawaited",
         budget: "once",
@@ -76,7 +77,7 @@ export const GUEST_API_DECLARATION = `declare const connecta: {
 ${GUEST_FUNCTIONS.flatMap((fn) => ("declaration" in fn ? [fn.declaration] : [])).join("\n")}
 };
 type Schemas = "json" | "compact" | "typescript";
-type Tool = { address: string; description?: string; inputSchema?: unknown; outputSchema?: unknown; signature?: string };
+type Tool = { address: string; name?: string; description?: string; inputSchema?: unknown; outputSchema?: unknown; signature?: string; guideRequired?: true };
 type Paged = { format: "paged"; valueFormat: "json" | "text"; resultId?: string; totalBytes: number; truncated: true; hint: string };
 type Result = ({ format: "json"; data: unknown } | { format: "text"; data: string } | Paged) & { content?: Native[] };
 type Block = { type: "text"; text: string } | { type: "image" | "audio"; data: string; mimeType: string };

package/dist/guest-runtime.js

@@ -1,4 +1,5 @@
 import { GUEST_FUNCTIONS } from "./guest-functions.js";
+import { LEADING_TRIVIA } from "./program-source.js";
 /** Capture the single-use runner before evaluating the guest expression. */
 export function wrapGuestProgram(code) {
     return `async () => globalThis.__connecta_run()(async (connecta) => await (\n${code}\n)())`;
@@ -109,6 +110,7 @@ export function guestInitializer() {
   const promiseCatch = Function.prototype.call.bind(NativePromise.prototype.catch);
   const promiseFinally = Function.prototype.call.bind(NativePromise.prototype.finally);
   const push = Function.prototype.call.bind(Array.prototype.push);
+  const join = Function.prototype.call.bind(Array.prototype.join);
   const apply = Function.prototype.call.bind(Function.prototype.apply);
   const NativeError = Error;
   const NativeWeakMap = WeakMap;
@@ -131,10 +133,35 @@ export function guestInitializer() {
         page = await hostResult(value.transfer);
         text += page.text;
       } while (page.hasMore);
-      return { data: value.handle.valueFormat === "json" ? JSON.parse(text) : text,
+      const whole = { data: value.handle.valueFormat === "json" ? JSON.parse(text) : text,
         format: value.handle.valueFormat };
+      // Nothing can name a read's bytes now, so the host may reclaim them.
+      if (value.reclaim) try { await hostResult(value.transfer); } catch {}
+      return whole;
     } catch { return value.handle; }
   }
+  async function result(id, options) {
+    if (!options || options.all !== true) {
+      const page = await apply(hostResult, undefined, arguments);
+      // The transfer cursor is the prelude's: a getter on all must not hand it to the program.
+      if (page && page.transfer) delete page.transfer;
+      return page;
+    }
+    let page = await hostResult(id, options);
+    const parts = [page.text];
+    const transfer = page.transfer;
+    while (page.hasMore) {
+      page = await hostResult(transfer);
+      push(parts, page.text);
+    }
+    const text = join(parts, "");
+    const stored = id ? id.valueFormat : undefined;
+    if (stored === "text") return { data: text, format: "text" };
+    // A handle's JSON that won't parse throws; only a bare id, which doesn't say, may be text.
+    if (stored === "json") try { return { data: JSON.parse(text), format: "json" }; } catch { throw new NativeError("This result can't be parsed whole, because redaction can leave its JSON invalid. Page it with { offset } instead."); }
+    try { return { data: JSON.parse(text), format: "json" }; } catch {}
+    return { data: text, format: "text" };
+  }
   async function call() {
     const reply = await apply(hostCall, undefined, arguments);
     if (!reply || !reply.native) return inline(reply);
@@ -208,6 +235,7 @@ ${GUEST_NAMESPACE}
           if (unawaited) try { await provider.unawaited(); } catch {}
           throw error;
         }
+        if (unawaited) try { await provider.unawaited(); } catch {}
         for (let i = 0; i < pending.length; i++) {
           const report = await pending[i].settled;
           if (!report.ok && !pending[i].handled) throw report.error;
@@ -272,6 +300,14 @@ export function programError(raw, code) {
         hint =
             'Use connecta.call(address, args), connecta.search, connecta.describe, connecta.result, and connecta.skill("usage"). Services are addressed by connector.tool, never guest globals.';
     }
+    else if (name === "TypeError" &&
+        /not a function|not iterable/.test(message) &&
+        /\bconnecta\s*\.\s*(?:search|describe|call)\b/.test(code.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, ""))) {
+        hint = "search and describe return { tools }; call returns { data, format }.";
+    }
+    else if (name === "SyntaxError" && !/^(?:async\b|\(|function\b)/.test(code.replace(LEADING_TRIVIA, ""))) {
+        hint = "Pass one expression: async () => { ...; return answer; }.";
+    }
     return {
         code: "program_error",
         message: `Program ${name}: ${message}`,

package/dist/guest-types.d.ts

@@ -15,6 +15,10 @@ export interface GuestApi {
         timeoutMs?: number;
     }): Promise<GuestResult>;
     read(uri: string): Promise<GuestResourceResult>;
+    /** Reads a retained result whole, for one host call; a larger one throws `result_too_large`. */
+    result(id: string | GuestResultHandle, options: {
+        all: true;
+    }): Promise<Exclude<GuestResult, GuestResultHandle>>;
     result(id: string | GuestResultHandle, options?: {
         page?: number;
         offset?: number;
@@ -138,8 +142,16 @@ interface CatalogSearchFailure extends CatalogFailureDetail {
     connector: string;
     nextAction?: Extract<NonNullable<CallErrorDetails["nextAction"]>, {
         tool: "authorize_connector";
+    } | {
+        url: string;
+    } | {
+        action: string;
     }>;
     retry?: string;
+    /** This connector's tools are listed from its last complete catalog; a call still checks the live one. */
+    stale?: true;
+    /** With `stale`: milliseconds since the downstream last confirmed that catalog. */
+    ageMs?: number;
 }
 interface CatalogSearchPage {
     catalogErrors: CatalogSearchFailure[];
@@ -196,6 +208,7 @@ interface CatalogDescription {
     schemaFormat?: "json" | "text";
     name?: string;
     description?: string;
+    descriptionTruncated?: true;
     guide?: string;
     guideSummary?: string;
     guideRequired?: true;
@@ -207,6 +220,8 @@ interface CatalogDescription {
     inputSchemaTruncated?: true;
     outputSchemaTruncated?: true;
     annotations?: ToolDef["annotations"];
+    /** In `execute_read_code`: false when this route refuses the tool because it can write. */
+    callable?: false;
     error?: string;
     errorDetails?: CatalogDescriptionFailureDetail;
 }
@@ -214,6 +229,7 @@ type CatalogSearchTool = {
     name: string;
     address: string;
     description?: string;
+    descriptionTruncated?: true;
     inputSchema?: unknown;
     outputSchema?: unknown;
     signature?: string;
@@ -226,6 +242,8 @@ type CatalogSearchTool = {
     outputKeys?: string[];
     annotations?: ToolDef["annotations"];
     classification?: ToolDef["classification"];
+    /** In `execute_read_code`: false when this route refuses the tool because it can write. */
+    callable?: false;
     guideRequired?: true;
     guideRequiredReasons?: GuideRequiredReason[];
 };

package/dist/http/client.js

@@ -30,6 +30,12 @@ import { RedirectRefused, Refusal, RequestRefused, ResendRefused, ResponseTooLar
 import { Classification, Dispatches, IdempotencyKey, Ledger, RequestFacts, Secrets, Signal, WriteCapacity, reserveWrite, writeRequestKey, } from "./services.js";
 const decoder = new TextDecoder();
 const responseEntries = new WeakMap();
+// Private request identity for middleware observing a rejected response. Never
+// attach headers or body to the failure or its payload-free ledger entry.
+const failedRequests = new WeakMap();
+export function failedResponseRequest(failure) {
+    return failedRequests.get(failure);
+}
 /** The core's physical request, also available to direct HttpClient middleware. */
 export function responseRequest(response) {
     return responseEntries.get(response);
@@ -88,18 +94,23 @@ export function guardedClient(options) {
                 confined = HttpClientRequest.setHeader(confined, name, value);
         }
         const secrets = yield* Secrets;
+        const identifiers = new Set();
         for (const [name, value] of Object.entries(yield* options.authenticate)) {
             if (confined.headers[name.toLowerCase()] !== undefined) {
                 return yield* refuse(`A ${provider} request may not set the ${name.toLowerCase()} header; authentication is connector-owned.`);
             }
             confined = HttpClientRequest.setHeader(confined, name, value);
-            secrets.header(value);
+            const lower = name.toLowerCase();
+            if (!options.publicIdentifierHeaders?.includes(lower))
+                secrets.header(value);
+            else if (secrets.publicIdentifierHeader(value))
+                identifiers.add(lower);
         }
         // Registered as guarded-fetch registers: the final URL, headers, and a
         // text body (a form body's secrets are read from it).
         const text = bodyText(confined);
         secrets.request(wireUrl(confined), {
-            headers: Object.fromEntries(Object.entries(confined.headers)),
+            headers: Object.fromEntries(Object.entries(confined.headers).filter(([name]) => !identifiers.has(name))),
             ...(text === undefined ? {} : { body: text }),
         });
         preparedEntries.set(confined, entry);
@@ -216,6 +227,7 @@ export function guardedClient(options) {
             const refused = (failure) => {
                 dispatch.failure = failure;
                 responseEntries.set(failure, entry);
+                failedRequests.set(failure, request);
                 return Effect.fail(failure);
             };
             const response = yield* Effect.tryPromise({

package/dist/http/errors.js

@@ -88,6 +88,9 @@ export function isHttpFailure(error) {
 export function validateVendorErrors(vendor) {
     errorMeanings(vendor);
     captureErrorReviews(vendor);
+    const limit = vendor.maxHeaderChars;
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_REVIEWED_HEADER))
+        throw new Error(`maxHeaderChars must be a whole number from 1 to ${MAX_REVIEWED_HEADER}.`);
     const proof = vendor.authBeforeExecution;
     if (proof && (typeof proof.evidence !== "string" || !proof.evidence.trim() || typeof proof.matches !== "function")) {
         throw new Error("An authBeforeExecution declaration requires nonempty evidence and a narrow raw-fact predicate.");
@@ -106,6 +109,7 @@ const TOKEN = /^[A-Za-z0-9_.:[\]-]{1,128}$/;
 /** How many entries of a list the detail line sees. Classification sees them all. */
 const DISPLAYED = 8;
 const MAX_HEADER = 128;
+const MAX_REVIEWED_HEADER = 1024;
 const MAX_DEPTH = 32;
 const MAX_WAIT_MS = 86_400_000;
 const errorReviews = new WeakMap();
@@ -292,11 +296,12 @@ function displayed(facts, vendor) {
         Array.isArray(value) ? value.slice(0, display[name] ?? DISPLAYED) : value,
     ]));
 }
-function visibleHeaders(headers, allowed) {
+function visibleHeaders(headers, vendor) {
     const out = Object.create(null);
-    for (const name of allowed ?? []) {
+    const limit = vendor.maxHeaderChars ?? MAX_HEADER;
+    for (const name of vendor.headers ?? []) {
         const value = headers.get(name);
-        if (value !== null && value.length <= MAX_HEADER && !hasControl(value))
+        if (value !== null && value.length <= limit && !hasControl(value))
             out[name.toLowerCase()] = value;
     }
     return out;
@@ -518,7 +523,7 @@ function classificationInput(failure, vendor, withheld) {
         facts: { ...redacted, ...(captured?.vendor === vendor ? captured.facts : vocabularyFacts(redacted, vendor)) },
         presence: structuralPresence(failure.body, captureErrorReviews(vendor).presence),
         numbers,
-        headers: visibleHeaders(failure.headers, vendor.headers),
+        headers: visibleHeaders(failure.headers, vendor),
         retryAfterMs: numbers["retryAfterMs"],
         operation: failure.operation,
         withheld,

package/dist/http/fields.js

@@ -22,8 +22,10 @@ const ANCHORS = {
     item: "each item in items",
     data: "the response body in data, each item when the body is a list",
 };
+/** What a result can carry that its schema cannot name: the withheld marker and cuts for size. */
+const RESULT_NOTE = 'It only narrows the result. A withheld value reads "[redacted]"; truncated lists paths cut for size, and the ids to fetch them stay.';
 /** The description of a `fields` argument: its anchor, one valid example, then any tool note. */
-export function fieldsDescription(anchor, example, note = "It only narrows the result.") {
+export function fieldsDescription(anchor, example, note = RESULT_NOTE) {
     return `Dot paths to keep. Paths start at ${ANCHORS[anchor]}, e.g. ${JSON.stringify([example])}. ${note}`;
 }
 /** The `fields` argument: at most 50 dot paths of 1 to 200 characters. */
@@ -174,13 +176,15 @@ export function boundWarnings(warnings) {
     const omitted = warnings.length - kept.length;
     return omitted ? [...kept, `${omitted} more warning${omitted === 1 ? "" : "s"} omitted.`] : kept;
 }
+/** Enough declared names to repair a path; a wide contract's full list costs more than most replies. */
+const NAMED_CHARS = 160;
 /** Declared names listed in one warning, within its character budget. */
 function named(names) {
     let text = "";
     let shown = 0;
     for (const name of names) {
         const next = text ? `${text}, ${name}` : name;
-        if (next.length > WARNING_BUDGET.chars - 200)
+        if (next.length > NAMED_CHARS)
             break;
         text = next;
         shown += 1;
@@ -201,6 +205,8 @@ export function fieldsMisses(data, fields, declared = []) {
         return [];
     const flat = (values) => values.flatMap((value) => (Array.isArray(value) ? flat(value) : [value]));
     const contract = declared.map((path) => segments(path.replace(/^\[\]\.?/, "")));
+    // Misses stopping at the same place list its names once.
+    const listed = new Map();
     return fields.flatMap((field, index) => {
         const path = segments(field);
         let values = flat([data]);
@@ -219,9 +225,15 @@ export function fieldsMisses(data, fields, declared = []) {
                     .filter((parts) => parts.length > depth && prefix.every((part, at) => parts[at] === part))
                     .map((parts) => parts[depth])),
             ];
-            return [
-                `fields/${index} matched nothing in this response after value safety and privacy filtering, at segment ${depth + 1}; ${names.length ? `declared there: ${named(names)}` : "the operation declares no properties there"}.`,
-            ];
+            const opening = `fields/${index} matched nothing after filtering, at segment ${depth + 1}`;
+            if (!names.length)
+                return [`${opening}; nothing is declared there.`];
+            const list = named(names);
+            const earlier = listed.get(list);
+            if (earlier !== undefined)
+                return [`${opening}; declared there: same as fields/${earlier}.`];
+            listed.set(list, index);
+            return [`${opening}; declared there: ${list}.`];
         }
         return [];
     });