@zackbart/connecta 0.2.1 → 0.3.0

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

@@ -159,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/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.1";
+export const CONNECTA_VERSION = "0.3.0";