@zackbart/connecta 0.2.1 → 0.4.0

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,54 @@ const DEFAULT_SEARCH_LIMIT = 25;
 const enc = new TextEncoder();
 const dec = new TextDecoder();
 
-interface ErrorDetails {
-  code: string;
-  message: string;
-  retryable: boolean;
+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:
-      /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). */
@@ -264,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.
@@ -332,11 +375,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 +389,7 @@ export function createMetaTools(
                 attempts,
                 ...(call.diagnostics ? { timing: diagnostics } : {}),
               })
-            : errorResult(message),
+            : errorResult(error.message),
         durationMs,
         attempts,
         timing: diagnostics,
@@ -355,14 +397,15 @@ 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;
-    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)),
@@ -375,13 +418,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 +436,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 +469,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,26 +495,27 @@ 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) =>
-            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,
           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 +586,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 +901,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;
@@ -985,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/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

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