@zackbart/connecta 0.38.0 → 0.40.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,
@@ -425,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));
@@ -468,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,
@@ -698,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 () => {
@@ -822,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.");
@@ -856,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;
+                },
+            ];
+        })),
     };
 }
 /**
@@ -1054,6 +1077,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
         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, maxResultChars);
         const resultDependencies = [];
+        const unawaited = { read: false };
         const dispatchController = new AbortController();
         const terminal = Deferred.makeUnsafe();
         let budgetFailure;
@@ -1104,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."));
@@ -1142,6 +1168,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             emitted,
             diagnostics,
             program,
+            unawaited,
             // Emitted text shares the return cap; a follow-up page run gets all of it.
             guardResult: (value) => authCall(guardProgramReturn, [
                 value,
@@ -1256,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.", {
@@ -1300,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),
             });
         }
@@ -1356,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.callTimeoutMs === hostLimits.hostCallTimeoutMs ? `${hostLimits.callTimeoutMs / 1_000}s/host call` : `${hostLimits.callTimeoutMs / 1_000}s/call (${hostLimits.hostCallTimeoutMs / 1_000}s result/skill/read)`}.
+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. connecta.skill("usage"): repair${connectorGuides ? ", guide handling" : ""}; connecta.skill("investigate"): workflow.`;
+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.
@@ -1439,13 +1476,14 @@ export function registerExecuteTool(server, registry, ctx) {
         maxWrites,
         maxResultChars: ctx.maxResultChars,
         requestScope: ctx.requestScope,
+        routes: ctx.routes,
     });
     server.registerTool("execute_code", {
         description: executeDescription(emitBudgets, {
             ...hostLimits,
             // 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),
+        }, 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.
@@ -1480,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,3 +1,4 @@
+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. */
@@ -7,7 +8,8 @@ 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/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 };`;

package/dist/guest-runtime.js

@@ -1,3 +1,4 @@
+import { GUEST_FUNCTIONS } from "./guest-functions.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)())`;
@@ -62,6 +63,34 @@ export function guestPromiseInitializer() {
   Object.freeze(NativePromise.prototype);
 })()`;
 }
+/**
+ * The frozen namespace, joined from the registry. A `wrapped` or `emission`
+ * function uses the initializer's local of the same name; an alias shares one
+ * function object. Only guest source enters this string.
+ */
+const GUEST_NAMESPACE = (() => {
+    const before = [];
+    const entries = ["__proto__: null"];
+    for (const fn of GUEST_FUNCTIONS) {
+        if (fn.budget === "once")
+            continue;
+        if (fn.budget === "emission") {
+            entries.push(`${fn.name}(block) {
+      const ref = block && typeof block === "object" ? weakGet(nativeRefs, block) : undefined;
+      return trackEmission(${fn.name}(ref || block));
+    }`);
+            continue;
+        }
+        const value = `hosted(${"wrapped" in fn ? fn.name : `provider.${fn.name}`})`;
+        if (!("alias" in fn)) {
+            entries.push(`${fn.name}: ${value}`);
+            continue;
+        }
+        before.push(`  const ${fn.name} = ${value};\n`);
+        entries.push(fn.name, `// Undeclared alias: ${fn.alias.note}\n    ${fn.alias.name}: ${fn.name}`);
+    }
+    return `${before.join("")}  const namespace = freeze({\n    ${entries.join(",\n    ")}\n  });`;
+})();
 /** Capture a private initializer before a Worker evaluates its guest module. */
 export function guestInitializer() {
     return `(() => {
@@ -152,21 +181,17 @@ export function guestInitializer() {
       }
     });
   }
-  const namespace = freeze({
-    __proto__: null,
-    search: provider.search,
-    describe: provider.describe,
-    call,
-    read: provider.read,
-    result: provider.result,
-    skill: provider.skill,
-    // Undeclared alias: models write connecta.skills, the top-level tool's name.
-    skills: provider.skill,
-    emit(block) {
-      const ref = block && typeof block === "object" ? weakGet(nativeRefs, block) : undefined;
-      return trackEmission(emit(ref || block));
-    }
-  });
+  // Result fields read off an unawaited host call flag the run, still undefined.
+  let unawaited = false;
+  const fields = {};
+  for (const key of ["data", "format", "content", "tools", "catalogErrors", "total", "text", "resultId", "hasMore", "nextOffset"])
+    fields[key] = { get() { unawaited = true; } };
+  const hosted = (fn) => function () {
+    const promise = apply(fn, undefined, arguments);
+    if (promise && typeof promise === "object") defineProperties(promise, fields);
+    return promise;
+  };
+${GUEST_NAMESPACE}
   globalThis.connecta = namespace;
   defineProperties(globalThis, {
     Error: { value: NativeError, writable: false, configurable: false },
@@ -176,7 +201,13 @@ export function guestInitializer() {
       return async (program) => {
         if (used) throw new NativeError("Guest runner initialization is single-use.");
         used = true;
-        const result = await program(namespace);
+        let result;
+        try {
+          result = await program(namespace);
+        } catch (error) {
+          if (unawaited) try { await provider.unawaited(); } catch {}
+          throw error;
+        }
         for (let i = 0; i < pending.length; i++) {
           const report = await pending[i].settled;
           if (!report.ok && !pending[i].handled) throw report.error;
@@ -200,8 +231,15 @@ const ERROR_NAMES = new Set([
 ]);
 /** Fixed repair guidance, used only in agent-facing results. */
 export function programError(raw, code) {
-    const message = typeof raw.message === "string" ? raw.message : "Program failed.";
-    const name = typeof raw.name === "string" && ERROR_NAMES.has(raw.name) ? raw.name : "Error";
+    const text = typeof raw.message === "string" ? raw.message : "Program failed.";
+    // Executors may report "TypeError: …" as the message itself; name it once.
+    const prefix = /^([A-Za-z]*Error): /.exec(text)?.[1];
+    const name = typeof raw.name === "string" && ERROR_NAMES.has(raw.name)
+        ? raw.name
+        : prefix && ERROR_NAMES.has(prefix)
+            ? prefix
+            : "Error";
+    const message = prefix === name ? text.slice(name.length + 2) : text;
     const stack = typeof raw.stack === "string" ? raw.stack : "";
     // Compare QuickJS/V8 locations to the wrapper baseline after the source.
     const location = /:(\d+)(?::\d+)?\)?(?:\n|$)/.exec(stack);
@@ -217,7 +255,10 @@ export function programError(raw, code) {
                 ? Math.max(1, Number(location[1]) - Number(baseline[1]) + code.split("\n").length + 1)
                 : null;
     let hint = "Use plain JavaScript in one async () => { ... } expression and the connecta global.";
-    if (/\brequire\b|\b[Ii]mports?\b|\bfs\b|filesystem|node:/.test(message) ||
+    if (raw.unawaited === true) {
+        hint = "connecta.* returns a Promise; await it: (await connecta.call(address, args)).data.";
+    }
+    else if (/\brequire\b|\b[Ii]mports?\b|\bfs\b|filesystem|node:/.test(message) ||
         (name === "SyntaxError" && /\bimport\b/.test(code))) {
         hint =
             "Imports, require, and filesystem access are outside the guest API. Use connecta.call to access configured services.";