@zackbart/connecta 0.10.6 → 0.12.0

package/src/execute.ts

@@ -1,6 +1,10 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type { ActivityRequestContext } from "./activity.js";
+import {
+  PROGRAM_UI_META_KEY,
+  PROGRAM_UI_RESOURCE_URI,
+} from "./apps-shell.js";
 import {
   boundedDiscoveryText,
   CatalogService,
@@ -15,6 +19,7 @@ import {
 } from "./executor-result.js";
 import {
   ExecutorAdmissionError,
+  ExecutorExecutionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
 import { classifyCallError } from "./errors.js";
@@ -24,7 +29,6 @@ import {
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type {
-  ConnectaSurface,
   Executor,
   ExecutorProvider,
   Logger,
@@ -70,6 +74,7 @@ class ExecuteDiagnostics {
   setupMs = 0;
   executorWallMs = 0;
   private emitted?: { count: number; bytes: number };
+  private ui?: number;
 
   /** Numbers only, per R8 — and only once something was emitted, so a
    * non-emitting run's diagnostics stay byte-for-byte what they were. */
@@ -77,6 +82,15 @@ class ExecuteDiagnostics {
     if (count > 0) this.emitted = { count, bytes };
   }
 
+  /**
+   * U9: the UI payload gets its own aggregate — one number, the payload's
+   * serialized size. Folding it into `emitted` would desync that aggregate's
+   * pair, which reports the bytes a specific block count cost.
+   */
+  recordUi(bytes: number): void {
+    this.ui = bytes;
+  }
+
   private stats(operation: ExecuteDiagnosticOperation) {
     let stats = this.operations.get(operation);
     if (!stats) {
@@ -159,6 +173,7 @@ class ExecuteDiagnostics {
     };
     operations: ExecuteOperationDiagnostics[];
     emitted?: { count: number; bytes: number };
+    ui?: number;
   } {
     const operations = [...this.operations.values()];
     return {
@@ -175,6 +190,7 @@ class ExecuteDiagnostics {
       },
       operations,
       ...(this.emitted ? { emitted: this.emitted } : {}),
+      ...(this.ui !== undefined ? { ui: this.ui } : {}),
     };
   }
 }
@@ -232,16 +248,49 @@ function requireEmittedBlock(raw: unknown): EmittedBlock {
   return raw as EmittedBlock;
 }
 
+const UI_SHAPE_HINT =
+  "connecta.ui accepts exactly one argument: a non-empty string of HTML";
+
+/** What the argument was, named the way the emit validator names a bad field. */
+function describeUiArgument(raw: unknown): string {
+  if (raw === null) return "null";
+  if (raw === undefined) return "undefined";
+  if (Array.isArray(raw)) return "an array";
+  if (typeof raw === "string") return "an empty string";
+  const kind = typeof raw;
+  return `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`;
+}
+
 /**
- * Request-local collection for `connecta.emit`. Budgets fail loudly at the
- * crossing call — the block is not partially accepted and prior blocks are
- * unaffected — so a program learns it is over budget while it can still
- * choose differently (M5). Accepted blocks never ride `ExecuteResult`; the
- * handler that owns this collector appends them to the final tool result.
+ * Strict U1 validation. There is no options parameter and no sugar form, for
+ * M1's reason: sugar is how a one-shape contract grows hair. An options bag or
+ * an MCP block object is just a non-string, and fails as one.
+ */
+function requireUiHtml(raw: unknown): string {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`${UI_SHAPE_HINT}; got ${describeUiArgument(raw)}`);
+  }
+  return raw;
+}
+
+/**
+ * Request-local collection for `connecta.emit` and `connecta.ui`. Budgets fail
+ * loudly at the crossing call — nothing is partially accepted and prior blocks
+ * are unaffected — so a program learns it is over budget while it can still
+ * choose differently (M5, U4). Accepted output never rides `ExecuteResult`; the
+ * handler that owns this collector delivers it on the final tool result.
+ *
+ * The two channels share the byte aggregate and nothing else: a UI payload is
+ * not a block, so it spends no block count, and at most one is ever accepted.
  */
 export class EmitCollector {
   readonly blocks: EmittedBlock[] = [];
+  /** The shared transport aggregate: emitted blocks plus the UI payload. */
   bytes = 0;
+  /** The one accepted UI payload (U2), delivered in result `_meta` on success. */
+  ui?: { html: string };
+  /** What the blocks alone cost, so the `emitted` aggregate stays a true pair. */
+  private blockBytes = 0;
   constructor(
     private readonly maxBytes: number,
     private readonly maxBlocks: number,
@@ -263,7 +312,38 @@ export class EmitCollector {
     }
     this.blocks.push(block);
     this.bytes += size;
-    this.diagnostics?.recordEmitted(this.blocks.length, this.bytes);
+    this.blockBytes += size;
+    this.diagnostics?.recordEmitted(this.blocks.length, this.blockBytes);
+  }
+
+  /**
+   * U2 and U4: one payload per run, measured as the serialized bytes of
+   * `{ html }` against the same aggregate emit spends. A second call throws
+   * naming the constraint rather than replacing the first — one tool result
+   * renders one view, and last-wins would silently discard a payload the
+   * program deliberately supplied.
+   *
+   * Multiplicity is checked before shape, so the second call is told what it
+   * actually broke. A program whose second payload is also malformed has one
+   * problem worth naming — that there is a second payload at all — and a
+   * complaint about its type would send the author to fix the wrong thing.
+   */
+  acceptUi(raw: unknown): void {
+    if (this.ui) {
+      throw new Error(
+        "connecta.ui accepts at most one payload per run: a view was already accepted and stands",
+      );
+    }
+    const payload = { html: requireUiHtml(raw) };
+    const size = diagnosticsEncoder.encode(JSON.stringify(payload)).byteLength;
+    if (this.bytes + size > this.maxBytes) {
+      throw new Error(
+        `connecta.ui byte budget exceeded: payload is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`,
+      );
+    }
+    this.ui = payload;
+    this.bytes += size;
+    this.diagnostics?.recordUi(size);
   }
 }
 
@@ -425,12 +505,7 @@ export async function buildSandboxProviders(
   const requestScope = {};
   const catalog = new CatalogService(registry, baseUrl, {
     requestScope,
-    // Every describe reaching this catalog came from inside a program, on a
-    // code-first and a classic-with-executor deployment alike, so the retry
-    // advice names connecta.describe regardless of what this server advertises.
-    describeRoute: "connecta.describe",
-    // Same reasoning for the discovery route a routing failure hands back: the
-    // program that just missed an address cannot call search_tools.
+    // A program that just missed an address cannot call search_tools.
     searchRoute: "connecta.search",
     ...(limits.discoveryConcurrency !== undefined
       ? { concurrency: limits.discoveryConcurrency }
@@ -564,6 +639,18 @@ export async function buildSandboxProviders(
           }
           limits.emitCollector.accept(block);
         },
+        // The rendered-output channel rides the same bridge for the same
+        // reason (U7): one more provider fn, no change to ExecuteResult or
+        // the Executor contract. Delivery is the handler's job, not the
+        // guest's — nothing here becomes addressable.
+        ui: async (html: unknown) => {
+          if (!limits.emitCollector) {
+            throw new Error(
+              "connecta.ui is unavailable: no emission collector was configured for this execution",
+            );
+          }
+          limits.emitCollector.acceptUi(html);
+        },
         batch: async (calls: unknown) => {
           const started = Date.now();
           const callCount = Array.isArray(calls) ? calls.length : 0;
@@ -588,8 +675,8 @@ export async function buildSandboxProviders(
                     ),
                   };
                 } catch (err) {
-                  // Same failure shape batch_call reports: the message a program
-                  // can log, plus the typed details it must classify by. A
+                  // The failure shape connecta.batch reports: the message a
+                  // program can log, plus the typed details it must classify by. A
                   // thrown host error crosses the sandbox bridge as a bare
                   // message string in every executor, so this is the one place a
                   // program can tell a policy refusal from a transient failure.
@@ -818,6 +905,9 @@ export function createExecuteTool(
               ? { retryAfterMs: err.retryAfterMs }
               : {}),
           },
+          ...(err instanceof ExecutorExecutionError
+            ? discardedEmits(emitted)
+            : {}),
           ...(diagnostics ? { diagnostics: diagnostics.finish() } : {}),
         });
         result.isError = true;
@@ -857,7 +947,7 @@ export function createExecuteTool(
       // Executor bridges necessarily reduce thrown host errors to strings.
       // Match that terminal string back to the request-local typed failure so
       // an unhandled tool failure keeps the same structured contract as
-      // call_tool and batch_call. Failures caught by model code never reach
+      // call_tool. 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
@@ -942,9 +1032,19 @@ export function createExecuteTool(
     const response = jsonResult({
       result,
       ...(emitted.blocks.length > 0 ? { emitted: emitted.blocks.length } : {}),
+      // U3: the model learns a view rendered without seeing its bytes. Spread
+      // conditionally so a program that never called connecta.ui produces
+      // today's byte-for-byte response.
+      ...(emitted.ui ? { ui: true } : {}),
       ...(logs ? { logs } : {}),
       ...(diagnostics ? { diagnostics: diagnostics.finish() } : {}),
     });
+    if (emitted.ui) {
+      // _meta is where the Apps spec's best practices put data "not intended
+      // for model context", and how shipped hosts behave. The shell reads
+      // exactly this key out of the tool result the host delivers to it.
+      response._meta = { [PROGRAM_UI_META_KEY]: { html: emitted.ui.html } };
+    }
     if (emitted.blocks.length > 0) {
       // Emitted image/audio blocks are valid MCP content that ToolResult's
       // text-only typing does not model — the same acknowledged gap
@@ -957,52 +1057,43 @@ export function createExecuteTool(
   };
 }
 
-/** M4: a failed program delivers no blocks, but the discard is visible. */
+/**
+ * M4 and U3: a failed program delivers no blocks and no view, but each
+ * discard is visible — and one failure can discard both.
+ */
 function discardedEmits(emitted: EmitCollector): {
   emittedDiscarded?: number;
+  uiDiscarded?: true;
 } {
-  return emitted.blocks.length > 0
-    ? { emittedDiscarded: emitted.blocks.length }
-    : {};
+  return {
+    ...(emitted.blocks.length > 0
+      ? { emittedDiscarded: emitted.blocks.length }
+      : {}),
+    ...(emitted.ui ? { uiDiscarded: true as const } : {}),
+  };
 }
 
 /** The same visibility for the plain-text error paths. */
 function discardedEmitsText(emitted: EmitCollector): string {
-  return emitted.blocks.length > 0
-    ? `\n\nemittedDiscarded: ${emitted.blocks.length}`
-    : "";
+  const lines = [
+    ...(emitted.blocks.length > 0
+      ? [`emittedDiscarded: ${emitted.blocks.length}`]
+      : []),
+    ...(emitted.ui ? ["uiDiscarded: true"] : []),
+  ];
+  return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
 }
 
-/**
- * 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,
   emitBudgets: { maxBytes: number; maxBlocks: number },
-) => `${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.
+) => `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 handles independent calls. The exception is a single call at an address already in hand: search_tools then one call_tool is cheaper than a program. 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 ${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.
+- 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 connecta.describe. 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), connecta.describe({ address: "<connectorId>.<toolName>" }), and connecta.describe({ addresses: [...] }) — load and inspect request-local catalogs on demand. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; the filter changes results, not authority. 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.
 - connecta.emit(block) — deliver rich MCP content alongside the JSON return: exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }, no other fields. Blocks are appended to the result on success only, spend no host calls, and are budgeted per run (${emitBudgets.maxBlocks} blocks, ${emitBudgets.maxBytes} serialized bytes); an over-budget or invalid emit throws catchably and accepts nothing.
+- connecta.ui(html) — hand the client one rendered view of this run: exactly one argument, a non-empty HTML string, no options and no block object. At most one per run, delivered on success only, out of model context (the envelope just reports ui: true), and spending no host calls. It draws on the same ${emitBudgets.maxBytes}-byte budget as connecta.emit; a second, over-budget, or invalid call throws catchably and accepts nothing. The view is display-only — no network, no tool calls, no links.
 - 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. 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.
@@ -1032,8 +1123,6 @@ export function registerExecuteTool(
     maxEmittedBytes?: number;
     /** Block-count budget for connecta.emit. Default 32. */
     maxEmittedBlocks?: number;
-    /** The advertised surface, which decides this tool's routing copy. */
-    surface?: ConnectaSurface;
   },
 ): void {
   // Resolved once so the description and the collector cannot disagree about
@@ -1065,7 +1154,7 @@ export function registerExecuteTool(
   server.registerTool(
     "execute_code",
     {
-      description: executeDescription(ctx.surface ?? "classic", emitBudgets),
+      description: executeDescription(emitBudgets),
       inputSchema: z.object({
         code: z
           .string()
@@ -1084,6 +1173,18 @@ export function registerExecuteTool(
         destructiveHint: false,
         openWorldHint: true,
       },
+      // U5 and U10: declared unconditionally. A host without the Apps
+      // extension ignores unknown _meta and sees the ordinary envelope, which
+      // is the text fallback the spec mandates — and a stateless aggregator
+      // has nowhere dependable to hold a negotiation check anyway. The
+      // explicit visibility keeps hosts from being told the view may call
+      // execute_code; the default ["model","app"] would say exactly that.
+      _meta: {
+        ui: {
+          resourceUri: PROGRAM_UI_RESOURCE_URI,
+          visibility: ["model"],
+        },
+      },
     },
     async (args, extra) => {
       const controller = new AbortController();

package/src/executor-admission.ts

@@ -36,6 +36,18 @@ export class ExecutorAdmissionError extends Error {
   }
 }
 
+/**
+ * A lifecycle failure after the sandbox started running. It keeps the stable
+ * admission-error envelope while letting response assembly distinguish work
+ * torn down in flight from work that never entered the executor.
+ */
+export class ExecutorExecutionError extends ExecutorAdmissionError {
+  constructor(code: ExecutorAdmissionErrorCode, message: string) {
+    super(code, message);
+    this.name = "ExecutorExecutionError";
+  }
+}
+
 export interface AdmissionLease {
   /** Time spent waiting behind active work. Zero for immediate admission. */
   readonly waitMs: number;

package/src/executors/quickjs.ts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import {
   AdmissionController,
   ExecutorAdmissionError,
+  ExecutorExecutionError,
 } from "../executor-admission.js";
 import type {
   AdmittingExecutor,
@@ -737,7 +738,7 @@ class QuickJsChildPool implements AdmittingExecutor {
     if (!child) return Promise.resolve();
     this.rejectActive(
       slot,
-      new ExecutorAdmissionError(
+      new ExecutorExecutionError(
         "executor_closed",
         "Executor is shutting down.",
       ),

package/src/index.ts

@@ -18,7 +18,6 @@ import type { ActivityReadGate, ActivityStore } from "./activity.js";
 import type {
   Connector,
   ConnectaBranding,
-  ConnectaSurface,
   Executor,
   InboundAuth,
   KVStorage,
@@ -77,10 +76,11 @@ export interface ConnectaDiscoveryConfig {
   staleCatalogSeconds?: number;
   /**
    * Deadline (ms) for each downstream probe/catalog call fanned out by
-   * `list_connectors`, `search_tools`, and `describe_tools`. Defaults to
-   * 30_000. A timed-out connector degrades independently; this does not apply
-   * to tool calls. Catalog walks receive the same cancellation signal, which
-   * aborts an in-flight page where supported and prevents another from starting.
+   * `search_tools` and by `connecta.search`/`connecta.describe` inside
+   * `execute_code`. Defaults to 30_000. A timed-out connector degrades
+   * independently; this does not apply to tool calls. Catalog walks receive the
+   * same cancellation signal, which aborts an in-flight page where supported and
+   * prevents another from starting.
    */
   probeTimeoutMs?: number;
 }
@@ -88,9 +88,9 @@ export interface ConnectaDiscoveryConfig {
 /** Deployment-wide call deadlines and inline-result paging thresholds. */
 export interface ConnectaCallsConfig {
   /**
-   * Deadline (ms) for `call_tool`/`batch_call` calls that pass no `timeoutMs`.
-   * An explicit per-call value wins. Opt-in: unset by default, so existing
-   * long-running calls gain no surprise deadline.
+   * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
+   * `timeoutMs`. An explicit per-call value wins. Opt-in: unset by default, so
+   * existing long-running calls gain no surprise deadline.
    *
    * This bounds one attempt, not all retries. `execute_code` host calls are
    * unaffected because they already carry their own bound.
@@ -102,13 +102,6 @@ export interface ConnectaCallsConfig {
    * 50_000. Connectors may override it individually.
    */
   maxResultBytes?: number;
-  /**
-   * Max serialized `batch_call` envelope size (bytes) before the full batch is
-   * stashed for `get_result` and only an ordered outcome summary is returned
-   * inline. Must be a finite whole number >= 1; invalid values warn and fall
-   * back to 100_000. This cap is independent of per-connector child caps.
-   */
-  maxBatchResultBytes?: number;
 }
 
 /** Budgets for rich output emitted by execute_code programs (`connecta.emit`). */
@@ -197,22 +190,12 @@ export interface ConnectaConfig {
   /** Deployment metadata exposed by /health (for example a Worker version). */
   deploymentInfo?: Record<string, unknown>;
   /**
-   * 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".
+   * Required sandbox for `execute_code`. Workers use
+   * `new DynamicWorkerExecutor({ loader: env.LOADER })` from
+   * `@cloudflare/codemode`; Node uses `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;
+  executor: Executor;
 }
 
 export interface Connecta {
@@ -306,6 +289,20 @@ function assertNoLegacyConfig(config: ConnectaConfig): void {
         "issue #179. Credentials now fail at use; see ethos.md.",
     );
   }
+  const calls = candidate.calls;
+  if (
+    typeof calls === "object" &&
+    calls !== null &&
+    hasOwn(calls, "maxBatchResultBytes")
+  ) {
+    throw new Error(
+      "`calls.maxBatchResultBytes` was removed in issue #273 along with " +
+        "batch_call. Remove it; a program's batching is bounded by " +
+        "execute_code's own limits — connecta.batch's per-run call ceiling " +
+        "and the executor result cap — while each call inside it still honours " +
+        "calls.maxResultBytes and any per-connector override.",
+    );
+  }
   const found: Array<readonly [string, string]> = [];
   if (hasOwn(candidate, "activity")) {
     const activity = candidate.activity;
@@ -444,43 +441,22 @@ 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") {
+export function createConnecta(config: ConnectaConfig): Connecta {
+  assertNoLegacyConfig(config);
+  if (Object.prototype.hasOwnProperty.call(config, "surface")) {
     throw new Error(
-      `ConnectaConfig.surface must be "classic" or "code-first", not ` +
-        `${JSON.stringify(surface)}.`,
+      "ConnectaConfig.surface was removed in issue #273. Remove it; connecta " +
+        "now serves one seven-tool surface.",
     );
   }
-  if (surface === "code-first" && !config.executor) {
+  if (!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).",
+      "ConnectaConfig.executor is required. Configure quickJsExecutor() from " +
+        '"@zackbart/connecta/quickjs" on Node, or ' +
+        "new DynamicWorkerExecutor({ loader: env.LOADER }) from " +
+        '"@cloudflare/codemode" 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);
@@ -524,9 +500,6 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.calls?.maxResultBytes !== undefined
       ? { maxResultBytes: config.calls.maxResultBytes }
       : {}),
-    ...(config.calls?.maxBatchResultBytes !== undefined
-      ? { maxBatchResultBytes: config.calls.maxBatchResultBytes }
-      : {}),
   });
   const inboundAuth = normalizeAuth(
     accessTokens ? [accessTokens.auth, ...configuredAuth] : configuredAuth,
@@ -542,10 +515,10 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   );
   let codeAdmission: AdmissionController | undefined;
   let executor = config.executor;
-  if (executor && !isAdmittingExecutor(executor)) {
+  if (!isAdmittingExecutor(executor)) {
     codeAdmission = configuredCodeAdmission;
     executor = withExecutorAdmission(executor, codeAdmission);
-  } else if (executor && config.admission?.code) {
+  } else if (config.admission?.code) {
     logger.warn(
       "[connecta] admission.code is ignored because the configured executor " +
         "implements acquire() and owns its admission pool; configure that " +
@@ -571,8 +544,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.activity?.deploymentId !== undefined
       ? { activityDeploymentId: config.activity.deploymentId }
       : {}),
-    ...(executor !== undefined ? { executor } : {}),
-    surface,
+    executor,
     requestAdmission,
     ...(config.calls?.defaultTimeoutMs !== undefined
       ? { defaultToolTimeoutMs: config.calls.defaultTimeoutMs }
@@ -653,7 +625,6 @@ export type {
   ConnectorCallAdmissionRule,
   ConnectorRollingWindowBudget,
   ConnectaBranding,
-  ConnectaSurface,
   ConnectorCredentialAccess,
   ConnectorCredentialConfig,
   ConnectorCredentialFieldConfig,

package/src/invocation.ts

@@ -395,8 +395,8 @@ export class InvocationService {
         // A connector whose catalog cannot be fetched is as unusable as one
         // whose execution fails, so it feeds health accounting the same way the
         // attempt catch below does — otherwise a connector every call fails
-        // against (a revoked downstream grant, say) still reads clean from the
-        // cheap `list_connectors({ probe: false })` signal.
+        // against (a revoked downstream grant, say) still reads clean in the
+        // deployment's health log.
         //
         // Recorded HERE rather than inside the registry's catalog fetch because
         // a cache hit that avoids a live listTools call records nothing — it is