@csntgao/uni-base 0.1.0

package/packages/core/tests/client.test.ts

@@ -0,0 +1,760 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  AiEmployeeClient,
+  AiEmployeeTransportError,
+  type AiEmployeeFirstMessageRequestStore,
+  type AiEmployeeMessage,
+  type AiEmployeeTransport,
+} from '../src'
+import { FakeWebSocket } from './fake-websocket'
+
+function createTransport(history: AiEmployeeMessage[] = []) {
+  return {
+    createSessionWithFirstMessage: vi.fn(async () => ({
+      sessionId: 'atomic-session-default',
+      messageId: 'atomic-message-default',
+      executionId: 'atomic-execution-default',
+      status: 'running' as const,
+      startedAt: '2026-08-18T08:00:00.000Z',
+      aeCode: 'recruit',
+      agentCode: 'default',
+      conversationType: 'default',
+    })),
+    listMessages: vi.fn(async () => history),
+    sendMessage: vi.fn(async () => undefined),
+    getAccessToken: vi.fn(async () => 'header.payload.signature'),
+  } satisfies AiEmployeeTransport
+}
+
+function createHarness(
+  transport = createTransport(),
+  options: {
+    draft?: boolean
+    firstMessageRequestStore?: AiEmployeeFirstMessageRequestStore | null
+    requestIdFactory?: () => string
+  } = {},
+) {
+  const sockets: FakeWebSocket[] = []
+  const client = new AiEmployeeClient({
+    realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+    aeCode: 'recruit',
+    agentCode: 'default',
+    transport,
+    ...(options.draft ? {} : { sessionId: 'session-1' }),
+    reconnect: { initialDelayMs: 1_000, maximumDelayMs: 4_000, jitter: 0 },
+    minimumHeartbeatMs: 1,
+    requestIdFactory: options.requestIdFactory ?? (() => '6afdb617-5997-46cf-aef1-f043c22c32de'),
+    firstMessageRequestStore: options.firstMessageRequestStore ?? null,
+    webSocketFactory: (url) => {
+      const socket = new FakeWebSocket(url)
+      sockets.push(socket)
+      return socket.asWebSocket()
+    },
+  })
+  return { client, sockets, transport }
+}
+
+async function authenticateAndReady(socket: FakeWebSocket): Promise<void> {
+  socket.open()
+  await Promise.resolve()
+  socket.receive({
+    type: 'realtime_ready',
+    channels: { ai_employee: { available: true } },
+    heartbeat_interval_seconds: 25,
+  })
+}
+
+describe('AiEmployeeClient', () => {
+  beforeEach(() => vi.useFakeTimers())
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('loads history, sends JWT only in the first frame, then subscribes', async () => {
+    const history: AiEmployeeMessage[] = [
+      {
+        id: 'history-1',
+        sessionId: 'session-1',
+        role: 'assistant',
+        content: '历史消息',
+        createdAt: '2026-08-03T00:00:00.000Z',
+      },
+    ]
+    const { client, sockets, transport } = createHarness(createTransport(history))
+    const states: string[] = []
+    client.on('connection-state-change', ({ current }) => states.push(current))
+
+    const result = await client.start()
+    expect(result.messages).toEqual(history)
+    expect(sockets).toHaveLength(1)
+    expect(sockets[0]?.url).toBe('wss://kanban.example.com/api/user-realtime/ws')
+    expect(sockets[0]?.url).not.toContain('header.payload.signature')
+
+    await authenticateAndReady(sockets[0]!)
+
+    expect(transport.getAccessToken).toHaveBeenCalledTimes(1)
+    expect(sockets[0]?.sent.map((item) => JSON.parse(item))).toEqual([
+      {
+        type: 'authenticate',
+        protocol_version: 1,
+        access_token: 'header.payload.signature',
+        requested_channels: ['ai_employee'],
+        cursors: {},
+      },
+      {
+        action: 'subscribe',
+        channel: 'ai_employee',
+        resource_type: 'session',
+        resource_id: 'session-1',
+        replay_history: false,
+      },
+    ])
+    expect(states).toEqual(['connecting', 'authenticating', 'subscribing', 'connected'])
+
+    await vi.advanceTimersByTimeAsync(25_000)
+    expect(JSON.parse(sockets[0]!.sent.at(-1)!)).toMatchObject({ action: 'ping' })
+    client.destroy()
+  })
+
+  it('accepts an anonymous principal without exposing its JWT or identity context', async () => {
+    const anonymousToken = 'anonymous.test.jwt'
+    const transport = createTransport()
+    transport.getAccessToken.mockResolvedValue(anonymousToken)
+    const { client, sockets } = createHarness(transport)
+    const readyDetails: unknown[] = []
+    const errorDetails: unknown[] = []
+    client.on('ready', (detail) => readyDetails.push(detail))
+    client.on('error', (detail) => errorDetails.push(detail))
+
+    await client.start()
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({
+      type: 'realtime_ready',
+      principal_type: 'anonymous_user',
+      scope: { anonymous_user_id: 'anonymous-user-17' },
+      channels: { ai_employee: { available: true } },
+      heartbeat_interval_seconds: 25,
+    })
+
+    expect(client.connectionState).toBe('connected')
+    expect(JSON.parse(sockets[0]!.sent[0]!)).toMatchObject({
+      type: 'authenticate',
+      access_token: anonymousToken,
+    })
+    expect(sockets[0]?.url).not.toContain(anonymousToken)
+    expect(JSON.stringify(readyDetails)).not.toContain(anonymousToken)
+    expect(JSON.stringify(readyDetails)).not.toContain('anonymous-user-17')
+    expect(JSON.stringify(errorDetails)).not.toContain(anonymousToken)
+    expect(JSON.stringify(errorDetails)).not.toContain('anonymous-user-17')
+    client.destroy()
+  })
+
+  it('deduplicates repeated realtime messages', async () => {
+    const { client, sockets } = createHarness()
+    const received: string[] = []
+    client.on('message', ({ message }) => received.push(message.id))
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+
+    const frame = {
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: {
+          JsonPatch: [
+            {
+              path: '/0',
+              value: {
+                ws_message_id: 'ws-message-1',
+                entry_type: { type: 'assistant_message' },
+                content: JSON.stringify({ text: '实时回复' }),
+              },
+            },
+          ],
+        },
+      },
+    }
+    sockets[0]?.receive(frame)
+    sockets[0]?.receive(frame)
+
+    expect(received).toEqual(['ws-message-1'])
+    expect(client.messages.filter((message) => message.id === 'ws-message-1')).toHaveLength(1)
+  })
+
+  it('uses a top-level result only when the current turn has no assistant message', async () => {
+    const { client, sockets } = createHarness()
+    const received: string[] = []
+    client.on('message', ({ message }) => received.push(message.content))
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: {
+          Ready: true,
+          JsonPatch: [
+            {
+              path: '/0',
+              value: {
+                ws_message_id: 'assistant-message-1',
+                entry_type: { type: 'assistant_message' },
+                content: JSON.stringify({ text: '同一份回复' }),
+              },
+            },
+          ],
+        },
+      },
+    })
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: { result: '同一份回复' },
+      },
+    })
+
+    expect(received).toEqual(['同一份回复'])
+    expect(client.messages.filter((message) => message.role === 'assistant')).toHaveLength(1)
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: { Ready: true },
+      },
+    })
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: { result: '仅有结果的兼容回复' },
+      },
+    })
+
+    expect(received).toEqual(['同一份回复', '仅有结果的兼容回复'])
+    client.destroy()
+  })
+
+  it('reloads history and obtains a fresh JWT after an expired-token close', async () => {
+    const transport = createTransport()
+    transport.getAccessToken
+      .mockResolvedValueOnce('anonymous.first.jwt')
+      .mockResolvedValueOnce('anonymous.refreshed.jwt')
+    const { client, sockets } = createHarness(transport)
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+
+    sockets[0]?.serverClose(4401)
+    expect(client.connectionState).toBe('reconnecting')
+    await vi.advanceTimersByTimeAsync(1_000)
+    expect(sockets).toHaveLength(2)
+    expect(transport.listMessages).toHaveBeenCalledTimes(2)
+
+    await authenticateAndReady(sockets[1]!)
+    expect(transport.getAccessToken).toHaveBeenCalledTimes(2)
+    expect(JSON.parse(sockets[1]!.sent[0]!)).toMatchObject({
+      type: 'authenticate',
+      access_token: 'anonymous.refreshed.jwt',
+    })
+    expect(errors).toContainEqual({
+      code: 'AUTHENTICATION_FAILED',
+      message: '连接凭证已失效，正在重新连接。',
+      recoverable: true,
+    })
+    expect(JSON.stringify(errors)).not.toContain('登录')
+  })
+
+  it('maps transport throttling to a stable safe error without leaking its cause', async () => {
+    const transport = createTransport()
+    transport.sendMessage.mockRejectedValueOnce(
+      Object.assign(new AiEmployeeTransportError('TOO_MANY_REQUESTS'), {
+        unsafeResponse: 'anonymous JWT and backend stack must stay private',
+      }),
+    )
+    const { client } = createHarness(transport)
+    const errors: unknown[] = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+
+    await expect(client.sendMessage('请帮我查询服务')).rejects.toMatchObject({
+      code: 'RATE_LIMITED',
+      message: '请求过于频繁，请稍后再试。',
+    })
+    expect(errors).toEqual([
+      {
+        code: 'RATE_LIMITED',
+        message: '请求过于频繁，请稍后再试。',
+        recoverable: false,
+      },
+    ])
+    expect(JSON.stringify(errors)).not.toContain('anonymous JWT')
+    expect(JSON.stringify(errors)).not.toContain('backend stack')
+    client.destroy()
+  })
+
+  it('keeps service authentication failures distinct from expired JWT and bounds retries', async () => {
+    const { client, sockets } = createHarness()
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+
+    for (let attempt = 0; attempt <= 3; attempt += 1) {
+      const socket = sockets.at(-1)!
+      socket.open()
+      await Promise.resolve()
+      socket.receive({ type: 'authentication_error', code: 'SERVICE_SIGNATURE_INVALID' })
+      socket.serverClose(4401)
+
+      if (attempt < 3) {
+        expect(client.connectionState).toBe('reconnecting')
+        await vi.advanceTimersByTimeAsync(1_000 * 2 ** attempt)
+      }
+    }
+
+    expect(client.connectionState).toBe('disconnected')
+    expect(sockets).toHaveLength(4)
+    expect(errors).toContainEqual({
+      code: 'REALTIME_UNAVAILABLE',
+      message: '实时鉴权服务暂不可用，正在重试。',
+      recoverable: true,
+    })
+    expect(errors).toContainEqual({
+      code: 'REALTIME_UNAVAILABLE',
+      message: '实时鉴权服务持续不可用，请稍后重试。',
+      recoverable: false,
+    })
+    expect(JSON.stringify(errors)).not.toContain('登录凭证已失效')
+  })
+
+  it('does not retry or overwrite an organization-context authentication error', async () => {
+    const { client, sockets } = createHarness()
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({ type: 'authentication_error', code: 'ORGANIZATION_CONTEXT_REQUIRED' })
+    sockets[0]?.serverClose(4403)
+
+    expect(client.connectionState).toBe('disconnected')
+    expect(vi.getTimerCount()).toBe(0)
+    expect(errors).toEqual([
+      {
+        code: 'ORGANIZATION_CONTEXT_REQUIRED',
+        message: '请选择企业/团队后再开始咨询。',
+        recoverable: false,
+      },
+    ])
+  })
+
+  it('stops on an invalid authentication argument without reporting a credential error', async () => {
+    const { client, sockets } = createHarness()
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({ type: 'authentication_error', code: 'INVALID_ARGUMENT' })
+    sockets[0]?.serverClose(4400)
+
+    expect(client.connectionState).toBe('disconnected')
+    expect(vi.getTimerCount()).toBe(0)
+    expect(errors).toEqual([
+      {
+        code: 'PROTOCOL_ERROR',
+        message: '实时连接协议不受支持。',
+        recoverable: false,
+      },
+    ])
+  })
+
+  it('does not treat an unknown authentication error frame as an expired JWT', async () => {
+    const { client, sockets, transport } = createHarness()
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({ type: 'authentication_error', code: 'UNRECOGNIZED_SERVER_CODE' })
+    sockets[0]?.serverClose(4401)
+
+    expect(client.connectionState).toBe('disconnected')
+    expect(vi.getTimerCount()).toBe(0)
+    expect(transport.getAccessToken).toHaveBeenCalledTimes(1)
+    expect(errors).toEqual([
+      {
+        code: 'AUTHENTICATION_FAILED',
+        message: '实时连接认证失败。',
+        recoverable: false,
+      },
+    ])
+    expect(JSON.stringify(errors)).not.toContain('UNRECOGNIZED_SERVER_CODE')
+  })
+
+  it('treats a bare service-unavailable close as bounded availability recovery', async () => {
+    const { client, sockets } = createHarness()
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+    sockets[0]?.serverClose(1013)
+
+    expect(client.connectionState).toBe('reconnecting')
+    expect(errors).toEqual([
+      {
+        code: 'REALTIME_UNAVAILABLE',
+        message: '实时鉴权服务暂不可用，正在重试。',
+        recoverable: true,
+      },
+    ])
+  })
+
+  it('keeps an atomic new conversation local until the first message is accepted', async () => {
+    const transport = {
+      ...createTransport(),
+      createSessionWithFirstMessage: vi.fn(async () => ({
+        sessionId: 'atomic-session-1',
+        messageId: 'atomic-message-1',
+        executionId: 'atomic-execution-1',
+        status: 'running' as const,
+        startedAt: '2026-08-18T08:30:00.000Z',
+        aeCode: 'recruit',
+        agentCode: 'default',
+        conversationType: 'default',
+        title: '新对话',
+        createdAt: '2026-08-18T08:30:00.000Z',
+      })),
+    } satisfies AiEmployeeTransport
+    const { client, sockets } = createHarness(transport, { draft: true })
+    const result = await client.start()
+
+    expect(result).toEqual({ sessionId: null, messages: [] })
+    expect(client.sessionId).toBeNull()
+    expect(transport.listMessages).not.toHaveBeenCalled()
+    expect(transport.createSessionWithFirstMessage).not.toHaveBeenCalled()
+    expect(sockets).toHaveLength(1)
+
+    await authenticateAndReady(sockets[0]!)
+    expect(sockets[0]?.sent.map((item) => JSON.parse(item))).toEqual([
+      {
+        type: 'authenticate',
+        protocol_version: 1,
+        access_token: 'header.payload.signature',
+        requested_channels: ['ai_employee'],
+        cursors: {},
+      },
+    ])
+
+    const message = await client.sendMessage('  帮我梳理招聘需求  ', {
+      attachments: [{ transactionId: 'upload-1', fspath: 'fs/recruit/job.pdf' }],
+      trustedContext: { source: 'job-draft' },
+    })
+
+    expect(transport.createSessionWithFirstMessage).toHaveBeenCalledWith({
+      requestId: '6afdb617-5997-46cf-aef1-f043c22c32de',
+      aeCode: 'recruit',
+      agentCode: 'default',
+      content: '帮我梳理招聘需求',
+      attachments: [{ transactionId: 'upload-1', fspath: 'fs/recruit/job.pdf' }],
+      trustedContext: { source: 'job-draft' },
+    })
+    expect(transport.sendMessage).not.toHaveBeenCalled()
+    expect(message).toMatchObject({
+      id: 'atomic-message-1',
+      sessionId: 'atomic-session-1',
+      role: 'user',
+      content: '帮我梳理招聘需求',
+    })
+    expect(client.sessionId).toBe('atomic-session-1')
+    expect(sockets[0]?.sent.map((item) => JSON.parse(item)).at(-1)).toEqual({
+      action: 'subscribe',
+      channel: 'ai_employee',
+      resource_type: 'session',
+      resource_id: 'atomic-session-1',
+      replay_history: true,
+    })
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'atomic-session-1',
+        payload: {
+          JsonPatch: [
+            {
+              path: '/0',
+              value: {
+                message_id: 'atomic-message-1',
+                ws_message_id: 'atomic-websocket-message-1',
+                entry_type: { type: 'user_message' },
+                content: JSON.stringify({ text: '帮我梳理招聘需求' }),
+                create_time: '2026-08-18T08:30:00.000Z',
+              },
+            },
+          ],
+        },
+      },
+    })
+    expect(client.messages.filter((item) => item.id === 'atomic-message-1')).toHaveLength(1)
+    client.destroy()
+  })
+
+  it('reuses the first-message request id after a failed atomic attempt', async () => {
+    const transport = {
+      ...createTransport(),
+      createSessionWithFirstMessage: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('unsafe transient response'))
+        .mockResolvedValueOnce({
+          sessionId: 'atomic-session-retry',
+          messageId: 'atomic-message-retry',
+          executionId: 'atomic-execution-retry',
+          status: 'queued' as const,
+          startedAt: '2026-08-18T08:35:00.000Z',
+          aeCode: 'recruit',
+          agentCode: 'default',
+          conversationType: 'default',
+        }),
+    } satisfies AiEmployeeTransport
+    const { client } = createHarness(transport, { draft: true })
+    await client.start()
+
+    await expect(client.sendMessage('重新提交首条消息')).rejects.toMatchObject({
+      code: 'SEND_FAILED',
+    })
+    expect(client.sessionId).toBeNull()
+    expect(client.messages).toEqual([])
+
+    const message = await client.sendMessage('重新提交首条消息')
+    expect(message.id).toBe('atomic-message-retry')
+    expect(transport.createSessionWithFirstMessage).toHaveBeenCalledTimes(2)
+    expect(
+      transport.createSessionWithFirstMessage.mock.calls.map(([request]) => request.requestId),
+    ).toEqual(['6afdb617-5997-46cf-aef1-f043c22c32de', '6afdb617-5997-46cf-aef1-f043c22c32de'])
+    client.destroy()
+  })
+
+  it('reuses the persisted request id after the client is recreated', async () => {
+    let storedState: { fingerprint: string; requestId: string } | null = null
+    const store: AiEmployeeFirstMessageRequestStore = {
+      load: vi.fn(async () => storedState),
+      save: vi.fn(async (_scope, state) => {
+        storedState = { ...state }
+      }),
+      clear: vi.fn(async () => {
+        storedState = null
+      }),
+    }
+    const firstTransport = createTransport()
+    firstTransport.createSessionWithFirstMessage.mockRejectedValueOnce(
+      new Error('unsafe transient response'),
+    )
+    const first = createHarness(firstTransport, {
+      draft: true,
+      firstMessageRequestStore: store,
+      requestIdFactory: () => '6afdb617-5997-46cf-aef1-f043c22c32de',
+    })
+    await first.client.start()
+
+    await expect(first.client.sendMessage('刷新后继续重试')).rejects.toMatchObject({
+      code: 'SEND_FAILED',
+    })
+    expect(storedState).toMatchObject({
+      requestId: '6afdb617-5997-46cf-aef1-f043c22c32de',
+    })
+    expect(JSON.stringify(storedState)).not.toContain('刷新后继续重试')
+    first.client.destroy()
+
+    const secondTransport = createTransport()
+    const second = createHarness(secondTransport, {
+      draft: true,
+      firstMessageRequestStore: store,
+      requestIdFactory: () => 'ef6d946d-4186-4af5-8dc7-1be256afd711',
+    })
+    await second.client.start()
+    await second.client.sendMessage('刷新后继续重试')
+
+    expect(secondTransport.createSessionWithFirstMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ requestId: '6afdb617-5997-46cf-aef1-f043c22c32de' }),
+    )
+    expect(storedState).toBeNull()
+    second.client.destroy()
+  })
+
+  it('maps an idempotency conflict to one stable non-recoverable public error', async () => {
+    const transport = createTransport()
+    transport.createSessionWithFirstMessage.mockRejectedValueOnce(
+      Object.assign(new AiEmployeeTransportError('IDEMPOTENCY_CONFLICT'), {
+        unsafeResponse: 'original content and backend stack',
+      }),
+    )
+    const { client } = createHarness(transport, { draft: true })
+    const errors: unknown[] = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+
+    await expect(client.sendMessage('发生幂等冲突')).rejects.toMatchObject({
+      code: 'FIRST_MESSAGE_CONFLICT',
+      message: '首条消息内容已变化，请开启新对话后重试。',
+    })
+    expect(errors).toEqual([
+      {
+        code: 'FIRST_MESSAGE_CONFLICT',
+        message: '首条消息内容已变化，请开启新对话后重试。',
+        recoverable: false,
+      },
+    ])
+    expect(JSON.stringify(errors)).not.toContain('original content')
+    expect(JSON.stringify(errors)).not.toContain('backend stack')
+    client.destroy()
+  })
+
+  it('rejects an atomic response for a different AI employee without binding its session', async () => {
+    const transport = createTransport()
+    transport.createSessionWithFirstMessage.mockResolvedValueOnce({
+      sessionId: 'foreign-session',
+      messageId: 'foreign-message',
+      executionId: 'foreign-execution',
+      status: 'running',
+      startedAt: '2026-08-18T09:00:00.000Z',
+      aeCode: 'another-employee',
+      agentCode: 'default',
+      conversationType: 'default',
+    })
+    const { client } = createHarness(transport, { draft: true })
+    await client.start()
+
+    await expect(client.sendMessage('不能绑定错误响应')).rejects.toMatchObject({
+      code: 'SEND_FAILED',
+      message: '首条消息受理响应与当前数字员工不匹配。',
+    })
+    expect(client.sessionId).toBeNull()
+    expect(client.messages).toEqual([])
+    client.destroy()
+  })
+
+  it('clears a persisted retry operation when the user starts another conversation', async () => {
+    let storedState: { fingerprint: string; requestId: string } | null = {
+      fingerprint: 'v1:stale',
+      requestId: '6afdb617-5997-46cf-aef1-f043c22c32de',
+    }
+    const store: AiEmployeeFirstMessageRequestStore = {
+      load: vi.fn(async () => storedState),
+      save: vi.fn(async (_scope, state) => {
+        storedState = { ...state }
+      }),
+      clear: vi.fn(async () => {
+        storedState = null
+      }),
+    }
+    const { client } = createHarness(createTransport(), {
+      draft: true,
+      firstMessageRequestStore: store,
+    })
+    await client.start()
+
+    await client.startNewConversation()
+
+    expect(storedState).toBeNull()
+    expect(store.clear).toHaveBeenCalledTimes(1)
+    client.destroy()
+  })
+
+  it('starts a new atomic conversation as a local draft without creating a server session', async () => {
+    const transport = createTransport()
+    const { client } = createHarness(transport)
+    await client.start()
+
+    const result = await client.startNewConversation()
+
+    expect(result).toEqual({ sessionId: null, messages: [] })
+    expect(client.sessionId).toBeNull()
+    expect(transport.createSessionWithFirstMessage).not.toHaveBeenCalled()
+    client.destroy()
+  })
+
+  it('rejects a transport that only exposes the removed empty-session capability', () => {
+    const legacyTransport = {
+      getOrCreateSession: vi.fn(async () => ({ sessionId: 'legacy-session' })),
+      listMessages: vi.fn(async () => []),
+      sendMessage: vi.fn(async () => undefined),
+      getAccessToken: vi.fn(async () => 'header.payload.signature'),
+    }
+
+    expect(
+      () =>
+        new AiEmployeeClient({
+          realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+          aeCode: 'recruit',
+          agentCode: 'default',
+          transport: legacyTransport as unknown as AiEmployeeTransport,
+        }),
+    ).toThrow(/首条消息原子创建能力/)
+    expect(legacyTransport.getOrCreateSession).not.toHaveBeenCalled()
+  })
+
+  it('closes the socket and cancels heartbeat and reconnect work on destroy', async () => {
+    const { client, sockets, transport } = createHarness()
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+    expect(vi.getTimerCount()).toBe(1)
+
+    client.destroy()
+    expect(client.connectionState).toBe('destroyed')
+    expect(sockets[0]?.closeCount).toBe(1)
+    expect(vi.getTimerCount()).toBe(0)
+
+    await vi.advanceTimersByTimeAsync(60_000)
+    expect(sockets).toHaveLength(1)
+    expect(transport.getAccessToken).toHaveBeenCalledTimes(1)
+  })
+
+  it('rejects credential-bearing URLs and empty messages', async () => {
+    expect(
+      () =>
+        new AiEmployeeClient({
+          realtimeUrl: 'wss://example.com/api/user-realtime/ws?ticket=secret',
+          aeCode: 'recruit',
+          agentCode: 'default',
+          transport: createTransport(),
+        }),
+    ).toThrow(/不允许包含查询参数/)
+
+    const { client } = createHarness()
+    await client.start()
+    await expect(client.sendMessage('   ')).rejects.toMatchObject({ code: 'EMPTY_MESSAGE' })
+  })
+
+  it('does not leak a rejected token provider error', async () => {
+    const transport = createTransport()
+    transport.getAccessToken.mockRejectedValueOnce(
+      new Error('access_token=very-secret-jwt and backend stack'),
+    )
+    const { client, sockets } = createHarness(transport)
+    const errors: string[] = []
+    client.on('error', (detail) => errors.push(JSON.stringify(detail)))
+    await client.start()
+    sockets[0]?.open()
+    await Promise.resolve()
+
+    expect(errors.join('')).not.toContain('very-secret-jwt')
+    expect(errors.join('')).not.toContain('backend stack')
+    client.destroy()
+  })
+})