@zackbart/connecta 0.1.0

package/src/executors/quickjs.ts

@@ -0,0 +1,321 @@
+// QuickJS-in-WebAssembly executor — the Node-side sandbox for execute_code.
+//
+// Model-written code runs inside a QuickJS interpreter compiled to WASM:
+// memory-safe, no ambient authority — the guest has no fetch, filesystem,
+// env, timers, or imports. The only bridge to the host is `__call`, which
+// returns a QuickJS promise that the host resolves with a JSON payload after
+// running the provider function; `executePendingJobs` drives guest
+// continuations from a host-side loop. Values cross the boundary as JSON, so
+// provider args/results must be JSON-serializable.
+
+import {
+  getQuickJS,
+  shouldInterruptAfterDeadline,
+  type QuickJSContext,
+  type QuickJSDeferredPromise,
+} from "quickjs-emscripten";
+import type { ExecuteResult, Executor, ExecutorProvider } from "../types.js";
+
+export interface QuickJsExecutorOptions {
+  /**
+   * Wall-clock budget for the whole execution, host tool calls included
+   * (same wall-clock-budget semantics as codemode's DynamicWorkerExecutor).
+   * Default 30s — intentionally tighter than codemode's 60s default: connecta
+   * sandbox code is tool-call glue, not compute, so a shorter leash surfaces
+   * hung downstreams sooner. Raise it here if a workload legitimately needs it.
+   */
+  timeoutMs?: number;
+  /** Guest heap limit. Default 64 MiB. */
+  memoryLimitBytes?: number;
+  /** Guest stack limit. Default 1 MiB. */
+  maxStackSizeBytes?: number;
+}
+
+const MAX_LOG_ENTRIES = 200;
+
+function msg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Normalize model output into an async-arrow expression: strip markdown fences, wrap bare bodies. */
+export function normalizeCode(code: string): string {
+  let c = code.trim();
+  const fence = /^```[\w-]*\s*\n([\s\S]*?)\n?```$/.exec(c);
+  if (fence) c = fence[1].trim();
+  // Sniff for an existing function expression past any leading comments/blank
+  // lines — models routinely prefix their code with a `//` or `/* */` note,
+  // which would otherwise defeat the detection and wrap the whole thing.
+  const head = c.replace(/^(?:\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\/)+/, "");
+  if (/^async\b/.test(head) || head.startsWith("(")) return c;
+  return `async () => {\n${c}\n}`;
+}
+
+/** Guest-side prelude: console capture, the JSON call bridge, one frozen global per provider. */
+function setupScript(providers: ExecutorProvider[]): string {
+  const lines: string[] = [
+    `globalThis.console = (() => {
+  const fmt = (x) => { if (typeof x === "string") return x; try { return JSON.stringify(x); } catch { return String(x); } };
+  const emit = (...a) => __log(a.map(fmt).join(" "));
+  return { log: emit, info: emit, warn: emit, error: emit, debug: emit };
+})();`,
+    `globalThis.__invoke = async (ns, fn, args) => {
+  const r = JSON.parse(await __call(ns, fn, JSON.stringify(args)));
+  if (!r.ok) throw new Error(r.error);
+  return r.value;
+};`,
+  ];
+  for (const p of providers) {
+    const ns = JSON.stringify(p.name);
+    const fields = Object.keys(p.fns).map((fn) => {
+      const f = JSON.stringify(fn);
+      // Forward every argument verbatim, positionally — same as codemode's
+      // sandbox proxy (`(...args) => call(fn, args)`). The host wrappers in
+      // buildSandboxProviders already guard the no-arg case, so no coercion.
+      return `  [${f}]: (...a) => __invoke(${ns}, ${f}, a),`;
+    });
+    lines.push(`globalThis[${ns}] = Object.freeze({\n${fields.join("\n")}\n});`);
+  }
+  return lines.join("\n");
+}
+
+/** True when a dumped error is QuickJS's deadline-interrupt signal. */
+function isInterrupt(dumped: unknown): boolean {
+  if (!dumped || typeof dumped !== "object") return false;
+  const e = dumped as { name?: unknown; message?: unknown };
+  return e.name === "InternalError" && e.message === "interrupted";
+}
+
+function formatGuestError(dumped: unknown): string {
+  if (dumped && typeof dumped === "object") {
+    const e = dumped as { name?: unknown; message?: unknown };
+    if (e.message != null) {
+      return e.name != null && e.name !== "Error"
+        ? `${String(e.name)}: ${String(e.message)}`
+        : String(e.message);
+    }
+  }
+  return typeof dumped === "string" ? dumped : JSON.stringify(dumped);
+}
+
+interface HostBridge {
+  pending: number;
+  aborted: boolean;
+  wake: () => void;
+  waitForSettle: Promise<void>;
+}
+
+function armWake(bridge: HostBridge): void {
+  bridge.waitForSettle = new Promise((resolve) => {
+    bridge.wake = resolve;
+  });
+}
+
+function installBridge(
+  ctx: QuickJSContext,
+  providers: ExecutorProvider[],
+  logs: string[],
+): HostBridge {
+  const bridge: HostBridge = {
+    pending: 0,
+    aborted: false,
+    wake: () => {},
+    waitForSettle: Promise.resolve(),
+  };
+  armWake(bridge);
+
+  const logFn = ctx.newFunction("__log", (h) => {
+    if (logs.length < MAX_LOG_ENTRIES) {
+      logs.push(ctx.getString(h));
+    } else if (logs.length === MAX_LOG_ENTRIES) {
+      logs.push(`[log truncated after ${MAX_LOG_ENTRIES} entries]`);
+    }
+  });
+  ctx.setProp(ctx.global, "__log", logFn);
+  logFn.dispose();
+
+  const byName = new Map(providers.map((p) => [p.name, p]));
+  const invoke = async (
+    ns: string,
+    fn: string,
+    argsJson: string,
+  ): Promise<string> => {
+    try {
+      const provider = byName.get(ns);
+      const f =
+        provider && Object.hasOwn(provider.fns, fn)
+          ? provider.fns[fn]
+          : undefined;
+      if (!f) throw new Error(`Unknown function ${ns}.${fn}`);
+      const args = JSON.parse(argsJson) as unknown[];
+      const value = await f(...args);
+      return JSON.stringify({ ok: true, value });
+    } catch (err) {
+      return JSON.stringify({ ok: false, error: msg(err) });
+    }
+  };
+
+  const callFn = ctx.newFunction("__call", (nsH, fnH, argsH) => {
+    const ns = ctx.getString(nsH);
+    const fn = ctx.getString(fnH);
+    const argsJson = ctx.getString(argsH);
+    const deferred: QuickJSDeferredPromise = ctx.newPromise();
+    bridge.pending++;
+    void invoke(ns, fn, argsJson).then((json) => {
+      bridge.pending--;
+      if (bridge.aborted) {
+        // Context is (about to be) torn down — settle nothing, free our handles.
+        deferred.dispose();
+      } else {
+        const h = ctx.newString(json);
+        deferred.resolve(h);
+        h.dispose();
+      }
+      bridge.wake();
+    });
+    return deferred.handle;
+  });
+  ctx.setProp(ctx.global, "__call", callFn);
+  callFn.dispose();
+
+  return bridge;
+}
+
+/**
+ * Sandbox executor for Node (or any JS runtime) built on quickjs-emscripten.
+ * Suits connecta's execute_code: code is tool-call glue, so an interpreter's
+ * speed is irrelevant while its isolation (plain WASM, zero native deps) is
+ * the point. One fresh QuickJS context per execution; the WASM module itself
+ * is cached across calls by quickjs-emscripten.
+ */
+export function quickJsExecutor(
+  options: QuickJsExecutorOptions = {},
+): Executor {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const memoryLimitBytes = options.memoryLimitBytes ?? 64 * 1024 * 1024;
+  const maxStackSizeBytes = options.maxStackSizeBytes ?? 1024 * 1024;
+
+  return {
+    async execute(
+      code: string,
+      providers: ExecutorProvider[],
+    ): Promise<ExecuteResult> {
+      const QuickJS = await getQuickJS();
+      const ctx = QuickJS.newContext();
+      const deadline = Date.now() + timeoutMs;
+      const timeoutError = `Execution timed out after ${timeoutMs}ms.`;
+      ctx.runtime.setMemoryLimit(memoryLimitBytes);
+      ctx.runtime.setMaxStackSize(maxStackSizeBytes);
+      ctx.runtime.setInterruptHandler(shouldInterruptAfterDeadline(deadline));
+
+      const logs: string[] = [];
+      const bridge = installBridge(ctx, providers, logs);
+      const finish = (r: ExecuteResult): ExecuteResult => {
+        bridge.aborted = true;
+        // Outstanding host calls still hold deferred-promise handles; their
+        // callbacks free them and wake the drain, which disposes the context
+        // once the last straggler settles. Re-arm before every wait so the
+        // deferred never resolves-and-stays-resolved between settles — that
+        // would spin the microtask queue and starve the very timers the
+        // stragglers are waiting on. Arming before the pending check (and
+        // synchronously, before the first await) closes the settle-before-arm
+        // window: any settle after this point resolves the promise we await.
+        if (bridge.pending === 0) ctx.dispose();
+        else {
+          void (async () => {
+            armWake(bridge);
+            while (bridge.pending > 0) {
+              await bridge.waitForSettle;
+              armWake(bridge);
+            }
+            ctx.dispose();
+          })();
+        }
+        return logs.length > 0 ? { ...r, logs } : r;
+      };
+      const fail = (error: string): ExecuteResult =>
+        finish({ result: undefined, error });
+
+      const setup = ctx.evalCode(setupScript(providers));
+      if (setup.error) {
+        const detail = formatGuestError(ctx.dump(setup.error));
+        setup.error.dispose();
+        return fail(`Sandbox setup failed: ${detail}`);
+      }
+      setup.value.dispose();
+
+      const evaluated = ctx.evalCode(
+        `Promise.resolve((\n${normalizeCode(code)}\n)())`,
+      );
+      if (evaluated.error) {
+        const dumped = ctx.dump(evaluated.error);
+        evaluated.error.dispose();
+        // A synchronous runaway (no await to yield on) trips the deadline
+        // interrupt here; surface the friendly timeout, not "interrupted".
+        if (isInterrupt(dumped) && Date.now() >= deadline) return fail(timeoutError);
+        return fail(formatGuestError(dumped));
+      }
+      const promiseHandle = evaluated.value;
+
+      // Drive the guest: run microtask jobs, inspect the result promise,
+      // sleep until a host call settles (or the budget runs out), repeat.
+      // Returns without touching the context lifecycle; disposal happens below.
+      const drive = async (): Promise<ExecuteResult> => {
+        for (;;) {
+          const jobs = ctx.runtime.executePendingJobs();
+          if (jobs.error) {
+            const dumped = ctx.dump(jobs.error);
+            jobs.error.dispose();
+            // A runaway inside a resumed continuation trips the interrupt here.
+            if (isInterrupt(dumped) && Date.now() >= deadline) {
+              return { result: undefined, error: timeoutError };
+            }
+            return { result: undefined, error: formatGuestError(dumped) };
+          }
+          const state = ctx.getPromiseState(promiseHandle);
+          if (state.type === "fulfilled") {
+            const result: unknown = ctx.dump(state.value);
+            state.value.dispose();
+            return { result };
+          }
+          if (state.type === "rejected") {
+            const dumped = ctx.dump(state.error);
+            state.error.dispose();
+            // A synchronous runaway rejects the async fn's promise with the
+            // interrupt; surface the friendly timeout, not "interrupted".
+            if (isInterrupt(dumped) && Date.now() >= deadline) {
+              return { result: undefined, error: timeoutError };
+            }
+            return { result: undefined, error: formatGuestError(dumped) };
+          }
+          if (bridge.pending === 0) {
+            return {
+              result: undefined,
+              error:
+                "Execution stalled: code awaits something that can never settle.",
+            };
+          }
+          const remaining = deadline - Date.now();
+          if (remaining <= 0) {
+            return { result: undefined, error: timeoutError };
+          }
+          const settled = await Promise.race([
+            bridge.waitForSettle.then(() => true),
+            new Promise<boolean>((r) => setTimeout(() => r(false), remaining)),
+          ]);
+          if (settled) armWake(bridge);
+          else {
+            return { result: undefined, error: timeoutError };
+          }
+        }
+      };
+
+      let outcome: ExecuteResult;
+      try {
+        outcome = await drive();
+      } finally {
+        promiseHandle.dispose();
+      }
+      return finish(outcome);
+    },
+  };
+}

package/src/favicon.ts

@@ -0,0 +1,53 @@
+/** Build a dependency-free 32px ICO matching the default SVG "C" mark. */
+function buildIco(): Uint8Array {
+  const size = 32;
+  const directoryLength = 22;
+  const bitmapHeaderLength = 40;
+  const colorLength = size * size * 4;
+  const maskRowLength = 4;
+  const maskLength = maskRowLength * size;
+  const imageLength = bitmapHeaderLength + colorLength + maskLength;
+  const ico = new Uint8Array(directoryLength + imageLength);
+  const view = new DataView(ico.buffer);
+
+  view.setUint16(0, 0, true); // reserved
+  view.setUint16(2, 1, true); // image type: icon
+  view.setUint16(4, 1, true); // image count
+  ico[6] = size;
+  ico[7] = size;
+  view.setUint16(10, 1, true); // color planes
+  view.setUint16(12, 32, true); // bits per pixel
+  view.setUint32(14, imageLength, true);
+  view.setUint32(18, directoryLength, true);
+
+  const dib = directoryLength;
+  view.setUint32(dib, bitmapHeaderLength, true);
+  view.setInt32(dib + 4, size, true);
+  view.setInt32(dib + 8, size * 2, true); // color image + transparency mask
+  view.setUint16(dib + 12, 1, true);
+  view.setUint16(dib + 14, 32, true);
+  view.setUint32(dib + 20, colorLength, true);
+
+  const pixels = dib + bitmapHeaderLength;
+  const mask = pixels + colorLength;
+  for (let y = 0; y < size; y += 1) {
+    for (let x = 0; x < size; x += 1) {
+      const dx = x - 15.5;
+      const dy = y - 15.5;
+      const radius = Math.sqrt(dx * dx + dy * dy);
+      const opaque = radius >= 8 && radius <= 13 &&
+        (x <= 18 || Math.abs(dy) >= 7);
+      const row = size - 1 - y;
+      const pixel = pixels + (row * size + x) * 4;
+      ico[pixel + 3] = opaque ? 255 : 0;
+      if (!opaque) {
+        ico[mask + row * maskRowLength + Math.floor(x / 8)] |=
+          0x80 >> (x % 8);
+      }
+    }
+  }
+
+  return ico;
+}
+
+export const CONNECTA_FAVICON_ICO = buildIco();

package/src/index.ts

@@ -0,0 +1,197 @@
+import { CredentialVault } from "./credentials.js";
+import { Registry } from "./registry.js";
+import { createFetchHandler } from "./server.js";
+import { memoryStorage } from "./storage/memory.js";
+import type { ActivityReadGate, ActivityStore } from "./activity.js";
+import type {
+  Connector,
+  ConnectaBranding,
+  Executor,
+  InboundAuth,
+  KVStorage,
+  Logger,
+} from "./types.js";
+
+export interface ConnectaConfig {
+  connectors: Connector[];
+  /**
+   * Privacy-minimal downstream tool activity storage. Writes are best-effort
+   * and never change tool results. Implement `list` to enable the Activity UI.
+   */
+  activity?: ActivityStore;
+  /**
+   * Optional authorization gate for the Activity read API. MCP authentication
+   * is still required first. Omit to admit every authenticated actor.
+   */
+  activityReadGate?: ActivityReadGate;
+  /** Stable deployment label included in activity events, e.g. "production". */
+  activityDeploymentId?: string;
+  /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
+  auth?: InboundAuth | InboundAuth[];
+  /** KVStorage impl. Defaults to memoryStorage(). */
+  storage?: KVStorage;
+  /**
+   * Public base URL. Defaults to the request origin per-request. Configuring an
+   * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
+   */
+  publicUrl?: string;
+  /**
+   * Base64-encoded 32-byte AES key for connector credentials managed in /ui.
+   * Keep this in the runtime's secret store, never in KV or source control.
+   */
+  credentialEncryptionKey?: string;
+  /** Optional browser UI and OAuth result-page labels. */
+  branding?: ConnectaBranding;
+  logger?: Logger;
+  /** Tool-list cache TTL (seconds). Default 300. */
+  toolCacheTtlSeconds?: number;
+  /**
+   * Persist serializable remote tool catalogs in storage so cold isolates can
+   * discover tools without a downstream handshake. Default true.
+   */
+  persistToolCatalog?: boolean;
+  /**
+   * How long an expired persisted catalog remains available as a fallback
+   * when a live refresh fails. Default 3600 seconds.
+   */
+  toolCatalogStaleSeconds?: number;
+  /**
+   * Max inline result size (bytes) before call_tool/batch_call truncate and
+   * stash the full text for get_result paging. Default 50_000.
+   */
+  maxResultBytes?: number;
+  serverInfo?: { name?: string; version?: string };
+  /** Deployment metadata exposed by /health (for example a Worker version). */
+  deploymentInfo?: Record<string, unknown>;
+  /**
+   * Sandbox for the optional execute_code meta-tool (code mode). Omit → the
+   * tool is not registered and connecta serves the nine base tools. Workers:
+   * `new DynamicWorkerExecutor({ loader: env.LOADER })` from
+   * `@cloudflare/codemode`. Node: `quickJsExecutor()` from "@zackbart/connecta/quickjs".
+   */
+  executor?: Executor;
+}
+
+export interface Connecta {
+  /** Web-standard fetch handler. Usable as `export default { fetch: connecta.fetch }`. */
+  fetch: (request: Request, env?: unknown, ctx?: unknown) => Promise<Response>;
+  registry: Registry;
+}
+
+function defaultLogger(): Logger {
+  return {
+    debug: (...a) => console.debug("[connecta]", ...a),
+    info: (...a) => console.info("[connecta]", ...a),
+    warn: (...a) => console.warn("[connecta]", ...a),
+    error: (...a) => console.error("[connecta]", ...a),
+  };
+}
+
+/** Bearer providers are checked before Clerk (per spec). */
+function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
+  const list = auth ? (Array.isArray(auth) ? auth : [auth]) : [];
+  return [...list].sort((a, b) => {
+    const rank = (x: InboundAuth) => (x.kind === "bearer" ? 0 : 1);
+    return rank(a) - rank(b);
+  });
+}
+
+export function createConnecta(config: ConnectaConfig): Connecta {
+  const storage = config.storage ?? memoryStorage();
+  const logger = config.logger ?? defaultLogger();
+  const credentialConnectors = config.connectors.filter((c) => c.credential);
+  if (credentialConnectors.length > 0 && !config.credentialEncryptionKey) {
+    throw new Error(
+      `credentialEncryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
+    );
+  }
+  const credentialVault = config.credentialEncryptionKey
+    ? new CredentialVault(storage, config.credentialEncryptionKey)
+    : undefined;
+  const registry = new Registry(config.connectors, {
+    storage,
+    logger,
+    credentialVault,
+    toolCacheTtlSeconds: config.toolCacheTtlSeconds,
+    persistToolCatalog: config.persistToolCatalog,
+    toolCatalogStaleSeconds: config.toolCatalogStaleSeconds,
+    maxResultBytes: config.maxResultBytes,
+  });
+  const handler = createFetchHandler({
+    registry,
+    auth: normalizeAuth(config.auth),
+    publicUrl: config.publicUrl,
+    serverInfo: {
+      name: config.serverInfo?.name ?? "connecta",
+      version: config.serverInfo?.version ?? "0.1.0",
+    },
+    logger,
+    activity: config.activity,
+    activityReadGate: config.activityReadGate,
+    activityDeploymentId: config.activityDeploymentId,
+    executor: config.executor,
+    credentialVault,
+    deploymentInfo: config.deploymentInfo,
+    branding: config.branding,
+  });
+  return {
+    fetch: (request, _env, ctx) =>
+      handler(
+        request,
+        ctx && typeof (ctx as { waitUntil?: unknown }).waitUntil === "function"
+          ? (ctx as { waitUntil(promise: Promise<unknown>): void })
+          : undefined,
+      ),
+    registry,
+  };
+}
+
+export { remoteMcp } from "./connectors/remote-mcp.js";
+export { api } from "./connectors/api.js";
+export { bearerToken } from "./auth/bearer.js";
+export { memoryStorage } from "./storage/memory.js";
+export { CredentialVault } from "./credentials.js";
+export { Registry } from "./registry.js";
+export { createMetaTools } from "./meta-tools.js";
+export {
+  buildSandboxProviders,
+  createExecuteTool,
+  sanitizeIdentifier,
+} from "./execute.js";
+
+export type { RemoteMcpOptions, RemoteMcpAuth } from "./connectors/remote-mcp.js";
+export type { ApiOptions, ApiTool } from "./connectors/api.js";
+export type {
+  Connector,
+  ConnectaBranding,
+  ConnectorCredentialAccess,
+  ConnectorCredentialConfig,
+  ConnectorCredentialFieldConfig,
+  ConnectorCredentialValues,
+  ConnectorContext,
+  ConnectorStatus,
+  CredentialTestResult,
+  ExecuteResult,
+  Executor,
+  ExecutorProvider,
+  InboundAuth,
+  UiAuthConfig,
+  AuthResult,
+  JsonSchema,
+  KVStorage,
+  Logger,
+  ToolDef,
+  ToolAnnotations,
+} from "./types.js";
+export type {
+  ActivityActor,
+  ActivityCallSource,
+  ActivityOutcome,
+  ActivityPage,
+  ActivityReader,
+  ActivityReadGate,
+  ActivitySink,
+  ActivityStore,
+  ToolCallActivityEvent,
+} from "./activity.js";
+export { InvalidActivityCursorError } from "./activity.js";

package/src/mcp-result.ts

@@ -0,0 +1,43 @@
+import type { Connector } from "./types.js";
+
+interface McpishResult {
+  content?: { type?: string; text?: string }[];
+  isError?: boolean;
+  structuredContent?: unknown;
+  toolResult?: unknown;
+}
+
+/**
+ * Unwrap an MCP CallToolResult into an ordinary JavaScript value:
+ * `toolResult` wins when present, then `structuredContent`; all-text content is
+ * JSON-parsed when possible. Downstream `isError` results become exceptions.
+ * Non-MCP connectors already return plain values.
+ */
+export function unwrapMcpResult(
+  kind: Connector["kind"],
+  result: unknown,
+): unknown {
+  if (kind !== "mcp" || result == null || typeof result !== "object") {
+    return result;
+  }
+  const r = result as McpishResult;
+  if ("toolResult" in r) return r.toolResult;
+  const content = Array.isArray(r.content) ? r.content : [];
+  if (r.isError) {
+    const text = content
+      .filter((c) => c.type === "text")
+      .map((c) => c.text ?? "")
+      .join("\n");
+    throw new Error(text || "Tool call failed");
+  }
+  if (r.structuredContent != null) return r.structuredContent;
+  if (content.length > 0 && content.every((c) => c.type === "text")) {
+    const text = content.map((c) => c.text ?? "").join("\n");
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return result;
+}