refactor: migrate Serializable type to Zod schema and fix circular reference handling (#12865)

### What this PR does

Before this PR:
- `Serializable` type and `isSerializable` function were maintained
separately
- `SerializableValue` used `any` workaround (with FIXME comment about
TS2589)
- No runtime validation schema available for consumers
- `error.ts` directly assigned `error.response` without serialization,
causing type errors with `Date` objects
- `isSerializable` incorrectly returned `true` for circular references,
despite `JSON.stringify` throwing on them

After this PR:
- Unified type definition using Zod schema backed by the existing
`isSerializable` type guard via `z.custom()`, ensuring consistent
validation behavior
- Added `SerializableSchema` export for use by other modules
- Removed unused helper functions (`assertSerializable`,
`tryParseSerializable`) to keep exports minimal
- Fixed `error.ts` to properly serialize `response` field using
`safeSerialize()`
- Fixed `isSerializable` to correctly reject circular references
- Improved `isSerializable` return type to `value is Serializable` for
better type narrowing
- Added comprehensive unit tests for `isSerializable` and
`SerializableSchema`
- Removed misleading FIXME comment about TS2589

Fixes #

### Why we need it and why it was done in this way

The following tradeoffs were made:
- Used `z.custom(isSerializable)` instead of building a recursive Zod
schema with `z.lazy()`, to guarantee the Zod schema and the hand-written
type guard share identical validation logic (e.g. circular reference
handling, prototype chain checks, built-in object rejection)
- Kept existing `isSerializable()` implementation as the single source
of truth for runtime checks

The following alternatives were considered:
- Building a standalone recursive Zod schema with `z.lazy()` +
`z.union()` + `z.record()`, but this had subtle behavioral differences
from `isSerializable()` (e.g. `z.record()` does not check prototype
chains or reject `Date`/class instances)
- Using `z.infer` to derive type from schema, but `z.lazy()` requires
explicit type annotation to avoid `any` inference
- **Using Zod 4's built-in `z.json()`** — this was evaluated as a
potential replacement for the entire hand-written `isSerializable` +
`z.custom()` approach. `z.json()` validates the same recursive union
(`string | number | boolean | null | JsonValue[] | Record<string,
JsonValue>`), which is structurally identical to our `Serializable`
type. However, it was not adopted for the following reasons:
1. **Circular reference safety**: `z.json()` is built on `z.lazy()`,
which recurses without cycle detection. Passing a circular reference
causes a stack overflow instead of returning a validation failure. Our
`isSerializable()` uses a `seen` Set to detect cycles and safely returns
`false`. This is critical because `utils/serialize.ts` calls
`isSerializable()` on arbitrary values of unknown provenance.
2. **Performance**: The hand-written check uses direct `typeof`
comparisons and a single recursive walk. `z.json()` uses
`z.union([...])` which must attempt each branch in order, adding
overhead for deep/large objects.
3. **Explicit built-in object rejection**: `isSerializable()` explicitly
rejects `Date`, `RegExp`, `Map`, `Set`, `Error`, `File`, and `Blob` with
clear `instanceof` checks and a prototype chain guard, making the
rejection reasons self-documenting. `z.json()` rejects them implicitly
(they don't match any union branch), which is correct but less obvious
to readers.

### Breaking changes

None. All existing exports remain unchanged:
- `Serializable` type (same signature)
- `isSerializable` function (same behavior for all valid inputs;
circular references now correctly return `false` instead of `true` —
this is a bug fix, as circular references are not JSON-serializable and
`tryLenientSerialize` already expects them to be rejected)

### Special notes for your reviewer

- The `error.ts` change (line 196) fixes a type error that surfaced
after making `Serializable` stricter — `error.response` is
`LanguageModelResponseMetadata` which contains `Date` objects, so it
needs `safeSerialize()` instead of direct assignment.
- `SerializableSchema` uses `z.custom()` to delegate all validation to
`isSerializable`, so the two are guaranteed to be consistent.
- The circular reference fix is a bug fix: `isSerializable` previously
returned `true` for circular references to "avoid infinite recursion",
but this was incorrect — circular references cause `JSON.stringify` to
throw, so they are by definition not serializable. The
`tryLenientSerialize` design also assumes circular references are not
serializable.

### Checklist

- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780096809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. You want a
user-guide update if it's a user facing feature.

### Release note

```release-note
NONE
```

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Happy <yesreply@happy.engineering>

Author: 3 people

src/renderer/src/types/__tests__/serialize.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest'
+
+import { isSerializable, SerializableSchema } from '../serialize'
+
+describe('isSerializable', () => {
+  describe('primitives', () => {
+    it.each([
+      ['null', null],
+      ['string', 'hello'],
+      ['empty string', ''],
+      ['number', 42],
+      ['zero', 0],
+      ['NaN', NaN],
+      ['Infinity', Infinity],
+      ['negative number', -3.14],
+      ['true', true],
+      ['false', false]
+    ])('should accept %s', (_, value) => {
+      expect(isSerializable(value)).toBe(true)
+    })
+  })
+
+  describe('non-serializable primitives', () => {
+    it.each([
+      ['undefined', undefined],
+      ['symbol', Symbol('test')],
+      ['bigint', BigInt(123)],
+      ['function', () => {}]
+    ])('should reject %s', (_, value) => {
+      expect(isSerializable(value)).toBe(false)
+    })
+  })
+
+  describe('arrays', () => {
+    it('should accept empty array', () => {
+      expect(isSerializable([])).toBe(true)
+    })
+
+    it('should accept array of primitives', () => {
+      expect(isSerializable([1, 'two', true, null])).toBe(true)
+    })
+
+    it('should accept nested arrays', () => {
+      expect(
+        isSerializable([
+          [1, 2],
+          [3, [4, 5]]
+        ])
+      ).toBe(true)
+    })
+
+    it('should reject array containing undefined', () => {
+      expect(isSerializable([1, undefined, 3])).toBe(false)
+    })
+
+    it('should reject array containing function', () => {
+      expect(isSerializable([1, () => {}, 3])).toBe(false)
+    })
+  })
+
+  describe('plain objects', () => {
+    it('should accept empty object', () => {
+      expect(isSerializable({})).toBe(true)
+    })
+
+    it('should accept object with primitive values', () => {
+      expect(isSerializable({ a: 1, b: 'two', c: true, d: null })).toBe(true)
+    })
+
+    it('should accept deeply nested objects', () => {
+      expect(isSerializable({ a: { b: { c: { d: 1 } } } })).toBe(true)
+    })
+
+    it('should accept object with array values', () => {
+      expect(isSerializable({ items: [1, 2, 3] })).toBe(true)
+    })
+
+    it('should reject object with undefined value', () => {
+      expect(isSerializable({ a: undefined })).toBe(false)
+    })
+
+    it('should reject object with function value', () => {
+      expect(isSerializable({ fn: () => {} })).toBe(false)
+    })
+  })
+
+  describe('built-in objects', () => {
+    it.each([
+      ['Date', new Date()],
+      ['RegExp', /test/],
+      ['Map', new Map()],
+      ['Set', new Set()],
+      ['Error', new Error('test')]
+    ])('should reject %s', (_, value) => {
+      expect(isSerializable(value)).toBe(false)
+    })
+  })
+
+  describe('class instances', () => {
+    it('should reject class instances (non-plain objects)', () => {
+      class Foo {
+        x = 1
+      }
+      expect(isSerializable(new Foo())).toBe(false)
+    })
+  })
+
+  describe('circular references', () => {
+    it('should reject circular reference in object', () => {
+      const obj: Record<string, unknown> = { a: 1 }
+      obj.self = obj
+      expect(isSerializable(obj)).toBe(false)
+    })
+
+    it('should reject circular reference in array', () => {
+      const arr: unknown[] = [1, 2]
+      arr.push(arr)
+      expect(isSerializable(arr)).toBe(false)
+    })
+  })
+})
+
+describe('SerializableSchema', () => {
+  it('should accept valid serializable values', () => {
+    const value = { a: 1, b: [true, 'hello', null], c: { nested: 42 } }
+    expect(SerializableSchema.safeParse(value).success).toBe(true)
+  })
+
+  it('should reject non-serializable values', () => {
+    expect(SerializableSchema.safeParse(undefined).success).toBe(false)
+    expect(SerializableSchema.safeParse(() => {}).success).toBe(false)
+    expect(SerializableSchema.safeParse(new Date()).success).toBe(false)
+  })
+
+  it('should have consistent behavior with isSerializable', () => {
+    const cases = [null, 42, 'str', true, [1, 2], { a: 1 }, undefined, new Date(), new Map(), () => {}]
+    for (const value of cases) {
+      expect(SerializableSchema.safeParse(value).success).toBe(isSerializable(value))
+    }
+  })
+})

src/renderer/src/types/serialize.ts

@@ -1,19 +1,26 @@
-export type Serializable = null | boolean | number | string | { [key: string]: SerializableValue } | SerializableValue[]
+import * as z from 'zod'
 
-// FIXME: any 不是可安全序列化的类型，但是递归定义会报ts2589
-type SerializableValue = null | boolean | number | string | { [key: string]: any } | any[]
+/**
+ * Serializable type
+ */
+export type Serializable = string | number | boolean | null | Serializable[] | { [key: string]: Serializable }
 
 /**
- * 判断一个值是否可序列化（适合用于 Redux 状态）
- * 支持嵌套对象、数组的深度检测
+ * Zod schema for serializable values
+ * Uses z.custom() with isSerializable type guard to ensure consistent validation behavior
  */
+export const SerializableSchema: z.ZodType<Serializable> = z.custom<Serializable>(isSerializable)
 
-export function isSerializable(value: unknown): boolean {
-  const seen = new Set() // 用于防止循环引用
+/**
+ * Check if a value is serializable (suitable for Redux state)
+ * Supports deep detection of nested objects and arrays
+ */
+export function isSerializable(value: unknown): value is Serializable {
+  const seen = new Set<unknown>()
 
   function _isSerializable(val: unknown): boolean {
     if (val === null || val === undefined) {
-      return val !== undefined // null ✅, undefined ❌
+      return val !== undefined
     }
 
     const type = typeof val
@@ -23,23 +30,23 @@ export function isSerializable(value: unknown): boolean {
     }
 
     if (type === 'object') {
-      // 检查循环引用
+      // Circular references are not JSON-serializable
       if (seen.has(val)) {
-        return true // 避免无限递归，假设循环引用对象本身结构合法（但实际 JSON.stringify 会报错）
+        return false
       }
       seen.add(val)
 
       if (Array.isArray(val)) {
         return val.every((item) => _isSerializable(item))
       }
 
-      // 检查是否为纯对象（plain object）
+      // Check if it's a plain object
       const proto = Object.getPrototypeOf(val)
       if (proto !== null && proto !== Object.prototype && proto !== Array.prototype) {
-        return false // 不是 plain object，比如 class 实例
+        return false
       }
 
-      // 检查内置对象（如 Date、RegExp、Map、Set 等）
+      // Check for built-in objects (Date, RegExp, Map, Set, etc.)
       if (
         val instanceof Date ||
         val instanceof RegExp ||
@@ -52,17 +59,17 @@ export function isSerializable(value: unknown): boolean {
         return false
       }
 
-      // 递归检查所有属性值
+      // Recursively check all property values
       return Object.values(val).every((v) => _isSerializable(v))
     }
 
-    // function、symbol 不可序列化
+    // function, symbol are not serializable
     return false
   }
 
   try {
     return _isSerializable(value)
   } catch {
-    return false // 如出现循环引用错误等
+    return false
   }
 }

src/renderer/src/utils/error.ts

@@ -193,7 +193,7 @@ export const serializeError = (error: AiSdkErrorUnion): SerializedError => {
   if ('toolInput' in error) serializedError.toolInput = error.toolInput
   if ('text' in error) serializedError.text = error.text ?? null
   if ('originalMessage' in error) serializedError.originalMessage = safeSerialize(error.originalMessage)
-  if ('response' in error) serializedError.response = error.response ?? null
+  if ('response' in error) serializedError.response = safeSerialize(error.response)
   if ('usage' in error) serializedError.usage = safeSerialize(error.usage)
   if ('finishReason' in error) serializedError.finishReason = error.finishReason ?? null
   if ('modelId' in error) serializedError.modelId = error.modelId