@zackbart/connecta 0.2.1 → 0.4.0

package/src/catalog.ts

@@ -79,6 +79,41 @@ function refName(ref: string): string {
   return ref.split("/").pop() ?? ref;
 }
 
+/**
+ * Whether a schema declares anything renderSchema knows how to render on its
+ * own. Used to decide if the non-allOf half of a schema is worth rendering:
+ * without this, a plain `{ allOf: [...] }` would render its (empty) local half
+ * through the raw-JSON fallback and emit `{} & …`.
+ */
+function declaresShape(s: Record<string, unknown>): boolean {
+  return (
+    typeof s.$ref === "string" ||
+    Array.isArray(s.oneOf) ||
+    Array.isArray(s.anyOf) ||
+    Array.isArray(s.enum) ||
+    s.const !== undefined ||
+    s.items !== undefined ||
+    s.properties !== undefined ||
+    s.type !== undefined
+  );
+}
+
+/**
+ * Parenthesize a top-level union so it doesn't read as part of a surrounding
+ * `&`. Only separators outside braces count, so a nested union or a property
+ * description containing a pipe doesn't trigger stray parentheses.
+ */
+function grouped(part: string): string {
+  let nesting = 0;
+  for (let i = 0; i < part.length; i += 1) {
+    const char = part[i];
+    if (char === "{" || char === "(" || char === "[") nesting += 1;
+    else if (char === "}" || char === ")" || char === "]") nesting -= 1;
+    else if (nesting === 0 && part.startsWith(" | ", i)) return `(${part})`;
+  }
+  return part;
+}
+
 function renderSchema(
   schema: unknown,
   defs: Record<string, unknown>,
@@ -91,6 +126,27 @@ function renderSchema(
   }
   const s = schema as Record<string, unknown>;
 
+  // allOf composes rather than replaces: it is checked before every other
+  // keyword, and renders the schema's own shape alongside its members instead
+  // of returning early. A schema carrying both allOf and properties (the usual
+  // OpenAPI-derived "extend this base" shape, and equally legal with $ref,
+  // enum, const, or items) would otherwise silently drop whichever half lost
+  // the branch race. The schema's own shape comes first, being the more
+  // specific half, and is rendered at the current depth because its members
+  // sit at this nesting level, not one below.
+  if (Array.isArray(s.allOf)) {
+    const { allOf: _members, ...own } = s;
+    const parts = declaresShape(own)
+      ? [renderSchema(own, defs, seen, depth)]
+      : [];
+    for (const member of s.allOf) {
+      parts.push(renderSchema(member, defs, seen, depth + 1));
+    }
+    if (parts.length === 0) return "unknown";
+    if (parts.length === 1) return parts[0] as string;
+    return parts.map(grouped).join(" & ");
+  }
+
   if (typeof s.$ref === "string") {
     const name = refName(s.$ref);
     if (seen.has(name)) return name;
@@ -112,6 +168,11 @@ function renderSchema(
   if (Array.isArray(s.enum)) {
     return s.enum.map((value) => JSON.stringify(value)).join(" | ");
   }
+  // Checked before type/properties so a discriminator like
+  // { type: "string", const: "emoji" } renders as "emoji" rather than string.
+  // JSON.stringify(undefined) returns undefined (not a string), so an explicit
+  // `const: undefined` must fall through to the regular type rendering.
+  if (s.const !== undefined) return JSON.stringify(s.const);
 
   const type = s.type;
   if (type === "array" || s.items) {

package/src/connectors/api.ts

@@ -1,3 +1,4 @@
+import { validateToolInput } from "../validate.js";
 import type {
   Connector,
   ConnectorCredentialConfig,
@@ -40,6 +41,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 +56,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 +72,7 @@ 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;
   return {
     id,
     title: opts.title,
@@ -74,7 +90,15 @@ 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 invalid = validateToolInput(tool.inputSchema, input, {
+          address: `${id}.${name}`,
+          logger: ctx.logger,
+        });
+        if (invalid) throw invalid;
+      }
+      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,126 @@
+// 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,
+};
+
+/** Non-negative integer milliseconds, or undefined for anything else. */
+function normalizeRetryAfterMs(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isFinite(value) || value < 0) return undefined;
+  return Math.trunc(value);
+}
+
+/**
+ * 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.
+ *
+ * `retryAfterMs` carries a wait window the connector already knows — a
+ * `Retry-After` header, say — so the engine can wait that long instead of
+ * guessing, and so an agent that receives the failure can decide when to
+ * re-issue.
+ */
+export class ConnectorCallError extends Error {
+  readonly code: ConnectorCallErrorCode;
+  readonly retryable: boolean;
+  /**
+   * Connector-known wait window in ms before this call is worth repeating,
+   * or undefined when the connector reported none. Always an own property —
+   * under ES2022 class fields the declaration itself defines it, so guarding
+   * the assignment would not keep it off the instance. Keeping the window out
+   * of the wire format is `classifyCallError`'s job, not this constructor's.
+   */
+  readonly retryAfterMs?: number;
+
+  constructor(
+    code: ConnectorCallErrorCode,
+    message: string,
+    opts: { retryable?: boolean; retryAfterMs?: number; 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];
+    this.retryAfterMs = normalizeRetryAfterMs(opts.retryAfterMs);
+  }
+}
+
+/** The `error` object surfaced in call_tool/batch_call value-mode results. */
+export interface CallErrorDetails {
+  code: string;
+  message: string;
+  retryable: boolean;
+  /**
+   * Connector-reported wait window in ms, when known. Reported verbatim — the
+   * engine bounds how long it will itself wait, but the caller sees the real
+   * window so it can schedule a re-issue.
+   */
+  retryAfterMs?: number;
+}
+
+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,
+      ...(err.retryAfterMs !== undefined
+        ? { retryAfterMs: err.retryAfterMs }
+        : {}),
+    };
+  }
+  // An aborted fetch rejects with a DOMException named "AbortError" whose
+  // message ("The operation was aborted", and variants across runtimes) matches
+  // neither heuristic below — so a call the engine itself cancelled would read
+  // as a non-retryable failure, the opposite of the truth. Note this also
+  // covers an abort the connector triggered for its own reasons; running out of
+  // time is by far the likelier cause and retryable/timeout is the safer read.
+  if (err instanceof Error && err.name === "AbortError") {
+    return { code: "timeout", message: err.message, retryable: true };
+  }
+  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,6 +61,22 @@ export interface ConnectaConfig {
    * stash the full text for get_result paging. Default 50_000.
    */
   maxResultBytes?: number;
+  /**
+   * Deadline (ms) applied to call_tool/batch_call calls that pass no
+   * `timeoutMs`, giving the connector both a budget (`ctx.timeoutMs`) and a
+   * cancellation signal (`ctx.signal`). An explicit per-call `timeoutMs` always
+   * wins. **Opt-in — undefined by default**, because switching it on globally
+   * would put a deadline on every call in an existing deployment and the
+   * failure mode is a working long-running call starting to time out.
+   * `execute_code` host calls are unaffected; they already carry a 15 s bound.
+   *
+   * Bounds a single attempt, not the whole call — the same as an explicit
+   * `timeoutMs` has always done. A call that also passes `maxRetries` can
+   * therefore run to roughly `(maxRetries + 1)` times this value plus backoff.
+   * `maxRetries` defaults to 0, so this is the total for every call that does
+   * not explicitly ask to retry.
+   */
+  defaultToolTimeoutMs?: number;
   serverInfo?: {
     name?: string;
     version?: string;
@@ -141,6 +157,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     activityReadGate: config.activityReadGate,
     activityDeploymentId: config.activityDeploymentId,
     executor: config.executor,
+    defaultToolTimeoutMs: config.defaultToolTimeoutMs,
     credentialVault,
     deploymentInfo: config.deploymentInfo,
     branding: config.branding,
@@ -159,6 +176,13 @@ 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";
+// The same argument validation api() performs, usable by connectors that
+// implement the Connector interface directly. Returns the error rather than
+// throwing so the caller decides what to do with it.
+export { validateToolInput } from "./validate.js";
+export type { ValidateToolInputOptions } from "./validate.js";
 export { bearerToken } from "./auth/bearer.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";

package/src/json-schema.ts

@@ -0,0 +1,11 @@
+// Public re-export of the JSON Schema validator connecta itself uses, so
+// downstream code that validates at build time (a manifest generator asserting
+// its own output, say) resolves the same implementation and version through an
+// explicit subpath rather than through npm hoisting.
+export { Validator } from "@cfworker/json-schema";
+export type {
+  OutputUnit,
+  Schema,
+  SchemaDraft,
+  ValidationResult,
+} from "@cfworker/json-schema";