@zackbart/connecta 0.9.1 → 0.10.0

package/src/meta-tools.ts

@@ -49,7 +49,11 @@ import {
   normalizeTimeoutMs,
   withAbortableTimeout,
 } from "./timeout.js";
-import type { ConnectorStatus, KVStorage } from "./types.js";
+import type {
+  ConnectaSurface,
+  ConnectorStatus,
+  KVStorage,
+} from "./types.js";
 
 export {
   MAX_DESCRIBE_ADDRESSES,
@@ -473,10 +477,12 @@ export interface SkillArgs {
 }
 
 /**
- * The nine meta-tool handlers over a registry. Exported for direct testing;
- * registerMetaTools() wires them onto an McpServer. `opts.defaultToolTimeoutMs`
- * supplies a deadline for calls that don't carry one. (execute_code, the
- * optional tenth tool, is registered separately by registerExecuteTool.)
+ * Every base meta-tool handler over a registry — all nine, whichever surface is
+ * advertised, since folding a tool away only skips its registration and never
+ * its handler. Exported for direct testing; registerMetaTools() wires the ones
+ * this surface advertises onto an McpServer. `opts.defaultToolTimeoutMs`
+ * supplies a deadline for calls that don't carry one. (execute_code is
+ * registered separately by registerExecuteTool.)
  *
  * Deployment-wide result-size caps are read off the registry view rather than
  * passed in: `ConnectaConfig.calls.maxResultBytes`, its per-connector override,
@@ -498,8 +504,15 @@ export function createMetaTools(
     requestSignal?: AbortSignal;
     /** Runtime continuation for the bounded tail of probe-owned teardown. */
     defer?: DeferredWork;
+    /**
+     * The advertised surface, which the `skills` guidance must match: a
+     * code-first deployment never gets guidance naming a tool it does not
+     * advertise. Default `classic`.
+     */
+    surface?: ConnectaSurface;
   } = {},
 ) {
+  const surface: ConnectaSurface = opts.surface ?? "classic";
   // Already normalized and warned about at registry construction.
   const globalCap = registry.maxResultBytes;
   const batchCap = registry.maxBatchResultBytes;
@@ -666,14 +679,14 @@ export function createMetaTools(
               type: "text",
               text:
                 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
-                listSkills(connectors)
+                listSkills(connectors, surface)
                   .map((skill) => `- \`${skill.name}\` — ${skill.description}`)
                   .join("\n"),
             },
           ],
         };
       }
-      const skill = resolveSkill(args.name, connectors);
+      const skill = resolveSkill(args.name, connectors, surface);
       if (!skill.found) return errorResult(skill.message);
       return { content: [{ type: "text", text: skill.content }] };
     },
@@ -1133,6 +1146,23 @@ const AUTHORIZE_DESC =
 const SKILLS_DESC =
   'List or fetch concise guidance for choosing among Connecta meta-tools. Call skills({ name: "usage" }) once when the routing workflow is unfamiliar; do not refetch it in the same task.';
 
+/**
+ * Code-first replacements for the descriptions that route work between tools.
+ * Every one of these mentions a tool the consolidated surface removed, so on a
+ * code-first deployment the routing sentence has to point at the in-program
+ * function that took the work over — a description naming `batch_call` on a
+ * surface without one teaches a call that cannot succeed.
+ *
+ * The classic strings above are left byte-for-byte alone: classic is the
+ * compatibility surface and the eval's control arm, and rewording it would
+ * change what that control measures.
+ */
+const CODE_FIRST_SEARCH_DESC = `${SEARCH_DESC} Expand an ambiguous compact shape, or read exact JSON constraints, with connecta.describe inside execute_code.`;
+const CODE_FIRST_CALL_DESC =
+  'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths, resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
+const CODE_FIRST_GET_RESULT_DESC =
+  "Page a truncated result stashed by call_tool or call_destructive_tool; a program's oversized return is not paged, so reduce it in code instead. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. Unknown/expired id is an error.";
+
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,
@@ -1191,7 +1221,17 @@ const CALL_INPUT_SCHEMA = {
   diagnostics: z.boolean().optional(),
 };
 
-/** Register the nine meta-tools onto an McpServer instance. */
+/**
+ * Register the base meta-tools onto an McpServer instance: nine on the classic
+ * surface, six on the code-first one, where `list_connectors`,
+ * `describe_tools`, and `batch_call` have folded into the program surface
+ * (`registerExecuteTool` adds the seventh, `execute_code`).
+ *
+ * Only the registrations differ. Every handler still exists on the object
+ * `createMetaTools` returns, and a folded tool's behavior is reached through
+ * `connecta.search` / `connecta.describe` / `connecta.batch` inside a program —
+ * the same code paths, one layer down.
+ */
 export function registerMetaTools(
   server: McpServer,
   registry: RegistryView,
@@ -1203,9 +1243,14 @@ export function registerMetaTools(
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
     defer?: DeferredWork;
+    /** The advertised surface. Default `classic`. */
+    surface?: ConnectaSurface;
   },
 ): void {
+  const surface: ConnectaSurface = ctx.surface ?? "classic";
+  const codeFirst = surface === "code-first";
   const mt = createMetaTools(registry, ctx.baseUrl, {
+    surface,
     ...(ctx.defaultToolTimeoutMs !== undefined
       ? { defaultToolTimeoutMs: ctx.defaultToolTimeoutMs }
       : {}),
@@ -1232,20 +1277,30 @@ export function registerMetaTools(
     async (args) => mt.skills(args as SkillArgs),
   );
 
-  server.registerTool(
-    "list_connectors",
-    {
-      description: LIST_DESC,
-      inputSchema: z.object({ probe: z.boolean().optional() }),
-      annotations: READ_ONLY_REMOTE,
-    },
-    async (args) => mt.listConnectors(args as ListArgs),
-  );
+  // Folded on the code-first surface: a program browses the same inventory with
+  // connecta.search({}) (every catalog) or connecta.search({ connector }) (one).
+  // Live connector probing is an operator concern, not a model one — it stays on
+  // the operator pages and /health, which is where the ethos puts observability.
+  if (!codeFirst) {
+    server.registerTool(
+      "list_connectors",
+      {
+        description: LIST_DESC,
+        inputSchema: z.object({ probe: z.boolean().optional() }),
+        annotations: READ_ONLY_REMOTE,
+      },
+      async (args) => mt.listConnectors(args as ListArgs),
+    );
+  }
 
   server.registerTool(
     "search_tools",
     {
-      description: describedFor(registry, SEARCH_DESC, "search"),
+      description: describedFor(
+        registry,
+        codeFirst ? CODE_FIRST_SEARCH_DESC : SEARCH_DESC,
+        "search",
+      ),
       inputSchema: z.object({
         query: z.string().optional(),
         connector: z.string().optional(),
@@ -1259,24 +1314,28 @@ export function registerMetaTools(
     async (args) => mt.searchTools(args as SearchArgs),
   );
 
-  server.registerTool(
-    "describe_tools",
-    {
-      description: describedFor(registry, DESCRIBE_DESC, "describe"),
-      inputSchema: z.object({
-        addresses: z.array(z.string()).max(MAX_DESCRIBE_ADDRESSES),
-        format: z.enum(["compact", "json"]).optional(),
-        fullDescriptions: z.boolean().optional(),
-      }),
-      annotations: READ_ONLY_REMOTE,
-    },
-    async (args) => mt.describeTools(args as DescribeArgs),
-  );
+  // Folded on the code-first surface: connecta.describe takes the same
+  // addresses, format, and per-address error reporting inside a program.
+  if (!codeFirst) {
+    server.registerTool(
+      "describe_tools",
+      {
+        description: describedFor(registry, DESCRIBE_DESC, "describe"),
+        inputSchema: z.object({
+          addresses: z.array(z.string()).max(MAX_DESCRIBE_ADDRESSES),
+          format: z.enum(["compact", "json"]).optional(),
+          fullDescriptions: z.boolean().optional(),
+        }),
+        annotations: READ_ONLY_REMOTE,
+      },
+      async (args) => mt.describeTools(args as DescribeArgs),
+    );
+  }
 
   server.registerTool(
     "call_tool",
     {
-      description: CALL_DESC,
+      description: codeFirst ? CODE_FIRST_CALL_DESC : CALL_DESC,
       inputSchema: z.object(CALL_INPUT_SCHEMA),
       // call_tool admits only tools that are themselves explicitly read-only;
       // anything else is refused and routed to call_destructive_tool.
@@ -1321,7 +1380,7 @@ export function registerMetaTools(
   server.registerTool(
     "get_result",
     {
-      description: GET_RESULT_DESC,
+      description: codeFirst ? CODE_FIRST_GET_RESULT_DESC : GET_RESULT_DESC,
       inputSchema: z.object({
         id: z.string(),
         // Both bounds are the shared rules (isValidResultOffset,
@@ -1336,24 +1395,28 @@ export function registerMetaTools(
     async (args) => mt.getResult(args as GetResultArgs),
   );
 
-  server.registerTool(
-    "batch_call",
-    {
-      description: BATCH_DESC,
-      inputSchema: z.object({
-        calls: z
-          .array(z.object(CALL_INPUT_SCHEMA))
-          .min(1)
-          .max(10),
-        resultMode: z.enum(["mcp", "value"]).optional(),
-        timeoutMs: z.number().int().positive().optional(),
-        maxRetries: z.number().int().min(0).max(2).optional(),
-        diagnostics: z.boolean().optional(),
-      }),
-      // Same gate as call_tool: every call in the batch must be explicitly
-      // read-only or the batch is refused.
-      annotations: READ_ONLY_REMOTE,
-    },
-    async (args) => mt.batchCall(args as BatchArgs),
-  );
+  // Folded on the code-first surface: connecta.batch runs the same 1–10
+  // parallel read-only calls and returns the same typed per-call outcomes.
+  if (!codeFirst) {
+    server.registerTool(
+      "batch_call",
+      {
+        description: BATCH_DESC,
+        inputSchema: z.object({
+          calls: z
+            .array(z.object(CALL_INPUT_SCHEMA))
+            .min(1)
+            .max(10),
+          resultMode: z.enum(["mcp", "value"]).optional(),
+          timeoutMs: z.number().int().positive().optional(),
+          maxRetries: z.number().int().min(0).max(2).optional(),
+          diagnostics: z.boolean().optional(),
+        }),
+        // Same gate as call_tool: every call in the batch must be explicitly
+        // read-only or the batch is refused.
+        annotations: READ_ONLY_REMOTE,
+      },
+      async (args) => mt.batchCall(args as BatchArgs),
+    );
+  }
 }

package/src/routes/mcp.ts

@@ -12,7 +12,7 @@ import {
 } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
 import type { RegistryView } from "../registry.js";
-import { CONNECTA_INSTRUCTIONS } from "../skills.js";
+import { instructionsFor } from "../skills.js";
 import type { Logger } from "../types.js";
 import {
   authorize,
@@ -192,9 +192,13 @@ 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: CONNECTA_INSTRUCTIONS,
+      instructions: instructionsFor(surface),
       cacheHints: {
         "tools/list": {
           ttlMs: 3_600_000,
@@ -219,6 +223,7 @@ async function serveMcp(
       : undefined;
     registerMetaTools(server, registry, {
       baseUrl,
+      surface,
       ...(activity ? { activity } : {}),
       ...(opts.defaultToolTimeoutMs !== undefined
         ? { defaultToolTimeoutMs: opts.defaultToolTimeoutMs }
@@ -237,6 +242,7 @@ async function serveMcp(
     if (opts.executor) {
       registerExecuteTool(server, registry, {
         baseUrl,
+        surface,
         executor: opts.executor,
         logger: opts.logger,
         ...(activity ? { activity } : {}),

package/src/routes/shared.ts

@@ -6,6 +6,7 @@ import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
 import type {
   ConnectaBranding,
+  ConnectaSurface,
   Executor,
   InboundAuth,
   Logger,
@@ -30,8 +31,14 @@ export interface ServerOptions {
   probeTimeoutMs?: number;
   /** Maximum simultaneous connector discovery operations. Default 4. */
   discoveryConcurrency?: number;
-  /** When set, the execute_code meta-tool is registered on top of the nine. */
+  /** 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;
   /** Global FIFO boundary for all non-preflight `/mcp` requests. */
   requestAdmission: AdmissionController;
   /** Encrypted connector-credential storage backing the Credentials page. */

package/src/skills.ts

@@ -1,8 +1,19 @@
-import type { Connector } from "./types.js";
+import type { Connector, ConnectaSurface } 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
@@ -29,6 +40,33 @@ Connector namespace calls and \`connecta.call\` use the same read-only gate and
 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.
+
+## 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.
+
+- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once. A lone cold call is cheaper direct than through a program.
+- Anything wider — two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one \`execute_code\` run.
+- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, individually and only after reviewing its schema and consequences. Generated code cannot make one.
+- 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.
+
+## Inside a program
+
+One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the four \`connecta\` functions, and \`console.log\`.
+
+- What exists: \`connecta.search({})\` browses every catalog and \`connecta.search({ connector: "<id>" })\` browses one — that inventory is what a program discovers with, and each match carries its \`address\` and annotations.
+- Exact schemas for known addresses: \`connecta.describe({ addresses: [...] })\`; \`format: "json"\` only for exact constraints.
+- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\`, which is also how a program tells a policy refusal from a transient failure.
+- Search inside the run rather than searching first, and return only the reduction the answer needs — never raw payloads.
+- Only tools annotated \`readOnlyHint: true\` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.
+`;
+
 /**
  * Appended to USAGE_SKILL only when the deployment actually has at least one
  * connector guide. A deployment with none — every deployment that has not
@@ -41,6 +79,20 @@ export const CONNECTOR_GUIDES_SECTION = `
 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;
+}
+
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
   return connectors.some(
@@ -49,10 +101,19 @@ 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[]): string {
-  return hasConnectorGuides(connectors)
-    ? USAGE_SKILL + CONNECTOR_GUIDES_SECTION
-    : USAGE_SKILL;
+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)
+  );
 }
 
 const AVAILABLE_SKILLS = [
@@ -60,6 +121,8 @@ 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,
   },
 ] as const;
@@ -149,10 +212,14 @@ 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[]): SkillListing[] {
+export function listSkills(
+  connectors: readonly Connector[],
+  surface: ConnectaSurface = "classic",
+): SkillListing[] {
   const listing: SkillListing[] = AVAILABLE_SKILLS.map((skill) => ({
     name: skill.name,
-    description: skill.description,
+    description:
+      surface === "code-first" ? skill.codeFirstDescription : skill.description,
   }));
   for (const connector of connectors) {
     const guide = connectorGuide(connector);
@@ -177,11 +244,14 @@ 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) };
+  if (builtIn) {
+    return { found: true, content: builtIn.content(connectors, surface) };
+  }
   const available = () =>
-    listSkills(connectors)
+    listSkills(connectors, surface)
       .map((skill) => skill.name)
       .join(", ");
   if (name.startsWith(CONNECTOR_SKILL_PREFIX)) {

package/src/types.ts

@@ -304,6 +304,21 @@ 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.9.1";
+export const CONNECTA_VERSION = "0.10.0";