@zackbart/connecta 0.10.6 → 0.11.0

package/src/registry.ts

@@ -34,8 +34,6 @@ const DEFAULT_STALE_SECONDS = 3600;
 const CATALOG_CHUNK_TTL_GRACE_SECONDS = 300;
 const DEFAULT_MAX_RESULT_BYTES = 50_000;
 const encoder = new TextEncoder();
-/** Independent final-envelope boundary for `batch_call`. */
-const DEFAULT_MAX_BATCH_RESULT_BYTES = 100_000;
 
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
@@ -189,11 +187,6 @@ export interface RegistryOptions {
    * to the default 50_000.
    */
   maxResultBytes?: number;
-  /**
-   * Cap on the complete serialized batch_call envelope. Must be a whole number
-   * of bytes >= 1; anything else warns and falls back to 100_000.
-   */
-  maxBatchResultBytes?: number;
 }
 
 function namespaced(storage: KVStorage, prefix: string): KVStorage {
@@ -225,8 +218,6 @@ export type ConnectorOperationOptions = Pick<
 export interface RegistryView {
   /** Deployment-wide result-size cap threaded to the meta-tools. */
   readonly maxResultBytes: number;
-  /** Independent cap for the complete serialized batch_call envelope. */
-  readonly maxBatchResultBytes: number;
   listConnectors(): Connector[];
   getConnector(id: string): Connector | undefined;
   resolveAddress(
@@ -302,8 +293,6 @@ export class Registry implements RegistryView {
   private readonly persistToolCatalog: boolean;
   /** Result-size guard cap threaded to the meta-tools. */
   readonly maxResultBytes: number;
-  /** Final batch envelope cap threaded to the meta-tools. */
-  readonly maxBatchResultBytes: number;
 
   constructor(
     connectors: Connector[],
@@ -318,10 +307,6 @@ export class Registry implements RegistryView {
       opts.maxResultBytes,
       DEFAULT_MAX_RESULT_BYTES,
     );
-    this.maxBatchResultBytes = resolveMaxResultBytes(
-      opts.maxBatchResultBytes,
-      DEFAULT_MAX_BATCH_RESULT_BYTES,
-    );
     for (const c of connectors) {
       if (!ID_RE.test(c.id)) {
         throw new Error(
@@ -340,11 +325,7 @@ export class Registry implements RegistryView {
       }
     }
     this.checkConventions(opts.logger);
-    this.checkResultCaps(
-      opts.logger,
-      opts.maxResultBytes,
-      opts.maxBatchResultBytes,
-    );
+    this.checkResultCaps(opts.logger, opts.maxResultBytes);
   }
 
   /**
@@ -358,7 +339,6 @@ export class Registry implements RegistryView {
   private checkResultCaps(
     logger: Logger,
     configured: number | undefined,
-    configuredBatch: number | undefined,
   ): void {
     if (configured !== undefined && !isValidMaxResultBytes(configured)) {
       logger.warn(
@@ -368,17 +348,6 @@ export class Registry implements RegistryView {
           `default ${DEFAULT_MAX_RESULT_BYTES} instead.`,
       );
     }
-    if (
-      configuredBatch !== undefined &&
-      !isValidMaxResultBytes(configuredBatch)
-    ) {
-      logger.warn(
-        `[connecta] calls.maxBatchResultBytes ${configuredBatch} is not a whole ` +
-          `number of bytes >= ${MIN_MAX_RESULT_BYTES}: it would leave the final ` +
-          "batch envelope unbounded or serve an unusable page. Using the " +
-          `default ${DEFAULT_MAX_BATCH_RESULT_BYTES} instead.`,
-      );
-    }
     for (const c of this.connectors.values()) {
       if (
         c.maxResultBytes !== undefined &&
@@ -1059,7 +1028,7 @@ export class Registry implements RegistryView {
     }
   }
 
-  /** Best-effort connector status for list_connectors. */
+  /** Best-effort connector status for the operator UI. */
   async statusFor(
     id: string,
     baseUrl: string,

package/src/routes/mcp.ts

@@ -192,13 +192,9 @@ async function serveMcp(
   registry: RegistryView,
   runtimeContext?: RuntimeExecutionContext,
 ): Promise<Response> {
-  // One deployment-wide value, read once here so the instructions, the
-  // registered tools, and the guidance the `skills` tool serves cannot
-  // disagree about which surface this deployment advertises.
-  const surface = opts.surface ?? "classic";
   const createServer = (): McpServer => {
     const server = new McpServer(opts.serverInfo, {
-      instructions: instructionsFor(surface),
+      instructions: instructionsFor(),
       cacheHints: {
         "tools/list": {
           ttlMs: 3_600_000,
@@ -223,7 +219,6 @@ async function serveMcp(
       : undefined;
     registerMetaTools(server, registry, {
       baseUrl,
-      surface,
       ...(activity ? { activity } : {}),
       ...(opts.defaultToolTimeoutMs !== undefined
         ? { defaultToolTimeoutMs: opts.defaultToolTimeoutMs }
@@ -235,32 +230,26 @@ async function serveMcp(
         ? { discoveryConcurrency: opts.discoveryConcurrency }
         : {}),
       requestSignal: request.signal,
-      ...(runtimeContext
-        ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+    });
+    registerExecuteTool(server, registry, {
+      baseUrl,
+      executor: opts.executor,
+      logger: opts.logger,
+      ...(activity ? { activity } : {}),
+      requestSignal: request.signal,
+      ...(opts.discoveryConcurrency !== undefined
+        ? { discoveryConcurrency: opts.discoveryConcurrency }
+        : {}),
+      ...(opts.probeTimeoutMs !== undefined
+        ? { probeTimeoutMs: opts.probeTimeoutMs }
+        : {}),
+      ...(opts.maxEmittedBytes !== undefined
+        ? { maxEmittedBytes: opts.maxEmittedBytes }
+        : {}),
+      ...(opts.maxEmittedBlocks !== undefined
+        ? { maxEmittedBlocks: opts.maxEmittedBlocks }
         : {}),
     });
-    if (opts.executor) {
-      registerExecuteTool(server, registry, {
-        baseUrl,
-        surface,
-        executor: opts.executor,
-        logger: opts.logger,
-        ...(activity ? { activity } : {}),
-        requestSignal: request.signal,
-        ...(opts.discoveryConcurrency !== undefined
-          ? { discoveryConcurrency: opts.discoveryConcurrency }
-          : {}),
-        ...(opts.probeTimeoutMs !== undefined
-          ? { probeTimeoutMs: opts.probeTimeoutMs }
-          : {}),
-        ...(opts.maxEmittedBytes !== undefined
-          ? { maxEmittedBytes: opts.maxEmittedBytes }
-          : {}),
-        ...(opts.maxEmittedBlocks !== undefined
-          ? { maxEmittedBlocks: opts.maxEmittedBlocks }
-          : {}),
-      });
-    }
     return server;
   };
 

package/src/routes/shared.ts

@@ -7,7 +7,6 @@ import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
 import type {
   ConnectaBranding,
-  ConnectaSurface,
   Executor,
   InboundAuth,
   Logger,
@@ -26,9 +25,9 @@ export interface ServerOptions {
   activityReadGate?: ActivityReadGate;
   activityDeploymentId?: string;
   deploymentInfo?: Record<string, unknown>;
-  /** Deadline for call_tool/batch_call calls that pass no timeoutMs. Off when unset. */
+  /** Deadline for call_tool/call_destructive_tool calls that pass no timeoutMs. Off when unset. */
   defaultToolTimeoutMs?: number;
-  /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+  /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
   probeTimeoutMs?: number;
   /** Maximum simultaneous connector discovery operations. Default 4. */
   discoveryConcurrency?: number;
@@ -36,14 +35,8 @@ export interface ServerOptions {
   maxEmittedBytes?: number;
   /** Block-count budget for connecta.emit per run. Default 32. */
   maxEmittedBlocks?: number;
-  /** When set, the execute_code meta-tool is registered on top of the base surface. */
-  executor?: Executor;
-  /**
-   * The advertised model-facing surface. createConnecta() always resolves it
-   * from the executor; absent (a direct createFetchHandler() caller) is
-   * classic, and `code-first` is only ever set alongside an `executor`.
-   */
-  surface?: ConnectaSurface;
+  /** Required sandbox backing the execute_code meta-tool. */
+  executor: Executor;
   /** Global FIFO boundary for all non-preflight `/mcp` requests. */
   requestAdmission: AdmissionController;
   /** Encrypted connector-credential storage backing the Credentials page. */

package/src/server.ts

@@ -122,10 +122,12 @@ export function createFetchHandler(
       }
 
       if (path === "/health") {
-        const codeAdmission =
-          opts.executor && isAdmittingExecutor(opts.executor)
-            ? opts.executor.admissionSnapshot?.()
-            : undefined;
+        // The executor is required, so code admission always has a shape to
+        // report: either the executor's own pool or the fallback controller
+        // wrapped around it at construction.
+        const codeAdmission = isAdmittingExecutor(opts.executor)
+          ? opts.executor.admissionSnapshot?.()
+          : undefined;
         return Response.json({
           status: "ok",
           connectors: registry.listConnectors().length,
@@ -133,9 +135,7 @@ export function createFetchHandler(
           admission: {
             policy: "global-fifo",
             requests: opts.requestAdmission.snapshot(),
-            code: opts.executor
-              ? (codeAdmission ?? { managedByExecutor: true })
-              : null,
+            code: codeAdmission ?? { managedByExecutor: true },
             downstreamCalls: {
               policy: "connector-partitioned-per-runtime",
               connectors: registry.callAdmissionSnapshot(),

package/src/skills.ts

@@ -1,47 +1,10 @@
-import type { Connector, ConnectaSurface } from "./types.js";
+import type { Connector } from "./types.js";
 
 export const CONNECTA_INSTRUCTIONS =
-  'Connecta exposes integrations behind meta-tools. Unknown address: use search_tools with 2–4 distinctive action/object terms, no initial limit, and includeSchemas="compact"; describe_tools only if that shape is ambiguous or exact JSON constraints are needed. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent read-only calls, and execute_code (when available) only for dependencies, loops, joins, or substantial reduction — searching inside that one run rather than searching first. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools. authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
-
-/**
- * The instructions a code-first deployment loads (#224). It never names
- * `list_connectors`, `describe_tools`, or `batch_call` — not even to say they
- * are gone. Always-loaded text describes the surface that exists; a sentence
- * about three tools this deployment does not have is context paid for the past,
- * and a model that names one anyway gets an unknown-tool error, which is a
- * cheaper correction than the tokens the disclaimer costs every request.
- */
-export const CODE_FIRST_INSTRUCTIONS =
   'Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
 
 export const USAGE_SKILL = `# Connecta usage
 
-## Choose the smallest execution tool
-
-Use exact addresses returned by discovery; never invent one. Search with 2–4 distinctive action/object terms rather than the full request, and omit \`limit\` initially so the default page stays small.
-
-- Unknown address: \`search_tools({ query, includeSchemas: "compact" })\`; every match then includes its input shape plus any declared output shape and annotations.
-- Compact shape still ambiguous: \`describe_tools({ addresses: [...] })\`; use \`format: "json"\` only for exact constraints.
-- One explicitly read-only call: \`call_tool\`.
-- Two to ten independent explicitly read-only calls: \`batch_call\`.
-- Dependent read-only calls, loops, joins, branching, or large-result reduction: \`execute_code\` when available.
-- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, individually and only after reviewing its schema and consequences.
-- Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
-- \`auth_required\`: use \`authorize_connector\`, give its recovery handoff to the operator, then retry the original call.
-
-Use \`list_connectors({ probe: false })\` for a fast observed-health inventory; use \`probe: true\` only to diagnose live health or authorization.
-
-## Code mode
-
-Unknown addresses plus dependent calls: search inside the run, not in an outer \`search_tools\`. Parallelize independent calls with \`Promise.all\` or \`connecta.batch\`.
-
-Connector namespace calls and \`connecta.call\` use the same read-only gate and throw on downstream errors. Catch only failures the workflow can handle; let authorization failures return to the agent for recovery.
-
-Skip code mode for one call, calls suited to \`batch_call\`, or tools lacking \`readOnlyHint: true\`. Return only the needed reduction.
-`;
-
-export const CODE_FIRST_USAGE_SKILL = `# Connecta usage
-
 ## The surface
 
 Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live inside a program rather than in top-level tools.
@@ -76,21 +39,12 @@ One async arrow function. The only capabilities are one global per connector (\`
 export const CONNECTOR_GUIDES_SECTION = `
 ## Per-connector guides
 
-Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\` and \`describe_tools\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
-`;
-
-/** The same section, naming only surfaces a code-first deployment has. */
-const CODE_FIRST_CONNECTOR_GUIDES_SECTION = `
-## Per-connector guides
-
 Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\`, \`connecta.search\`, and \`connecta.describe\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
 `;
 
-/** The always-loaded MCP `instructions` string for `surface`. */
-export function instructionsFor(surface: ConnectaSurface): string {
-  return surface === "code-first"
-    ? CODE_FIRST_INSTRUCTIONS
-    : CONNECTA_INSTRUCTIONS;
+/** The always-loaded MCP `instructions` string. */
+export function instructionsFor(): string {
+  return CONNECTA_INSTRUCTIONS;
 }
 
 /** True when at least one of `connectors` carries a usage guide. */
@@ -101,27 +55,15 @@ export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
 }
 
 /** The built-in usage guide, plus the guides section when there is one to point at. */
-function usageSkill(
-  connectors: readonly Connector[],
-  surface: ConnectaSurface,
-): string {
-  const base =
-    surface === "code-first" ? CODE_FIRST_USAGE_SKILL : USAGE_SKILL;
-  if (!hasConnectorGuides(connectors)) return base;
-  return (
-    base +
-    (surface === "code-first"
-      ? CODE_FIRST_CONNECTOR_GUIDES_SECTION
-      : CONNECTOR_GUIDES_SECTION)
-  );
+function usageSkill(connectors: readonly Connector[]): string {
+  if (!hasConnectorGuides(connectors)) return USAGE_SKILL;
+  return USAGE_SKILL + CONNECTOR_GUIDES_SECTION;
 }
 
 const AVAILABLE_SKILLS = [
   {
     name: "usage",
     description:
-      "How to choose among Connecta discovery, direct, batch, destructive, and code-mode tools.",
-    codeFirstDescription:
       "How to route work between one execute_code program and Connecta's explicit call, authorization, and result tools.",
     content: usageSkill,
   },
@@ -212,14 +154,10 @@ export interface SkillListing {
  * carries a usage guide. Derived from the connector list passed in — the single
  * place guide visibility is decided.
  */
-export function listSkills(
-  connectors: readonly Connector[],
-  surface: ConnectaSurface = "classic",
-): SkillListing[] {
+export function listSkills(connectors: readonly Connector[]): SkillListing[] {
   const listing: SkillListing[] = AVAILABLE_SKILLS.map((skill) => ({
     name: skill.name,
-    description:
-      surface === "code-first" ? skill.codeFirstDescription : skill.description,
+    description: skill.description,
   }));
   for (const connector of connectors) {
     const guide = connectorGuide(connector);
@@ -244,14 +182,13 @@ export type SkillLookup =
 export function resolveSkill(
   name: string,
   connectors: readonly Connector[],
-  surface: ConnectaSurface = "classic",
 ): SkillLookup {
   const builtIn = AVAILABLE_SKILLS.find((skill) => skill.name === name);
   if (builtIn) {
-    return { found: true, content: builtIn.content(connectors, surface) };
+    return { found: true, content: builtIn.content(connectors) };
   }
   const available = () =>
-    listSkills(connectors, surface)
+    listSkills(connectors)
       .map((skill) => skill.name)
       .join(", ");
   if (name.startsWith(CONNECTOR_SKILL_PREFIX)) {

package/src/types.ts

@@ -35,8 +35,8 @@ export interface ToolDef {
   /**
    * Standard MCP tool behavior hints plus provider-specific extensions.
    * Connecta fails closed: only readOnlyHint === true (without a contradictory
-   * destructiveHint) may use call_tool, batch_call, or execute_code. Every
-   * other tool must cross the call_destructive_tool approval boundary.
+   * destructiveHint) may use call_tool or execute_code. Every other tool must
+   * cross the call_destructive_tool approval boundary.
    */
   annotations?: ToolAnnotations;
 }
@@ -198,7 +198,7 @@ export interface Connector {
   description?: string;
   /**
    * Max inline result size (bytes) for this connector's tools before
-   * call_tool/batch_call truncate and stash the full text for get_result
+   * call_tool truncates and stashes the full text for get_result
    * paging. Overrides `ConnectaConfig.calls.maxResultBytes`;
    * omit to inherit it (which itself defaults to 50_000). Must be a whole
    * number of bytes >= 1; anything else warns at startup and is ignored, so
@@ -207,8 +207,8 @@ export interface Connector {
   maxResultBytes?: number;
   /**
    * Optional per-runtime admission policy for downstream tool calls. It covers
-   * call_tool, every batch_call child, and execute_code host calls, but not
-   * catalog/status/auth operations.
+   * call_tool, call_destructive_tool, and every execute_code host call, but
+   * not catalog/status/auth operations.
    */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
@@ -255,7 +255,7 @@ export interface Connector {
    * request-local reuse remains in force until the request boundary.
    */
   closeScope?(ctx: ConnectorContext): Promise<void>;
-  /** Optional connector-level health/auth status for list_connectors. */
+  /** Optional connector-level health/auth status for the operator UI. */
   status?(ctx: ConnectorContext): Promise<ConnectorStatus>;
   /**
    * Optional: start (or with force, restart from scratch) a downstream OAuth
@@ -309,21 +309,6 @@ export interface Connector {
   ): Promise<Response | null>;
 }
 
-/**
- * Which model-facing surface a deployment advertises. The `executor` decides
- * it; this type is how a deployment overrides that.
- *
- * - `code-first`: seven tools, the default wherever an executor is configured.
- *   `list_connectors`, `describe_tools`, and `batch_call` are not top-level
- *   tools; their behavior lives in `connecta.search`, `connecta.describe`, and
- *   `connecta.batch` inside a program.
- * - `classic`: the nine base meta-tools, plus `execute_code` when an executor
- *   is configured. Without an executor it is what a deployment necessarily
- *   serves and the eval gate's control arm; with one it is the ten-tool shape
- *   the gate's incremental arm measures, and the only thing `surface` is for.
- */
-export type ConnectaSurface = "classic" | "code-first";
-
 /** Result of one sandboxed code execution. */
 export interface ExecuteResult {
   result: unknown;

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.10.6";
+export const CONNECTA_VERSION = "0.11.0";

package/templates/node/README.md

@@ -13,7 +13,8 @@ Then point an MCP client at `http://localhost:8787/mcp` with
 ## Deployment contract
 
 - Edit `src/index.ts` for connectors, auth, storage, and the public URL.
-- Keep `executor: quickJsExecutor()` for the seven-tool code-first surface.
+- Keep the required `executor: quickJsExecutor()` configuration; a deployment
+  without an executor refuses to boot.
 - Keep secrets in environment variables or an external secret store.
 - Add application code only inside deliberate `api()` connector handlers.
 - Do not copy Connecta package internals into this deployment.

package/templates/node/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.10.6",
+    "@zackbart/connecta": "0.11.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/index.ts

@@ -21,7 +21,7 @@ const connecta = createConnecta({
   storage: fileStorage("./.connecta-state.json"),
   auth: bearerToken(token, { subjectId: "operator" }),
   publicUrl: `http://localhost:${port}`,
-  // Keep this for the prescribed seven-tool code-first surface.
+  // Required: model-written programs run in a bounded QuickJS child.
   executor: quickJsExecutor(),
   connectors: [
     api("time", {