@zackbart/connecta 0.3.0 → 0.4.0

package/src/connectors/api.ts

@@ -1,5 +1,4 @@
-import { Validator } from "@cfworker/json-schema";
-import { ConnectorCallError } from "../errors.js";
+import { validateToolInput } from "../validate.js";
 import type {
   Connector,
   ConnectorCredentialConfig,
@@ -74,34 +73,6 @@ export function api(id: string, opts: ApiOptions): Connector {
   }));
   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,
@@ -121,27 +92,11 @@ export function api(id: string, opts: ApiOptions): Connector {
       }
       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"}`,
-          );
-        }
+        const invalid = validateToolInput(tool.inputSchema, input, {
+          address: `${id}.${name}`,
+          logger: ctx.logger,
+        });
+        if (invalid) throw invalid;
       }
       return tool.handler(input, ctx);
     },

package/src/errors.ts

@@ -19,6 +19,13 @@ const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
   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
@@ -26,15 +33,28 @@ const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
  * 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; cause?: unknown } = {},
+    opts: { retryable?: boolean; retryAfterMs?: number; cause?: unknown } = {},
   ) {
     super(
       message,
@@ -43,6 +63,7 @@ export class ConnectorCallError extends Error {
     this.name = "ConnectorCallError";
     this.code = code;
     this.retryable = opts.retryable ?? RETRYABLE_BY_CODE[code];
+    this.retryAfterMs = normalizeRetryAfterMs(opts.retryAfterMs);
   }
 }
 
@@ -51,6 +72,12 @@ 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 =
@@ -72,7 +99,23 @@ export function classifyCallError(
   fallbackCode = "connector_call_failed",
 ): CallErrorDetails {
   if (err instanceof ConnectorCallError) {
-    return { code: err.code, message: err.message, retryable: err.retryable };
+    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 {

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,
@@ -161,6 +178,11 @@ 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";

package/src/meta-tools.ts

@@ -53,6 +53,49 @@ const dec = new TextDecoder();
 
 type ErrorDetails = CallErrorDetails;
 
+/**
+ * The longest the engine will park a synchronous inbound request in *waiting
+ * alone*. The engine already treats ~15 s as the outer bound of one reasonable
+ * connector call (EXECUTE_HOST_CALL_TIMEOUT_MS), so sleeping for minutes trades
+ * a fast, informative failure for a hung one. A connector-reported window this
+ * long isn't truncated — it's declined (see `retryBackoffMs`) and reported
+ * verbatim as `error.retryAfterMs`, so the agent, which can afford to wait,
+ * decides when to re-issue.
+ */
+export const MAX_RETRY_BACKOFF_MS = 10_000;
+
+/** A finite, positive integer number of milliseconds, or undefined. */
+function normalizeTimeoutMs(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || !(value > 0)) {
+    return undefined;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+/**
+ * How long to wait before the next attempt, or `undefined` for "don't retry".
+ *
+ * A connector that read a `Retry-After` header knows the window exactly, so it
+ * is honoured **exactly or not at all**: truncating an exponential *guess* is
+ * harmless, but truncating a *known* window means deliberately retrying inside
+ * a rate limit — the harm this channel exists to prevent. A window longer than
+ * `MAX_RETRY_BACKOFF_MS` therefore declines the retry rather than shortening
+ * it. (`retryAfterMs` is normalized non-negative, so `0` means "retry now".)
+ * Connectors that report no window keep the historical exponential guess.
+ *
+ * Waits are per attempt, matching the per-attempt `timeoutMs` race in
+ * `runCall`. Exported for direct testing.
+ */
+export function retryBackoffMs(
+  attempt: number,
+  retryAfterMs: number | undefined,
+): number | undefined {
+  if (retryAfterMs === undefined) {
+    return Math.min(250 * 2 ** (attempt - 1), 1_000);
+  }
+  return retryAfterMs <= MAX_RETRY_BACKOFF_MS ? retryAfterMs : undefined;
+}
+
 /** Details for failures that never reached a connector (no thrown value). */
 function errorDetails(code: string, message: string): ErrorDetails {
   return { code, message, retryable: messageLooksRetryable(message) };
@@ -260,18 +303,22 @@ export interface SkillArgs {
 /**
  * The nine meta-tool handlers over a registry. Exported for direct testing;
  * registerMetaTools() wires them onto an McpServer. `opts.maxResultBytes`
- * overrides the registry's default result-size cap. (execute_code, the optional
- * tenth tool, is registered separately by registerExecuteTool.)
+ * overrides the registry's default result-size cap; `opts.defaultToolTimeoutMs`
+ * supplies a deadline for calls that don't carry one. (execute_code, the
+ * optional tenth tool, is registered separately by registerExecuteTool.)
  */
 export function createMetaTools(
   registry: Registry,
   baseUrl: string,
   opts: {
     maxResultBytes?: number;
+    /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
+    defaultToolTimeoutMs?: number;
     activity?: ActivityRequestContext;
   } = {},
 ) {
   const cap = opts.maxResultBytes ?? registry.maxResultBytes;
+  const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   // createMetaTools() is called once per inbound MCP request. Sharing this
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
@@ -356,10 +403,9 @@ export function createMetaTools(
     }
     const results = registry.resultsStorage();
     const fields = call.fields && call.fields.length > 0 ? call.fields : null;
-    const timeoutMs =
-      call.timeoutMs && call.timeoutMs > 0
-        ? Math.max(1, Math.trunc(call.timeoutMs))
-        : undefined;
+    // An explicit per-call deadline always wins; the config default only fills
+    // the gap, and stays off entirely when the deployment sets none.
+    const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
     const maxRetries = Math.min(
       2,
       Math.max(0, Math.trunc(call.maxRetries ?? 0)),
@@ -451,12 +497,18 @@ export function createMetaTools(
         connectorMs += Date.now() - connectorStarted;
         const details = classifyCallError(err);
         if (attempts <= maxRetries && retrySafe && details.retryable) {
-          const backoffStarted = Date.now();
-          await new Promise((resolve) =>
-            setTimeout(resolve, Math.min(250 * 2 ** (attempts - 1), 1_000)),
-          );
-          backoffMs += Date.now() - backoffStarted;
-          continue;
+          const wait = retryBackoffMs(attempts, details.retryAfterMs);
+          if (wait !== undefined) {
+            const backoffStarted = Date.now();
+            if (wait > 0) {
+              await new Promise((resolve) => setTimeout(resolve, wait));
+            }
+            backoffMs += Date.now() - backoffStarted;
+            continue;
+          }
+          // The reported window is longer than the engine will park a
+          // synchronous request for. Fall through to failure with
+          // retryAfterMs reported verbatim so the agent can re-issue.
         }
         registry.recordFailure(
           resolved.connector.id,
@@ -987,11 +1039,13 @@ export function registerMetaTools(
   ctx: {
     baseUrl: string;
     maxResultBytes?: number;
+    defaultToolTimeoutMs?: number;
     activity?: ActivityRequestContext;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
     maxResultBytes: ctx.maxResultBytes,
+    defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
     activity: ctx.activity,
   });
 

package/src/server.ts

@@ -47,6 +47,8 @@ export interface ServerOptions {
   activityReadGate?: ActivityReadGate;
   activityDeploymentId?: string;
   deploymentInfo?: Record<string, unknown>;
+  /** Deadline for call_tool/batch_call calls that pass no timeoutMs. Off when unset. */
+  defaultToolTimeoutMs?: number;
   /** When set, the execute_code meta-tool is registered on top of the nine. */
   executor?: Executor;
   /** Encrypted connector-credential storage backing the authenticated /ui controls. */
@@ -517,7 +519,11 @@ async function serveMcp(
         logger: opts.logger,
       }
     : undefined;
-  registerMetaTools(server, opts.registry, { baseUrl, activity });
+  registerMetaTools(server, opts.registry, {
+    baseUrl,
+    activity,
+    defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
+  });
   if (opts.executor) {
     registerExecuteTool(server, opts.registry, {
       baseUrl,

package/src/validate.ts

@@ -0,0 +1,96 @@
+import { Validator } from "@cfworker/json-schema";
+import { ConnectorCallError } from "./errors.js";
+import type { JsonSchema, Logger } from "./types.js";
+
+export interface ValidateToolInputOptions {
+  /**
+   * Tool address used in the error and warning text, conventionally
+   * `"connectorId.toolName"`.
+   */
+  address: string;
+  /**
+   * Destination for the one-time warning emitted when a schema turns out to be
+   * unusable. Default console.
+   */
+  logger?: Logger;
+}
+
+// Lazy validator cache keyed by the schema object itself; null marks a schema
+// the validator rejected (warned once, then passed through rather than
+// breaking a working tool). A WeakMap so schemas belonging to a discarded
+// connector are collectable, the same pattern compactSchema uses.
+const validators = new WeakMap<JsonSchema, Validator | null>();
+
+function disableValidation(
+  schema: JsonSchema,
+  address: string,
+  logger: Logger,
+  err: unknown,
+): void {
+  validators.set(schema, null);
+  logger.warn(
+    `[connecta] tool "${address}" has an inputSchema the validator cannot use (${
+      err instanceof Error ? err.message : String(err)
+    }) — arguments are not validated`,
+  );
+}
+
+/**
+ * Validate call arguments against a tool's JSON Schema.
+ *
+ * Returns a non-retryable `invalid_args` ConnectorCallError describing the
+ * mismatch, or null when the arguments are acceptable. It deliberately returns
+ * rather than throws: the caller decides what to do with the failure, which is
+ * what lets a connector own its error prose, or strip connector-wide
+ * convention arguments (a `confirm` flag on writes, say) that individual tool
+ * schemas do not declare before deciding the call is really invalid.
+ *
+ * A schema the validator cannot compile (or that only fails on first use, e.g.
+ * an unresolvable `$ref`) is warned about once and then passed through — a
+ * broken schema should not break an otherwise working tool.
+ *
+ * The compiled validator is cached by **schema object identity**, so pass a
+ * stable object: hold the parsed manifest and hand the same schema back on
+ * every call. A schema rebuilt per call is a cache miss every time — it still
+ * validates correctly, but recompiles the validator on each call, silently and
+ * with nothing to show for it but latency.
+ *
+ * `api()` uses this internally; it is exported for connectors that implement
+ * the `Connector` interface directly.
+ */
+export function validateToolInput(
+  schema: JsonSchema,
+  args: unknown,
+  opts: ValidateToolInputOptions,
+): ConnectorCallError | null {
+  const logger = opts.logger ?? console;
+  let validator = validators.get(schema);
+  if (validator === undefined) {
+    try {
+      validator = new Validator(schema as never, "2020-12", false);
+      validators.set(schema, validator);
+    } catch (err) {
+      disableValidation(schema, opts.address, logger, err);
+      validator = null;
+    }
+  }
+  let result;
+  try {
+    result = validator?.validate(args);
+  } catch (err) {
+    // e.g. an unresolvable $ref — surfaces on first validate, not compile.
+    disableValidation(schema, opts.address, logger, 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("; ");
+    return new ConnectorCallError(
+      "invalid_args",
+      `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`,
+    );
+  }
+  return null;
+}

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