@veltra/ai 2.1.5 → 2.1.7

package/src/chat/fold.ts

@@ -0,0 +1,260 @@
+import type { AskQuestionItem } from '../tools'
+import type { ChatSessionEvent } from './session'
+import type { ChatJob, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatToolCall } from './types'
+
+function eventSeq(event: ChatSessionEvent): number | undefined {
+  return 'seq' in event ? event.seq : undefined
+}
+
+export interface ChatPendingApproval {
+  approvalId: string
+  toolName: string
+  callId?: string
+  reason?: string
+  rpcId: string
+}
+
+/** 历史回放与实时 onEvent 共用的折叠状态 */
+export interface ChatFoldState {
+  lastSeq: number | null
+  messages: ChatMessage[]
+  queue: ChatQueuedMessage[]
+  jobs: ChatJob[]
+  tokenUsage: ChatTokenUsage | null
+  projections: Record<string, unknown>
+  title: string | null
+  running: boolean
+  pendingApprovals: ChatPendingApproval[]
+  pendingQuestion: { questions: AskQuestionItem[]; rpcId: string } | null
+  error: { code: string; message: string } | null
+}
+
+export function createFoldState(): ChatFoldState {
+  return {
+    lastSeq: null,
+    messages: [],
+    queue: [],
+    jobs: [],
+    tokenUsage: null,
+    projections: {},
+    title: null,
+    running: false,
+    pendingApprovals: [],
+    pendingQuestion: null,
+    error: null
+  }
+}
+
+function mergeOptionalCount(a?: number, b?: number): number | undefined {
+  if (a == null && b == null) return undefined
+  return (a ?? 0) + (b ?? 0)
+}
+
+function addTokenUsage(a: ChatTokenUsage, b: ChatTokenUsage): ChatTokenUsage {
+  const usage: ChatTokenUsage = {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens
+  }
+  const cacheHitTokens = mergeOptionalCount(a.cacheHitTokens, b.cacheHitTokens)
+  if (cacheHitTokens != null) usage.cacheHitTokens = cacheHitTokens
+  const cacheMissTokens = mergeOptionalCount(a.cacheMissTokens, b.cacheMissTokens)
+  if (cacheMissTokens != null) usage.cacheMissTokens = cacheMissTokens
+  const cacheCreationTokens = mergeOptionalCount(a.cacheCreationTokens, b.cacheCreationTokens)
+  if (cacheCreationTokens != null) usage.cacheCreationTokens = cacheCreationTokens
+  return usage
+}
+
+function isTokenUsage(value: unknown): value is ChatTokenUsage {
+  if (value == null || typeof value !== 'object') return false
+  const usage = value as ChatTokenUsage
+  return (
+    typeof usage.promptTokens === 'number' &&
+    typeof usage.completionTokens === 'number' &&
+    typeof usage.totalTokens === 'number'
+  )
+}
+
+function replaceAt<T>(list: T[], idx: number, item: T): T[] {
+  const next = list.slice()
+  next[idx] = item
+  return next
+}
+
+function patchMessage(
+  messages: ChatMessage[],
+  id: string,
+  patch: Partial<ChatMessage>
+): ChatMessage[] {
+  const idx = messages.findIndex((m) => m.id === id)
+  if (idx < 0) {
+    return [...messages, { id, role: 'assistant', content: '', status: 'streaming', ...patch }]
+  }
+  return replaceAt(messages, idx, { ...messages[idx]!, ...patch })
+}
+
+function appendToolCall(messages: ChatMessage[], call: ChatToolCall): ChatMessage[] {
+  const idx = messages.findLastIndex((m) => m.role === 'assistant')
+  if (idx < 0) {
+    return [
+      ...messages,
+      {
+        id: `tool-host:${call.id}`,
+        role: 'assistant',
+        content: '',
+        status: 'streaming',
+        toolCalls: [call]
+      }
+    ]
+  }
+  const target = messages[idx]!
+  return replaceAt(messages, idx, { ...target, toolCalls: [...(target.toolCalls ?? []), call] })
+}
+
+function updateToolCall(
+  messages: ChatMessage[],
+  callId: string,
+  patch: Partial<ChatToolCall>
+): ChatMessage[] {
+  const idx = messages.findIndex((m) => m.toolCalls?.some((c) => c.id === callId))
+  if (idx < 0) return messages
+  const msg = messages[idx]!
+  const calls = (msg.toolCalls ?? []).slice()
+  const callIdx = calls.findIndex((c) => c.id === callId)
+  if (callIdx < 0) return messages
+  calls[callIdx] = { ...calls[callIdx]!, ...patch }
+  return replaceAt(messages, idx, { ...msg, toolCalls: calls })
+}
+
+/**
+ * 纯函数 fold：历史回放与实时 onEvent 走同一套。
+ * 后到的更小/重复 seq 不覆盖已应用事件。
+ */
+export function foldSessionEvent(state: ChatFoldState, event: ChatSessionEvent): ChatFoldState {
+  const seq = eventSeq(event)
+  if (seq != null && state.lastSeq != null && seq <= state.lastSeq) return state
+
+  const next: ChatFoldState = {
+    ...state,
+    lastSeq: seq ?? state.lastSeq,
+    projections: { ...state.projections }
+  }
+
+  switch (event.type) {
+    case 'user/message': {
+      if (next.messages.some((m) => m.id === event.messageId)) break
+      const userMessage: ChatMessage = { id: event.messageId, role: 'user', content: event.content }
+      if (event.attachments) userMessage.attachments = event.attachments
+      next.messages = [...next.messages, userMessage]
+      break
+    }
+    case 'assistant/chunk': {
+      const current = next.messages.find((m) => m.id === event.messageId)
+      next.messages = patchMessage(next.messages, event.messageId, {
+        role: 'assistant',
+        status: 'streaming',
+        content: (current?.content ?? '') + event.delta,
+        reasoning: event.reasoningDelta
+          ? (current?.reasoning ?? '') + event.reasoningDelta
+          : current?.reasoning
+      })
+      break
+    }
+    case 'assistant/message': {
+      next.messages = patchMessage(next.messages, event.messageId, {
+        role: 'assistant',
+        status: 'done',
+        content: event.content,
+        reasoning: event.reasoning,
+        toolCalls: event.toolCalls ?? next.messages.find((m) => m.id === event.messageId)?.toolCalls
+      })
+      break
+    }
+    case 'tool/call': {
+      const call: ChatToolCall = {
+        id: event.callId,
+        name: event.name,
+        arguments: event.arguments,
+        status: 'pending'
+      }
+      if (event.view !== undefined) call.view = event.view
+      next.messages = appendToolCall(next.messages, call)
+      break
+    }
+    case 'tool/result': {
+      const patch: Partial<ChatToolCall> = { status: event.status }
+      if (event.result !== undefined) patch.result = event.result
+      if (event.error !== undefined) patch.error = event.error
+      if (event.view !== undefined) patch.view = event.view
+      next.messages = updateToolCall(next.messages, event.callId, patch)
+      break
+    }
+    case 'queue/snapshot': {
+      next.queue = event.items.slice()
+      break
+    }
+    case 'jobs/snapshot': {
+      next.jobs = event.jobs.slice()
+      break
+    }
+    case 'projection': {
+      if (event.key === 'tokenUsage' && isTokenUsage(event.value)) {
+        next.tokenUsage = next.tokenUsage
+          ? addTokenUsage(next.tokenUsage, event.value)
+          : event.value
+      } else if (event.key === 'title' && typeof event.value === 'string') {
+        next.title = event.value
+      } else {
+        next.projections[event.key] = event.value
+      }
+      break
+    }
+    case 'running': {
+      next.running = event.running
+      break
+    }
+    case 'finish': {
+      next.running = false
+      break
+    }
+    case 'error': {
+      next.running = false
+      next.error = { code: event.code, message: event.message }
+      break
+    }
+    case 'approval/requested': {
+      if (event.callId) {
+        next.messages = updateToolCall(next.messages, event.callId, { status: 'awaiting-confirm' })
+      }
+      next.pendingApprovals = [
+        ...next.pendingApprovals,
+        {
+          approvalId: event.approvalId,
+          toolName: event.toolName,
+          callId: event.callId,
+          reason: event.reason,
+          rpcId: event.rpcId
+        }
+      ]
+      break
+    }
+    case 'approval/resolved': {
+      const hit = next.pendingApprovals.find((a) => a.approvalId === event.approvalId)
+      next.pendingApprovals = next.pendingApprovals.filter((a) => a.approvalId !== event.approvalId)
+      if (hit?.callId && event.outcome === 'rejected') {
+        next.messages = updateToolCall(next.messages, hit.callId, { status: 'rejected' })
+      }
+      break
+    }
+    case 'question/requested': {
+      next.pendingQuestion = { questions: event.questions, rpcId: event.rpcId }
+      break
+    }
+    case 'question/resolved': {
+      if (next.pendingQuestion?.rpcId === event.questionRpcId) next.pendingQuestion = null
+      break
+    }
+  }
+
+  return next
+}

package/src/chat/index.ts

@@ -1,3 +1,5 @@
 export * from './types'
 export * from './use-chat'
 export * from './transports'
+export * from './session'
+export * from './fold'

package/src/chat/session.ts

@@ -0,0 +1,168 @@
+import type { AskQuestionItem } from '../tools'
+import type { ChatAttachment, ChatJob, ChatQueuedMessage, ChatToolCall } from './types'
+
+/** 归一化后的服务端会话事件（协议无关） */
+export type ChatSessionEvent =
+  | {
+      type: 'user/message'
+      messageId: string
+      seq: number
+      content: string
+      attachments?: ChatAttachment[]
+    }
+  | {
+      type: 'assistant/chunk'
+      messageId: string
+      seq: number
+      delta: string
+      reasoningDelta?: string
+    }
+  | {
+      type: 'assistant/message'
+      messageId: string
+      seq: number
+      content: string
+      reasoning?: string
+      toolCalls?: ChatToolCall[]
+    }
+  | {
+      type: 'tool/call'
+      callId: string
+      name: string
+      arguments: string
+      seq: number
+      view?: unknown
+    }
+  | {
+      type: 'tool/result'
+      callId: string
+      status: 'success' | 'error' | 'rejected'
+      result?: string
+      error?: string
+      seq: number
+      view?: unknown
+    }
+  | {
+      type: 'approval/requested'
+      approvalId: string
+      toolName: string
+      callId?: string
+      reason?: string
+      rpcId: string
+    }
+  | { type: 'approval/resolved'; approvalId: string; outcome: string }
+  | { type: 'question/requested'; questions: AskQuestionItem[]; rpcId: string }
+  | { type: 'question/resolved'; questionRpcId: string; outcome: 'answered' | 'cancelled' }
+  | { type: 'queue/snapshot'; items: ChatQueuedMessage[] }
+  | { type: 'jobs/snapshot'; jobs: ChatJob[] }
+  | { type: 'projection'; key: string; value: unknown; seq: number }
+  | { type: 'running'; running: boolean }
+  | { type: 'finish' }
+  | { type: 'error'; code: string; message: string }
+
+/** 服务端会话 transport：对象形态，与函数型 ChatTransport 互斥 */
+export interface ChatSessionTransport {
+  readonly kind: 'session'
+  open(handlers: { onEvent(event: ChatSessionEvent): void; onDisconnect?(): void }): () => void
+  send(content: string, attachments?: ChatAttachment[]): Promise<void>
+  cancel(): Promise<void>
+  respond(rpcId: string, ok: boolean, value?: unknown): Promise<void>
+  fetchHistory(beforeSeq?: number): Promise<{ events: ChatSessionEvent[]; hasMore: boolean }>
+  selectModel(provider: string, model: string): Promise<void>
+}
+
+/**
+ * 协议翻译层：订阅事件流、把动作打到远端、拉历史。
+ * 时序校验 / dispose / 断线补拉 / in-flight 去重由 createServerTransport 完成。
+ */
+export interface ChatSessionAdapter {
+  subscribe(handlers: { onEvent(event: ChatSessionEvent): void; onDisconnect?(): void }): () => void
+  send(content: string, attachments?: ChatAttachment[]): Promise<void>
+  cancel(): Promise<void>
+  respond(rpcId: string, ok: boolean, value?: unknown): Promise<void>
+  fetchHistory(beforeSeq?: number): Promise<{ events: ChatSessionEvent[]; hasMore: boolean }>
+  selectModel(provider: string, model: string): Promise<void>
+}
+
+function eventSeq(event: ChatSessionEvent): number | undefined {
+  return 'seq' in event ? event.seq : undefined
+}
+
+/** 仅带 kind: 'session' 的对象为 true；函数 / null / 无 kind 均为 false */
+export function isServerTransport(t: unknown): t is ChatSessionTransport {
+  return typeof t === 'object' && t !== null && (t as { kind?: unknown }).kind === 'session'
+}
+
+function runExclusive(gate: { busy: boolean }, action: () => Promise<void>): Promise<void> {
+  if (gate.busy) return Promise.resolve()
+  gate.busy = true
+  return action().finally(() => {
+    gate.busy = false
+  })
+}
+
+/**
+ * 用 adapter 包出 ChatSessionTransport。
+ * 包内完成 seq 校验、disposer、断线补拉、动作 in-flight 去重。
+ */
+export function createServerTransport(adapter: ChatSessionAdapter): ChatSessionTransport {
+  let lastSeq: number | undefined
+  const sendGate = { busy: false }
+  const cancelGate = { busy: false }
+  const respondGate = { busy: false }
+  const selectModelGate = { busy: false }
+
+  const deliver = (event: ChatSessionEvent, onEvent: (e: ChatSessionEvent) => void) => {
+    const seq = eventSeq(event)
+    if (seq != null && lastSeq != null && seq <= lastSeq) {
+      console.warn(`[ChatSessionTransport] 丢弃乱序事件 seq=${seq} lastSeq=${lastSeq}`)
+      return
+    }
+    if (seq != null) lastSeq = seq
+    onEvent(event)
+  }
+
+  return {
+    kind: 'session',
+    open(handlers) {
+      let disposed = false
+      const unsubscribe = adapter.subscribe({
+        onEvent(event) {
+          if (!disposed) deliver(event, handlers.onEvent)
+        },
+        onDisconnect() {
+          if (disposed) return
+          void adapter.fetchHistory(lastSeq).then(
+            ({ events }) => {
+              if (disposed) return
+              for (const event of events) deliver(event, handlers.onEvent)
+              handlers.onDisconnect?.()
+            },
+            () => {
+              if (!disposed) handlers.onDisconnect?.()
+            }
+          )
+        }
+      })
+      return () => {
+        disposed = true
+        unsubscribe()
+      }
+    },
+    send(content, attachments) {
+      return runExclusive(sendGate, () => adapter.send(content, attachments))
+    },
+    cancel() {
+      return runExclusive(cancelGate, () => adapter.cancel())
+    },
+    respond(rpcId, ok, value) {
+      return runExclusive(respondGate, () => adapter.respond(rpcId, ok, value))
+    },
+    fetchHistory(beforeSeq) {
+      return adapter.fetchHistory(beforeSeq)
+    },
+    selectModel(provider, model) {
+      return runExclusive(selectModelGate, () => adapter.selectModel(provider, model))
+    }
+  }
+}

package/src/chat/types.ts

@@ -35,6 +35,8 @@ export interface ChatToolCall {
   result?: string
   /** 执行失败信息 */
   error?: string
+  /** 服务端下发的展示视图原文（session 模式可选） */
+  view?: unknown
 }
 
 /** 聊天消息 */
@@ -129,6 +131,44 @@ export interface ChatTool<A = any> {
   execute: (args: A, ctx: ChatToolContext) => unknown
 }
 
+/**
+ * 服务端驱动模式下 tools 的合法形态：纯渲染元信息（执行在服务端）。
+ * 没有 execute / description / parameters / needsConfirm / terminal。
+ */
+export interface ChatToolMeta {
+  /** 与服务端 tool/call.name 匹配 */
+  name: string
+  /** 覆盖通用图标 */
+  icon?: Component
+  /** 工具显示名，缺省取 name */
+  label?: string
+  /** 自定义卡片/面板渲染，props 为 ChatToolRenderProps */
+  render?: Component
+  /** 渲染位置，语义同 ChatTool.renderTo */
+  renderTo?: 'inline' | 'panel'
+  /** 侧边面板默认宽度，语义同 ChatTool.panelWidth */
+  panelWidth?: number
+  /** 侧边面板标题，语义同 ChatTool.panelTitle */
+  panelTitle?: string | ((toolCall: ChatToolCall) => string)
+  /** 执行完成后是否自动折叠 */
+  autoCollapse?: boolean
+}
+
+/** 作业条项状态：至少区分进行中与终态 */
+export type ChatJobStatus = 'running' | 'done' | 'error'
+
+/** 服务端下发的作业条项 */
+export interface ChatJob {
+  /** 稳定 id */
+  id: string
+  /** 作业类型（用于图标映射） */
+  kind: string
+  /** 展示文案 */
+  label: string
+  /** 进行中或终态 */
+  status: ChatJobStatus
+}
+
 /** 工具自定义渲染组件 / 渲染函数的 props */
 export interface ChatToolRenderProps {
   /** 本次工具调用（含 status/arguments/result/error，可自行渲染进度与错误） */

package/src/chat/use-chat-helpers.ts

@@ -0,0 +1,39 @@
+import { createBuiltinTools } from '../tools'
+import type { ChatTokenUsage, ChatTool } from './types'
+
+export function serializeResult(result: unknown): string {
+  if (typeof result === 'string') return result
+  try {
+    return JSON.stringify(result) ?? 'null'
+  } catch {
+    return String(result)
+  }
+}
+
+/** 内置工具 + 用户工具，同名时内置优先 */
+export function resolveTools(userTools?: ChatTool[]): ChatTool[] {
+  const builtins = createBuiltinTools()
+  const names = new Set(builtins.map((t) => t.name))
+  return [...builtins, ...(userTools ?? []).filter((t) => !names.has(t.name))]
+}
+
+function mergeOptionalCount(a?: number, b?: number): number | undefined {
+  if (a == null && b == null) return undefined
+  return (a ?? 0) + (b ?? 0)
+}
+
+/** 累加两次 usage；缓存字段只在至少一侧有值时保留 */
+export function addTokenUsage(a: ChatTokenUsage, b: ChatTokenUsage): ChatTokenUsage {
+  const usage: ChatTokenUsage = {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens
+  }
+  const cacheHitTokens = mergeOptionalCount(a.cacheHitTokens, b.cacheHitTokens)
+  if (cacheHitTokens != null) usage.cacheHitTokens = cacheHitTokens
+  const cacheMissTokens = mergeOptionalCount(a.cacheMissTokens, b.cacheMissTokens)
+  if (cacheMissTokens != null) usage.cacheMissTokens = cacheMissTokens
+  const cacheCreationTokens = mergeOptionalCount(a.cacheCreationTokens, b.cacheCreationTokens)
+  if (cacheCreationTokens != null) usage.cacheCreationTokens = cacheCreationTokens
+  return usage
+}

package/src/chat/use-chat-session.ts

@@ -0,0 +1,87 @@
+import type { Ref } from 'vue'
+
+import type { AskQuestionItem } from '../tools'
+import {
+  createFoldState,
+  foldSessionEvent,
+  type ChatFoldState,
+  type ChatPendingApproval
+} from './fold'
+import type { ChatSessionEvent, ChatSessionTransport } from './session'
+import type { ChatJob, ChatMessage, ChatQueuedMessage, ChatTokenUsage } from './types'
+
+export interface SessionChatSurface {
+  messages: Ref<ChatMessage[]>
+  queue: Ref<ChatQueuedMessage[]>
+  jobs: Ref<ChatJob[]>
+  tokenUsage: Ref<ChatTokenUsage | null>
+  projections: Ref<Record<string, unknown>>
+  title: Ref<string | null>
+  running: Ref<boolean>
+  pendingApprovals: Ref<ChatPendingApproval[]>
+  pendingQuestion: Ref<{ questions: AskQuestionItem[]; rpcId: string } | null>
+}
+
+/** 把 fold 状态同步到 useChat 的渲染面 */
+function syncFold(fold: ChatFoldState, surface: SessionChatSurface) {
+  surface.messages.value = fold.messages
+  surface.queue.value = fold.queue
+  surface.jobs.value = fold.jobs
+  surface.tokenUsage.value = fold.tokenUsage
+  surface.projections.value = fold.projections
+  surface.title.value = fold.title
+  surface.running.value = fold.running
+  surface.pendingApprovals.value = fold.pendingApprovals
+  surface.pendingQuestion.value = fold.pendingQuestion
+}
+
+/**
+ * session transport 的 open / fetchHistory / fold。
+ * 历史回放与实时 onEvent 走同一套 fold。
+ */
+export function createSessionRuntime(surface: SessionChatSurface) {
+  let fold = createFoldState()
+  let opened = false
+
+  const apply = (event: ChatSessionEvent) => {
+    fold = foldSessionEvent(fold, event)
+    syncFold(fold, surface)
+  }
+
+  return {
+    get opened() {
+      return opened
+    },
+    attach(transport: ChatSessionTransport, onCleanup: (fn: () => void) => void) {
+      // isServerTransport 只认 kind，不保证 open 存在
+      if (typeof transport.open !== 'function') return
+      fold = createFoldState()
+      syncFold(fold, surface)
+      let disposed = false
+      const dispose = transport.open({
+        onEvent(event) {
+          if (!disposed) apply(event)
+        },
+        onDisconnect() {
+          if (disposed) return
+          fold = { ...fold, running: false }
+          surface.running.value = false
+        }
+      })
+      opened = true
+      onCleanup(() => {
+        disposed = true
+        opened = false
+        dispose()
+      })
+      void transport.fetchHistory().then(({ events }) => {
+        if (disposed) return
+        for (const event of events) apply(event)
+      })
+    },
+    resetLocal() {
+      fold = createFoldState()
+      syncFold(fold, surface)
+    }
+  }
+}