@pi-unipi/web-api 2.14.1 → 2.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/web-api",
-  "version": "2.14.1",
+  "version": "2.14.2",
   "description": "Web search, read, and summarize tools with provider-based backend selection for Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "2.14.1",
+    "@pi-unipi/core": "2.14.2",
     "defuddle": "^0.18.1",
     "linkedom": "^0.18.12",
     "wreq-js": "^2.3.0"

package/src/engine/errors.ts

@@ -0,0 +1,30 @@
+/**
+ * @unipi/web-api — error serialization
+ *
+ * Engines and providers throw a mix of Error instances and plain objects
+ * (FetchError-shaped payloads, wreq-js native errors, provider API bodies).
+ * `String()` on a plain object yields "[object Object]", which masked the
+ * real diagnosis behind "Read failed: [object Object]". Everything that
+ * surfaces an error to the agent must go through describeError().
+ */
+
+/** Best-effort human-readable message for any thrown value. */
+export function describeError(error: unknown): string {
+	if (error instanceof Error) return error.message || error.toString();
+	if (typeof error === "string") return error;
+	if (error && typeof error === "object") {
+		const obj = error as Record<string, unknown>;
+		for (const key of ["message", "error", "reason", "detail"]) {
+			const v = obj[key];
+			if (typeof v === "string" && v.trim()) return v;
+		}
+		try {
+			return JSON.stringify(error) ?? String(error);
+		} catch {
+			// circular or otherwise unserializable — describe by shape
+			const keys = Object.getOwnPropertyNames(obj).join(",");
+			return keys ? `[${keys}]` : String(error);
+		}
+	}
+	return String(error);
+}

package/src/engine/extract.ts

@@ -25,6 +25,7 @@ import {
 } from "./constants.js";
 import { resolveBrowserProfile, resolveOSProfile } from "./profiles.js";
 import { getWreq, getDefuddle } from "./dependencies.js";
+import { describeError } from "./errors.js";
 import { parseHTML, extractTextContent, elementToMarkdown } from "./dom.js";
 import { truncateContent, formatContent } from "./format.js";
 
@@ -68,21 +69,22 @@ function validateUrl(url: string): URL {
 
 /**
  * Create a FetchError object.
+ *
+ * Returns a REAL Error instance carrying the FetchError fields (.error,
+ * .code, .phase, .retryable) so boundary catches surface `message` instead
+ * of serializing a plain object to "[object Object]".
  */
-function createError(
+export function createError(
   code: FetchError["code"],
   phase: FetchError["phase"],
   message: string,
   retryable: boolean,
   extra: Partial<FetchError> = {}
 ): FetchError {
-  return {
-    error: message,
-    code,
-    phase,
-    retryable,
-    ...extra,
-  };
+  const err = new Error(message) as Error & FetchError;
+  err.name = "FetchError";
+  Object.assign(err, { error: message, code, phase, retryable, ...extra });
+  return err;
 }
 
 /**
@@ -401,25 +403,26 @@ export async function defuddleFetch(
         throw error;
       }
 
-      const err = error as Error;
+      // Classify error — describeError() is safe on plain objects from the
+      // native wreq binding that carry no .message of their own.
+      const message = describeError(error);
 
-      // Classify error
-      if (err.message.includes("timeout")) {
-        throw createError("timeout", "waiting", err.message, true, {
+      if (message.includes("timeout")) {
+        throw createError("timeout", "waiting", message, true, {
           url,
           finalUrl,
           timeoutMs,
         });
       }
 
-      if (err.message.includes("network") || err.message.includes("ECONNREFUSED")) {
-        throw createError("network_error", "connecting", err.message, true, {
+      if (message.includes("network") || message.includes("ECONNREFUSED")) {
+        throw createError("network_error", "connecting", message, true, {
           url,
           finalUrl,
         });
       }
 
-      throw createError("unexpected_response", "loading", err.message, false, {
+      throw createError("unexpected_response", "loading", message, false, {
         url,
         finalUrl,
       });

package/src/providers/wigolo-client.ts

@@ -15,6 +15,8 @@
  * module-level singleton, closed on session shutdown.
  */
 
+import { describeError } from "../engine/errors.js";
+
 /** Minimal structural types — avoids a type-level dependency on the AGPL SDK. */
 interface WigoloSearchResponse {
   results?: unknown[];
@@ -112,7 +114,7 @@ export async function getWigoloClient(): Promise<WigoloClientLike> {
       try {
         return await sdk.createLocalClient();
       } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = describeError(error);
         throw new WigoloUnavailableError(`${NOT_RUNNING_MESSAGE}\n→ Cause: ${detail}`);
       }
     })();

package/src/tools.ts

@@ -28,6 +28,7 @@ import {
 } from "./engine/extract.js";
 import type { FetchOptions, FetchResult, BatchFetchResult } from "./engine/types.js";
 import { formatSingleResult, formatBatchResult } from "./engine/format.js";
+import { describeError } from "./engine/errors.js";
 
 /** Tool names */
 export const WEB_TOOLS = {
@@ -124,7 +125,7 @@ export async function withProviderFallthrough<T>(
     try {
       return await attempt(provider);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = describeError(error);
       failures.push(`${provider.name}: ${message}`);
     }
   }
@@ -339,7 +340,7 @@ export function registerWebTools(pi: ExtensionAPI): void {
         };
       } catch (error) {
         const message =
-          error instanceof Error ? error.message : String(error);
+          describeError(error);
         return {
           content: [{ type: "text", text: `Search failed: ${message}` }],
           isError: true,
@@ -503,7 +504,7 @@ export function registerWebTools(pi: ExtensionAPI): void {
                   return {
                     url,
                     status: "error",
-                    error: error instanceof Error ? error.message : String(error),
+                    error: describeError(error),
                   };
                 }
               })
@@ -560,7 +561,7 @@ export function registerWebTools(pi: ExtensionAPI): void {
         };
       } catch (error) {
         const message =
-          error instanceof Error ? error.message : String(error);
+          describeError(error);
         return {
           content: [{ type: "text", text: `Read failed: ${message}` }],
           isError: true,
@@ -623,7 +624,7 @@ export function registerWebTools(pi: ExtensionAPI): void {
         };
       } catch (error) {
         const message =
-          error instanceof Error ? error.message : String(error);
+          describeError(error);
         return {
           content: [{ type: "text", text: `Summarize failed: ${message}` }],
           isError: true,