@zackbart/connecta 0.2.0 → 0.3.0

package/src/connectors/api.ts

@@ -1,3 +1,5 @@
+import { Validator } from "@cfworker/json-schema";
+import { ConnectorCallError } from "../errors.js";
 import type {
   Connector,
   ConnectorCredentialConfig,
@@ -40,6 +42,14 @@ export interface ApiOptions {
     values: ConnectorCredentialValues,
     ctx: ConnectorContext,
   ) => Promise<CredentialTestResult>;
+  /**
+   * Validate call arguments against each tool's `inputSchema` before invoking
+   * the handler (default true). Mismatches fail with a non-retryable
+   * `invalid_args` ConnectorCallError instead of reaching the handler. Set
+   * false to restore the pre-validation pass-through for deployments relying
+   * on loose coercion.
+   */
+  validateArgs?: boolean;
   tools: ApiTool[];
 }
 
@@ -47,6 +57,12 @@ export interface ApiOptions {
  * A connector defined entirely in code: static tool defs + fetch handlers.
  * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
  * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
+ *
+ * Arguments are validated against `inputSchema` before the handler runs
+ * (disable with `validateArgs: false`). This is deliberately asymmetric with
+ * remote MCP connectors, which stay pass-through: the downstream server is
+ * authoritative for its own schemas, and re-validating with our JSON Schema
+ * draft/format semantics could reject calls the downstream would accept.
  */
 export function api(id: string, opts: ApiOptions): Connector {
   const defs: ToolDef[] = opts.tools.map((t) => ({
@@ -57,6 +73,35 @@ export function api(id: string, opts: ApiOptions): Connector {
     annotations: t.annotations,
   }));
   const byName = new Map(opts.tools.map((t) => [t.name, t]));
+  const validateArgs = opts.validateArgs ?? true;
+  // Lazy per-tool validator cache; null marks a schema the validator rejected
+  // (warned once, then passed through rather than breaking a working tool).
+  const validators = new Map<string, Validator | null>();
+  const disableValidation = (
+    tool: ApiTool,
+    ctx: ConnectorContext,
+    err: unknown,
+  ) => {
+    validators.set(tool.name, null);
+    ctx.logger.warn(
+      `[connecta] tool "${id}.${tool.name}" has an inputSchema the validator cannot use (${
+        err instanceof Error ? err.message : String(err)
+      }) — arguments are not validated`,
+    );
+  };
+  const validatorFor = (tool: ApiTool, ctx: ConnectorContext) => {
+    let validator = validators.get(tool.name);
+    if (validator === undefined) {
+      try {
+        validator = new Validator(tool.inputSchema as never, "2020-12", false);
+        validators.set(tool.name, validator);
+      } catch (err) {
+        disableValidation(tool, ctx, err);
+        validator = null;
+      }
+    }
+    return validator;
+  };
   return {
     id,
     title: opts.title,
@@ -74,7 +119,31 @@ export function api(id: string, opts: ApiOptions): Connector {
       if (!tool) {
         throw new Error(`Unknown tool "${name}" on connector "${id}"`);
       }
-      return tool.handler(args ?? {}, ctx);
+      const input = args ?? {};
+      if (validateArgs && tool.inputSchema) {
+        const validator = validatorFor(tool, ctx);
+        let result;
+        try {
+          result = validator?.validate(input);
+        } catch (err) {
+          // e.g. an unresolvable $ref — surfaces on first validate, not compile.
+          disableValidation(tool, ctx, err);
+        }
+        if (result && !result.valid) {
+          const units = result.errors.filter(
+            (u) => u.instanceLocation !== "#",
+          );
+          const detail = (units.length > 0 ? units : result.errors)
+            .slice(0, 3)
+            .map((u) => `${u.instanceLocation}: ${u.error}`)
+            .join("; ");
+          throw new ConnectorCallError(
+            "invalid_args",
+            `Invalid arguments for "${id}.${name}": ${detail || "input does not match the tool's inputSchema"}`,
+          );
+        }
+      }
+      return tool.handler(input, ctx);
     },
   };
 }

package/src/connectors/remote-mcp.ts

@@ -4,6 +4,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
 import { KvOAuthProvider } from "../auth/downstream-oauth.js";
+import { ConnectorCallError } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
 import type {
   Connector,
@@ -60,6 +61,14 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   const states = new WeakMap<object, ConnectionState>();
   const isOauth = opts.auth?.type === "oauth";
 
+  /** Typed per-call auth signal; the SDK's UnauthorizedError stays as cause. */
+  const authRequiredError = (cause: unknown) =>
+    new ConnectorCallError(
+      "auth_required",
+      `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`,
+      { cause },
+    );
+
   const stateFor = (ctx: ConnectorContext): ConnectionState => {
     const scope = ctx.requestScope ?? ctx;
     let state = states.get(scope);
@@ -176,6 +185,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
         // "auth_required".
         if (err instanceof UnauthorizedError) {
           state.authRequired = true;
+          throw authRequiredError(err);
         }
         throw err;
       } finally {
@@ -209,19 +219,28 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     async callTool(name, args, ctx) {
       const state = stateFor(ctx);
       await ensureConnected(ctx, state);
-      return state.client!.callTool(
-        {
-          name,
-          arguments: (args ?? {}) as Record<string, unknown>,
-        },
-        undefined,
-        ctx.timeoutMs || ctx.signal
-          ? {
-              ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
-              ...(ctx.signal ? { signal: ctx.signal } : {}),
-            }
-          : undefined,
-      );
+      try {
+        return await state.client!.callTool(
+          {
+            name,
+            arguments: (args ?? {}) as Record<string, unknown>,
+          },
+          undefined,
+          ctx.timeoutMs || ctx.signal
+            ? {
+                ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+              }
+            : undefined,
+        );
+      } catch (err) {
+        // A grant revoked after connect surfaces here, not in ensureConnected.
+        if (err instanceof UnauthorizedError) {
+          state.authRequired = true;
+          throw authRequiredError(err);
+        }
+        throw err;
+      }
     },
 
     async status(ctx): Promise<ConnectorStatus> {

package/src/credentials.ts

@@ -219,7 +219,10 @@ export class CredentialVault {
     value: string,
     updatedBy: string,
   ): Promise<CredentialMetadata> {
-    return this.setAll(connectorId, { value }, updatedBy);
+    // `await` (not a bare promise return) so a validation throw inside setAll
+    // never sits handler-less for the thenable-adoption microtask — workerd
+    // reports that gap as an unhandled rejection.
+    return await this.setAll(connectorId, { value }, updatedBy);
   }
 
   async setAll(

package/src/errors.ts

@@ -0,0 +1,83 @@
+// Typed failure contract for connector tool calls. Web-API only — no node:
+// imports here.
+
+/** Machine-readable classification of a failed connector tool call. */
+export type ConnectorCallErrorCode =
+  | "timeout"
+  | "auth_required"
+  | "rate_limited"
+  | "unavailable"
+  | "invalid_args"
+  | "connector_call_failed";
+
+const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
+  timeout: true,
+  rate_limited: true,
+  unavailable: true,
+  auth_required: false,
+  invalid_args: false,
+  connector_call_failed: false,
+};
+
+/**
+ * Throw from `Connector.callTool` (or anything beneath it) to classify a
+ * failure exactly. Untyped errors fall back to a message-text heuristic, so a
+ * connector whose legitimate error text mentions "timeout" is misread as a
+ * retryable timeout — this class is the escape hatch. `retryable` defaults per
+ * code (timeout, rate_limited, and unavailable retry; the rest do not) and may
+ * be overridden.
+ */
+export class ConnectorCallError extends Error {
+  readonly code: ConnectorCallErrorCode;
+  readonly retryable: boolean;
+
+  constructor(
+    code: ConnectorCallErrorCode,
+    message: string,
+    opts: { retryable?: boolean; cause?: unknown } = {},
+  ) {
+    super(
+      message,
+      opts.cause !== undefined ? { cause: opts.cause } : undefined,
+    );
+    this.name = "ConnectorCallError";
+    this.code = code;
+    this.retryable = opts.retryable ?? RETRYABLE_BY_CODE[code];
+  }
+}
+
+/** The `error` object surfaced in call_tool/batch_call value-mode results. */
+export interface CallErrorDetails {
+  code: string;
+  message: string;
+  retryable: boolean;
+}
+
+const RETRYABLE_MESSAGE_RE =
+  /timeout|timed out|econnreset|econnrefused|temporar|rate.?limit|429|502|503|504|refcountedcanceler|different request/i;
+const TIMEOUT_MESSAGE_RE = /timed out|timeout/i;
+
+/** Message-text fallback used when an error carries no typed classification. */
+export function messageLooksRetryable(message: string): boolean {
+  return RETRYABLE_MESSAGE_RE.test(message);
+}
+
+/**
+ * Classify a value thrown by a connector call. A `ConnectorCallError` is
+ * authoritative; anything else falls back to the historical message-text
+ * heuristic.
+ */
+export function classifyCallError(
+  err: unknown,
+  fallbackCode = "connector_call_failed",
+): CallErrorDetails {
+  if (err instanceof ConnectorCallError) {
+    return { code: err.code, message: err.message, retryable: err.retryable };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    code: TIMEOUT_MESSAGE_RE.test(message) ? "timeout" : fallbackCode,
+    message,
+    retryable: RETRYABLE_MESSAGE_RE.test(message),
+  };
+}

package/src/execute.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
 import { recordToolActivity, type ActivityRequestContext } from "./activity.js";
 import { errorResult, jsonResult, type ToolResult } from "./meta-tools.js";
+import { classifyCallError, ConnectorCallError } from "./errors.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import type { Registry } from "./registry.js";
 import type {
@@ -191,7 +192,10 @@ export async function buildSandboxProviders(
     try {
       timer = setTimeout(() => {
         controller.abort(
-          new Error(`Tool call timed out after ${hostCallTimeoutMs}ms`),
+          new ConnectorCallError(
+            "timeout",
+            `Tool call timed out after ${hostCallTimeoutMs}ms`,
+          ),
         );
       }, hostCallTimeoutMs);
       const pending = resolved.connector.callTool(
@@ -216,16 +220,16 @@ export async function buildSandboxProviders(
       return value;
     } catch (err) {
       registry.recordFailure(resolved.connector.id, Date.now() - started, err);
-      const timedOut = /timed out|timeout/i.test(msg(err));
+      const details = classifyCallError(err);
       recordToolActivity(activity, {
         connectorId: resolved.connector.id,
         toolName: resolved.toolName,
         address: `${resolved.connector.id}.${resolved.toolName}`,
         source: "execute_code",
-        outcome: timedOut ? "timeout" : "error",
+        outcome: details.code === "timeout" ? "timeout" : "error",
         durationMs: Date.now() - started,
         attempts: 1,
-        errorCode: timedOut ? "timeout" : "connector_call_failed",
+        errorCode: details.code,
       });
       throw err;
     } finally {
@@ -269,8 +273,11 @@ export async function buildSandboxProviders(
         );
         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) =>
-        callAddress(`${connector.id}.${t.name}`, args);
+        await callAddress(`${connector.id}.${t.name}`, args);
     }
     if (Object.keys(fns).length > 0) {
       providers.push({ name: ns, fns });
@@ -288,7 +295,7 @@ export async function buildSandboxProviders(
             `connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS} calls`,
           );
         }
-        return Promise.all(
+        return await Promise.all(
           calls.map(async (call) => {
             const item = call as { address?: unknown; args?: unknown };
             try {

package/src/index.ts

@@ -61,7 +61,16 @@ export interface ConnectaConfig {
    * stash the full text for get_result paging. Default 50_000.
    */
   maxResultBytes?: number;
-  serverInfo?: { name?: string; version?: string };
+  serverInfo?: {
+    name?: string;
+    version?: string;
+    /** Human-readable name clients may show instead of `name`. */
+    title?: string;
+    /** Homepage clients may link from the server listing. */
+    websiteUrl?: string;
+    /** MCP icons-spec entries; clients render these instead of a scraped favicon. */
+    icons?: Array<{ src: string; mimeType?: string; sizes?: string[] }>;
+  };
   /** Deployment metadata exposed by /health (for example a Worker version). */
   deploymentInfo?: Record<string, unknown>;
   /**
@@ -123,6 +132,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     auth: normalizeAuth(config.auth),
     publicUrl: config.publicUrl,
     serverInfo: {
+      ...config.serverInfo,
       name: config.serverInfo?.name ?? "connecta",
       version: config.serverInfo?.version ?? CONNECTA_VERSION,
     },
@@ -149,6 +159,8 @@ export function createConnecta(config: ConnectaConfig): Connecta {
 
 export { remoteMcp } from "./connectors/remote-mcp.js";
 export { api } from "./connectors/api.js";
+export { ConnectorCallError } from "./errors.js";
+export type { ConnectorCallErrorCode, CallErrorDetails } from "./errors.js";
 export { bearerToken } from "./auth/bearer.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";

package/src/meta-tools.ts

@@ -7,6 +7,12 @@ import {
   type ActivityRequestContext,
 } from "./activity.js";
 import { unwrapMcpResult } from "./mcp-result.js";
+import {
+  classifyCallError,
+  ConnectorCallError,
+  messageLooksRetryable,
+  type CallErrorDetails,
+} from "./errors.js";
 import type { Registry } from "./registry.js";
 import { AVAILABLE_SKILLS } from "./skills.js";
 import type { KVStorage, ToolDef } from "./types.js";
@@ -45,21 +51,11 @@ const DEFAULT_SEARCH_LIMIT = 25;
 const enc = new TextEncoder();
 const dec = new TextDecoder();
 
-interface ErrorDetails {
-  code: string;
-  message: string;
-  retryable: boolean;
-}
+type ErrorDetails = CallErrorDetails;
 
+/** Details for failures that never reached a connector (no thrown value). */
 function errorDetails(code: string, message: string): ErrorDetails {
-  return {
-    code,
-    message,
-    retryable:
-      /timeout|timed out|econnreset|econnrefused|temporar|rate.?limit|429|502|503|504|refcountedcanceler|different request/i.test(
-        message,
-      ),
-  };
+  return { code, message, retryable: messageLooksRetryable(message) };
 }
 
 /** True if `b` is a UTF-8 continuation byte (0b10xxxxxx). */
@@ -332,11 +328,10 @@ export function createMetaTools(
         ...(errorCode ? { errorCode } : {}),
       });
     };
-    const failed = (code: string, message: string): RunCallOutcome => {
+    const failed = (error: ErrorDetails): RunCallOutcome => {
       const durationMs = Date.now() - started;
-      const error = errorDetails(code, message);
       const diagnostics = timing();
-      record(code === "timeout" ? "timeout" : "error", code);
+      record(error.code === "timeout" ? "timeout" : "error", error.code);
       return {
         toolResult:
           call.resultMode === "value"
@@ -347,7 +342,7 @@ export function createMetaTools(
                 attempts,
                 ...(call.diagnostics ? { timing: diagnostics } : {}),
               })
-            : errorResult(message),
+            : errorResult(error.message),
         durationMs,
         attempts,
         timing: diagnostics,
@@ -355,7 +350,9 @@ export function createMetaTools(
       };
     };
     if (!resolved) {
-      return failed("unknown_address", `Unknown address "${call.address}"`);
+      return failed(
+        errorDetails("unknown_address", `Unknown address "${call.address}"`),
+      );
     }
     const results = registry.resultsStorage();
     const fields = call.fields && call.fields.length > 0 ? call.fields : null;
@@ -375,13 +372,17 @@ export function createMetaTools(
       ).find((tool) => tool.name === resolved.toolName);
     } catch (err) {
       catalogMs += Date.now() - catalogStarted;
-      return failed("catalog_lookup_failed", msg(err));
+      // classifyCallError so a typed auth_required thrown while listing tools
+      // (e.g. a revoked downstream OAuth grant) keeps its code.
+      return failed(classifyCallError(err, "catalog_lookup_failed"));
     }
     catalogMs += Date.now() - catalogStarted;
     if (!definition) {
       return failed(
-        "unknown_tool",
-        `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
+        errorDetails(
+          "unknown_tool",
+          `Unknown tool "${resolved.toolName}" on connector "${resolved.connector.id}"`,
+        ),
       );
     }
     const explicitlyReadOnly =
@@ -389,8 +390,10 @@ export function createMetaTools(
       definition.annotations?.destructiveHint !== true;
     if (!explicitlyReadOnly && !options.allowDestructive) {
       return failed(
-        "destructive_tool_requires_approval",
-        `Tool "${call.address}" is not explicitly read-only. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`,
+        errorDetails(
+          "destructive_tool_requires_approval",
+          `Tool "${call.address}" is not explicitly read-only. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`,
+        ),
       );
     }
     const retrySafe =
@@ -420,7 +423,12 @@ export function createMetaTools(
               pending,
               new Promise<never>((_, reject) => {
                 timer = setTimeout(() => {
-                  reject(new Error(`Tool call timed out after ${timeoutMs}ms`));
+                  reject(
+                    new ConnectorCallError(
+                      "timeout",
+                      `Tool call timed out after ${timeoutMs}ms`,
+                    ),
+                  );
                   controller?.abort();
                 }, timeoutMs);
               }),
@@ -441,7 +449,7 @@ export function createMetaTools(
       } catch (err) {
         // Includes connector setup, downstream execution, and timeout wait.
         connectorMs += Date.now() - connectorStarted;
-        const details = errorDetails("connector_call_failed", msg(err));
+        const details = classifyCallError(err);
         if (attempts <= maxRetries && retrySafe && details.retryable) {
           const backoffStarted = Date.now();
           await new Promise((resolve) =>
@@ -455,12 +463,7 @@ export function createMetaTools(
           Date.now() - started,
           err,
         );
-        return failed(
-          /timed out|timeout/i.test(msg(err))
-            ? "timeout"
-            : "connector_call_failed",
-          msg(err),
-        );
+        return failed(details);
       } finally {
         if (timer) clearTimeout(timer);
       }
@@ -531,7 +534,7 @@ export function createMetaTools(
       };
     } catch (err) {
       resultProcessingMs += Date.now() - processingStarted;
-      return failed("result_processing_failed", msg(err));
+      return failed(errorDetails("result_processing_failed", msg(err)));
     }
   }
 
@@ -846,12 +849,11 @@ export function createMetaTools(
       const results = settled.map((s, i) => {
         const address = args.calls[i].address;
         if (s.status === "rejected") {
-          const message = msg(s.reason);
           return {
             address,
             ok: false,
-            error: message,
-            errorDetails: errorDetails("batch_call_failed", message),
+            error: msg(s.reason),
+            errorDetails: classifyCallError(s.reason, "batch_call_failed"),
           };
         }
         const r = s.value;

package/src/node.ts

@@ -5,6 +5,7 @@ import { pipeline } from "node:stream/promises";
 import type { Connecta } from "./index.js";
 
 export { fileStorage } from "./storage/file.js";
+export type { FileStorageOptions } from "./storage/file.js";
 
 /** 10 MiB. Tool arguments are JSON; nothing legitimate approaches this. */
 const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;

package/src/server.ts

@@ -39,7 +39,9 @@ export interface ServerOptions {
   registry: Registry;
   auth: InboundAuth[];
   publicUrl?: string;
-  serverInfo: { name: string; version: string };
+  // The SDK's Implementation shape: name/version plus optional title,
+  // websiteUrl, and icons (MCP icons spec) that clients may render.
+  serverInfo: ConstructorParameters<typeof McpServer>[0];
   logger: Logger;
   activity?: ActivityStore;
   activityReadGate?: ActivityReadGate;

package/src/storage/file.ts

@@ -6,19 +6,28 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname } from "node:path";
-import type { KVStorage } from "../types.js";
+import type { KVStorage, Logger } from "../types.js";
 
 interface Entry {
   value: string;
   exp?: number; // epoch ms
 }
 
+export interface FileStorageOptions {
+  /** Destination for the corrupt-state-file recovery report. Default console. */
+  logger?: Logger;
+}
+
 /**
  * JSON-file-backed KVStorage for Node. Loads once, persists on every write via
  * a temp-file + rename (atomic-ish). Only reachable via the "@zackbart/connecta/node"
  * subpath so the main entry stays Workers-clean.
  */
-export function fileStorage(path: string): KVStorage {
+export function fileStorage(
+  path: string,
+  opts: FileStorageOptions = {},
+): KVStorage {
+  const logger: Logger = opts.logger ?? console;
   let data: Record<string, Entry> = {};
   if (existsSync(path)) {
     try {
@@ -39,7 +48,7 @@ export function fileStorage(path: string): KVStorage {
             `than overwrite it. Move or repair the file, then restart.`,
         );
       }
-      console.error(
+      logger.error(
         `[connecta] state file ${path} is not valid JSON ` +
           `(${error instanceof Error ? error.message : String(error)}) — ` +
           `moved to ${quarantine}, starting from empty state. Downstream ` +

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.2.0";
+export const CONNECTA_VERSION = "0.3.0";