@zackbart/connecta 0.9.1 → 0.10.0

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "sideEffects": false,
-  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind nine meta-tools.",
+  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
   "license": "MIT",
   "engines": {
     "node": ">=20.9.0"

package/src/catalog-service.ts

@@ -10,7 +10,7 @@ import {
   mapSettledWithConcurrency,
   resolveDiscoveryConcurrency,
 } from "./concurrency.js";
-import { classifyCallError, messageLooksRetryable } from "./errors.js";
+import { classifyCallError, framingError } from "./errors.js";
 import type { CallErrorDetails } from "./errors.js";
 import type {
   ConnectorOperationOptions,
@@ -199,10 +199,6 @@ export type CatalogResolution =
       cause?: unknown;
     };
 
-function framingError(code: string, message: string): CallErrorDetails {
-  return { code, message, retryable: messageLooksRetryable(message) };
-}
-
 function renderSchema(schema: JsonSchema, format: "compact" | "json"): unknown {
   return format === "json" ? schema : compactSchema(schema);
 }

package/src/errors.ts

@@ -102,6 +102,34 @@ export interface CallErrorDetails {
   retry?: string;
 }
 
+/**
+ * Codes whose retryability is a fact about connecta's own framing, never a
+ * guess from text. The message embeds the address the caller asked for, so a
+ * connector named `svc-503` or `temporary-export` would otherwise flip a policy
+ * refusal into `retryable: true` through the heuristic below — and a caller that
+ * trusts the flag would cheerfully retry a refusal forever.
+ */
+const NEVER_RETRYABLE_FRAMING = new Set([
+  "unknown_address",
+  "unknown_tool",
+  "ambiguous_tool_alias",
+  "destructive_tool_requires_approval",
+]);
+
+/**
+ * Details for a failure connecta itself framed — an address it could not
+ * resolve, a tool it refuses to run — rather than one a connector threw.
+ */
+export function framingError(code: string, message: string): CallErrorDetails {
+  return {
+    code,
+    message,
+    retryable: NEVER_RETRYABLE_FRAMING.has(code)
+      ? false
+      : messageLooksRetryable(message),
+  };
+}
+
 const RETRYABLE_MESSAGE_RE =
   /timeout|timed out|econnreset|econnrefused|temporar|rate.?limit|429|502|503|504|refcountedcanceler|different request/i;
 const TIMEOUT_MESSAGE_RE = /timed out|timeout/i;

package/src/execute.ts

@@ -4,6 +4,7 @@ import type { ActivityRequestContext } from "./activity.js";
 import {
   boundedDiscoveryText,
   CatalogService,
+  DiscoveryPolicyError,
   flatSearchResult,
 } from "./catalog-service.js";
 import { errorResult, jsonResult, type ToolResult } from "./meta-tools.js";
@@ -16,12 +17,14 @@ import {
   ExecutorAdmissionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
+import { classifyCallError } from "./errors.js";
 import {
   InvocationFailure,
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type {
+  ConnectaSurface,
   Executor,
   ExecutorProvider,
   Logger,
@@ -205,6 +208,29 @@ export async function buildSandboxProviders(
       }
     },
   });
+  /**
+   * 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.
+   */
+  const typedDiscovery = async <T>(operation: () => Promise<T>): Promise<T> => {
+    try {
+      return await operation();
+    } catch (err) {
+      if (err instanceof DiscoveryPolicyError) {
+        limits.onInvocationFailure?.(
+          new InvocationFailure({
+            code: err.code,
+            message: err.message,
+            retryable: false,
+          }),
+        );
+      }
+      throw err;
+    }
+  };
   const callAddress = async (address: unknown, args: unknown) => {
     const outcome = await invocation.invoke(
       String(address),
@@ -262,53 +288,65 @@ export async function buildSandboxProviders(
                   data: await callAddress(item.address, item.args),
                 };
               } catch (err) {
+                // Same failure shape batch_call 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: msg(err),
+                  error: details.message,
+                  errorDetails: details,
                 };
               }
             }),
           );
         },
-        search: async (raw: unknown) => {
-          const args = (raw ?? {}) as {
-            query?: string;
-            connector?: string;
-            limit?: number;
-            offset?: number;
-            fullDescriptions?: boolean;
-            includeSchemas?: "compact" | "json";
-            includeSchemaKeys?: boolean;
-          };
-          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 hard discovery-byte ceiling.
-              includeSchemaKeys: args.includeSchemaKeys !== false,
-            }),
-          );
-          boundedDiscoveryText(
-            result,
-            "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.",
-          );
-          return result;
-        },
-        describe: async (raw: unknown) => {
-          const args = (raw ?? {}) as {
-            addresses?: unknown;
-            format?: "compact" | "json";
-            fullDescriptions?: boolean;
-          };
-          const result = { tools: await catalog.describe(args) };
-          boundedDiscoveryText(
-            result,
-            'Split the address list or use format: "compact".',
-          );
-          return result;
-        },
+        search: async (raw: unknown) =>
+          typedDiscovery(async () => {
+            const args = (raw ?? {}) as {
+              query?: string;
+              connector?: string;
+              limit?: number;
+              offset?: number;
+              fullDescriptions?: boolean;
+              includeSchemas?: "compact" | "json";
+              includeSchemaKeys?: boolean;
+            };
+            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;
+          }),
+        describe: async (raw: unknown) =>
+          typedDiscovery(async () => {
+            const args = (raw ?? {}) as {
+              addresses?: unknown;
+              format?: "compact" | "json";
+              fullDescriptions?: boolean;
+            };
+            const result = { tools: await catalog.describe(args) };
+            boundedDiscoveryText(
+              result,
+              'Split the address list or use format: "compact".',
+            );
+            return result;
+          }),
       },
     },
   ];
@@ -413,13 +451,26 @@ export function createExecuteTool(
       // an unhandled tool failure keeps the same structured contract as
       // call_tool and batch_call. Failures caught by model code never reach
       // outcome.error and therefore remain under that code's control.
+      //
+      // An error the program let through unchanged matches exactly, and an
+      // exact match always wins: a program that wrapped one failure's message
+      // around another's must not have the wrong type attached. Containment is
+      // the fallback, so a wrapped message still reports its underlying type
+      // rather than losing it to prose.
       let invocationFailure: InvocationFailure | undefined;
-      for (let i = invocationFailures.length - 1; i >= 0; i--) {
-        const candidate = invocationFailures[i];
-        if (candidate && outcome.error.includes(candidate.message)) {
-          invocationFailure = candidate;
-          break;
+      for (const match of [
+        (candidate: InvocationFailure) => outcome.error === candidate.message,
+        (candidate: InvocationFailure) =>
+          outcome.error?.includes(candidate.message) === true,
+      ]) {
+        for (let i = invocationFailures.length - 1; i >= 0; i--) {
+          const candidate = invocationFailures[i];
+          if (candidate && match(candidate)) {
+            invocationFailure = candidate;
+            break;
+          }
         }
+        if (invocationFailure) break;
       }
       if (invocationFailure) {
         const result = jsonResult({
@@ -451,15 +502,37 @@ export function createExecuteTool(
   };
 }
 
-const EXECUTE_DESC = `Use for dependent multi-step calls, loops, joins, branching, or reducing large results in a sandbox. Never use execute_code for search-only discovery or one downstream call: use search_tools, then call_tool when needed. For 2–10 independent calls use batch_call. Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
+/**
+ * How the tool opens, and where a program's argument schemas come from. Both
+ * differ by surface: on the classic surface `execute_code` is the tool of last
+ * resort and its neighbours (`batch_call`, `describe_tools`) own the simpler
+ * jobs, while on the code-first surface those tools are gone and the program is
+ * where all of that work happens. Everything after these two phrases is
+ * identical, so the shared body below has one source of truth.
+ */
+const EXECUTE_ROUTING = {
+  classic:
+    "Use for dependent multi-step calls, loops, joins, branching, or reducing large results in a sandbox. Never use execute_code for search-only discovery or one downstream call: use search_tools, then call_tool when needed. For 2–10 independent calls use batch_call.",
+  "code-first":
+    "The primary surface. Use for discovery beyond one lookup, two or more calls, dependent steps, loops, joins, branching, or reducing large results before they reach the model — connecta.search and connecta.describe browse and expand catalogs in the run, and connecta.batch replaces a separate batch tool. The exception is a single call at an address already in hand: search_tools then one call_tool is cheaper than a program.",
+} as const;
+
+const EXECUTE_SCHEMA_SOURCE = {
+  classic: "describe_tools",
+  "code-first": "connecta.describe",
+} as const;
+
+const executeDescription = (
+  surface: ConnectaSurface,
+) => `${EXECUTE_ROUTING[surface]} Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
 
 Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
-- One global per connector: every address <connectorId>.<toolName> from search_tools is callable as <connectorId>.<toolName>(args) with a single args object matching the schema from describe_tools. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (e.g. my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words get "_" appended.
+- One global per connector: every address <connectorId>.<toolName> from search_tools is callable as <connectorId>.<toolName>(args) with a single args object matching the schema from ${EXECUTE_SCHEMA_SOURCE[surface]}. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (e.g. my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words get "_" appended.
 - connecta.call(address, args) and connecta.batch(calls) — call raw addresses.
 - connecta.search(args) and connecta.describe(args) — load and inspect request-local catalogs on demand. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the same names the schema shows, ready to check against before building args. They are absent when a schema is not a plain object shape, so read the schema itself rather than assuming a missing list means no fields.
 - console.log(...) — captured and returned alongside the result.
 
-Tool calls return plain values (MCP text content is JSON-parsed when possible) and throw on downstream errors — use try/catch to handle them. Return a JSON-serializable value; large results are truncated, so reduce data in code instead of returning raw payloads.
+Tool calls return plain values (MCP text content is JSON-parsed when possible) and throw on downstream errors — use try/catch to handle them. A thrown error carries only a message; connecta.batch reports each call as { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }, so use it when the program must tell a policy refusal from a transient failure. Never retry a failure whose retryable is false, and never retry a rate_limited one immediately — the sandbox has no timers. Return a JSON-serializable value; large results are truncated, so reduce data in code instead of returning raw payloads.
 
 Plain JavaScript only — no TypeScript syntax. For unknown-address dependent work, use one execute_code call: search inside it, read the compact schemas, and continue to the dependent calls; do not return search results for a second execute_code call. Compact schemas are TypeScript-like strings, not JSON Schema objects: write the property names they display, never a positional guess or an invented alias.
 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", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((tool) => tool.address.endsWith(suffix)); if (!match) throw new Error("no tool matching " + 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]; }`;
@@ -475,6 +548,8 @@ export function registerExecuteTool(
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
     discoveryConcurrency?: number;
+    /** The advertised surface, which decides this tool's routing copy. */
+    surface?: ConnectaSurface;
   },
 ): void {
   const handler = createExecuteTool(
@@ -490,7 +565,7 @@ export function registerExecuteTool(
   server.registerTool(
     "execute_code",
     {
-      description: EXECUTE_DESC,
+      description: executeDescription(ctx.surface ?? "classic"),
       inputSchema: z.object({
         code: z
           .string()

package/src/executor-result.ts

@@ -13,15 +13,59 @@ function serializeExecuteValue(value: unknown): string {
   return serialized === undefined ? String(value) : serialized;
 }
 
+const TRUNCATION_HINT =
+  "filter/map/slice data inside execute_code 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
+ * text whose quotes and newlines re-escape to well over it, so a fixed slice
+ * would leave the envelope over-cap and a second pass through this guard would
+ * truncate the truncation — reporting the envelope's length as `totalChars` and
+ * burying the real size. Shrinking proportionally until it fits keeps the guard
+ * idempotent by construction: `totalChars` is always the true serialized size
+ * of what the program returned, and truncation happens exactly once no matter
+ * how many hops the value takes.
+ */
+function truncationEnvelope(text: string): {
+  truncated: true;
+  preview: string;
+  totalChars: number;
+  hint: string;
+} {
+  const base = {
+    truncated: true as const,
+    preview: "",
+    totalChars: text.length,
+    hint: TRUNCATION_HINT,
+  };
+  let budget = Math.max(
+    0,
+    MAX_EXECUTE_RESULT_CHARS - JSON.stringify(base).length,
+  );
+  for (let attempt = 0; attempt < 8 && budget > 0; attempt += 1) {
+    const candidate = { ...base, preview: text.slice(0, budget) };
+    const size = JSON.stringify(candidate).length;
+    if (size <= MAX_EXECUTE_RESULT_CHARS) return candidate;
+    // Every character costs at least one serialized character, so scaling by
+    // the overshoot ratio (minus a step) strictly shrinks the budget.
+    budget = Math.max(
+      0,
+      Math.floor(budget * (MAX_EXECUTE_RESULT_CHARS / size)) - 8,
+    );
+  }
+  // The loop shrinks monotonically, so this is unreachable in practice — but an
+  // unchecked slice is exactly how a "bounded" envelope stops being bounded.
+  const clamped = { ...base, preview: text.slice(0, Math.max(0, budget)) };
+  return JSON.stringify(clamped).length <= MAX_EXECUTE_RESULT_CHARS
+    ? clamped
+    : { ...base, preview: "" };
+}
+
 export function guardExecuteResultValue(value: unknown): unknown {
   const text = serializeExecuteValue(value);
   if (text.length <= MAX_EXECUTE_RESULT_CHARS) return value;
-  return {
-    truncated: true,
-    preview: text.slice(0, MAX_EXECUTE_RESULT_CHARS),
-    totalChars: text.length,
-    hint: "filter/map/slice data inside execute_code and return only what you need",
-  };
+  return truncationEnvelope(text);
 }
 
 export function truncateExecuteText(text: string, max: number): string {

package/src/executors/quickjs-protocol.ts

@@ -57,6 +57,25 @@ export interface ExecutionPayload {
   timedOut?: boolean;
 }
 
+/**
+ * How a host call should be named in an error a program will read. The lazy
+ * connector namespaces all dispatch through one internal function, so the raw
+ * provider/function pair would report every shortcut call as
+ * `connecta.__callNamespace` — an internal name that appears nowhere in the
+ * documented surface. Report the address the program actually called.
+ */
+export function hostCallLabel(payload: {
+  namespace: string;
+  functionName: string;
+  args: unknown[];
+}): string {
+  if (payload.functionName === "__callNamespace") {
+    const [connectorId, toolAlias] = payload.args;
+    return `${String(connectorId)}.${String(toolAlias)}`;
+  }
+  return `${payload.namespace}.${payload.functionName}`;
+}
+
 export function serializedBytes(text: string): number {
   return new TextEncoder().encode(text).length;
 }

package/src/executors/quickjs-runtime.ts

@@ -15,6 +15,7 @@ import {
 } from "quickjs-emscripten";
 import type { ExecuteResult, ExecutorProvider } from "../types.js";
 import {
+  hostCallLabel,
   MAX_QUICKJS_LOG_TRANSPORT_BYTES,
   serializedBytes,
 } from "./quickjs-protocol.js";
@@ -245,18 +246,21 @@ function installBridge(
           : undefined;
       if (!f) throw new Error(`Unknown function ${ns}.${fn}`);
       const args = JSON.parse(argsJson) as unknown[];
+      // Name the address the program called, never the internal dispatcher the
+      // lazy connector namespaces share.
+      const label = hostCallLabel({ namespace: ns, functionName: fn, args });
       const value = await f(...args);
       let json: string;
       try {
         json = JSON.stringify({ ok: true, value });
       } catch (err) {
         throw new Error(
-          `Host result from ${ns}.${fn} could not be serialized: ${msg(err)}`,
+          `Host result from ${label} could not be serialized: ${msg(err)}`,
         );
       }
       if (exceedsUtf8ByteLimit(json, MAX_HOST_RESULT_BYTES)) {
         throw new Error(
-          `Host result from ${ns}.${fn} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`,
+          `Host result from ${label} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`,
         );
       }
       return json;

package/src/executors/quickjs.ts

@@ -18,6 +18,7 @@ import type {
   ExecutorProvider,
 } from "../types.js";
 import {
+  hostCallLabel,
   MAX_QUICKJS_IPC_BYTES,
   MAX_QUICKJS_HOST_RPC_BYTES,
   type ChildToParentMessage,
@@ -593,6 +594,9 @@ class QuickJsChildPool implements AdmittingExecutor {
         serializedBytes(message.payloadJson) >
         MAX_QUICKJS_HOST_RPC_BYTES
       ) {
+        // Refused before parsing, so there is no address to name here: parsing
+        // an over-limit payload to improve its error message would spend the
+        // work the limit exists to refuse.
         throw new RangeError("Host call arguments exceeded the IPC limit.");
       }
       const payload = JSON.parse(message.payloadJson) as HostCallPayload;
@@ -610,14 +614,17 @@ class QuickJsChildPool implements AdmittingExecutor {
       try {
         payloadJson = stringifyBounded(
           { ok: true, value } satisfies HostResultPayload,
-          `Host result from ${payload.namespace}.${payload.functionName}`,
+          `Host result from ${hostCallLabel(payload)}`,
           MAX_QUICKJS_HOST_RPC_BYTES,
         );
       } catch (err) {
+        // The guest reads this text, so it names the address the program called
+        // rather than the internal dispatcher every shortcut namespace shares.
+        const label = hostCallLabel(payload);
         const detail =
           err instanceof RangeError
-            ? `Host result from ${payload.namespace}.${payload.functionName} exceeds the ${MAX_QUICKJS_HOST_RPC_BYTES}-byte serialized bridge limit.`
-            : `Host result from ${payload.namespace}.${payload.functionName} could not be serialized: ${msg(err)}`;
+            ? `Host result from ${label} exceeds the ${MAX_QUICKJS_HOST_RPC_BYTES}-byte serialized bridge limit.`
+            : `Host result from ${label} could not be serialized: ${msg(err)}`;
         payloadJson = errorPayload(detail);
       }
     } catch (err) {

package/src/index.ts

@@ -17,6 +17,7 @@ import type { ActivityReadGate, ActivityStore } from "./activity.js";
 import type {
   Connector,
   ConnectaBranding,
+  ConnectaSurface,
   Executor,
   InboundAuth,
   KVStorage,
@@ -169,12 +170,22 @@ export interface ConnectaConfig {
   /** Deployment metadata exposed by /health (for example a Worker version). */
   deploymentInfo?: Record<string, unknown>;
   /**
-   * Sandbox for the optional execute_code meta-tool (code mode). Omit → the
-   * tool is not registered and connecta serves the nine base tools. Workers:
-   * `new DynamicWorkerExecutor({ loader: env.LOADER })` from
-   * `@cloudflare/codemode`. Node: `quickJsExecutor()` from "@zackbart/connecta/quickjs".
+   * Sandbox for `execute_code`, and the switch that decides the surface: with
+   * an executor a model sees the seven code-first tools, without one the nine
+   * classic ones. Workers: `new DynamicWorkerExecutor({ loader: env.LOADER })`
+   * from `@cloudflare/codemode`. Node: `quickJsExecutor()` from
+   * "@zackbart/connecta/quickjs".
    */
   executor?: Executor;
+  /**
+   * Override the surface the `executor` implies. The only reason to set it is
+   * `"classic"` alongside an executor — ten tools, the shape the eval gate's
+   * *incremental* arm measures ("does adding `execute_code` to classic help on
+   * its own?"). The gate's control arm is executor-free classic, which needs no
+   * override. `"code-first"` is the default wherever an executor exists and
+   * throws without one.
+   */
+  surface?: ConnectaSurface;
 }
 
 export interface Connecta {
@@ -406,8 +417,43 @@ function warnInsecureConfig(
   }
 }
 
+/**
+ * The advertised surface: the executor is the switch. Configure one and the
+ * deployment serves the seven-tool code-first surface; omit it and there is no
+ * program to fold discovery and batching into, so it serves classic.
+ *
+ * Two mistakes are structural rather than recoverable, so neither is warned
+ * past: a surface name connecta does not implement, which would otherwise
+ * resolve to something the operator did not ask for; and `code-first` without
+ * an executor, which would advertise six tools and no program surface.
+ */
+function resolveSurface(config: ConnectaConfig): ConnectaSurface {
+  const surface = config.surface;
+  if (surface === undefined) {
+    return config.executor ? "code-first" : "classic";
+  }
+  if (surface !== "classic" && surface !== "code-first") {
+    throw new Error(
+      `ConnectaConfig.surface must be "classic" or "code-first", not ` +
+        `${JSON.stringify(surface)}.`,
+    );
+  }
+  if (surface === "code-first" && !config.executor) {
+    throw new Error(
+      'ConnectaConfig.surface "code-first" requires an executor: it folds ' +
+        "list_connectors, describe_tools, and batch_call into connecta.search, " +
+        "connecta.describe, and connecta.batch inside execute_code, so without " +
+        "an executor there is nothing left to reach them through. Configure " +
+        "one (quickJsExecutor() from \"@zackbart/connecta/quickjs\" on Node, " +
+        "new DynamicWorkerExecutor({ loader: env.LOADER }) on Workers).",
+    );
+  }
+  return surface;
+}
+
 export function createConnecta(config: ConnectaConfig): Connecta {
   assertNoLegacyConfig(config);
+  const surface = resolveSurface(config);
   const storage = config.storage ?? memoryStorage();
   const logger = config.logger ?? defaultLogger();
   const credentialConnectors = config.connectors.filter((c) => c.credential);
@@ -484,6 +530,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       ? { activityDeploymentId: config.activity.deploymentId }
       : {}),
     ...(executor !== undefined ? { executor } : {}),
+    surface,
     requestAdmission,
     ...(config.calls?.defaultTimeoutMs !== undefined
       ? { defaultToolTimeoutMs: config.calls.defaultTimeoutMs }
@@ -553,6 +600,7 @@ export type {
   ConnectorCallAdmissionRule,
   ConnectorRollingWindowBudget,
   ConnectaBranding,
+  ConnectaSurface,
   ConnectorCredentialAccess,
   ConnectorCredentialConfig,
   ConnectorCredentialFieldConfig,

package/src/invocation.ts

@@ -12,7 +12,7 @@ import {
 import {
   classifyCallError,
   ConnectorCallError,
-  messageLooksRetryable,
+  framingError,
   type AuthRecoveryMode,
   type CallErrorDetails,
 } from "./errors.js";
@@ -70,10 +70,6 @@ function retrySafe(definition: ToolDef): boolean {
   );
 }
 
-function framingError(code: string, message: string): CallErrorDetails {
-  return { code, message, retryable: messageLooksRetryable(message) };
-}
-
 function callerCancelledDetails(): CallErrorDetails {
   return {
     code: "cancelled",