@mlx-node/agent 0.0.12 → 0.0.15

package/src/extensions/terminal-title.ts

@@ -0,0 +1,53 @@
+/**
+ * Keep pi's terminal title branded for the mlx CLI.
+ *
+ * Pi refreshes its own title after `session_start`, so startup/rebind updates
+ * must run on the next task. Session-name changes are emitted after pi updates
+ * its title and can be handled immediately.
+ */
+
+import { basename } from 'node:path';
+
+import type { ExtensionAPI, ExtensionContext, InlineExtension } from '@earendil-works/pi-coding-agent';
+
+function buildTerminalTitle(pi: ExtensionAPI, ctx: ExtensionContext): string {
+  const cwd = basename(ctx.cwd);
+  const context = pi.getSessionName() ?? ctx.model?.id;
+  return context ? `mlx - ${context} - ${cwd}` : `mlx - ${cwd}`;
+}
+
+export function createTerminalTitleExtension(): InlineExtension {
+  return {
+    name: 'mlx-terminal-title',
+    factory: (pi: ExtensionAPI) => {
+      let pendingUpdate: ReturnType<typeof setTimeout> | undefined;
+
+      const updateTitle = (ctx: ExtensionContext): void => {
+        if (ctx.mode === 'tui') {
+          ctx.ui.setTitle(buildTerminalTitle(pi, ctx));
+        }
+      };
+
+      pi.on('session_start', (_event, ctx) => {
+        if (pendingUpdate !== undefined) clearTimeout(pendingUpdate);
+        pendingUpdate = setTimeout(() => {
+          pendingUpdate = undefined;
+          updateTitle(ctx);
+        }, 0);
+      });
+
+      pi.on('session_info_changed', (_event, ctx) => {
+        updateTitle(ctx);
+      });
+
+      pi.on('model_select', (_event, ctx) => {
+        updateTitle(ctx);
+      });
+
+      pi.on('session_shutdown', () => {
+        if (pendingUpdate !== undefined) clearTimeout(pendingUpdate);
+        pendingUpdate = undefined;
+      });
+    },
+  };
+}

package/src/extensions/trace-notice.ts

@@ -0,0 +1,37 @@
+/**
+ * Surface the native inference-log path after Pi owns the terminal.
+ *
+ * The CLI must configure tracing before importing the native addon, but a
+ * message printed at that point is erased when Pi starts its fullscreen TUI.
+ * Announcing from `session_start` keeps the early subscriber setup while
+ * placing the path in Pi's persistent chat/status area.
+ */
+
+import type { ExtensionAPI, InlineExtension } from '@earendil-works/pi-coding-agent';
+
+export function createTraceNoticeExtension(logFile: string): InlineExtension {
+  return {
+    name: 'mlx-trace-notice',
+    factory: (pi: ExtensionAPI) => {
+      let pendingNotice: ReturnType<typeof setTimeout> | undefined;
+
+      pi.on('session_start', (_event, ctx) => {
+        if (pendingNotice !== undefined) clearTimeout(pendingNotice);
+        if (ctx.mode !== 'tui') return;
+
+        // Pi renders restored session messages immediately after extension
+        // binding. Defer one task so the notice is appended after that history
+        // instead of being buried above it in resumed sessions.
+        pendingNotice = setTimeout(() => {
+          pendingNotice = undefined;
+          ctx.ui.notify(`mlx agent: inference log ${logFile}`, 'info');
+        }, 0);
+      });
+
+      pi.on('session_shutdown', () => {
+        if (pendingNotice !== undefined) clearTimeout(pendingNotice);
+        pendingNotice = undefined;
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export type { DiscoveredModelLike } from './types.js';
+
+export { type CatalogEntry, catalogRepo, catalogRepoFor, MODEL_CATALOG, visibleCatalog } from './catalog.js';
+export { createPermissionGateExtension } from './extensions/permission-gate.js';
+export {
+  createSubagentExtension,
+  discoverSubagents,
+  normalizeSubagentMode,
+  type InProcessSubagentSession,
+  type SubagentConfig,
+  type SubagentExtensionOptions,
+  type SubagentMode,
+  type SubagentSessionCreateOptions,
+} from './extensions/subagent.js';
+export { createTerminalTitleExtension } from './extensions/terminal-title.js';
+export { buildChatConfig } from './provider/chat-config.js';
+export { contextToChatMessages, toolsToDefinitions } from './provider/convert-messages.js';
+export { TurnEmitter } from './provider/events.js';
+export { createMlxProviderExtension } from './provider/index.js';
+export { MlxModelHost, type MlxModelHostOptions } from './provider/model-host.js';
+export { discoverMlxModels, type MlxModelInfo } from './provider/models.js';
+export { runAgent, type RunAgentMain, type RunAgentOptions } from './run-agent.js';
+export { makeMlxStreamSimple, type StreamSimpleHost } from './provider/stream-adapter.js';

package/src/paths.ts

@@ -0,0 +1,36 @@
+/**
+ * `$HOME/.mlx-node` layout helpers owned by the agent.
+ *
+ * The agent must not import `@mlx-node/cli` (wrong dependency direction), so
+ * the small home-directory layout it needs lives here. Mirrors
+ * `resolveMlxNodeHome()` in `@mlx-node/server/host/paths`
+ * (`packages/server/src/host/paths.ts`).
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Expand an agent directory for both the CLI and desktop settings readers.
+ * Accept home-relative paths and file URLs without trimming literal paths or
+ * expanding another user's `~user` prefix. `home` is a test seam.
+ */
+export function expandPiAgentDir(dir: string, home: string = homedir()): string {
+  if (dir === '~') return home;
+  if (dir.startsWith('~/') || (process.platform === 'win32' && dir.startsWith('~\\'))) {
+    return join(home, dir.slice(2));
+  }
+  if (dir.startsWith('file://')) return fileURLToPath(dir);
+  return dir;
+}
+
+/** Absolute path to `$HOME/.mlx-node`. */
+export function mlxNodeHome(): string {
+  return join(homedir(), '.mlx-node');
+}
+
+/** Directory holding per-process `MetricsTrace` JSONL files. */
+export function metricsTraceDir(): string {
+  return join(mlxNodeHome(), 'metrics', 'traces');
+}

package/src/provider/chat-config.ts

@@ -0,0 +1,132 @@
+/**
+ * Per-call `ChatConfig` assembly for the provider bridge.
+ *
+ * Base sampling + output budget come from the family-data launch preset
+ * (`@mlx-node/lm`), then pi's per-call `SimpleStreamOptions` overlay on top.
+ */
+
+import type { SimpleStreamOptions, ThinkingLevel } from '@earendil-works/pi-ai';
+import {
+  launchPresetFor,
+  MODEL_FAMILY_DATA,
+  type ChatConfig,
+  type ModelFamilyData,
+  type ModelType,
+  type ToolDefinition,
+} from '@mlx-node/lm';
+
+/**
+ * Model types the no-preset error names: trainable rows, then loadable rows,
+ * each in registry order. Pinned byte-exactly by
+ * `packages/agent/__test__/chat-config.test.ts`.
+ */
+const KNOWN_PRESET_MODEL_TYPES: readonly string[] = (() => {
+  const rows: readonly ModelFamilyData[] = MODEL_FAMILY_DATA;
+  const chatRows = rows.filter((row) => row.kind === 'trainable' || row.kind === 'loadable');
+  return [
+    ...chatRows.filter((row) => row.kind === 'trainable'),
+    ...chatRows.filter((row) => row.kind === 'loadable'),
+  ].map((row) => row.id);
+})();
+
+/**
+ * pi thinking level → native `reasoningEffort`. pi never delivers 'off'
+ * here (the agent loop converts it to `undefined` before the provider
+ * sees it), so `undefined` is the "thinking disabled" signal → 'none'.
+ */
+const THINKING_LEVEL_TO_EFFORT: Record<ThinkingLevel, 'low' | 'medium' | 'high' | 'xhigh' | 'max'> = {
+  minimal: 'low',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+  xhigh: 'xhigh',
+  max: 'max',
+};
+
+export interface ResolvedReasoningMode {
+  reasoningEffort: 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  /** The `enable_thinking` value implied by `reasoningEffort` for templates. */
+  thinkingEnabled: boolean;
+}
+
+function isPositiveSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+/**
+ * Resolve Pi's thinking level once for both native config and persisted replay
+ * provenance. Keeping these values together gives generation and replay the same
+ * enabled-thinking state, including low/minimal turns.
+ */
+export function resolveReasoningMode(reasoning: ThinkingLevel | undefined): ResolvedReasoningMode {
+  const reasoningEffort = reasoning === undefined ? 'none' : THINKING_LEVEL_TO_EFFORT[reasoning];
+  return {
+    reasoningEffort,
+    thinkingEnabled: reasoningEffort !== 'none',
+  };
+}
+
+/** An explicit hard cap, independent from the model's reasoning effort. */
+export function parseThinkingBudget(value: unknown): number | undefined {
+  if (value === undefined) return undefined;
+  const budget = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : value;
+  if (typeof budget !== 'number' || !Number.isSafeInteger(budget) || budget < 0 || budget > 2_147_483_647) {
+    throw new Error('Thinking budget must be an integer between 0 and 2147483647.');
+  }
+  return budget;
+}
+
+export function buildChatConfig(
+  modelType: ModelType,
+  options: SimpleStreamOptions | undefined,
+  tools: ToolDefinition[] | undefined,
+  rootCacheOwnerId?: string,
+  resolvedReasoning = resolveReasoningMode(options?.reasoning),
+  modelMaxTokens?: unknown,
+  thinkingTokenBudget?: number,
+): ChatConfig {
+  const preset = launchPresetFor(modelType);
+  if (!preset) {
+    const known = KNOWN_PRESET_MODEL_TYPES.join(', ');
+    throw new Error(`buildChatConfig: no launch preset for model type "${modelType}" (known types: ${known})`);
+  }
+
+  // Pi's numeric budget settings currently stop at high. Preserve effort
+  // itself while using that highest configured cap for xhigh/max.
+  const budgetLevel = options?.reasoning === 'xhigh' || options?.reasoning === 'max' ? 'high' : options?.reasoning;
+  const budget = parseThinkingBudget(
+    thinkingTokenBudget ?? (budgetLevel === undefined ? undefined : options?.thinkingBudgets?.[budgetLevel]),
+  );
+  const config: ChatConfig = {
+    ...(budget === undefined ? {} : { thinkingTokenBudget: budget }),
+    ...preset.sampling,
+    maxNewTokens: preset.maxOutputTokens,
+    reasoningEffort: resolvedReasoning.reasoningEffort,
+    // The terminal native chunk carries TTFT/prefill/decode telemetry when
+    // requested. The provider keeps it transient and only renders it in TUI.
+    reportPerformance: true,
+  };
+  // Pi assigns one stable id to the root AgentSession and a distinct id to
+  // every in-memory subagent session. Native Qwen3.5 uses this only to retain
+  // GDN sidecars per logical branch; PagedAttention KV blocks remain shared by
+  // their existing exact content hashes.
+  if (options?.sessionId !== undefined) config.cacheOwnerId = options.sessionId;
+  // The active owner above can be a child AgentSession. Keep the current
+  // top-level session identity separate so a /new or /resume rotation updates
+  // which branch the bounded GDN sidecar store protects from child eviction.
+  if (rootCacheOwnerId !== undefined) config.cacheRootOwnerId = rootCacheOwnerId;
+  const explicitMaxTokens = options?.maxTokens;
+  if (isPositiveSafeInteger(explicitMaxTokens)) {
+    // A valid per-call provider option is the topmost layer.
+    config.maxNewTokens = explicitMaxTokens;
+  } else if (isPositiveSafeInteger(modelMaxTokens)) {
+    // Normal Pi agent turns omit SimpleStreamOptions.maxTokens. Honor the
+    // composed Model metadata (including models.json modelOverrides) without
+    // allowing malformed/hostile metadata to replace the family preset.
+    config.maxNewTokens = modelMaxTokens;
+  }
+  if (options?.temperature !== undefined) config.temperature = options.temperature;
+  if (tools && tools.length > 0) config.tools = tools;
+  // `reuseCache` is deliberately NOT set: ChatSession.mergeConfig forces it on.
+  return config;
+}

package/src/provider/convert-messages.ts

@@ -0,0 +1,273 @@
+/**
+ * pi `Context` → native `ChatMessage[]` / `ToolDefinition[]` conversion.
+ *
+ * The provider bridge replays pi's full message history through
+ * `ChatSession.primeHistory()` on every LLM call, so this conversion must
+ * be deterministic and byte-stable: an unstable rendering (key-order
+ * churn, nondeterministic joins) would change the token prefix between
+ * replays and silently kill native KV-cache reuse.
+ */
+
+import type { Context, ImageContent, Message, TextContent, Tool } from '@earendil-works/pi-ai';
+import type { ChatMessage, ToolDefinition } from '@mlx-node/lm';
+
+const IMAGE_PLACEHOLDER = '[image omitted]';
+const PI_NON_VISION_IMAGE_NOTE =
+  '[Current model does not support images. The image will be omitted from this request.]';
+const TOOL_RESULT_IMAGE_PLACEHOLDER = '(see attached image)';
+const TOOL_RESULT_IMAGE_PROMPT = 'Attached image(s) from tool result:';
+
+interface ConvertedParts {
+  content: string;
+  images?: Uint8Array[];
+}
+
+interface ConvertedMessage {
+  message: ChatMessage;
+  toolResultImages?: Uint8Array[];
+}
+
+/**
+ * Convert Pi's mixed text/image blocks into the native message shape.
+ *
+ * Text-only models retain the historical byte-stable placeholder rendering.
+ * Image-capable models keep text order and image order independently — the
+ * most ordering the native `ChatMessage { content, images }` shape can express
+ * — while decoding Pi's base64 payloads into the bytes consumed by NAPI.
+ */
+function convertParts(
+  parts: ReadonlyArray<TextContent | ImageContent>,
+  supportsImages: boolean,
+  stripStaleToolImageNote = false,
+): ConvertedParts {
+  if (!supportsImages) {
+    return {
+      content: parts.map((part) => (part.type === 'image' ? IMAGE_PLACEHOLDER : part.text)).join('\n'),
+    };
+  }
+
+  const text: string[] = [];
+  const images: Uint8Array[] = [];
+  for (const part of parts) {
+    if (part.type === 'image') {
+      images.push(Buffer.from(part.data, 'base64'));
+    } else {
+      // Pi added this exact standalone line to image tool results before the
+      // loaded native capability could be published. A resumed pre-fix history
+      // still contains it; replaying the warning contradicts the now-loaded
+      // capability even when image processing failed before producing bytes.
+      // Scope cleanup to tool results: identical direct-user text is literal.
+      text.push(
+        stripStaleToolImageNote
+          ? part.text
+              .split('\n')
+              .filter((line) => line !== PI_NON_VISION_IMAGE_NOTE)
+              .join('\n')
+          : part.text,
+      );
+    }
+  }
+  return {
+    content: text.join('\n'),
+    ...(images.length > 0 ? { images } : {}),
+  };
+}
+
+/** Per-message conversion (byte-stable joins). Never drops — the drop / orphan
+ * repair and grouped tool-result image turn live in
+ * {@link contextToChatMessages}, mirroring pi's transformMessages and OpenAI
+ * provider conversion. */
+function convertMessage(message: Message, supportsImages: boolean): ConvertedMessage {
+  switch (message.role) {
+    case 'user': {
+      if (typeof message.content === 'string') {
+        return { message: { role: 'user', content: message.content } };
+      }
+      return { message: { role: 'user', ...convertParts(message.content, supportsImages) } };
+    }
+    case 'assistant': {
+      // Preserve the parser's reasoning body so thinking-capable templates can
+      // reconstruct the exact channel/tag sequence generated on the prior
+      // turn. The native Gemma4 parser already removes its fixed `thought\n`
+      // channel label; the template adds that label back during replay.
+      const reasoningContent = message.content
+        .filter((part) => part.type === 'thinking')
+        .map((part) => part.thinking)
+        .join('');
+      const text = message.content
+        .filter((part): part is TextContent => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+      const toolCalls = message.content
+        .filter((part) => part.type === 'toolCall')
+        .map((part) => ({ id: part.id, name: part.name, arguments: JSON.stringify(part.arguments) }));
+      const converted: ChatMessage = { role: 'assistant', content: text };
+      if (reasoningContent.length > 0) converted.reasoningContent = reasoningContent;
+      const thinkingEnabled = (message as typeof message & { mlxThinkingEnabled?: boolean }).mlxThinkingEnabled;
+      if (thinkingEnabled !== undefined) converted.thinkingEnabled = thinkingEnabled;
+      if (toolCalls.length > 0) converted.toolCalls = toolCalls;
+      return { message: converted };
+    }
+    case 'toolResult': {
+      const converted = convertParts(message.content, supportsImages, true);
+      const images = converted.images ?? [];
+      return {
+        message: {
+          role: 'tool',
+          content:
+            converted.content.length > 0
+              ? converted.content
+              : images.length > 0
+                ? TOOL_RESULT_IMAGE_PLACEHOLDER
+                : converted.content,
+          toolCallId: message.toolCallId,
+          isError: message.isError,
+        },
+        ...(images.length > 0 ? { toolResultImages: images } : {}),
+      };
+    }
+  }
+}
+
+/**
+ * Convert a pi `Context` into the `ChatMessage[]` accepted by
+ * `ChatSession.primeHistory()`.
+ *
+ * - `systemPrompt` becomes the leading `system` message.
+ * - For text-only models (the default), image parts become literal
+ *   `[image omitted]` lines.
+ * - For an image-capable loaded model, user images stay on their native user
+ *   message. Images from a consecutive tool-result run are decoded, collected
+ *   in source order, and emitted on one synthetic user message after every
+ *   textual tool message in that run. This mirrors pi's OpenAI conversion and
+ *   avoids templates that ignore images attached to the `tool` role.
+ *
+ * Two-pass mirror of pi's canonical `transformMessages` (pi-ai
+ * `dist/api/transform-messages.js`). That transform normally sanitizes the
+ * history INSIDE pi's built-in providers, but our custom `streamSimple` bypasses
+ * it (and `defaultConvertToLlm` filters by role only), so the same two passes
+ * must run here or a failed/interrupted turn reaches `primeHistory` unchanged:
+ *
+ *  1. DROP every assistant turn whose `stopReason` is `error` or `aborted` —
+ *     partial or not. These incomplete turns (partial text, a half-emitted tool
+ *     call) must not be replayed: after a native error (R2-3 resets the native
+ *     cache) or an Esc/abort, priming the invalid partial turn garbles the
+ *     continuation or leaves a dangling `<tool_call>` and corrupts the native
+ *     `unresolvedOkToolCallCount`. A dropped turn's tool calls are NOT tracked.
+ *  2. ORPHAN-REPAIR: track the tool-call ids of each RETAINED assistant and,
+ *     before every following user/assistant message and at the end, synthesize a
+ *     native tool result (`{ role: 'tool', content: 'No result provided',
+ *     isError: true }`) for any tracked call with no matching `toolResult`
+ *     (pi's `insertSyntheticToolResults`), so no assistant tool call is left
+ *     unanswered in the primed history.
+ *
+ * The happy path (every assistant completes, every tool call answered) is
+ * untouched, so the byte-stable joins that keep the replayed KV prefix stable
+ * are preserved.
+ */
+export function contextToChatMessages(context: Context, supportsImages = false): ChatMessage[] {
+  const messages: ChatMessage[] = [];
+  if (context.systemPrompt) {
+    messages.push({ role: 'system', content: context.systemPrompt });
+  }
+
+  // Orphan-repair state: the tool-call ids awaiting a result from the most
+  // recent RETAINED assistant, and the result ids seen since.
+  let pendingToolCallIds: string[] = [];
+  let seenToolResultIds = new Set<string>();
+  let pendingToolResultImages: Uint8Array[] = [];
+
+  const flushOrphans = (): void => {
+    if (pendingToolCallIds.length === 0) return;
+    for (const id of pendingToolCallIds) {
+      if (!seenToolResultIds.has(id)) {
+        messages.push({ role: 'tool', content: 'No result provided', toolCallId: id, isError: true });
+      }
+    }
+    pendingToolCallIds = [];
+    seenToolResultIds = new Set();
+  };
+
+  const flushToolResultImages = (): void => {
+    if (pendingToolResultImages.length === 0) return;
+    messages.push({
+      role: 'user',
+      content: TOOL_RESULT_IMAGE_PROMPT,
+      images: pendingToolResultImages,
+    });
+    pendingToolResultImages = [];
+  };
+
+  const flushToolResultBoundary = (): void => {
+    // A grouped image attachment is logically a user turn. Repair any missing
+    // sibling tool result before that boundary, then append the single image
+    // turn after every real/synthetic tool result.
+    flushOrphans();
+    flushToolResultImages();
+  };
+
+  for (const message of context.messages) {
+    switch (message.role) {
+      case 'user':
+        flushToolResultBoundary();
+        messages.push(convertMessage(message, supportsImages).message);
+        break;
+      case 'assistant': {
+        flushToolResultBoundary();
+        if (message.stopReason === 'error' || message.stopReason === 'aborted') {
+          break; // dropped: not primed, and its tool calls are NOT tracked
+        }
+        const converted = convertMessage(message, supportsImages).message;
+        messages.push(converted);
+        if (converted.toolCalls && converted.toolCalls.length > 0) {
+          // Native ToolCall.id is optional; only ids can be matched against a
+          // tool result, so an id-less call is never tracked for orphan repair.
+          pendingToolCallIds = converted.toolCalls.map((tc) => tc.id).filter((id): id is string => id !== undefined);
+          seenToolResultIds = new Set();
+        }
+        break;
+      }
+      case 'toolResult': {
+        seenToolResultIds.add(message.toolCallId);
+        const converted = convertMessage(message, supportsImages);
+        messages.push(converted.message);
+        if (converted.toolResultImages) {
+          pendingToolResultImages.push(...converted.toolResultImages);
+        }
+        break;
+      }
+    }
+  }
+  flushToolResultBoundary();
+  return messages;
+}
+
+/**
+ * Convert pi `Tool[]` (TypeBox-built plain JSON Schema objects) into the
+ * native OpenAI-style `ToolDefinition[]`.
+ *
+ * The NAPI layer requires `parameters.properties` as a JSON string;
+ * `JSON.stringify` preserves the schema's own key order, keeping the
+ * rendered tool block byte-stable across replays. Returns `undefined`
+ * for an absent or empty tool list so `ChatConfig.tools` stays unset.
+ */
+export function toolsToDefinitions(tools: Tool[] | undefined): ToolDefinition[] | undefined {
+  if (!tools || tools.length === 0) return undefined;
+  return tools.map((tool) => {
+    // pi's Tool.parameters is a TSchema — at runtime a plain JSON Schema
+    // object (TypeBox kind markers live on symbols, which JSON ignores).
+    const schema = tool.parameters as { properties?: Record<string, unknown>; required?: string[] };
+    return {
+      type: 'function' as const,
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: {
+          type: 'object' as const,
+          properties: JSON.stringify(schema.properties ?? {}),
+          required: schema.required,
+        },
+      },
+    };
+  });
+}

package/src/provider/error-coercion.ts

@@ -0,0 +1,36 @@
+/**
+ * Hardened coercion of arbitrary thrown values to message strings.
+ *
+ * Shared by the stream adapter's TurnEmitter-independent failsafe path
+ * and `TurnEmitter.onError`: both receive caller-supplied error values
+ * and both promise never to throw, so every read here is guarded.
+ */
+
+/**
+ * Coerce an arbitrary thrown value to a message string without trusting
+ * it: an `Error` whose `message` getter throws, an object with a poisoned
+ * `toString` / `Symbol.toPrimitive`, a null-prototype object (where
+ * `String(err)` itself throws), and a revoked Proxy — where even
+ * `err instanceof Error` throws, because `instanceof` walks the prototype
+ * chain through the (revoked or throwing) `getPrototypeOf` trap — all
+ * land on the constant fallback instead of escaping. Circular objects are
+ * fine — `String` never serializes deeply.
+ */
+export function coerceErrorMessage(err: unknown): string {
+  try {
+    // The `instanceof` check MUST live inside the guard: on a revoked
+    // Proxy (or any Proxy with a throwing `getPrototypeOf` trap) the
+    // check itself throws a TypeError before any property is read.
+    if (err instanceof Error) {
+      const { message } = err;
+      if (typeof message === 'string' && message.length > 0) return message;
+    }
+  } catch {
+    // hostile prototype walk or poisoned `message` getter — fall through
+  }
+  try {
+    return String(err);
+  } catch {
+    return 'unserializable error';
+  }
+}