feat: preserve rich errors in dumps and MCP output

Extends the structured-clone error fallback shipped for the WS RPC
transport to the dump and MCP surfaces:

- Dumps capture `Error.cause` chains and own properties instead of
  reducing to `{ message, name }`. Static-dump promotes error-bearing
  records to structured-clone per-record (via new
  `recordSerializations`/`fallbackSerialization` manifest fields) so
  `jsonSerializable: true` functions still round-trip thrown errors
  losslessly.
- MCP replaces the bare `JSON.stringify` with a coercing helper for
  `BigInt`/`Date`/`Map`/`Set`/`Error`/cycles, since MCP wire format is
  text-only and cannot use the `s:` structured-clone prefix. Error
  responses now include `name` and `cause.message`.

Author: antfu

packages/devframe/src/client/static-rpc.ts

@@ -1,3 +1,5 @@
+import type { RpcDumpRecordError } from '../rpc/types'
+import { reviveDumpError } from '../rpc/dump-error'
 import { hash } from '../utils/hash'
 import { structuredCloneDeserialize } from '../utils/structured-clone'
 
@@ -16,6 +18,15 @@ export interface StaticRpcManifestQueryEntry {
   fallback?: string
   /** Encoder used when each record/fallback file was written. Default: `'json'`. */
   serialization?: StaticRpcSerialization
+  /**
+   * Per-record encoder override. When a record file was written with a
+   * different serializer than {@link serialization} (e.g. an error-bearing
+   * record promoted to `'structured-clone'` for a `jsonSerializable: true`
+   * function), the override is recorded here.
+   */
+  recordSerializations?: Record<string, StaticRpcSerialization>
+  /** Encoder override for the fallback shard. */
+  fallbackSerialization?: StaticRpcSerialization
 }
 
 export type StaticRpcManifestEntry
@@ -28,10 +39,7 @@ export type StaticRpcManifest = Record<string, StaticRpcManifestEntry>
 export interface StaticRpcRecord {
   inputs?: any[]
   output?: any
-  error?: {
-    message: string
-    name: string
-  }
+  error?: RpcDumpRecordError
 }
 
 function isStaticEntry(value: unknown): value is StaticRpcManifestStaticEntry {
@@ -56,11 +64,8 @@ function isRecord(value: unknown): value is StaticRpcRecord {
 }
 
 function resolveRecordOutput(record: StaticRpcRecord): any {
-  if (record.error) {
-    const error = new Error(record.error.message)
-    error.name = record.error.name
-    throw error
-  }
+  if (record.error)
+    throw reviveDumpError(record.error)
   return record.output
 }
 
@@ -124,12 +129,14 @@ export function createStaticRpcCaller(
       const recordPath = entry.records[argsHash]
 
       if (recordPath) {
-        const record = await loadQueryRecord(recordPath, entry.serialization)
+        const recordSerialization = entry.recordSerializations?.[argsHash] ?? entry.serialization
+        const record = await loadQueryRecord(recordPath, recordSerialization)
         return resolveRecordOutput(record)
       }
 
       if (entry.fallback) {
-        const fallback = await loadQueryRecord(entry.fallback, entry.serialization)
+        const fallbackSerialization = entry.fallbackSerialization ?? entry.serialization
+        const fallback = await loadQueryRecord(entry.fallback, fallbackSerialization)
         return resolveRecordOutput(fallback)
       }
 

packages/devframe/src/node/__tests__/static-dump.test.ts

@@ -216,4 +216,111 @@ describe('collectStaticRpcDump', () => {
         .toThrowError(/jsonSerializable: true.*is a Map/)
     })
   })
+
+  describe('error-bearing records', () => {
+    it('promotes error-bearing query records to structured-clone for jsonSerializable: true', async () => {
+      const flaky = defineRpcFunction({
+        name: 'test:flaky',
+        type: 'query',
+        jsonSerializable: true,
+        handler: (id: string) => {
+          if (id === 'bad')
+            throw new Error('boom')
+          return { id }
+        },
+        dump: {
+          inputs: [['good'], ['bad']],
+        },
+      })
+
+      const result = await collectStaticRpcDump([flaky], {})
+      const entry = result.manifest['test:flaky'] as {
+        type: 'query'
+        records: Record<string, string>
+        serialization: 'json'
+        recordSerializations?: Record<string, 'json' | 'structured-clone'>
+      }
+
+      expect(entry.serialization).toBe('json')
+      expect(entry.recordSerializations).toBeDefined()
+
+      const erroredKeys = Object.keys(entry.recordSerializations!)
+      expect(erroredKeys).toHaveLength(1)
+
+      const erroredPath = entry.records[erroredKeys[0]!]!
+      expect(result.files[erroredPath]!.serialization).toBe('structured-clone')
+
+      const goodPath = entry.records[Object.keys(entry.records).find(k => k !== erroredKeys[0])!]!
+      expect(result.files[goodPath]!.serialization).toBe('json')
+    })
+
+    it('keeps the entry serialization on error-bearing records when default is structured-clone', async () => {
+      const flaky = defineRpcFunction({
+        name: 'test:flaky-sc',
+        type: 'query',
+        // default jsonSerializable: false → structured-clone shards
+        handler: (id: string) => {
+          if (id === 'bad')
+            throw new Error('boom')
+          return { id }
+        },
+        dump: {
+          inputs: [['good'], ['bad']],
+        },
+      })
+
+      const result = await collectStaticRpcDump([flaky], {})
+      const entry = result.manifest['test:flaky-sc'] as {
+        serialization: 'json' | 'structured-clone'
+        recordSerializations?: Record<string, 'json' | 'structured-clone'>
+      }
+
+      expect(entry.serialization).toBe('structured-clone')
+      // No overrides — everything is already SC.
+      expect(entry.recordSerializations).toBeUndefined()
+    })
+
+    it('preserves rich error info (cause + custom props) through a full read round-trip', async () => {
+      const tags = new Map<string, number>([['a', 1]])
+      const flaky = defineRpcFunction({
+        name: 'test:flaky-roundtrip',
+        type: 'query',
+        jsonSerializable: true,
+        handler: (id: string) => {
+          if (id === 'bad') {
+            const err = new TypeError('boom', { cause: new Error('inner') }) as Error & { tags?: unknown }
+            err.tags = tags
+            throw err
+          }
+          return { id }
+        },
+        dump: {
+          inputs: [['bad']],
+        },
+      })
+
+      const result = await collectStaticRpcDump([flaky], {})
+      const entry = result.manifest['test:flaky-roundtrip'] as {
+        records: Record<string, string>
+        recordSerializations?: Record<string, 'json' | 'structured-clone'>
+      }
+
+      const recordKey = Object.keys(entry.records)[0]!
+      const recordPath = entry.records[recordKey]!
+      const file = result.files[recordPath]!
+
+      // The shard was promoted to structured-clone — verify the Error
+      // (and its Map property) round-trips losslessly through the wire format.
+      expect(file.serialization).toBe('structured-clone')
+      const wireText = structuredCloneStringify(file.data)
+      const revived = structuredCloneDeserialize(JSON.parse(wireText)) as {
+        error: { name: string, message: string, cause: { message: string }, tags: Map<string, number> }
+      }
+      expect(revived.error.name).toBe('TypeError')
+      expect(revived.error.message).toBe('boom')
+      expect(revived.error.cause.message).toBe('inner')
+      expect(revived.error.tags).toBeInstanceOf(Map)
+      expect(revived.error.tags.get('a')).toBe(1)
+    })
+  })
 })

packages/devframe/src/node/mcp/__tests__/mcp-server.test.ts

@@ -80,6 +80,47 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
+  it('coerces non-JSON values returned from a tool', async () => {
+    const { ctx, client, cleanup } = await bootPair()
+    try {
+      ctx.agent.registerTool({
+        id: 'rich',
+        description: 'Returns BigInt + Date.',
+        handler: () => ({ count: 42n, when: new Date(0) }),
+      })
+
+      const result = await client.callTool({ name: 'rich', arguments: {} })
+      const content = result.content as Array<{ type: string, text: string }>
+      expect(content[0]!.text).toContain('"42n"')
+      expect(content[0]!.text).toContain('1970-01-01T00:00:00.000Z')
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
+  it('surfaces Error name and cause when a tool throws', async () => {
+    const { ctx, client, cleanup } = await bootPair()
+    try {
+      ctx.agent.registerTool({
+        id: 'crash',
+        description: 'Throws.',
+        handler: () => {
+          throw new TypeError('boom', { cause: new Error('inner') })
+        },
+      })
+
+      const result = await client.callTool({ name: 'crash', arguments: {} })
+      expect(result.isError).toBe(true)
+      const content = result.content as Array<{ type: string, text: string }>
+      expect(content[0]!.text).toContain('TypeError: boom')
+      expect(content[0]!.text).toContain('cause: inner')
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
   it('lists and reads registered resources', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {

packages/devframe/src/node/mcp/__tests__/stringify.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest'
+import { formatMcpError, stringifyForMcp } from '../stringify'
+
+describe('stringifyForMcp', () => {
+  it('returns "undefined" sentinel for undefined', () => {
+    expect(stringifyForMcp(undefined)).toBe('undefined')
+  })
+
+  it('passes strings through unchanged', () => {
+    expect(stringifyForMcp('hello')).toBe('hello')
+  })
+
+  it('serializes plain JSON-safe objects with indentation', () => {
+    expect(stringifyForMcp({ a: 1, b: 'two' })).toBe('{\n  "a": 1,\n  "b": "two"\n}')
+  })
+
+  it('coerces BigInt to a trailing-n string', () => {
+    expect(JSON.parse(stringifyForMcp({ count: 42n }))).toEqual({ count: '42n' })
+  })
+
+  it('coerces Date to ISO string via toJSON', () => {
+    expect(JSON.parse(stringifyForMcp({ when: new Date(0) }))).toEqual({
+      when: '1970-01-01T00:00:00.000Z',
+    })
+  })
+
+  it('coerces Map to a tagged entries object', () => {
+    const value = new Map<string, number>([['a', 1], ['b', 2]])
+    expect(JSON.parse(stringifyForMcp(value))).toEqual({
+      __type: 'Map',
+      entries: [['a', 1], ['b', 2]],
+    })
+  })
+
+  it('coerces Set to a tagged entries object', () => {
+    const value = new Set(['x', 'y'])
+    expect(JSON.parse(stringifyForMcp(value))).toEqual({
+      __type: 'Set',
+      entries: ['x', 'y'],
+    })
+  })
+
+  it('serializes Error with name, message, stack, and cause', () => {
+    const inner = new Error('inner')
+    const outer = new TypeError('boom', { cause: inner })
+    const parsed = JSON.parse(stringifyForMcp(outer))
+    expect(parsed.name).toBe('TypeError')
+    expect(parsed.message).toBe('boom')
+    expect(typeof parsed.stack).toBe('string')
+    expect(parsed.cause.name).toBe('Error')
+    expect(parsed.cause.message).toBe('inner')
+  })
+
+  it('coerces Function to a readable token', () => {
+    function namedFn() {}
+    expect(JSON.parse(stringifyForMcp({ fn: namedFn }))).toEqual({
+      fn: '[Function: namedFn]',
+    })
+  })
+
+  it('coerces anonymous functions', () => {
+    expect(JSON.parse(stringifyForMcp({ fn: () => {} }))).toEqual({
+      fn: '[Function: fn]',
+    })
+  })
+
+  it('coerces Symbol to its description', () => {
+    expect(JSON.parse(stringifyForMcp({ s: Symbol('hi') }))).toEqual({
+      s: 'Symbol(hi)',
+    })
+  })
+
+  it('replaces circular refs with [Circular]', () => {
+    const obj: Record<string, unknown> = { name: 'root' }
+    obj.self = obj
+    const parsed = JSON.parse(stringifyForMcp(obj))
+    expect(parsed.name).toBe('root')
+    expect(parsed.self).toBe('[Circular]')
+  })
+
+  it('handles a mixed payload end-to-end', () => {
+    const value = {
+      count: 42n,
+      when: new Date(0),
+      tags: new Set(['a', 'b']),
+    }
+    const text = stringifyForMcp(value)
+    expect(text).toContain('"42n"')
+    expect(text).toContain('1970-01-01T00:00:00.000Z')
+    expect(text).toContain('"__type": "Set"')
+  })
+})
+
+describe('formatMcpError', () => {
+  it('returns String(value) for non-Error throws', () => {
+    expect(formatMcpError('boom')).toBe('boom')
+    expect(formatMcpError(42)).toBe('42')
+  })
+
+  it('formats an Error as "name: message"', () => {
+    expect(formatMcpError(new TypeError('bad'))).toBe('TypeError: bad')
+  })
+
+  it('appends cause.message for Error causes', () => {
+    const err = new Error('outer', { cause: new Error('inner') })
+    expect(formatMcpError(err)).toBe('Error: outer (cause: inner)')
+  })
+
+  it('appends String(cause) for non-Error causes', () => {
+    const err = new Error('outer', { cause: 'bad input' })
+    expect(formatMcpError(err)).toBe('Error: outer (cause: bad input)')
+  })
+})

packages/devframe/src/node/mcp/build-server.ts

@@ -13,6 +13,7 @@ import {
 import { join } from 'pathe'
 import { createHostContext } from '../context'
 import { logger } from '../diagnostics'
+import { formatMcpError, stringifyForMcp } from './stringify'
 import { valibotArgsToJsonSchema, valibotReturnToJsonSchema } from './to-json-schema'
 
 export interface CreateMcpServerOptions {
@@ -158,7 +159,7 @@ function registerToolHandlers(server: Server, ctx: DevToolsNodeContext): void {
         content: [
           {
             type: 'text',
-            text: stringify(result),
+            text: stringifyForMcp(result),
           },
         ],
       }
@@ -169,7 +170,7 @@ function registerToolHandlers(server: Server, ctx: DevToolsNodeContext): void {
         content: [
           {
             type: 'text',
-            text: `Error invoking "${name}": ${error instanceof Error ? error.message : String(error)}`,
+            text: `Error invoking "${name}": ${formatMcpError(error)}`,
           },
         ],
       }
@@ -218,7 +219,7 @@ function registerResourceHandlers(
           {
             uri,
             mimeType: content.mimeType ?? 'application/json',
-            text: content.text ?? stringify(content.json),
+            text: content.text ?? stringifyForMcp(content.json),
           },
         ],
       }
@@ -231,7 +232,7 @@ function registerResourceHandlers(
           {
             uri,
             mimeType: 'application/json',
-            text: stringify(state.value()),
+            text: stringifyForMcp(state.value()),
           },
         ],
       }
@@ -287,16 +288,3 @@ function parseResourceUri(uri: string): { kind: 'resource', id: string } | { kin
     return { kind: 'resource', id: decoded }
   return { kind: 'state', key: decoded }
 }
-
-function stringify(value: unknown): string {
-  if (value === undefined)
-    return 'undefined'
-  if (typeof value === 'string')
-    return value
-  try {
-    return JSON.stringify(value, null, 2)
-  }
-  catch {
-    return String(value)
-  }
-}