@zackbart/connecta 0.7.8 → 0.8.0

package/src/execute.ts

@@ -1,39 +1,38 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
-import { recordToolActivity, type ActivityRequestContext } from "./activity.js";
+import type { ActivityRequestContext } from "./activity.js";
 import {
   assertDiscoveryResultSize,
-  discoveryAddresses,
-  discoverySearchLimit,
-  errorResult,
-  jsonResult,
-  type ToolResult,
-} from "./meta-tools.js";
+  CatalogService,
+  flatSearchResult,
+} from "./catalog-service.js";
+import { errorResult, jsonResult, type ToolResult } from "./meta-tools.js";
 import {
   guardExecuteResultValue,
   MAX_EXECUTE_LOG_CHARS,
   truncateExecuteText,
 } from "./executor-result.js";
-import { classifyCallError, ConnectorCallError } from "./errors.js";
 import {
   ExecutorAdmissionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
 import { unwrapMcpResult } from "./mcp-result.js";
+import {
+  InvocationFailure,
+  InvocationService,
+} from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type {
   Connector,
   Executor,
   ExecutorProvider,
   Logger,
-  ToolDef,
 } from "./types.js";
 
 /** Keep one model-written program from amplifying into an unbounded fan-out. */
-export const EXECUTE_MAX_HOST_CALLS = 20;
+const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
-export const EXECUTE_HOST_CALL_TIMEOUT_MS = 15_000;
+const EXECUTE_HOST_CALL_TIMEOUT_MS = 15_000;
 
 // deno-fmt-ignore
 const RESERVED = new Set([
@@ -88,10 +87,56 @@ export function sanitizeIdentifier(name: string): string {
   return id;
 }
 
+const SANDBOX_RESERVED_NAMES = new Set([
+  "connecta",
+  "console",
+  "arguments",
+  "result",
+  "undefined",
+  "setTimeout",
+  "Promise",
+  "Error",
+  "WorkerEntrypoint",
+  "CodeExecutor",
+  "__invoke",
+  "__namespace",
+  "__call",
+  "__log",
+  "__dispatchers",
+  "__connectors",
+  "__logs",
+  "__CODEMODE_BINARY_TAG",
+  "__bytesToBase64",
+  "__base64ToBytes",
+  "__encodeCodemodeValue",
+  "__decodeCodemodeValue",
+  "__stringifyForCodemode",
+  "__parseForCodemode",
+]);
+
 function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function lazyNamespacePrelude(
+  connectors: Array<{ id: string; namespace: string }>,
+): string {
+  const declarations = connectors
+    .map(
+      ({ id, namespace }) =>
+        `globalThis[${JSON.stringify(namespace)}] = __makeConnectaNamespace(${JSON.stringify(id)});`,
+    )
+    .join("\n");
+  return `(() => {
+  const __makeConnectaNamespace = (connectorId) => Object.freeze(new Proxy(Object.create(null), {
+    get: (_target, toolName) => typeof toolName === "string"
+      ? (args) => connecta.__callNamespace(connectorId, toolName, args)
+      : undefined
+  }));
+${declarations}
+})();`;
+}
+
 /**
  * Unwrap an MCP CallToolResult so sandbox code sees plain values:
  * isError throws (a real exception the code can catch), structuredContent
@@ -106,9 +151,9 @@ export function unwrapForSandbox(
 }
 
 /**
- * Expose the registry to a sandbox: one provider (global namespace) per
- * connector with a function per tool, plus `connecta.call(address, args)` as
- * the raw-address escape hatch. Broken connectors are skipped, not fatal.
+ * Expose one fixed host provider plus trusted sandbox setup that creates a
+ * lazy proxy global per connector. No connector catalog is touched until code
+ * calls that namespace or explicitly asks search/describe.
  */
 export async function buildSandboxProviders(
   registry: RegistryView,
@@ -119,12 +164,19 @@ export async function buildSandboxProviders(
     signal?: AbortSignal;
     maxHostCalls?: number;
     hostCallTimeoutMs?: number;
+    discoveryConcurrency?: number;
   } = {},
 ): Promise<ExecutorProvider[]> {
-  const providers: ExecutorProvider[] = [];
   // All host calls made by one execute_code invocation share a downstream
   // connection, while a later invocation receives a fresh request scope.
   const requestScope = {};
+  const catalog = new CatalogService(registry, baseUrl, {
+    requestScope,
+    ...(limits.discoveryConcurrency !== undefined
+      ? { concurrency: limits.discoveryConcurrency }
+      : {}),
+  });
+  const invocation = new InvocationService(registry, catalog, activity);
   const maxHostCalls = Math.max(
     1,
     Math.trunc(limits.maxHostCalls ?? EXECUTE_MAX_HOST_CALLS),
@@ -134,374 +186,129 @@ export async function buildSandboxProviders(
     Math.trunc(limits.hostCallTimeoutMs ?? EXECUTE_HOST_CALL_TIMEOUT_MS),
   );
   let hostCalls = 0;
-  // Reserve the `connecta` namespace plus every global the sandbox bridge
-  // installs (see setupScript/installBridge in quickjs.ts) — a connector id
-  // sanitizing to one of these would clobber log capture or the call bridge.
-  const used = new Set<string>([
-    "connecta",
-    "console",
-    "__invoke",
-    "__namespace",
-    "__call",
-    "__log",
-  ]);
   const connectors = registry.listConnectors();
-  const catalogStarted = Date.now();
-  const loaded = await Promise.allSettled(
-    connectors.map((connector) =>
-      registry.getTools(connector.id, baseUrl, requestScope, {
-        signal: limits.signal,
-      }),
-    ),
-  );
-  if (limits.signal?.aborted) {
-    throw new ExecutorAdmissionError(
-      "executor_cancelled",
-      "Execution was cancelled during catalog construction.",
-    );
+  const namespaces: Array<{ id: string; namespace: string }> = [];
+  const namespaceOwners = new Map<string, string>();
+  for (const connector of connectors) {
+    const namespace = sanitizeIdentifier(connector.id);
+    const owner = namespaceOwners.get(namespace);
+    const problem = SANDBOX_RESERVED_NAMES.has(namespace)
+      ? `Connector "${connector.id}" sanitizes to reserved execute_code namespace "${namespace}". Rename or exclude the connector before using execute_code.`
+      : owner
+        ? `Connector ids "${owner}" and "${connector.id}" both sanitize to execute_code namespace "${namespace}". Rename or exclude one connector before using execute_code.`
+        : undefined;
+    if (problem) {
+      logger.warn(`[connecta] execute_code: ${problem}`);
+      throw new Error(problem);
+    }
+    namespaceOwners.set(namespace, connector.id);
+    namespaces.push({ id: connector.id, namespace });
   }
-  const catalogs = new Map<string, ToolDef[]>();
+
+  const invocationContext = () => ({
+    source: "execute_code" as const,
+    timeoutMs: hostCallTimeoutMs,
+    ...(limits.signal !== undefined ? { requestSignal: limits.signal } : {}),
+    unwrapResult: true,
+    beforeDispatch: () => {
+      hostCalls++;
+      if (hostCalls > maxHostCalls) {
+        throw new Error(
+          `execute_code host-call budget exceeded (${maxHostCalls} calls maximum)`,
+        );
+      }
+    },
+  });
   const callAddress = async (address: unknown, args: unknown) => {
-    const resolved = registry.resolveAddress(String(address));
-    if (!resolved) throw new Error(`Unknown address "${String(address)}"`);
-    const definition = catalogs
-      .get(resolved.connector.id)
-      ?.find((tool) => tool.name === resolved.toolName);
-    if (!definition) {
-      throw new Error(
-        `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
-      );
-    }
-    if (
-      definition.annotations?.readOnlyHint !== true ||
-      definition.annotations?.destructiveHint === true
-    ) {
-      throw new Error(
-        `Tool "${String(address)}" is not explicitly read-only and cannot run inside execute_code. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`,
-      );
-    }
-    hostCalls++;
-    if (hostCalls > maxHostCalls) {
-      throw new Error(
-        `execute_code host-call budget exceeded (${maxHostCalls} calls maximum)`,
-      );
-    }
-    if (limits.signal?.aborted) {
-      throw new Error("execute_code host call cancelled");
-    }
-    const controller = new AbortController();
-    const cancel = () => controller.abort(limits.signal?.reason);
-    limits.signal?.addEventListener("abort", cancel, { once: true });
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let rejectCancelled!: (reason: Error) => void;
-    const cancelled = new Promise<never>((_, reject) => {
-      rejectCancelled = reject;
-    });
-    const onAbort = () => {
-      rejectCancelled(
-        controller.signal.reason instanceof Error
-          ? controller.signal.reason
-          : new Error("execute_code host call cancelled"),
-      );
-    };
-    controller.signal.addEventListener("abort", onAbort, { once: true });
-    const ctx = registry.contextFor(
-      resolved.connector.id,
-      baseUrl,
-      requestScope,
-      { signal: controller.signal, timeoutMs: hostCallTimeoutMs },
+    const outcome = await invocation.invoke(
+      String(address),
+      args ?? {},
+      invocationContext(),
     );
-    const started = Date.now();
-    try {
-      timer = setTimeout(() => {
-        controller.abort(
-          new ConnectorCallError(
-            "timeout",
-            `Tool call timed out after ${hostCallTimeoutMs}ms`,
-          ),
-        );
-      }, hostCallTimeoutMs);
-      const pending = resolved.connector.callTool(
-        resolved.toolName,
-        args ?? {},
-        ctx,
-      );
-      const value = unwrapForSandbox(
-        resolved.connector.kind,
-        await Promise.race([pending, cancelled]),
-      );
-      registry.recordSuccess(resolved.connector.id, Date.now() - started);
-      recordToolActivity(activity, {
-        connectorId: resolved.connector.id,
-        toolName: resolved.toolName,
-        address: `${resolved.connector.id}.${resolved.toolName}`,
-        source: "execute_code",
-        outcome: "success",
-        durationMs: Date.now() - started,
-        attempts: 1,
-      });
-      return value;
-    } catch (err) {
-      registry.recordFailure(resolved.connector.id, Date.now() - started, err);
-      const details = classifyCallError(err);
-      recordToolActivity(activity, {
-        connectorId: resolved.connector.id,
-        toolName: resolved.toolName,
-        address: `${resolved.connector.id}.${resolved.toolName}`,
-        source: "execute_code",
-        outcome: details.code === "timeout" ? "timeout" : "error",
-        durationMs: Date.now() - started,
-        attempts: 1,
-        errorCode: details.code,
-      });
-      throw err;
-    } finally {
-      if (timer) clearTimeout(timer);
-      controller.signal.removeEventListener("abort", onAbort);
-      limits.signal?.removeEventListener("abort", cancel);
-    }
+    if (!outcome.ok) throw new InvocationFailure(outcome.error);
+    return outcome.value;
   };
-  for (let i = 0; i < connectors.length; i++) {
-    const connector = connectors[i];
-    const ns = sanitizeIdentifier(connector.id);
-    if (used.has(ns)) {
-      logger.warn(
-        `[connecta] execute_code: namespace "${ns}" (connector "${connector.id}") collides with a reserved name or an earlier connector — connector skipped`,
-      );
-      continue;
-    }
-    const loadedTools = loaded[i];
-    if (loadedTools.status === "rejected") {
-      // Same health accounting as the call_tool catalog catch: a connector whose
-      // catalog cannot be fetched is unusable, and dropping its namespace with
-      // only a warn would leave the cheap `list_connectors({ probe: false })`
-      // signal clean for a code-mode deployment whose downstream grant was
-      // revoked. Recorded through `registry` — this run's view — so a
-      // toolkit-scoped execute_code lands in that toolkit's log as well.
-      registry.recordFailure(
-        connector.id,
-        Date.now() - catalogStarted,
-        loadedTools.reason,
-      );
-      // classifyCallError so a typed auth_required thrown while listing tools
-      // keeps its code where an operator can see it; health stores the message.
-      const details = classifyCallError(
-        loadedTools.reason,
-        "catalog_lookup_failed",
-      );
-      logger.warn(
-        `[connecta] execute_code: connector "${connector.id}" skipped (${details.code}): ${msg(loadedTools.reason)}`,
-      );
-      continue;
-    }
-    const tools = loadedTools.value;
-    catalogs.set(connector.id, tools);
-    // Null-prototype map: tools named `toString`/`hasOwnProperty`/`constructor`
-    // are legitimate and must not collide with inherited Object members.
-    const fns: ExecutorProvider["fns"] = Object.create(null);
-    for (const t of tools) {
-      if (
-        t.annotations?.readOnlyHint !== true ||
-        t.annotations?.destructiveHint === true
-      ) {
-        continue;
-      }
-      const key = sanitizeIdentifier(t.name);
-      if (Object.hasOwn(fns, key)) {
-        logger.warn(
-          `[connecta] execute_code: tool "${connector.id}.${t.name}" sanitizes to duplicate "${key}" — skipped`,
-        );
-        continue;
-      }
-      // `await` (not a bare promise return) so a synchronous throw inside
-      // callAddress never sits handler-less for the thenable-adoption
-      // microtask — workerd reports that gap as an unhandled rejection.
-      fns[key] = async (args: unknown) =>
-        await callAddress(`${connector.id}.${t.name}`, args);
-    }
-    if (Object.keys(fns).length > 0) {
-      providers.push({ name: ns, fns });
-      used.add(ns);
-    }
-  }
-  providers.push({
-    name: "connecta",
-    fns: {
-      call: callAddress,
-      batch: async (calls: unknown) => {
-        if (!Array.isArray(calls)) throw new Error("calls must be an array");
-        if (calls.length > EXECUTE_MAX_BATCH_CALLS) {
-          throw new Error(
-            `connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS} calls`,
-          );
-        }
-        return await Promise.all(
-          calls.map(async (call) => {
-            const item = call as { address?: unknown; args?: unknown };
-            try {
-              return {
-                address: String(item.address),
-                ok: true,
-                data: await callAddress(item.address, item.args),
-              };
-            } catch (err) {
-              return {
-                address: String(item.address),
-                ok: false,
-                error: msg(err),
-              };
-            }
-          }),
-        );
-      },
-      search: async (raw: unknown) => {
-        const args = (raw ?? {}) as {
-          query?: string;
-          connector?: string;
-          limit?: number;
-          offset?: number;
-          fullDescriptions?: boolean;
-          includeSchemas?: "compact" | "json";
-        };
-        const matches: Array<{
-          connector: string;
-          tool: ToolDef;
-          score: number;
-          order: number;
-        }> = [];
-        let matchMode: "all" | "partial" = "all";
-        const collectMatches = (mode: "all" | "partial") => {
-          matches.length = 0;
-          let orderBase = 0;
-          for (const connector of connectors) {
-            if (args.connector && connector.id !== args.connector) continue;
-            const tools = catalogs.get(connector.id);
-            if (!tools) continue;
-            for (const ranked of rankTools(
-              tools,
-              args.query ?? "",
-              mode,
-            )) {
-              matches.push({
-                connector: connector.id,
-                tool: ranked.tool,
-                score: ranked.score,
-                order: orderBase + ranked.order,
-              });
-            }
-            orderBase += tools.length;
+  const callNamespace = async (
+    connectorId: unknown,
+    toolAlias: unknown,
+    args: unknown,
+  ) => {
+    const outcome = await invocation.invokeToolAlias(
+      String(connectorId),
+      String(toolAlias),
+      sanitizeIdentifier,
+      args ?? {},
+      invocationContext(),
+    );
+    if (!outcome.ok) throw new InvocationFailure(outcome.error);
+    return outcome.value;
+  };
+
+  return [
+    {
+      name: "connecta",
+      prelude: lazyNamespacePrelude(namespaces),
+      fns: {
+        __callNamespace: callNamespace,
+        call: callAddress,
+        batch: async (calls: unknown) => {
+          if (!Array.isArray(calls)) throw new Error("calls must be an array");
+          if (calls.length > EXECUTE_MAX_BATCH_CALLS) {
+            throw new Error(
+              `connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS} calls`,
+            );
           }
-        };
-        collectMatches("all");
-        if ((args.query ?? "").trim() && matches.length === 0) {
-          matchMode = "partial";
-          collectMatches(matchMode);
-        }
-        matches.sort((a, b) => b.score - a.score || a.order - b.order);
-        const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-        const limit = discoverySearchLimit(args.limit);
-        const page = matches.slice(offset, offset + limit).map((match) => {
-          const input = match.tool.inputSchema ?? { type: "object" };
-          return {
-            name: match.tool.name,
-            address: `${match.connector}.${match.tool.name}`,
-            description: summarizeDescription(
-              match.tool.description,
-              args.fullDescriptions === true,
-            ),
-            ...(args.includeSchemas
-              ? {
-                  inputSchema:
-                    args.includeSchemas === "json"
-                      ? input
-                      : compactSchema(input),
-                }
-              : {}),
-            ...(args.includeSchemas && match.tool.outputSchema
-              ? {
-                  outputSchema:
-                    args.includeSchemas === "json"
-                      ? match.tool.outputSchema
-                      : compactSchema(match.tool.outputSchema),
-                }
-              : {}),
-            ...(match.tool.annotations
-              ? { annotations: match.tool.annotations }
-              : {}),
+          return await Promise.all(
+            calls.map(async (call) => {
+              const item = call as { address?: unknown; args?: unknown };
+              try {
+                return {
+                  address: String(item.address),
+                  ok: true,
+                  data: await callAddress(item.address, item.args),
+                };
+              } catch (err) {
+                return {
+                  address: String(item.address),
+                  ok: false,
+                  error: msg(err),
+                };
+              }
+            }),
+          );
+        },
+        search: async (raw: unknown) => {
+          const args = (raw ?? {}) as {
+            query?: string;
+            connector?: string;
+            limit?: number;
+            offset?: number;
+            fullDescriptions?: boolean;
+            includeSchemas?: "compact" | "json";
           };
-        });
-        const nextOffset =
-          offset + page.length < matches.length
-            ? offset + page.length
-            : undefined;
-        const result = {
-          tools: page,
-          total: matches.length,
-          offset,
-          limit,
-          hasMore: nextOffset !== undefined,
-          ...(nextOffset !== undefined ? { nextOffset } : {}),
-          ...(matchMode === "partial" && matches.length > 0
-            ? { matchMode }
-            : {}),
-        };
-        assertDiscoveryResultSize(
-          result,
-          "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
-        );
-        return result;
-      },
-      describe: async (raw: unknown) => {
-        const args = (raw ?? {}) as {
-          addresses?: unknown;
-          format?: "compact" | "json";
-          fullDescriptions?: boolean;
-        };
-        const addresses = discoveryAddresses(args.addresses);
-        const format = args.format ?? "compact";
-        const result = {
-          tools: addresses.map((rawAddress) => {
-            const address = String(rawAddress);
-            const resolved = registry.resolveAddress(address);
-            if (!resolved) {
-              return { address, error: `Unknown address "${address}"` };
-            }
-            const tool = catalogs
-              .get(resolved.connector.id)
-              ?.find((item) => item.name === resolved.toolName);
-            if (!tool) {
-              return { address, error: `Unknown tool "${address}"` };
-            }
-            const input = tool.inputSchema ?? { type: "object" };
-            return {
-              address,
-              name: tool.name,
-              description: summarizeDescription(
-                tool.description,
-                args.fullDescriptions === true,
-              ),
-              inputSchema: format === "json" ? input : compactSchema(input),
-              ...(tool.outputSchema
-                ? {
-                    outputSchema:
-                      format === "json"
-                        ? tool.outputSchema
-                        : compactSchema(tool.outputSchema),
-                  }
-                : {}),
-              ...(tool.annotations ? { annotations: tool.annotations } : {}),
-            };
-          }),
-        };
-        assertDiscoveryResultSize(
-          result,
-          'Split the address list or use format: "compact".',
-        );
-        return result;
+          const result = flatSearchResult(await catalog.search(args));
+          assertDiscoveryResultSize(
+            result,
+            "Request a smaller limit, omit fullDescriptions, or use compact schemas.",
+          );
+          return result;
+        },
+        describe: async (raw: unknown) => {
+          const args = (raw ?? {}) as {
+            addresses?: unknown;
+            format?: "compact" | "json";
+            fullDescriptions?: boolean;
+          };
+          const result = { tools: await catalog.describe(args) };
+          assertDiscoveryResultSize(
+            result,
+            'Split the address list or use format: "compact".',
+          );
+          return result;
+        },
       },
     },
-  });
-  return providers;
+  ];
 }
 
 /** The execute_code handler. Exported for direct testing. */
@@ -511,6 +318,7 @@ export function createExecuteTool(
   executor: Executor,
   logger: Logger,
   activity?: ActivityRequestContext,
+  config: { discoveryConcurrency?: number } = {},
 ) {
   return async (
     { code }: { code: string },
@@ -540,7 +348,12 @@ export function createExecuteTool(
         baseUrl,
         logger,
         activity,
-        { signal: controller.signal },
+        {
+          signal: controller.signal,
+          ...(config.discoveryConcurrency !== undefined
+            ? { discoveryConcurrency: config.discoveryConcurrency }
+            : {}),
+        },
       );
       if (controller.signal.aborted) {
         throw new ExecutorAdmissionError(
@@ -615,7 +428,7 @@ const EXECUTE_DESC = `Use for dependent multi-step calls, loops, joins, branchin
 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.
 - connecta.call(address, args) and connecta.batch(calls) — call raw addresses.
-- connecta.search(args) and connecta.describe(args) — inspect the loaded catalog inside the same request.
+- connecta.search(args) and connecta.describe(args) — load and inspect request-local catalogs on demand.
 - 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.
@@ -633,6 +446,7 @@ export function registerExecuteTool(
     logger: Logger;
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
+    discoveryConcurrency?: number;
   },
 ): void {
   const handler = createExecuteTool(
@@ -641,6 +455,9 @@ export function registerExecuteTool(
     ctx.executor,
     ctx.logger,
     ctx.activity,
+    ctx.discoveryConcurrency !== undefined
+      ? { discoveryConcurrency: ctx.discoveryConcurrency }
+      : {},
   );
   server.registerTool(
     "execute_code",