From a03e4302482bda17dbba3371afcafc925d5cda48 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 7 Apr 2026 03:55:26 +0100
Subject: [PATCH] refactor: dedupe core error helpers

---
 extensions/memory-core/src/tools.ts      |  2 +-
 extensions/qa-lab/web/src/app.ts         | 13 ++++++------
 src/agents/pi-embedded-runner/compact.ts |  6 +++---
 src/agents/pi-embedded-runner/utils.ts   | 14 ++-----------
 src/cli/gateway-cli/shared.ts            | 25 ++----------------------
 src/secrets/shared.ts                    | 20 ++-----------------
 6 files changed, 17 insertions(+), 63 deletions(-)

diff --git a/extensions/memory-core/src/tools.ts b/extensions/memory-core/src/tools.ts
index 7e6ba2595f3..c7b54710e82 100644
--- a/extensions/memory-core/src/tools.ts
+++ b/extensions/memory-core/src/tools.ts
@@ -115,7 +115,7 @@ async function resolveMemoryReadFailureResult(params: {
       return jsonResult(supplement);
     }
   }
-  const message = params.error instanceof Error ? params.error.message : String(params.error);
+  const message = formatErrorMessage(params.error);
   return jsonResult({ path: params.relPath, text: "", disabled: true, error: message });
 }
 
diff --git a/extensions/qa-lab/web/src/app.ts b/extensions/qa-lab/web/src/app.ts
index bfecafff7f9..226720353a5 100644
--- a/extensions/qa-lab/web/src/app.ts
+++ b/extensions/qa-lab/web/src/app.ts
@@ -1,3 +1,4 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import {
   type Bootstrap,
   type OutcomesEnvelope,
@@ -157,7 +158,7 @@ export async function createQaLabApp(root: HTMLDivElement) {
       }
       state.error = null;
     } catch (error) {
-      state.error = error instanceof Error ? error.message : String(error);
+      state.error = formatErrorMessage(error);
     }
 
     /* Only re-render when data actually changed; defer if a <select> is open */
@@ -206,7 +207,7 @@ export async function createQaLabApp(root: HTMLDivElement) {
       state.activeTab = "report";
       await refresh();
     } catch (error) {
-      state.error = error instanceof Error ? error.message : String(error);
+      state.error = formatErrorMessage(error);
       render();
     } finally {
       state.busy = false;
@@ -223,7 +224,7 @@ export async function createQaLabApp(root: HTMLDivElement) {
       state.selectedThreadId = null;
       await refresh();
     } catch (error) {
-      state.error = error instanceof Error ? error.message : String(error);
+      state.error = formatErrorMessage(error);
       render();
     } finally {
       state.busy = false;
@@ -259,7 +260,7 @@ export async function createQaLabApp(root: HTMLDivElement) {
       chatScrollLocked = true;
       await refresh();
     } catch (error) {
-      state.error = error instanceof Error ? error.message : String(error);
+      state.error = formatErrorMessage(error);
       render();
     } finally {
       state.busy = false;
@@ -295,7 +296,7 @@ export async function createQaLabApp(root: HTMLDivElement) {
       state.activeTab = "chat";
       await refresh();
     } catch (error) {
-      state.error = error instanceof Error ? error.message : String(error);
+      state.error = formatErrorMessage(error);
       render();
     } finally {
       state.busy = false;
@@ -313,7 +314,7 @@ export async function createQaLabApp(root: HTMLDivElement) {
       chatScrollLocked = true;
       await refresh();
     } catch (error) {
-      state.error = error instanceof Error ? error.message : String(error);
+      state.error = formatErrorMessage(error);
       render();
     } finally {
       state.busy = false;
diff --git a/src/agents/pi-embedded-runner/compact.ts b/src/agents/pi-embedded-runner/compact.ts
index a57ded1458f..9bb06f43578 100644
--- a/src/agents/pi-embedded-runner/compact.ts
+++ b/src/agents/pi-embedded-runner/compact.ts
@@ -993,7 +993,7 @@ export async function compactEmbeddedPiSessionDirect(
               }
             } catch (err) {
               log.warn("[compaction] failed to harden manual compaction boundary", {
-                errorMessage: err instanceof Error ? err.message : String(err),
+                errorMessage: formatErrorMessage(err),
               });
             }
           }
@@ -1028,7 +1028,7 @@ export async function compactEmbeddedPiSessionDirect(
               checkpointSnapshotRetained = storedCheckpoint !== null;
             } catch (err) {
               log.warn("failed to persist compaction checkpoint", {
-                errorMessage: err instanceof Error ? err.message : String(err),
+                errorMessage: formatErrorMessage(err),
               });
             }
           }
@@ -1319,7 +1319,7 @@ export async function compactEmbeddedPiSession(
               checkpointSnapshotRetained = storedCheckpoint !== null;
             } catch (err) {
               log.warn("failed to persist compaction checkpoint", {
-                errorMessage: err instanceof Error ? err.message : String(err),
+                errorMessage: formatErrorMessage(err),
               });
             }
           }
diff --git a/src/agents/pi-embedded-runner/utils.ts b/src/agents/pi-embedded-runner/utils.ts
index 9bac18ee7b4..991e767139b 100644
--- a/src/agents/pi-embedded-runner/utils.ts
+++ b/src/agents/pi-embedded-runner/utils.ts
@@ -1,5 +1,6 @@
 import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
 import type { ReasoningLevel, ThinkLevel } from "../../auto-reply/thinking.js";
+import { formatErrorMessage } from "../../infra/errors.js";
 
 export function mapThinkingLevel(level?: ThinkLevel): ThinkingLevel {
   // pi-agent-core supports "xhigh"; OpenClaw enables it for specific models.
@@ -17,18 +18,7 @@ export function mapThinkingLevel(level?: ThinkLevel): ThinkingLevel {
 }
 
 export function describeUnknownError(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (typeof error === "string") {
-    return error;
-  }
-  try {
-    const serialized = JSON.stringify(error);
-    return serialized ?? "Unknown error";
-  } catch {
-    return "Unknown error";
-  }
+  return formatErrorMessage(error);
 }
 
 export type { ReasoningLevel, ThinkLevel };
diff --git a/src/cli/gateway-cli/shared.ts b/src/cli/gateway-cli/shared.ts
index 224cce8bda7..a7cce082c28 100644
--- a/src/cli/gateway-cli/shared.ts
+++ b/src/cli/gateway-cli/shared.ts
@@ -4,6 +4,7 @@ import {
   resolveGatewayWindowsTaskName,
 } from "../../daemon/constants.js";
 import { resolveGatewayService } from "../../daemon/service.js";
+import { formatErrorMessage } from "../../infra/errors.js";
 import { defaultRuntime } from "../../runtime.js";
 import { formatCliCommand } from "../command-format.js";
 import { parsePort } from "../shared/parse-port.js";
@@ -21,29 +22,7 @@ export const toOptionString = (value: unknown): string | undefined => {
 };
 
 export function describeUnknownError(err: unknown): string {
-  if (err instanceof Error) {
-    return err.message;
-  }
-  if (typeof err === "string") {
-    return err;
-  }
-  if (typeof err === "number" || typeof err === "bigint") {
-    return err.toString();
-  }
-  if (typeof err === "boolean") {
-    return err ? "true" : "false";
-  }
-  if (err && typeof err === "object") {
-    if ("message" in err && typeof err.message === "string") {
-      return err.message;
-    }
-    try {
-      return JSON.stringify(err);
-    } catch {
-      return "Unknown error";
-    }
-  }
-  return "Unknown error";
+  return formatErrorMessage(err);
 }
 
 export function extractGatewayMiskeys(parsed: unknown): {
diff --git a/src/secrets/shared.ts b/src/secrets/shared.ts
index 43a1ff678f1..751cf670992 100644
--- a/src/secrets/shared.ts
+++ b/src/secrets/shared.ts
@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { formatErrorMessage } from "../infra/errors.js";
 export { isRecord } from "../utils.js";
 
 export function isNonEmptyString(value: unknown): value is string {
@@ -61,22 +62,5 @@ export function writeTextFileAtomic(pathname: string, value: string, mode = 0o60
 }
 
 export function describeUnknownError(err: unknown): string {
-  if (err instanceof Error && err.message.trim().length > 0) {
-    return err.message;
-  }
-  if (typeof err === "string" && err.trim().length > 0) {
-    return err;
-  }
-  if (typeof err === "number" || typeof err === "bigint") {
-    return err.toString();
-  }
-  if (typeof err === "boolean") {
-    return err ? "true" : "false";
-  }
-  try {
-    const serialized = JSON.stringify(err);
-    return serialized ?? "unknown error";
-  } catch {
-    return "unknown error";
-  }
+  return formatErrorMessage(err);
 }