@zackbart/connecta 0.37.1 → 0.39.0

package/dist/execute.js

@@ -1,6 +1,7 @@
+import { META_ROUTES, routeNames } from "./agent-routes.js";
 import { authCall, authFlow, authInvoke, authMethod } from "./auth/native.js";
 import { nativeRecovery } from "./native-recovery.js";
-import { GUEST_API_DECLARATION } from "./usage-guide.js";
+import { GUEST_API_DECLARATION, GUEST_FUNCTIONS, UNCOUNTED_GUEST_FUNCTIONS, } from "./guest-functions.js";
 import { bindMcpClient } from "./mcp-client-context.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { Cause, Deferred, Duration, Effect, Exit } from "effect";
@@ -37,8 +38,11 @@ const EXECUTE_MAX_CODE_BYTES = 64 * 1024;
  * never settles at all.
  */
 const EXECUTE_WATCHDOG_MS = CONFIG_DEFAULTS.execute.watchdogMs;
-/** Complete entries plus an exact omission count, all inside this byte cap. */
-export const CONNECTOR_INVENTORY_MAX_BYTES = 256;
+/**
+ * Room to name every connector of a typical deployment. Past it, complete
+ * entries plus an exact omission count stay inside this byte cap.
+ */
+export const CONNECTOR_INVENTORY_MAX_BYTES = 1_024;
 /**
  * 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,
@@ -175,13 +179,15 @@ export class EmitCollector {
     maxBytes;
     maxBlocks;
     diagnostics;
+    maxResultChars;
     blocks = [];
     bytes = 0;
     textChars = 0;
-    constructor(maxBytes, maxBlocks, diagnostics) {
+    constructor(maxBytes, maxBlocks, diagnostics, maxResultChars = MAX_EXECUTE_RESULT_CHARS) {
         this.maxBytes = maxBytes;
         this.maxBlocks = maxBlocks;
         this.diagnostics = diagnostics;
+        this.maxResultChars = maxResultChars;
     }
     accept(raw) {
         this.acceptNative([requireEmittedBlock(raw)]);
@@ -205,8 +211,8 @@ export class EmitCollector {
             // the transport budget, just like images and audio.
             if (block.type === "resource" && "text" in block.resource)
                 textChars += serialized.length;
-            if (textChars > MAX_EXECUTE_RESULT_CHARS - 512) {
-                throw guestFailure("result_too_large", "Emitted text shares the 24,000-character program result limit. Reduce the text before emitting it.");
+            if (textChars > this.maxResultChars - 512) {
+                throw guestFailure("result_too_large", `Emitted text shares the ${this.maxResultChars.toLocaleString("en-US")}-character program result limit. Reduce the text before emitting it.`);
             }
             count++;
             bytes += size;
@@ -423,6 +429,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         concurrency: limits.discoveryConcurrency,
         probeTimeoutMs: limits.probeTimeoutMs,
         defer: limits.defer,
+        routes: limits.routes,
     });
     const invocation = new InvocationService(registry, catalog, activity);
     const maxHostCalls = Math.max(1, Math.trunc(limits.maxHostCalls ?? EXECUTE_MAX_HOST_CALLS));
@@ -466,6 +473,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         source: "execute_code",
         sentSecrets,
         timeoutMs,
+        ...(limits.routes ? { routes: limits.routes } : {}),
         ...(signal !== undefined ? { requestSignal: signal } : {}),
         ...(limits.dispatchController ? { dispatchSignal: limits.dispatchController.signal } : {}),
         unwrapResult: true,
@@ -696,6 +704,11 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             catalogDependency(resolved.connector.id, resolved.toolName);
     };
     const operations = {
+        // Uncounted: a failed program read a result field off an unawaited host call.
+        unawaited: () => {
+            if (limits.unawaited)
+                limits.unawaited.read = true;
+        },
         call,
         result: (id, options, signal, onStage) => Effect.tryPromise({
             try: async () => {
@@ -750,8 +763,10 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         }),
         skill: (name, _options, utilitySignal) => Effect.tryPromise({
             try: async () => {
-                if (typeof name !== "string")
-                    throw guestFailure("invalid_args", "Use connecta.skill(name) with an exact skill name.");
+                // Accept the top-level skills tool's { name } shape too: models copy it into programs.
+                const skillName = name && typeof name === "object" ? name.name : name;
+                if (typeof skillName !== "string")
+                    throw guestFailure("invalid_args", 'Use connecta.skill("usage") or connecta.skill("connector:<id>") with an exact skill name; the skills tool lists names.');
                 const skills = new SkillsRegistry(registry, baseUrl, {
                     requestScope,
                     requestSignal: utilitySignal ?? hostAccessSignal,
@@ -763,7 +778,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                     probeTimeoutMs: limits.probeTimeoutMs,
                     defer: limits.defer,
                 });
-                return { name, format: "text", text: await skills.text(name) };
+                return { name: skillName, format: "text", text: await skills.text(skillName) };
             },
             catch: (err) => err instanceof ConnectorCallError ? guestFailure(err.code, err.message, err.code === "unavailable") : err,
         }),
@@ -818,7 +833,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             const args = (raw ?? {});
             const result = flatSearchResult(await catalog.search({
                 ...args,
-                includeSchemas: args.includeSchemas ?? "json",
+                includeSchemas: args.includeSchemas ?? "typescript",
                 includeSchemaKeys: args.includeSchemaKeys !== false,
             }, catalogDependency));
             boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
@@ -852,90 +867,102 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         const failure = boundedGuestFailure(redactAgentOutput(sentSecrets, err));
         return Effect.fail(failure);
     });
+    /** End the whole run: later bridge calls, including emit, lose host access. */
+    const endRun = (failure) => {
+        budgetFailure = failure;
+        programWrites?.close();
+        limits.dispatchController?.abort();
+        limits.onHostCallBudgetExceeded?.(failure);
+        return stopped;
+    };
     return {
         name: "connecta",
         // Trusted host code the program runs after and cannot undo.
         prelude: guestPrelude(),
-        fns: Object.fromEntries(Object.entries(operations).map(([name, operation]) => [
-            name,
-            (...args) => {
-                if (budgetFailure)
-                    return stopped;
-                // Invalid emits still allocate guest promises and typed rejections.
-                // Bound those attempts without consuming the invocation budget or discarding identities.
-                if (name === "emit" && ++emitAttempts > maxEmitAttempts) {
-                    budgetFailure = guestFailure("budget_exceeded", `execute_code emission-attempt budget exceeded (${maxEmitAttempts} attempts maximum).`);
-                    programWrites?.close();
-                    limits.dispatchController?.abort();
-                    limits.onHostCallBudgetExceeded?.(budgetFailure);
-                    return stopped;
-                }
-                // L4/M7: spend on entry, before even invalid arguments are checked;
-                // emit has a separate budget and never spends this one.
-                // Transparent transfer pages consume the already-admitted call, not guest host calls.
-                const counted = name !== "emit" && !(name === "result" && typeof args[0] === "string" && transfers.has(args[0]));
-                if (counted && ++hostCalls.attempted > maxHostCalls) {
-                    hostCalls.failed++;
-                    budgetFailure = new HostCallBudgetExceeded(hostCalls, maxHostCalls);
-                    programWrites?.close();
-                    limits.dispatchController?.abort();
-                    limits.onHostCallBudgetExceeded?.(budgetFailure);
-                    return stopped;
-                }
-                if (counted)
-                    hostCalls.admitted++;
-                const started = Date.now();
-                const utility = name === "result" || name === "skill";
-                let stage = name === "result" ? "result storage" : "skill lookup";
-                const invoke = Effect.suspend(() => operation(...args));
-                const guarded = utility
-                    ? withDeadlineEffect((utilitySignal) => Effect.suspend(() => operation(args[0], args[1], utilitySignal, (current) => {
-                        stage = current;
-                    })), {
-                        timeoutMs: hostCallTimeoutMs,
-                        ...(hostAccessSignal ? { signal: hostAccessSignal } : {}),
-                        timeoutError: guestFailure("timeout", `connecta.${name} timed out.`),
-                    })
-                    : invoke;
-                const settled = runEdge(guarded.pipe(Effect.catch((error) => {
-                    if (utility && hostAccessSignal?.aborted)
-                        return typedFailure(guestFailure("cancelled", `connecta.${name} was cancelled because the run ended.`));
-                    if (utility && error instanceof InvocationFailure && error.code === "timeout") {
-                        const elapsedMs = Date.now() - started;
-                        const message = `Operation "connecta.${name}" timed out during ${stage} after ${elapsedMs}ms (effective deadline ${hostCallTimeoutMs}ms).`;
-                        return typedFailure(new InvocationFailure({
-                            code: "timeout",
-                            message,
-                            retryable: true,
-                            details: {
-                                operation: `connecta.${name}`,
-                                stage,
-                                elapsedMs,
-                                deadlineMs: hostCallTimeoutMs,
-                            },
-                        }));
-                    }
-                    return typedFailure(error);
-                }))).then((value) => {
-                    if (counted)
-                        hostCalls.succeeded++;
-                    return budgetFailure ? stopped : redactAgentOutput(sentSecrets, value);
-                }, (err) => {
-                    if (counted)
-                        hostCalls.failed++;
+        // One bridge function per registry entry, admitted by its budget class.
+        fns: Object.fromEntries(GUEST_FUNCTIONS.map((fn) => {
+            const { name, budget } = fn;
+            const operation = operations[name];
+            const deadline = "deadline" in fn ? fn.deadline : undefined;
+            let notices = 0;
+            return [
+                name,
+                (...args) => {
                     if (budgetFailure)
                         return stopped;
-                    throw redactAgentOutput(sentSecrets, err);
-                });
-                // The executor owns this promise, and a program may abandon a call
-                // that the run's end then cancels before anyone has awaited it.
-                // The rejection is still there for whoever does; it is just not an
-                // unhandled rejection of the host's, which workerd reports as soon
-                // as a microtask passes without a handler.
-                settled.catch(() => { });
-                return settled;
-            },
-        ])),
+                    // Uncounted: one per run; any further call through the bridge ends the run.
+                    if (budget === "once") {
+                        if (++notices > 1)
+                            return endRun(guestFailure("budget_exceeded", `execute_code ${fn.label} is limited to one per run.`));
+                        operation();
+                        return Promise.resolve();
+                    }
+                    // Invalid emits still allocate guest promises and typed rejections.
+                    // Bound those attempts without consuming the invocation budget or discarding identities.
+                    if (budget === "emission" && ++emitAttempts > maxEmitAttempts)
+                        return endRun(guestFailure("budget_exceeded", `execute_code emission-attempt budget exceeded (${maxEmitAttempts} attempts maximum).`));
+                    // L4/M7: spend on entry, before even invalid arguments are checked;
+                    // emission has a separate budget and never spends this one.
+                    // Transparent transfer pages consume the already-admitted call, not guest host calls.
+                    const counted = budget === "hostCall" && !(name === "result" && typeof args[0] === "string" && transfers.has(args[0]));
+                    if (counted && ++hostCalls.attempted > maxHostCalls) {
+                        hostCalls.failed++;
+                        return endRun(new HostCallBudgetExceeded(hostCalls, maxHostCalls));
+                    }
+                    if (counted)
+                        hostCalls.admitted++;
+                    const started = Date.now();
+                    let stage = deadline ?? "";
+                    const invoke = Effect.suspend(() => operation(...args));
+                    const guarded = deadline
+                        ? withDeadlineEffect((utilitySignal) => Effect.suspend(() => operation(args[0], args[1], utilitySignal, (current) => {
+                            stage = current;
+                        })), {
+                            timeoutMs: hostCallTimeoutMs,
+                            ...(hostAccessSignal ? { signal: hostAccessSignal } : {}),
+                            timeoutError: guestFailure("timeout", `connecta.${name} timed out.`),
+                        })
+                        : invoke;
+                    const settled = runEdge(guarded.pipe(Effect.catch((error) => {
+                        if (deadline && hostAccessSignal?.aborted)
+                            return typedFailure(guestFailure("cancelled", `connecta.${name} was cancelled because the run ended.`));
+                        if (deadline && error instanceof InvocationFailure && error.code === "timeout") {
+                            const elapsedMs = Date.now() - started;
+                            const message = `Operation "connecta.${name}" timed out during ${stage} after ${elapsedMs}ms (effective deadline ${hostCallTimeoutMs}ms).`;
+                            return typedFailure(new InvocationFailure({
+                                code: "timeout",
+                                message,
+                                retryable: true,
+                                details: {
+                                    operation: `connecta.${name}`,
+                                    stage,
+                                    elapsedMs,
+                                    deadlineMs: hostCallTimeoutMs,
+                                },
+                            }));
+                        }
+                        return typedFailure(error);
+                    }))).then((value) => {
+                        if (counted)
+                            hostCalls.succeeded++;
+                        return budgetFailure ? stopped : redactAgentOutput(sentSecrets, value);
+                    }, (err) => {
+                        if (counted)
+                            hostCalls.failed++;
+                        if (budgetFailure)
+                            return stopped;
+                        throw redactAgentOutput(sentSecrets, err);
+                    });
+                    // The executor owns this promise, and a program may abandon a call
+                    // that the run's end then cancels before anyone has awaited it.
+                    // The rejection is still there for whoever does; it is just not an
+                    // unhandled rejection of the host's, which workerd reports as soon
+                    // as a microtask passes without a handler.
+                    settled.catch(() => { });
+                    return settled;
+                },
+            ];
+        })),
     };
 }
 /**
@@ -1044,11 +1071,13 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
         logger,
     };
     const hostCallTimeoutMs = resolveBudget(config.hostCallTimeoutMs, EXECUTE_HOST_CALL_TIMEOUT_MS);
+    const maxResultChars = resolveBudget(config.maxResultChars, MAX_EXECUTE_RESULT_CHARS);
     const play = (program, diagnosticsRequested, callerSignal, requestScope, hostCalls, programWrites) => Effect.suspend(() => {
         const sentSecrets = sentSecretsForRequest(requestScope);
         const diagnostics = diagnosticsRequested ? new ExecuteDiagnostics() : undefined;
-        const emitted = new EmitCollector(resolveBudget(config.maxEmittedBytes, EXECUTE_MAX_EMITTED_BYTES), resolveBudget(config.maxEmittedBlocks, EXECUTE_MAX_EMITTED_BLOCKS), diagnostics);
+        const emitted = new EmitCollector(resolveBudget(config.maxEmittedBytes, EXECUTE_MAX_EMITTED_BYTES), resolveBudget(config.maxEmittedBlocks, EXECUTE_MAX_EMITTED_BLOCKS), diagnostics, maxResultChars);
         const resultDependencies = [];
+        const unawaited = { read: false };
         const dispatchController = new AbortController();
         const terminal = Deferred.makeUnsafe();
         let budgetFailure;
@@ -1099,9 +1128,11 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 defer: config.defer,
                 readOnly: config.readOnly,
                 maxWrites: config.maxWrites,
+                routes: config.routes,
                 programWrites,
                 resultDependencies,
                 dispatchController,
+                unawaited,
             }, requestScope)));
             if (signal.aborted) {
                 return yield* Effect.fail(new ExecutorAdmissionError("executor_cancelled", "Execution was cancelled during sandbox setup."));
@@ -1137,15 +1168,18 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             emitted,
             diagnostics,
             program,
-            guardResult: (value, maxChars) => authCall(guardProgramReturn, [
+            unawaited,
+            // Emitted text shares the return cap; a follow-up page run gets all of it.
+            guardResult: (value) => authCall(guardProgramReturn, [
                 value,
                 registry,
                 baseUrl,
                 [...new Map(resultDependencies.map((dependency) => [JSON.stringify(dependency), dependency])).values()],
                 sentSecrets,
                 logger,
-                maxChars,
+                maxResultChars - emitted.textChars,
                 programWrites.hasSucceeded,
+                maxResultChars,
             ]),
         };
         const exited = Effect.exit(Effect.scoped(run)).pipe(Effect.flatMap((exit) => 
@@ -1249,7 +1283,7 @@ function failedRun(err, logger, { emitted, diagnostics, program }) {
     });
 }
 /** The response for an ExecuteResult: the program's error or its value. */
-function finishedRun(outcome, { emitted, diagnostics, program, guardResult }) {
+function finishedRun(outcome, { emitted, diagnostics, program, unawaited, guardResult }) {
     return authFlow(function* () {
         if (outcome === null || typeof outcome !== "object" || Array.isArray(outcome)) {
             return failureResponse("Executor failed: expected an ExecuteResult object.", {
@@ -1293,6 +1327,7 @@ function finishedRun(outcome, { emitted, diagnostics, program, guardResult }) {
                         name: outcome.failure?.name ?? /^(SyntaxError|ReferenceError|TypeError|RangeError):/.exec(outcome.error)?.[1],
                         message: outcome.error || "Execution failed without an error message.",
                         ...(outcome.failure?.line !== undefined ? { line: outcome.failure.line - 1 } : {}),
+                        unawaited: unawaited.read,
                     }, program),
             });
         }
@@ -1301,7 +1336,7 @@ function finishedRun(outcome, { emitted, diagnostics, program, guardResult }) {
         // error path so captured logs survive instead of a raw SDK 500.
         let result;
         try {
-            result = yield* guardResult(outcome.result, MAX_EXECUTE_RESULT_CHARS - emitted.textChars);
+            result = yield* guardResult(outcome.result);
         }
         catch (err) {
             const message = `Error: result is not JSON-serializable: ${msg(err)}`;
@@ -1349,50 +1384,59 @@ function failureResponse(message, options) {
 function discardedEmits(emitted) {
     return emitted.blocks.length > 0 ? { emittedDiscarded: emitted.blocks.length } : {};
 }
+const inventoryWords = (text) => text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean);
+/** A title that only respells the id ("Google Calendar" for google_calendar) adds nothing. */
+function titleAddsInformation(id, title) {
+    const words = inventoryWords(title);
+    const idWords = inventoryWords(id);
+    return words.join("") !== idWords.join("") && words.some((word) => !idWords.includes(word));
+}
+/**
+ * Every configured connector, from configuration alone. Detail degrades before
+ * names do: titles go first, then optional guide pointers, and only past the
+ * byte cap do whole entries give way to an exact omission count.
+ */
 function connectorInventory(connectors) {
     const prefix = "Connectors: ";
     if (connectors.length === 0)
         return `${prefix}none.`;
-    const entries = connectors.map((connector) => {
-        const address = connector.id;
+    const fits = (line) => boundedEchoText(line, CONNECTOR_INVENTORY_MAX_BYTES) === line;
+    const entry = (connector, detail) => {
+        const notes = [];
         const title = connector.title?.replace(/\s+/g, " ").trim();
-        const label = title && title !== connector.id ? `${address}: ${boundedEchoText(title, 45)}` : address;
-        if (!connectorGuide(connector))
-            return label;
-        const requirement = connectorGuideRequired(connector) ? "required guide" : "guide";
-        return `${label} (${requirement} ${connectorSkillName(connector.id)})`;
-    });
-    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;
+        if (detail >= 2 && title && titleAddsInformation(connector.id, title))
+            notes.push(boundedEchoText(title, 45));
+        const required = connectorGuideRequired(connector);
+        if (connectorGuide(connector) && (required || detail >= 1)) {
+            const fetch = `skills({name:"${connectorSkillName(connector.id)}"})`;
+            notes.push(required ? `read first: ${fetch}` : `guide: ${fetch}`);
         }
-        shown.push(entry);
+        return notes.length > 0 ? `${connector.id} (${notes.join("; ")})` : connector.id;
+    };
+    for (const detail of [2, 1, 0]) {
+        const line = `${prefix}${connectors.map((connector) => entry(connector, detail)).join(", ")}.`;
+        if (fits(line))
+            return line;
     }
-    const omitted = entries.length - shown.length;
-    if (omitted === 0)
-        return `${prefix}${shown.join(", ")}.`;
-    return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
+    const entries = connectors.map((connector) => entry(connector, 0));
+    let shown = 0;
+    while (fits(`${prefix}${entries.slice(0, shown + 1).join(", ")}; +${entries.length - shown - 1} more.`))
+        shown++;
+    return `${prefix}${entries.slice(0, shown).join(", ")}${shown > 0 ? "; " : ""}+${entries.length - shown} more.`;
 }
-const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, readOnly, native = false) => `${native ? `Call tools directly; combine work here using their program addresses. ${readOnly ? "Read-only endpoint: writes are omitted and refused." : "Writable endpoint: programs may read and write; the client approves."}` : readOnly ? "One known read: call_tool. Everything else: execute_code. Read-only endpoint: search and describe omit write tools, and every write call is refused." : "One known read: call_tool. One known write: call_destructive_tool. Everything else: execute_code. Writable endpoint: programs may read and write; the client approves."} Limits: ${hostLimits.maxHostCalls} host calls, ${readOnly ? "" : `${maxWrites} writes, `}${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
+const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, readOnly, native = false, routes = META_ROUTES) => `${native ? `Call tools directly; combine work here using their program addresses. ${readOnly ? "Read-only endpoint: writes are omitted and refused." : "Writable endpoint: programs may read and write; the client approves."}` : `${routes === routeNames("code") ? `Every operation uses ${routes.program}.` : readOnly ? `One known read: ${routes.read}. Everything else: ${routes.program}.` : `One known read: ${routes.read}. One known write: ${routes.write}. Everything else: ${routes.program}.`} ${readOnly ? "Read-only endpoint: search and describe omit write tools, and every write call is refused." : "Writable endpoint: programs may read and write; the client approves."}`} Limits: ${hostLimits.maxHostCalls} host calls, ${readOnly ? "" : `${maxWrites} writes, `}${hostLimits.callTimeoutMs === hostLimits.hostCallTimeoutMs ? `${hostLimits.callTimeoutMs / 1_000}s/host call` : `${hostLimits.callTimeoutMs / 1_000}s/call (${hostLimits.hostCallTimeoutMs / 1_000}s result/skill/read)`}.
 ${connectorInventory(connectors)}
 
 Use async () => { ... }, no arguments. No portable ambient capabilities. API:
 \`\`\`ts
-declare const connecta: {
 ${GUEST_API_DECLARATION}
-};
 \`\`\`
-Search: {tools}, catalogErrors. JSON schemas default; compact text. Calls: {data, format:"json"|"text"}; >1 MiB: paged handle. Oversized returns: resultId/nextAction. connecta.result pages; UTF-8 byte offsets. allSettled keeps typed errors; host budget_exceeded ends the run.
+search and describe return objects, not arrays. Search shows a TypeScript signature by default; describe, JSON Schema. A call result over 1 MiB returns a paged handle; read it with connecta.result(handle, { offset }), which pages by UTF-8 byte offset. Every function except ${UNCOUNTED_GUEST_FUNCTIONS} spends a host call. Promise.allSettled keeps per-call errors, but exceeding the host-call limit ends the program. When paging is available, an oversized program return carries resultId and nextAction.
 
-Never repeat writes for output. emit(result) or emit(block) from result.content forwards MCP blocks. Authored: text/base64 image/audio; no await. Caps: ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes. Text shares result cap. skills({ name: "investigate" }): workflow; skills({ name: "usage" }): repair${connectorGuides ? ", guide handling" : ""}.`;
+Never repeat writes for output. emit(result) or emit(block) from result.content forwards MCP blocks unchanged; an authored Block's image/audio data is base64. emit needs no await. Caps: ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes. Text shares result cap. connecta.skill("usage"): repair${connectorGuides ? ", guide handling" : ""}.`;
 // Module scope, like the other five meta-tool inputs: its JSON Schema is
 // derived once per process. Budgets and connectors vary by deployment and
 // view, so they live in the description, never here.
@@ -1430,13 +1474,16 @@ export function registerExecuteTool(server, registry, ctx) {
         defer: ctx.defer,
         readOnly: ctx.readOnly,
         maxWrites,
+        maxResultChars: ctx.maxResultChars,
         requestScope: ctx.requestScope,
+        routes: ctx.routes,
     });
     server.registerTool("execute_code", {
         description: executeDescription(emitBudgets, {
             ...hostLimits,
-            hostCallTimeoutMs: normalizeTimeoutMs(ctx.defaultToolTimeoutMs) ?? hostLimits.hostCallTimeoutMs,
-        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.readOnly === true, ctx.native === true),
+            // connecta.call falls back to calls.defaultTimeoutMs; result, skill and read always use hostCallTimeoutMs.
+            callTimeoutMs: normalizeTimeoutMs(ctx.defaultToolTimeoutMs) ?? hostLimits.hostCallTimeoutMs,
+        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.readOnly === true, ctx.native === true, ctx.routes),
         inputSchema: EXECUTE_INPUT,
         outputSchema: EXECUTE_OUTPUT,
         // The client sees execute_code as a write exactly when the endpoint writes.
@@ -1471,6 +1518,6 @@ export function registerExecuteTool(server, registry, ctx) {
         const result = yield* ctx.authElicitation
             ? authInvoke(ctx.authElicitation, "run", ["execute_code", args, extra, run])
             : authCall(run, []);
-        return ctx.native ? nativeRecovery(result, true) : result;
+        return ctx.native ? nativeRecovery(result) : result;
     })));
 }

package/dist/executor-result.js

@@ -1,12 +1,15 @@
+import { META_ROUTES } from "./agent-routes.js";
+import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { msg } from "./errors.js";
 /** ~6k tokens. Sandbox code should filter data down before returning. */
-export const MAX_EXECUTE_RESULT_CHARS = 24_000;
+export const MAX_EXECUTE_RESULT_CHARS = CONFIG_DEFAULTS.execute.maxResultChars;
 export const MAX_EXECUTE_LOG_CHARS = 4_000;
 export function serializeResultText(value) {
     const serialized = JSON.stringify(value);
     return serialized === undefined ? String(value) : serialized;
 }
-const TRUNCATION_HINT = "filter/map/slice data inside execute_code and return only what you need";
+// Only program returns carry it, and every surface running programs lists execute_code.
+const TRUNCATION_HINT = `filter/map/slice data inside ${META_ROUTES.program} and return only what you need`;
 /**
  * Shape the over-cap notice so the **serialized envelope** fits the same cap
  * the raw value missed. Escaping matters: a preview sliced to the cap is JSON

package/dist/executors/quickjs-runtime.js

@@ -1,3 +1,4 @@
+import { utf8Length } from "../bytes.js";
 // QuickJS-in-WebAssembly runtime used inside the disposable child process.
 //
 // Model-written code runs inside a QuickJS interpreter compiled to WASM:
@@ -37,30 +38,6 @@ function logTransportBytes(entry) {
     // encoded into ChildToParentMessage. Measure the units the IPC cap sees.
     return serializedBytes(JSON.stringify(JSON.stringify(entry)));
 }
-function exceedsUtf8ByteLimit(value, limit) {
-    let bytes = 0;
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code <= 0x7f)
-            bytes += 1;
-        else if (code <= 0x7ff)
-            bytes += 2;
-        else if (code >= 0xd800 &&
-            code <= 0xdbff &&
-            index + 1 < value.length &&
-            value.charCodeAt(index + 1) >= 0xdc00 &&
-            value.charCodeAt(index + 1) <= 0xdfff) {
-            bytes += 4;
-            index += 1;
-        }
-        else {
-            bytes += 3;
-        }
-        if (bytes > limit)
-            return true;
-    }
-    return false;
-}
 /** Normalize model output into an async-arrow expression: strip markdown fences, wrap bare bodies. */
 export function normalizeCode(code) {
     let c = code.trim();
@@ -216,7 +193,7 @@ function installBridge(ctx, providers, logs, onLog) {
             catch (err) {
                 throw new Error(`Host result from ${label} could not be serialized: ${msg(err)}`);
             }
-            if (exceedsUtf8ByteLimit(json, MAX_HOST_RESULT_BYTES)) {
+            if (utf8Length(json, MAX_HOST_RESULT_BYTES) > MAX_HOST_RESULT_BYTES) {
                 throw new Error(`Host result from ${label} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`);
             }
             return { json };

package/dist/executors/quickjs.js

@@ -119,7 +119,7 @@ function terminate(child) {
 }
 let providePoolProgram;
 class QuickJsChildPool {
-    /** What `/health` and `connecta doctor` call this sandbox (#368). */
+    /** What `/health` and `connecta doctor` call this sandbox. */
     name = "QuickJS";
     admission;
     slots;

package/dist/guest-functions.js

@@ -0,0 +1,83 @@
+/**
+ * Every `connecta.<name>` function a guest program can reach, in one list.
+ *
+ * Guest-safe data only: no host implementation, no imports. The guest runtime
+ * builds its namespace from it, execute.ts admits each host call by its budget
+ * class and binds it by name to an implementation typed against this list, and
+ * the execute_code description's compact declaration is joined from it.
+ * `GuestApi` in guest-types.ts stays the published type; the package-surface
+ * test compiles the joined declaration against it.
+ */
+export const GUEST_FUNCTIONS = [
+    /** Searches the catalog and returns one flat page of `{ tools }`. */
+    {
+        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 }>;",
+    },
+    /** Describes exact addresses, one entry per address in order. */
+    {
+        name: "describe",
+        budget: "hostCall",
+        declaration: "describe(args?: { address?: string; addresses?: string[]; format?: Schemas }): Promise<{ tools: (Tool & { error?: string })[] }>;",
+    },
+    /** Calls one tool and inlines transfer pages and native content. */
+    {
+        name: "call",
+        budget: "hostCall",
+        wrapped: true,
+        declaration: "call(address: string, args?: unknown, options?: { timeoutMs?: number }): Promise<Result>;",
+    },
+    /** Reads one advertised resource URI. */
+    {
+        name: "read",
+        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. */
+    {
+        name: "result",
+        budget: "hostCall",
+        deadline: "result storage",
+        declaration: "result(id: string | Paged, options?: { page?: number; offset?: number; maxBytes?: number }): Promise<{ text: string; hasMore: boolean; nextOffset?: number }>;",
+    },
+    /** Fetches a skill's text by exact name. */
+    {
+        name: "skill",
+        budget: "hostCall",
+        deadline: "skill lookup",
+        alias: { name: "skills", note: "models write connecta.skills, the top-level tool's name." },
+        declaration: "skill(name: string): Promise<{ text: string }>;",
+    },
+    /** Forwards a content block to the client; needs no await. */
+    {
+        name: "emit",
+        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. */
+    {
+        name: "unawaited",
+        budget: "once",
+        label: "missing-await notice",
+    },
+];
+/** Public guest functions that spend no host call, for the agent-facing text. */
+export const UNCOUNTED_GUEST_FUNCTIONS = GUEST_FUNCTIONS.filter((fn) => fn.budget === "emission")
+    .map((fn) => fn.name)
+    .join(" and ");
+/**
+ * The guest API as the execute_code description shows it: compact shapes of
+ * GuestApi in src/guest-types.ts, checked against it by the package-surface
+ * declaration test. Arguments match what GuestApi accepts in both directions,
+ * results are supertypes of its results, and no field is invented. Type notation, not runnable JS.
+ */
+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 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 };
+type Native = Block | { type: "resource"; resource: { uri: string } & ({ text: string } | { blob: string }) } | { type: "resource_link"; uri: string; name: string };`;