@zackbart/connecta 0.28.1 → 0.29.0

package/dist/errors.js

@@ -1,5 +1,63 @@
 // Typed failure contract for connector tool calls. Web-API only — no node:
 // imports here.
+const CLASSIFICATION_CODE_TABLE = {
+    timeout: true,
+    auth_required: true,
+    downstream_oauth_required: true,
+    oauth_revocation_failed: true,
+    provider_permission_denied: true,
+    rate_limited: true,
+    unavailable: true,
+    invalid_args: true,
+    not_found: true,
+    conflict: true,
+    resource_template_ambiguous: true,
+    resource_match_budget_exceeded: true,
+    input_required_unsupported: true,
+    input_required_invalid: true,
+    input_required_limit: true,
+    connector_call_failed: true,
+    executor_overloaded: true,
+    executor_cancelled: true,
+    executor_closed: true,
+    cancelled: true,
+    unknown_address: true,
+    unknown_tool: true,
+    ambiguous_tool_alias: true,
+    catalog_lookup_failed: true,
+    result_too_large: true,
+    destructive_tool_requires_approval: true,
+    auth_replay_refused: true,
+    write_outcome_unknown: true,
+    result_processing_failed: true,
+    budget_exceeded: true,
+    executor_failed: true,
+    program_error: true,
+};
+/** `value` when it is a code connecta assigns, else undefined. */
+export function classificationCode(value) {
+    return typeof value === "string" && Object.hasOwn(CLASSIFICATION_CODE_TABLE, value)
+        ? value
+        : undefined;
+}
+/** Drop oversized detail whole; clipping keys or examples changes their meaning. */
+function boundedRepair(details) {
+    if (!details)
+        return undefined;
+    try {
+        const text = JSON.stringify(details);
+        return new TextEncoder().encode(text).length <= 4096
+            ? JSON.parse(text)
+            : {
+                issues: [],
+                truncated: true,
+                exampleUnavailable: "Repair detail exceeds the response budget. Inspect the published inputSchema.",
+            };
+    }
+    catch {
+        return undefined;
+    }
+}
 export const MAX_ARGUMENT_VALIDATION_ISSUES = 3;
 const MAX_ARGUMENT_ISSUE_PATH_CHARS = 256;
 const MAX_ARGUMENT_ISSUE_CODE_CHARS = 64;
@@ -76,18 +134,13 @@ export function echoedCallArgs(args) {
     }
     if (text === undefined)
         return {};
-    return echoEncoder.encode(text).length <= MAX_ECHOED_BYTES
-        ? { args }
-        : {};
+    return echoEncoder.encode(text).length <= MAX_ECHOED_BYTES ? { args: JSON.parse(text) } : {};
 }
 function boundedValidation(details) {
     if (!details)
         return undefined;
-    let truncated = details.truncated === true ||
-        details.issues.length > MAX_ARGUMENT_VALIDATION_ISSUES;
-    const issues = details.issues
-        .slice(0, MAX_ARGUMENT_VALIDATION_ISSUES)
-        .map((issue) => {
+    let truncated = details.truncated === true || details.issues.length > MAX_ARGUMENT_VALIDATION_ISSUES;
+    const issues = details.issues.slice(0, MAX_ARGUMENT_VALIDATION_ISSUES).map((issue) => {
         const path = boundedIssueText(issue.path, MAX_ARGUMENT_ISSUE_PATH_CHARS);
         const code = boundedIssueText(issue.code, MAX_ARGUMENT_ISSUE_CODE_CHARS);
         const expected = boundedIssueText(issue.expected, MAX_ARGUMENT_ISSUE_EXPECTED_CHARS);
@@ -103,17 +156,30 @@ function boundedValidation(details) {
         ...(truncated ? { truncated: true } : {}),
     };
 }
-const NETWORK_ERROR_CODES = new Set([
-    "ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "ETIMEDOUT", "EAI_AGAIN",
-    "EAI_FAIL", "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN", "EHOSTDOWN",
-    "ECONNABORTED", "EPIPE", "EACCES", "EPERM",
-    "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT",
-    "UND_ERR_SOCKET", "timeout",
+/** The network errnos `networkErrorCode` reports, and `timeout`. */
+export const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "EAI_FAIL",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EHOSTDOWN",
+    "ECONNABORTED",
+    "EPIPE",
+    "EACCES",
+    "EPERM",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "timeout",
 ]);
 function networkCode(value) {
-    return typeof value === "string" && value.length <= 32 && NETWORK_ERROR_CODES.has(value)
-        ? value
-        : undefined;
+    return typeof value === "string" && value.length <= 32 && NETWORK_ERROR_CODES.has(value) ? value : undefined;
 }
 function sanitizedUnavailableDetails(details) {
     if (!details)
@@ -122,8 +188,7 @@ function sanitizedUnavailableDetails(details) {
     if (typeof details.host === "string") {
         try {
             const url = new URL(details.host);
-            if ((url.protocol === "https:" || url.protocol === "http:") &&
-                echoEncoder.encode(url.origin).length <= 253)
+            if ((url.protocol === "https:" || url.protocol === "http:") && echoEncoder.encode(url.origin).length <= 253)
                 host = url.origin;
         }
         catch {
@@ -137,33 +202,73 @@ function sanitizedUnavailableDetails(details) {
 export function networkErrorCode(error) {
     if (!error || typeof error !== "object")
         return undefined;
-    if (error instanceof Error &&
-        (error.name === "AbortError" || error.name === "TimeoutError")) {
+    if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) {
         return "timeout";
     }
     const runtime = error;
     const cause = runtime.cause;
-    return networkCode(runtime.code) ?? (cause && typeof cause === "object"
-        ? networkCode(cause.code)
-        : undefined);
+    return (networkCode(runtime.code) ??
+        (cause && typeof cause === "object" ? networkCode(cause.code) : undefined));
 }
-/** Use at a fetch boundary where the destination and transport failure are known. */
-export function unavailableCallError(cause, host, message = "Could not reach the downstream service.") {
-    const code = networkErrorCode(cause);
+/**
+ * Use at a fetch boundary where the destination and transport failure are
+ * known. The runtime's error is read for its errno and dropped, never kept as
+ * `cause`: its message and cause chain can quote the URL, headers, or body of
+ * the request that failed, and a logger that renders an error renders its
+ * cause. The origin and errno in `details` are what survives.
+ *
+ * The one failure kept is the request's own abort reason, when that is what
+ * the fetch rejected with: the caller wrote it, not the downstream, and it is
+ * how a cancelled request tells its reason from a network failure.
+ */
+export function unavailableCallError(failure, host, message = "Could not reach the downstream service.", signal) {
+    const code = networkErrorCode(failure);
+    const ownReason = signal?.aborted === true && failure === signal.reason;
     return new ConnectorCallError("unavailable", message, {
-        cause,
+        ...(ownReason ? { cause: failure } : {}),
         details: { ...(host ? { host } : {}), ...(code ? { code } : {}) },
     });
 }
+/**
+ * A failure told in connecta's words because the original's text came from a
+ * downstream or authorization server, which can echo what the request carried
+ * or plant whatever it likes. There is no `cause`: the original is dropped
+ * whole, never masked.
+ *
+ * It is classified exactly as the original would have been. That verdict is
+ * read from the original once, here, and kept as two flags, so withholding
+ * the text moves no failure between `timeout`, retryable, and the caller's
+ * fallback code. Never wrap a `ConnectorCallError`: it already speaks in
+ * connecta's words and carries its own code.
+ */
+export class WithheldTextError extends Error {
+    /** The original read as a timeout. */
+    timeout;
+    retryable;
+    constructor(message, original) {
+        super(message);
+        this.name = "WithheldTextError";
+        const verdict = classifyCallError(original);
+        this.timeout = verdict.code === "timeout";
+        this.retryable = verdict.retryable;
+    }
+}
 const RETRYABLE_BY_CODE = {
     timeout: true,
     rate_limited: true,
     unavailable: true,
     auth_required: false,
+    downstream_oauth_required: false,
+    oauth_revocation_failed: false,
+    provider_permission_denied: false,
     invalid_args: false,
     not_found: false,
     conflict: false,
+    resource_template_ambiguous: false,
+    resource_match_budget_exceeded: false,
     input_required_unsupported: false,
+    input_required_invalid: false,
+    input_required_limit: false,
     connector_call_failed: false,
 };
 /** Entries a conflict's `current` map may carry. */
@@ -196,9 +301,9 @@ function normalizeRetryAfterMs(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
+ * failure exactly. Untyped errors are non-retryable unless a runtime errno
+ * or abort identifies a transport failure. This class supplies the connector's
+ * reviewed verdict. `retryable` defaults per
  * code (timeout, rate_limited, and unavailable retry; the rest do not) and may
  * be overridden.
  *
@@ -220,6 +325,7 @@ export class ConnectorCallError extends Error {
     retryAfterMs;
     /** Bounded schema findings for `invalid_args`; never submitted values. */
     validation;
+    repair;
     /** Sanitized transport diagnostics for `unavailable` only. */
     details;
     /**
@@ -233,79 +339,51 @@ export class ConnectorCallError extends Error {
         this.code = code;
         this.retryable = opts.retryable ?? RETRYABLE_BY_CODE[code];
         this.retryAfterMs = normalizeRetryAfterMs(opts.retryAfterMs);
-        this.details =
-            code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
-        this.validation =
-            code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
+        this.details = code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
+        this.validation = code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
+        this.repair = code === "invalid_args" ? boundedRepair(opts.repair) : undefined;
         this.current = code === "conflict" ? boundedCurrent(opts.current) : undefined;
     }
 }
-/**
- * Codes whose retryability is a fact about connecta's own framing, never a
- * guess from text. The message embeds the address the caller asked for, so a
- * connector named `svc-503` or `temporary-export` would otherwise flip a policy
- * refusal into `retryable: true` through the heuristic below — and a caller that
- * trusts the flag would cheerfully retry a refusal forever.
- */
-const NEVER_RETRYABLE_FRAMING = new Set([
-    "result_processing_failed",
-    "unknown_address",
-    "unknown_tool",
-    "ambiguous_tool_alias",
-    "destructive_tool_requires_approval",
-]);
-/**
- * Details for a failure connecta itself framed — an address it could not
- * resolve, a tool it refuses to run — rather than one a connector threw.
- */
+/** Retryability of connecta framing depends only on its code. */
 export function framingError(code, message) {
     return {
         code,
         message,
-        retryable: NEVER_RETRYABLE_FRAMING.has(code)
-            ? false
-            : messageLooksRetryable(message),
+        retryable: code === "timeout" || code === "unavailable" || code === "rate_limited",
     };
 }
-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. */
-function messageLooksRetryable(message) {
-    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.
- */
+/** Typed connector verdicts and runtime facts only. Prose never changes a verdict. */
 export function classifyCallError(err, fallbackCode = "connector_call_failed") {
     if (err instanceof ConnectorCallError) {
         return {
             code: err.code,
             message: err.message,
             retryable: err.retryable,
-            ...(err.retryAfterMs !== undefined
-                ? { retryAfterMs: err.retryAfterMs }
-                : {}),
+            ...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
             ...(err.validation ? { validation: err.validation } : {}),
+            ...(err.repair ? { repair: err.repair } : {}),
             ...(err.details ? { details: err.details } : {}),
             ...(err.current ? { current: err.current } : {}),
         };
     }
-    // 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 };
+    if (err instanceof WithheldTextError) {
+        return {
+            code: err.timeout ? "timeout" : fallbackCode,
+            message: err.message,
+            retryable: err.retryable,
+        };
     }
     const message = err instanceof Error ? err.message : String(err);
+    const network = networkErrorCode(err);
     return {
-        code: TIMEOUT_MESSAGE_RE.test(message) ? "timeout" : fallbackCode,
+        code: network === "timeout" || network === "ETIMEDOUT" || network?.endsWith("_TIMEOUT")
+            ? "timeout"
+            : network
+                ? "unavailable"
+                : fallbackCode,
         message,
-        retryable: RETRYABLE_MESSAGE_RE.test(message),
+        retryable: network !== undefined,
     };
 }
 export function msg(err) {