@zackbart/connecta 0.16.1 → 0.18.0

package/dist/execute.js

@@ -4,7 +4,7 @@ import { boundedDiscoveryText, CatalogService, DiscoveryPolicyError, flatSearchR
 import { errorResult, jsonResult } from "./meta-tools.js";
 import { guardExecuteResultValue, MAX_EXECUTE_LOG_CHARS, truncateExecuteText, } from "./executor-result.js";
 import { ExecutorAdmissionError, ExecutorExecutionError, isAdmittingExecutor, } from "./executor-admission.js";
-import { classifyCallError } from "./errors.js";
+import { boundedEchoText, classifyCallError } from "./errors.js";
 import { InvocationFailure, InvocationService, } from "./invocation.js";
 import { hasConnectorGuides } from "./skills.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
@@ -12,6 +12,8 @@ import { isExplicitlyReadOnly } from "./tool-safety.js";
 const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
 const EXECUTE_HOST_CALL_TIMEOUT_MS = 15_000;
+/** Complete entries plus an exact omission count, all inside this byte cap. */
+export const CONNECTOR_INVENTORY_MAX_BYTES = 256;
 /**
  * Default budgets for `connecta.emit`. The byte budget is a transport bound,
  * not a context bound — emitted image/audio blocks reach the model as media,
@@ -125,7 +127,7 @@ const EMIT_SHAPE_HINT = '{ type: "text", text } or { type: "image" | "audio", da
  */
 function requireEmittedBlock(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error(`connecta.emit accepts exactly one content block: ${EMIT_SHAPE_HINT}`);
+        throw guestFailure("invalid_args", `connecta.emit accepts exactly one content block: ${EMIT_SHAPE_HINT}`);
     }
     const block = raw;
     const fields = block.type === "text"
@@ -134,16 +136,16 @@ function requireEmittedBlock(raw) {
             ? ["type", "data", "mimeType"]
             : undefined;
     if (!fields) {
-        throw new Error(`connecta.emit supports content types "text", "image", and "audio"; got ${JSON.stringify(block.type)}`);
+        throw guestFailure("invalid_args", `connecta.emit supports content types "text", "image", and "audio"; got ${JSON.stringify(block.type)}`);
     }
     for (const field of fields) {
         if (typeof block[field] !== "string") {
-            throw new Error(`connecta.emit block field "${field}" must be a string: ${EMIT_SHAPE_HINT}`);
+            throw guestFailure("invalid_args", `connecta.emit block field "${field}" must be a string: ${EMIT_SHAPE_HINT}`);
         }
     }
     const extra = Object.keys(block).filter((key) => !fields.includes(key));
     if (extra.length > 0) {
-        throw new Error(`connecta.emit block carries unsupported field(s) ${extra.map((key) => JSON.stringify(key)).join(", ")}; a "${String(block.type)}" block is exactly { ${fields.join(", ")} }`);
+        throw guestFailure("invalid_args", `connecta.emit block carries unsupported field(s) ${extra.map((key) => JSON.stringify(key)).join(", ")}; a "${String(block.type)}" block is exactly { ${fields.join(", ")} }`);
     }
     return raw;
 }
@@ -172,20 +174,20 @@ function describeUiArgument(raw) {
  */
 function requireUiHtml(raw) {
     if (typeof raw !== "string" || raw.length === 0) {
-        throw new Error(`${UI_SHAPE_HINT}; got ${describeUiArgument(raw)}`);
+        throw guestFailure("invalid_args", `${UI_SHAPE_HINT}; got ${describeUiArgument(raw)}`);
     }
     return raw;
 }
 function requireRecord(raw, label) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-        throw new Error(`${label} must be an object`);
+        throw guestFailure("invalid_args", `${label} must be an object`);
     }
     return raw;
 }
 function requireExactKeys(value, allowed, label) {
     const extras = Object.keys(value).filter((key) => !allowed.includes(key));
     if (extras.length > 0) {
-        throw new Error(`${label} carries unsupported field(s) ${extras.map((key) => JSON.stringify(key)).join(", ")}`);
+        throw guestFailure("invalid_args", `${label} carries unsupported field(s) ${extras.map((key) => JSON.stringify(key)).join(", ")}`);
     }
 }
 function requireUiReadKey(raw, label) {
@@ -193,7 +195,7 @@ function requireUiReadKey(raw, label) {
         raw.length === 0 ||
         raw.length > 128 ||
         FORBIDDEN_UI_KEY.has(raw)) {
-        throw new Error(`${label} must be a non-empty string of at most 128 characters and cannot be __proto__, constructor, or prototype`);
+        throw guestFailure("invalid_args", `${label} must be a non-empty string of at most 128 characters and cannot be __proto__, constructor, or prototype`);
     }
     return raw;
 }
@@ -201,32 +203,32 @@ function requireUiReads(raw) {
     const record = requireRecord(raw, "connecta.ui options.reads");
     const names = Object.keys(record);
     if (names.length === 0 || names.length > MAX_UI_READ_BINDINGS) {
-        throw new Error(`connecta.ui options.reads must contain from 1 through ${MAX_UI_READ_BINDINGS} named bindings`);
+        throw guestFailure("invalid_args", `connecta.ui options.reads must contain from 1 through ${MAX_UI_READ_BINDINGS} named bindings`);
     }
     const reads = Object.create(null);
     for (const name of names) {
         if (!UI_READ_NAME.test(name) || FORBIDDEN_UI_KEY.has(name)) {
-            throw new Error(`connecta.ui read binding name ${JSON.stringify(name)} must match ${UI_READ_NAME}`);
+            throw guestFailure("invalid_args", `connecta.ui read binding name ${JSON.stringify(name)} must match ${UI_READ_NAME}`);
         }
         const value = requireRecord(record[name], `connecta.ui read binding ${JSON.stringify(name)}`);
         requireExactKeys(value, ["address", "fixedArgs", "viewArgs"], `connecta.ui read binding ${JSON.stringify(name)}`);
         if (typeof value.address !== "string" || value.address.length === 0) {
-            throw new Error(`connecta.ui read binding ${JSON.stringify(name)} address must be a non-empty string`);
+            throw guestFailure("invalid_args", `connecta.ui read binding ${JSON.stringify(name)} address must be a non-empty string`);
         }
         const fixedArgs = value.fixedArgs === undefined
             ? {}
             : requireRecord(value.fixedArgs, `connecta.ui read binding ${JSON.stringify(name)} fixedArgs`);
         const rawViewArgs = value.viewArgs ?? [];
         if (!Array.isArray(rawViewArgs) || rawViewArgs.length > MAX_UI_VIEW_ARGS) {
-            throw new Error(`connecta.ui read binding ${JSON.stringify(name)} viewArgs must be an array of at most ${MAX_UI_VIEW_ARGS} strings`);
+            throw guestFailure("invalid_args", `connecta.ui read binding ${JSON.stringify(name)} viewArgs must be an array of at most ${MAX_UI_VIEW_ARGS} strings`);
         }
         const viewArgs = rawViewArgs.map((key) => requireUiReadKey(key, `connecta.ui read binding ${JSON.stringify(name)} viewArgs entry`));
         if (new Set(viewArgs).size !== viewArgs.length) {
-            throw new Error(`connecta.ui read binding ${JSON.stringify(name)} viewArgs must not repeat a key`);
+            throw guestFailure("invalid_args", `connecta.ui read binding ${JSON.stringify(name)} viewArgs must not repeat a key`);
         }
         for (const key of viewArgs) {
             if (Object.prototype.hasOwnProperty.call(fixedArgs, key)) {
-                throw new Error(`connecta.ui read binding ${JSON.stringify(name)} view argument ${JSON.stringify(key)} cannot override a fixed argument`);
+                throw guestFailure("invalid_args", `connecta.ui read binding ${JSON.stringify(name)} view argument ${JSON.stringify(key)} cannot override a fixed argument`);
             }
         }
         reads[name] = {
@@ -239,7 +241,7 @@ function requireUiReads(raw) {
 }
 function requireUiPayload(values) {
     if (values.length !== 1 && values.length !== 2) {
-        throw new Error(`${UI_SHAPE_HINT}; got ${values.length} arguments`);
+        throw guestFailure("invalid_args", `${UI_SHAPE_HINT}; got ${values.length} arguments`);
     }
     const html = requireUiHtml(values[0]);
     if (values.length === 1)
@@ -247,7 +249,7 @@ function requireUiPayload(values) {
     const options = requireRecord(values[1], "connecta.ui options");
     requireExactKeys(options, ["reads"], "connecta.ui options");
     if (!Object.prototype.hasOwnProperty.call(options, "reads")) {
-        throw new Error("connecta.ui options must contain reads");
+        throw guestFailure("invalid_args", "connecta.ui options must contain reads");
     }
     return { html, reads: requireUiReads(options.reads) };
 }
@@ -280,11 +282,11 @@ export class EmitCollector {
     accept(raw) {
         const block = requireEmittedBlock(raw);
         if (this.blocks.length >= this.maxBlocks) {
-            throw new Error(`connecta.emit block-count budget exceeded: ${this.maxBlocks} block(s) maximum, 0 remaining`);
+            throw guestFailure("budget_exceeded", `connecta.emit block-count budget exceeded: ${this.maxBlocks} block(s) maximum, 0 remaining`);
         }
         const size = diagnosticsEncoder.encode(JSON.stringify(block)).byteLength;
         if (this.bytes + size > this.maxBytes) {
-            throw new Error(`connecta.emit byte budget exceeded: block is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`);
+            throw guestFailure("budget_exceeded", `connecta.emit byte budget exceeded: block is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`);
         }
         this.blocks.push(block);
         this.bytes += size;
@@ -305,24 +307,24 @@ export class EmitCollector {
      */
     acceptUi(...values) {
         if (this.ui) {
-            throw new Error("connecta.ui accepts at most one payload per run: a view was already accepted and stands");
+            throw guestFailure("invalid_args", "connecta.ui accepts at most one payload per run: a view was already accepted and stands");
         }
         this.acceptUiPayload(requireUiPayload(values));
     }
     acceptUiPayload(payload) {
         if (this.ui) {
-            throw new Error("connecta.ui accepts at most one payload per run: a view was already accepted and stands");
+            throw guestFailure("invalid_args", "connecta.ui accepts at most one payload per run: a view was already accepted and stands");
         }
         let serialized;
         try {
             serialized = JSON.stringify(payload);
         }
         catch {
-            throw new Error("connecta.ui payload must be JSON-serializable");
+            throw guestFailure("invalid_args", "connecta.ui payload must be JSON-serializable");
         }
         const size = diagnosticsEncoder.encode(serialized).byteLength;
         if (this.bytes + size > this.maxBytes) {
-            throw new Error(`connecta.ui byte budget exceeded: payload is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`);
+            throw guestFailure("budget_exceeded", `connecta.ui byte budget exceeded: payload is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`);
         }
         this.ui = payload;
         this.bytes += size;
@@ -430,18 +432,75 @@ const SANDBOX_RESERVED_NAMES = new Set([
 function msg(err) {
     return err instanceof Error ? err.message : String(err);
 }
-function lazyNamespacePrelude(connectors) {
+function guestFailure(code, message, retryable = false) {
+    return new InvocationFailure({ code, message, retryable });
+}
+const GUEST_FAILURE_FRAME = "\u001econnecta-error:";
+const guestFailureFrames = new WeakMap();
+/** Per-execution secret: guest prose cannot collide with this host frame. */
+function guestFailureSecret() {
+    const words = new Uint32Array(4);
+    crypto.getRandomValues(words);
+    return Array.from(words, (word) => word.toString(16).padStart(8, "0")).join("");
+}
+function framedGuestFailure(secret, failure) {
+    const framed = new InvocationFailure(failure.details);
+    framed.message =
+        `${GUEST_FAILURE_FRAME}${secret}:${JSON.stringify(failure.details)}`;
+    guestFailureFrames.set(failure, framed.message);
+    return framed;
+}
+/**
+ * Rebuilds host failures as guest Error instances, then installs connector
+ * shortcuts. The random frame is hidden in this closure and Error is locked:
+ * connector prose and model code can neither collide with nor forge its frame.
+ */
+function lazyNamespacePrelude(connectors, failureSecret) {
     const declarations = connectors
         .map(({ id, namespace }) => `globalThis[${JSON.stringify(namespace)}] = __makeConnectaNamespace(${JSON.stringify(id)});`)
         .join("\n");
-    return `(() => {
+    return `((failurePrefix) => {
+  const NativeError = globalThis.Error;
+  const startsWith = Function.prototype.call.bind(String.prototype.startsWith);
+  const slice = Function.prototype.call.bind(String.prototype.slice);
+  const parse = JSON.parse;
+  const freeze = Object.freeze;
+  const defineProperties = Object.defineProperties;
+  const construct = Reflect.construct;
+  function ConnectaError(message, options) {
+    let details;
+    if (typeof message === "string" && startsWith(message, failurePrefix)) {
+      try { details = parse(slice(message, failurePrefix.length)); } catch {}
+    }
+    const error = construct(
+      NativeError,
+      options === undefined ? [details ? details.message : message] : [details ? details.message : message, options],
+      new.target || NativeError
+    );
+    if (details) {
+      freeze(details);
+      defineProperties(error, {
+        code: { value: details.code, enumerable: true },
+        retryable: { value: details.retryable, enumerable: true },
+        details: { value: details, enumerable: true }
+      });
+    }
+    return error;
+  }
+  ConnectaError.prototype = NativeError.prototype;
+  Object.setPrototypeOf(ConnectaError, NativeError);
+  Object.defineProperty(globalThis, "Error", {
+    value: ConnectaError,
+    writable: false,
+    configurable: false
+  });
   const __makeConnectaNamespace = (connectorId) => Object.freeze(new Proxy(Object.create(null), {
     get: (_target, toolName) => typeof toolName === "string"
       ? (args) => connecta.__callNamespace(connectorId, toolName, args)
       : undefined
   }));
 ${declarations}
-})();`;
+})(${JSON.stringify(`${GUEST_FAILURE_FRAME}${failureSecret}:`)});`;
 }
 /**
  * Expose one fixed host provider plus trusted sandbox setup that creates a
@@ -462,10 +521,12 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         ...(limits.probeTimeoutMs !== undefined
             ? { probeTimeoutMs: limits.probeTimeoutMs }
             : {}),
+        ...(limits.defer !== undefined ? { defer: limits.defer } : {}),
     });
     const invocation = new InvocationService(registry, catalog, activity);
     const maxHostCalls = Math.max(1, Math.trunc(limits.maxHostCalls ?? EXECUTE_MAX_HOST_CALLS));
     const hostCallTimeoutMs = Math.max(1, Math.trunc(limits.hostCallTimeoutMs ?? EXECUTE_HOST_CALL_TIMEOUT_MS));
+    const failureSecret = guestFailureSecret();
     let hostCalls = 0;
     const connectors = registry.listConnectors();
     const namespaces = [];
@@ -493,16 +554,13 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         beforeDispatch: () => {
             hostCalls++;
             if (hostCalls > maxHostCalls) {
-                throw new Error(`execute_code host-call budget exceeded (${maxHostCalls} calls maximum)`);
+                throw guestFailure("budget_exceeded", `execute_code host-call budget exceeded (${maxHostCalls} calls maximum)`);
             }
         },
     });
     /**
-     * A discovery bound is as typed a failure as a tool call is, and a program
-     * that lets one escape deserves the same envelope: register it on the same
-     * request-local channel so an unhandled `invalid_args`/`result_too_large`
-     * reaches the model with its code instead of as prose. The guest still sees
-     * only the message — that is the bridge's limit, not a policy.
+     * Discovery policy failures use the same thrown vocabulary as calls and
+     * utilities. The transport below reconstructs their code inside the guest.
      */
     const typedDiscovery = async (operation) => {
         try {
@@ -510,11 +568,7 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         }
         catch (err) {
             if (err instanceof DiscoveryPolicyError) {
-                limits.onInvocationFailure?.(new InvocationFailure({
-                    code: err.code,
-                    message: err.message,
-                    retryable: false,
-                }));
+                throw guestFailure(err.code, err.message);
             }
             throw err;
         }
@@ -524,7 +578,6 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         limits.diagnostics?.recordCall(diagnosticOperation, outcome);
         if (!outcome.ok) {
             const failure = new InvocationFailure(outcome.error);
-            limits.onInvocationFailure?.(failure);
             throw failure;
         }
         return outcome.value;
@@ -534,7 +587,6 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         limits.diagnostics?.recordCall("call", outcome);
         if (!outcome.ok) {
             const failure = new InvocationFailure(outcome.error);
-            limits.onInvocationFailure?.(failure);
             throw failure;
         }
         return outcome.value;
@@ -554,10 +606,13 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         for (const [name, binding] of Object.entries(payload.reads)) {
             const resolution = await catalog.resolveTool(binding.address, limits.signal !== undefined ? { signal: limits.signal } : {});
             if (!resolution.ok) {
-                throw new Error(`connecta.ui read binding ${JSON.stringify(name)} could not resolve ${JSON.stringify(binding.address)}: ${resolution.error.message}`);
+                throw new InvocationFailure({
+                    ...resolution.error,
+                    message: `connecta.ui read binding ${JSON.stringify(name)} could not resolve ${JSON.stringify(binding.address)}: ${resolution.error.message}`,
+                });
             }
             if (!isExplicitlyReadOnly(resolution.resolved.definition)) {
-                throw new Error(`connecta.ui read binding ${JSON.stringify(name)} refuses ${JSON.stringify(binding.address)}: the tool is not explicitly read-only`);
+                throw guestFailure("destructive_tool_requires_approval", `connecta.ui read binding ${JSON.stringify(name)} refuses ${JSON.stringify(binding.address)}: the tool is not explicitly read-only`);
             }
             reads[name] = {
                 ...binding,
@@ -566,118 +621,128 @@ export async function buildSandboxProviders(registry, baseUrl, logger, activity,
         }
         return { html: payload.html, reads };
     };
-    return [
-        {
-            name: "connecta",
-            prelude: lazyNamespacePrelude(namespaces),
-            fns: {
-                __callNamespace: callNamespace,
-                call: (address, args) => callAddress(address, args),
-                // Emission is a provider function, never an ExecuteResult field —
-                // that is what keeps the Executor contract untouched and parity
-                // structural (M8). It spends no host-call budget (M7); its own
-                // budgets live in the collector.
-                emit: async (block) => {
-                    if (!limits.emitCollector) {
-                        throw new Error("connecta.emit is unavailable: no emission collector was configured for this execution");
-                    }
-                    limits.emitCollector.accept(block);
-                },
-                // The rendered-output channel rides the same bridge for the same
-                // reason (U7): one more provider fn, no change to ExecuteResult or
-                // the Executor contract. Delivery is the handler's job, not the
-                // guest's — nothing here becomes addressable.
-                ui: async (...values) => {
-                    if (!limits.emitCollector) {
-                        throw new Error("connecta.ui is unavailable: no emission collector was configured for this execution");
-                    }
-                    const payload = await validateUiReads(requireUiPayload(values));
-                    limits.emitCollector.acceptUiPayload(payload);
-                },
-                batch: async (calls) => {
-                    const started = Date.now();
-                    const callCount = Array.isArray(calls) ? calls.length : 0;
-                    try {
-                        if (!Array.isArray(calls))
-                            throw new Error("calls must be an array");
-                        if (calls.length > EXECUTE_MAX_BATCH_CALLS) {
-                            throw new Error(`connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS} calls`);
-                        }
-                        const result = await Promise.all(calls.map(async (call) => {
-                            const item = call;
-                            try {
-                                return {
-                                    address: String(item.address),
-                                    ok: true,
-                                    data: await callAddress(item.address, item.args, "batch"),
-                                };
-                            }
-                            catch (err) {
-                                // The failure shape connecta.batch reports: the message a
-                                // program can log, plus the typed details it must classify by. A
-                                // thrown host error crosses the sandbox bridge as a bare
-                                // message string in every executor, so this is the one place a
-                                // program can tell a policy refusal from a transient failure.
-                                const details = err instanceof InvocationFailure
-                                    ? err.details
-                                    : classifyCallError(err, "batch_call_failed");
-                                return {
-                                    address: String(item.address),
-                                    ok: false,
-                                    error: details.message,
-                                    errorDetails: details,
-                                };
-                            }
-                        }));
-                        limits.diagnostics?.recordBatch(Date.now() - started, true, callCount, result);
-                        return result;
-                    }
-                    catch (err) {
-                        limits.diagnostics?.recordBatch(Date.now() - started, false, callCount);
-                        throw err;
-                    }
-                },
-                search: async (raw) => {
-                    const started = Date.now();
-                    try {
-                        const result = await typedDiscovery(async () => {
-                            const args = (raw ?? {});
-                            const result = flatSearchResult(await catalog.search({
-                                ...args,
-                                // Key metadata rides along with schemas by default, since that
-                                // is the whole point of it in code mode. It stays opt-out
-                                // because it counts against the same discovery-byte ceiling.
-                                includeSchemaKeys: args.includeSchemaKeys !== false,
-                            }));
-                            boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
-                            return result;
-                        });
-                        limits.diagnostics?.recordCatalog("search", Date.now() - started, true, result);
-                        return result;
-                    }
-                    catch (err) {
-                        limits.diagnostics?.recordCatalog("search", Date.now() - started, false);
-                        throw err;
-                    }
-                },
-                describe: async (raw) => {
-                    const started = Date.now();
+    const fns = {
+        __callNamespace: callNamespace,
+        call: (address, args) => callAddress(address, args),
+        // Emission is a provider function, never an ExecuteResult field —
+        // that is what keeps the Executor contract untouched and parity
+        // structural (M8). It spends no host-call budget (M7); its own
+        // budgets live in the collector.
+        emit: async (block) => {
+            if (!limits.emitCollector) {
+                throw guestFailure("unavailable", "connecta.emit is unavailable: no emission collector was configured for this execution", true);
+            }
+            limits.emitCollector.accept(block);
+        },
+        // The rendered-output channel rides the same bridge for the same
+        // reason (U7): one more provider fn, no change to ExecuteResult or
+        // the Executor contract. Delivery is the handler's job, not the
+        // guest's — nothing here becomes addressable.
+        ui: async (...values) => {
+            if (!limits.emitCollector) {
+                throw guestFailure("unavailable", "connecta.ui is unavailable: no emission collector was configured for this execution", true);
+            }
+            const payload = await validateUiReads(requireUiPayload(values));
+            limits.emitCollector.acceptUiPayload(payload);
+        },
+        batch: async (calls) => {
+            const started = Date.now();
+            const callCount = Array.isArray(calls) ? calls.length : 0;
+            try {
+                if (!Array.isArray(calls)) {
+                    throw guestFailure("invalid_args", "calls must be an array");
+                }
+                if (calls.length > EXECUTE_MAX_BATCH_CALLS) {
+                    throw guestFailure("invalid_args", `connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS} calls`);
+                }
+                const result = await Promise.all(calls.map(async (call) => {
+                    const item = call;
                     try {
-                        const result = await typedDiscovery(async () => {
-                            const args = (raw ?? {});
-                            const result = { tools: await catalog.describe(args) };
-                            boundedDiscoveryText(result, 'Split the address list or use format: "compact".');
-                            return result;
-                        });
-                        limits.diagnostics?.recordCatalog("describe", Date.now() - started, true, result);
-                        return result;
+                        return {
+                            address: String(item.address),
+                            ok: true,
+                            data: await callAddress(item.address, item.args, "batch"),
+                        };
                     }
                     catch (err) {
-                        limits.diagnostics?.recordCatalog("describe", Date.now() - started, false);
-                        throw err;
+                        const details = err instanceof InvocationFailure
+                            ? err.details
+                            : classifyCallError(err, "batch_call_failed");
+                        return {
+                            address: String(item.address),
+                            ok: false,
+                            error: details.message,
+                            errorDetails: details,
+                        };
                     }
-                },
-            },
+                }));
+                limits.diagnostics?.recordBatch(Date.now() - started, true, callCount, result);
+                return result;
+            }
+            catch (err) {
+                limits.diagnostics?.recordBatch(Date.now() - started, false, callCount);
+                throw err;
+            }
+        },
+        search: async (raw) => {
+            const started = Date.now();
+            try {
+                const result = await typedDiscovery(async () => {
+                    const args = (raw ?? {});
+                    const result = flatSearchResult(await catalog.search({
+                        ...args,
+                        includeSchemaKeys: args.includeSchemaKeys !== false,
+                    }));
+                    boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
+                    return result;
+                });
+                limits.diagnostics?.recordCatalog("search", Date.now() - started, true, result);
+                return result;
+            }
+            catch (err) {
+                limits.diagnostics?.recordCatalog("search", Date.now() - started, false);
+                throw err;
+            }
+        },
+        describe: async (raw) => {
+            const started = Date.now();
+            try {
+                const result = await typedDiscovery(async () => {
+                    const args = (raw ?? {});
+                    const result = { tools: await catalog.describe(args) };
+                    boundedDiscoveryText(result, 'Split the address list or use format: "compact".');
+                    return result;
+                });
+                limits.diagnostics?.recordCatalog("describe", Date.now() - started, true, result);
+                return result;
+            }
+            catch (err) {
+                limits.diagnostics?.recordCatalog("describe", Date.now() - started, false);
+                throw err;
+            }
+        },
+    };
+    const transportedFns = Object.fromEntries(Object.entries(fns).map(([name, fn]) => [
+        name,
+        async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (err) {
+                if (err instanceof InvocationFailure) {
+                    const framed = framedGuestFailure(failureSecret, err);
+                    limits.onInvocationFailure?.(err);
+                    throw framed;
+                }
+                throw err;
+            }
+        },
+    ]));
+    return [
+        {
+            name: "connecta",
+            prelude: lazyNamespacePrelude(namespaces, failureSecret),
+            fns: transportedFns,
         },
     ];
 }
@@ -731,6 +796,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                     ...(config.probeTimeoutMs !== undefined
                         ? { probeTimeoutMs: config.probeTimeoutMs }
                         : {}),
+                    ...(config.defer !== undefined ? { defer: config.defer } : {}),
                 });
             }
             finally {
@@ -816,8 +882,8 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             // rather than losing it to prose.
             let invocationFailure;
             for (const match of [
-                (candidate) => outcome.error === candidate.message,
-                (candidate) => outcome.error?.includes(candidate.message) === true,
+                (candidate) => [candidate.message, guestFailureFrames.get(candidate)].includes(outcome.error),
+                (candidate) => [candidate.message, guestFailureFrames.get(candidate)].some((message) => message !== undefined && outcome.error?.includes(message) === true),
             ]) {
                 for (let i = invocationFailures.length - 1; i >= 0; i--) {
                     const candidate = invocationFailures[i];
@@ -932,22 +998,47 @@ function discardedEmitsText(emitted) {
     ];
     return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
 }
-const executeDescription = (emitBudgets, connectorGuides) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool; a known address uses call_tool directly. This is the primary surface for everything wider. For any reduction, dependency, multiple calls, loop, join, or branch, make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
-
-Write an async arrow function. NO network, filesystem, timers, or imports; only:
-- Connector globals call <connectorId>.<toolName>(args). Sanitization: non-[A-Za-z0-9_$] → "_" (my-service.get.thing → my_service.get_thing); prefix a leading digit; suffix a reserved word.
-- connecta.call(address, args) and connecta.batch(calls) use canonical addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure it.
-- top-level search_tools returns { connectors: [{ id, tools }], total, offset, limit, hasMore }; connecta.search returns { tools, total, offset, limit, hasMore }; connecta.describe returns { tools }.
-- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Require address/description to match the operation, then check requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Select by fit; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Every required key needs task/prior-result data; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. connecta.describe takes { address: "<connectorId>.<toolName>" } or { addresses: [...] }. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. Missing key list = non-object, not no fields; read the schema.${connectorGuides ? " guideRequired: true = stop. Describe clears only schema_truncated; otherwise return its exact guide, fetch with top-level skills, then write the informed call." : ""}
-- connecta.emit(block) — emit exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only, no host call, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid or over-budget throws before accepting.
-- connecta.ui(html, options?) — one success-only view; one arg is display-only. Reads declare { reads: { name: { address, fixedArgs?, viewArgs? } } }; markup calls connecta.read(name, args). Admission applies. It shares the ${emitBudgets.maxBytes}-byte emit budget: one budget, not two; a second, over-budget, or invalid call throws catchably. Bytes stay out; the model reads the return value, not the view; return the initial summary from its variables.
-- console.log(...) — captured and returned with the result.
+function connectorInventory(connectors) {
+    const prefix = "Connectors: ";
+    if (connectors.length === 0)
+        return `${prefix}none.`;
+    const entries = connectors.map((connector) => {
+        const shortcut = sanitizeIdentifier(connector.id);
+        return shortcut === connector.id
+            ? connector.id
+            : `${connector.id} (shortcut ${shortcut})`;
+    });
+    const shown = [];
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (entry === undefined)
+            break;
+        const candidate = [...shown, entry].join(", ");
+        const omitted = entries.length - index - 1;
+        const suffix = omitted > 0 ? `; +${omitted} more.` : ".";
+        const serialized = prefix + candidate + suffix;
+        if (boundedEchoText(serialized, CONNECTOR_INVENTORY_MAX_BYTES) !== serialized) {
+            break;
+        }
+        shown.push(entry);
+    }
+    const omitted = entries.length - shown.length;
+    if (omitted === 0)
+        return `${prefix}${shown.join(", ")}.`;
+    return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
+}
+const executeDescription = (emitBudgets, connectorGuides, connectors) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool. execute_code is the primary surface for everything wider: make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
 
-Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }
+${connectorInventory(connectors)}
 
-Calls return plain values (JSON-parsing MCP text when possible) and throw; catch errors. A thrown error is only a message; connecta.batch tells a policy refusal from a transient failure. Never retry retryable: false, or rate_limited immediately; no timers. Return JSON; reduce large results before they truncate.
+Write one plain-JavaScript async arrow function. Use only:
+- <connectorId>.<toolName>(args) for a sanitized shortcut, or connecta.call(address, args) for a canonical address.
+- connecta.search(args), connecta.describe(args), and connecta.batch(calls) for discovery and independent read-only calls.
+- connecta.emit(block) — { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only; ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid/over-budget throws.
+- connecta.ui(html, options?) for one success-only view; return the same initial summary the HTML renders.
+- console.log(...) — captured.
 
-Plain JS, no TypeScript. Compact schemas are TypeScript-like, not JSON Schema: write the property names they display; never guess positions or aliases.`;
+Programs have no portable ambient capabilities. Return JSON and reduce large results before they truncate. Fetch skills({ name: "usage" }) once for selection rules, exact result shapes, repair, examples, guide handling${connectorGuides ? ", connector-guide rules" : ""}, and runtime differences.`;
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(server, registry, ctx) {
     // Resolved once so the description and the collector cannot disagree about
@@ -956,6 +1047,7 @@ export function registerExecuteTool(server, registry, ctx) {
         maxBytes: resolveEmitBudget(ctx.maxEmittedBytes, EXECUTE_MAX_EMITTED_BYTES),
         maxBlocks: resolveEmitBudget(ctx.maxEmittedBlocks, EXECUTE_MAX_EMITTED_BLOCKS),
     };
+    const connectors = registry.listConnectors();
     const handler = createExecuteTool(registry, ctx.baseUrl, ctx.executor, ctx.logger, ctx.activity, {
         ...(ctx.discoveryConcurrency !== undefined
             ? { discoveryConcurrency: ctx.discoveryConcurrency }
@@ -965,20 +1057,22 @@ export function registerExecuteTool(server, registry, ctx) {
             : {}),
         maxEmittedBytes: emitBudgets.maxBytes,
         maxEmittedBlocks: emitBudgets.maxBlocks,
+        ...(ctx.defer !== undefined ? { defer: ctx.defer } : {}),
     });
     server.registerTool("execute_code", {
-        description: executeDescription(emitBudgets, hasConnectorGuides(registry.listConnectors())),
+        description: executeDescription(emitBudgets, hasConnectorGuides(connectors), connectors),
         inputSchema: z.object({
             code: z
                 .string()
-                .describe("One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing. So does aborting on a missing tool match or result key — re-search, describe, or read the result's actual keys here instead."),
+                .describe("One complete JavaScript async arrow function that discovers, calls, and returns the reduced answer."),
             diagnostics: z
                 .boolean()
                 .optional()
                 .describe("Add request-local, payload-free timing and result-size summaries."),
         }),
-        // The sandbox exposes only tools that are explicitly read-only, and the
-        // executor grants no network, filesystem, env, or timer capabilities.
+        // This hint describes connector calls, all explicitly read-only. The
+        // supported executor constructions deny outbound access, filesystem,
+        // and deployment config; X5 documents Dynamic runtime modules separately.
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,