@aexol/spectral 0.9.177 → 0.9.178

package/dist/server/error-humanizer.d.ts

@@ -7,7 +7,9 @@
  *
  * This module converts any caught error into a short, safe, user-facing
  * string. Raw errors are still logged server-side at the catch sites; this
- * helper only controls the user-facing message.
+ * helper only controls the user-facing message. Unknown, non-transient errors
+ * keep a sanitized version of their underlying cause so the UI can show what
+ * actually happened instead of only a generic fallback.
  */
 /**
  * Classification regex reused from agent-loop.ts (retry classification).
@@ -22,10 +24,13 @@ export declare const PROVIDER_ERROR_PATTERNS: RegExp;
  *  1. Rate limit / 429 / overloaded / 529 / "too many requests" /
  *     "temporarily rate-limited" → "Rate limit reached. Please try again in a moment."
  *  2. timeout / econnreset / "fetch failed" / network → "Network error. Please try again."
- *  3. Any other Error or non-Error value → "Something went wrong. Please try again."
+ *  3. Any other Error / string → a sanitized, concise version of the underlying
+ *     cause. Non-string/non-Error values (or values whose cause is empty after
+ *     sanitization) → "Something went wrong. Please try again."
  *
- * Never leaks raw messages, JSON blobs, or internal identifiers (org_...,
- * user_id, provider_name, is_byok, upstream model names).
+ * The sanitizer still strips JSON blobs, stack frames, URLs, absolute paths,
+ * and internal identifiers (org_..., user_id, provider_name, is_byok,
+ * upstream model names).
  */
 export declare function humanizeProviderError(err: unknown): string;
 //# sourceMappingURL=error-humanizer.d.ts.map

package/dist/server/error-humanizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-humanizer.d.ts","sourceRoot":"","sources":["../../src/server/error-humanizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QACsN,CAAC;AAoC3P;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAa1D"}
+{"version":3,"file":"error-humanizer.d.ts","sourceRoot":"","sources":["../../src/server/error-humanizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QACsN,CAAC;AAqC3P;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAa1D"}

package/dist/server/error-humanizer.js

@@ -7,7 +7,9 @@
  *
  * This module converts any caught error into a short, safe, user-facing
  * string. Raw errors are still logged server-side at the catch sites; this
- * helper only controls the user-facing message.
+ * helper only controls the user-facing message. Unknown, non-transient errors
+ * keep a sanitized version of their underlying cause so the UI can show what
+ * actually happened instead of only a generic fallback.
  */
 /**
  * Classification regex reused from agent-loop.ts (retry classification).
@@ -18,6 +20,7 @@ export const PROVIDER_ERROR_PATTERNS = /rate.?limit|429|overloaded|529|timeout|n
 const RATE_LIMIT_MESSAGE = "Rate limit reached. Please try again in a moment.";
 const NETWORK_ERROR_MESSAGE = "Network error. Please try again.";
 const GENERIC_MESSAGE = "Something went wrong. Please try again.";
+const MAX_USER_ERROR_LENGTH = 240;
 /**
  * Coerce any caught value into a single string suitable for regex matching,
  * without ever returning it to the user. This is only used internally for
@@ -57,10 +60,13 @@ function toErrorString(err) {
  *  1. Rate limit / 429 / overloaded / 529 / "too many requests" /
  *     "temporarily rate-limited" → "Rate limit reached. Please try again in a moment."
  *  2. timeout / econnreset / "fetch failed" / network → "Network error. Please try again."
- *  3. Any other Error or non-Error value → "Something went wrong. Please try again."
+ *  3. Any other Error / string → a sanitized, concise version of the underlying
+ *     cause. Non-string/non-Error values (or values whose cause is empty after
+ *     sanitization) → "Something went wrong. Please try again."
  *
- * Never leaks raw messages, JSON blobs, or internal identifiers (org_...,
- * user_id, provider_name, is_byok, upstream model names).
+ * The sanitizer still strips JSON blobs, stack frames, URLs, absolute paths,
+ * and internal identifiers (org_..., user_id, provider_name, is_byok,
+ * upstream model names).
  */
 export function humanizeProviderError(err) {
     const text = toErrorString(err);
@@ -73,5 +79,69 @@ export function humanizeProviderError(err) {
     if (PROVIDER_ERROR_PATTERNS.test(text)) {
         return NETWORK_ERROR_MESSAGE;
     }
-    return GENERIC_MESSAGE;
+    return extractSafeErrorCause(err) || GENERIC_MESSAGE;
+}
+/**
+ * Extract the deepest, non-empty, human-readable cause from an Error/string
+ * and remove anything that could leak internal identifiers, credentials,
+ * JSON payloads, stack frames, URLs, or absolute filesystem paths.
+ *
+ * Non-Error, non-string values intentionally have no safe textual cause and
+ * fall back to the generic message.
+ */
+function extractSafeErrorCause(err) {
+    if (err instanceof Error) {
+        const parts = [];
+        let current = err;
+        while (current instanceof Error) {
+            const sanitized = sanitizeErrorCause(current.message);
+            if (sanitized)
+                parts.push(sanitized);
+            current = current.cause;
+        }
+        // Some SDKs attach a non-Error cause (usually a string or parsed JSON).
+        if (typeof current === "string") {
+            const sanitized = sanitizeErrorCause(current);
+            if (sanitized)
+                parts.push(sanitized);
+        }
+        return parts.length > 0 ? parts[parts.length - 1] : "";
+    }
+    if (typeof err === "string")
+        return sanitizeErrorCause(err);
+    return "";
+}
+function sanitizeErrorCause(raw) {
+    if (!raw)
+        return "";
+    let text = raw;
+    // Remove whole JSON payloads. Raw provider errors often wrap the cause in a
+    // JSON blob carrying org ids, provider names, and model names.
+    text = text.replace(/\{[\s\S]*\}/g, " ");
+    text = text.replace(/\[[\s\S]*\]/g, " ");
+    // Remove URLs (may embed signed tokens).
+    text = text.replace(/\bhttps?:\/\/\S+/gi, " ");
+    // Remove absolute filesystem paths (POSIX and Windows).
+    text = text.replace(/(?:^|[\s("'])\/[\w.@-]+(?:\/[\w.@-]+)*/g, " ");
+    text = text.replace(/(?:^|[\s("'])[A-Za-z]:[\\/][^\s]*/g, " ");
+    // Remove internal identifiers and sensitive key/value metadata. Key/value
+    // metadata is stripped first so an identifier inside a value is consumed
+    // with the key rather than leaving a dangling key that then eats the next
+    // word in the message.
+    text = text.replace(/\b(?:provider_name|user_id|is_byok|api[_-]?key|authorization|secret|token)\s*[:=]\s*[^\s,;]+/gi, " ");
+    text = text.replace(/\bmodel\s*[:=]\s*[^\s,;]+/gi, " ");
+    text = text.replace(/\borg_[A-Za-z0-9_-]+\b/gi, " ");
+    // Remove stack-trace frames (multi-line Error messages).
+    text = text.replace(/^\s+at\s+[^\n]*/gm, " ");
+    // Remove ANSI escape sequences and normalize whitespace/punctuation noise.
+    text = text
+        .replace(/\u001b\[[0-9;]*m/g, " ")
+        .replace(/\s+/g, " ")
+        .replace(/\s*([,;:])\s*(?=[,;:.])/g, "")
+        .trim();
+    if (!text)
+        return "";
+    if (text.length <= MAX_USER_ERROR_LENGTH)
+        return text;
+    return `${text.slice(0, MAX_USER_ERROR_LENGTH - 1).trimEnd()}…`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.177",
+  "version": "0.9.178",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,