@veltra/ai 2.1.6 → 2.1.8

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)
+    }
+  }
+}

package/src/chat/use-chat.ts

@@ -1,16 +1,21 @@
 import { useModel } from '@veltra/compositions'
 import { reactive, ref, watch, type Ref } from 'vue'
 
-import { createBuiltinTools } from '../tools'
+import type { AskQuestionItem } from '../tools'
 import type { AiChatEmits, AiChatProps } from '../types'
+import type { ChatPendingApproval } from './fold'
+import { isServerTransport, type ChatSessionTransport } from './session'
 import type {
   ChatAttachment,
+  ChatJob,
   ChatMessage,
   ChatQueuedMessage,
   ChatTokenUsage,
   ChatTool,
   ChatToolCall
 } from './types'
+import { addTokenUsage, resolveTools, serializeResult } from './use-chat-helpers'
+import { createSessionRuntime } from './use-chat-session'
 
 export interface UseChatOptions {
   props: AiChatProps
@@ -23,47 +28,10 @@ const uid = () => {
     : `${Date.now()}-${Math.random().toString(36).slice(2)}`
 }
 
-function serializeResult(result: unknown): string {
-  if (typeof result === 'string') return result
-  try {
-    return JSON.stringify(result) ?? 'null'
-  } catch {
-    return String(result)
-  }
-}
-
-/** 内置工具 + 用户工具，同名时内置优先 */
-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；缓存字段只在至少一侧有值时保留 */
-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
-}
-
 /**
  * AI 对话核心状态机：消息管理、流式追加、工具调用循环编排。
  * 与 UI 解耦，ai-chat.vue 只负责渲染与交互转发。
- * 始终注入内置工具（如 askQuestion），无需经 props 传入。
+ * 函数型 transport 注入内置工具；session transport 不注入、不执行客户端工具。
  */
 export function useChat(options: UseChatOptions) {
   const { props, emit } = options
@@ -93,6 +61,28 @@ export function useChat(options: UseChatOptions) {
   /** 最近一轮用户对话（含工具多轮请求）的 token；该轮无 usage 时为 null */
   const lastTurnUsage = ref<ChatTokenUsage | null>(null)
 
+  /** session 下由 jobs/snapshot 整体替换；函数 transport 保持空数组 */
+  const jobs = ref<ChatJob[]>([])
+  const projections = ref<Record<string, unknown>>({})
+  const title = ref<string | null>(null)
+  const pendingApprovals = ref<ChatPendingApproval[]>([])
+  const pendingQuestion = ref<{ questions: AskQuestionItem[]; rpcId: string } | null>(null)
+
+  const sessionRuntime = createSessionRuntime({
+    messages,
+    queue,
+    jobs,
+    tokenUsage,
+    projections,
+    title,
+    running,
+    pendingApprovals,
+    pendingQuestion
+  })
+
+  const session = (): ChatSessionTransport | null =>
+    isServerTransport(props.transport) ? props.transport : null
+
   let abortController: AbortController | null = null
   /** needsConfirm 工具的挂起确认器，key 为 toolCallId */
   const confirmResolvers = new Map<string, (approved: boolean) => void>()
@@ -129,6 +119,25 @@ export function useChat(options: UseChatOptions) {
     { immediate: true }
   )
 
+  // session：open + fetchHistory 播种；更换或卸载时 disposer
+  watch(
+    () => props.transport,
+    (transport, _prev, onCleanup) => {
+      if (!isServerTransport(transport)) return
+      sessionRuntime.attach(transport, onCleanup)
+    },
+    { immediate: true }
+  )
+
+  // session 且已 open 时，模型切换走 selectModel
+  watch(model, (modelId) => {
+    const current = session()
+    if (!sessionRuntime.opened || !current || !modelId) return
+    const option = props.models?.find((m) => m.id === modelId)
+    if (!option) return
+    void current.selectModel(option.providerId, modelId)
+  })
+
   /**
    * 向父组件同步消息快照（流式 delta 过于频繁，不同步，只在关键节点同步）。
    * 必须经 setter 赋值触发 emit，而非直接 emit 切片：setter 让本地数组与下发的
@@ -146,6 +155,11 @@ export function useChat(options: UseChatOptions) {
    */
   const send = (content: string, attachments?: ChatAttachment[]) => {
     if (!content.trim() && !attachments?.length) return
+    const current = session()
+    if (current) {
+      void current.send(content, attachments)
+      return
+    }
     enqueue(content, attachments)
   }
 
@@ -159,6 +173,7 @@ export function useChat(options: UseChatOptions) {
     beforeId?: string
   ): ChatQueuedMessage => {
     const item: ChatQueuedMessage = { id: uid(), content, attachments }
+    if (session()) return item
     const anchorIndex = beforeId ? queue.value.findIndex((q) => q.id === beforeId) : -1
     if (anchorIndex === -1) {
       queue.value.push(item)
@@ -177,6 +192,7 @@ export function useChat(options: UseChatOptions) {
 
   /** 立即执行队列中的某条：中断当前会话，该条插队为下一条（其余保持原顺序） */
   const startQueued = (id: string) => {
+    if (session()) return
     const item = removeQueued(id)
     if (!item) return
 
@@ -193,6 +209,7 @@ export function useChat(options: UseChatOptions) {
 
   /** 从队列移除某条（返回被移除项；编辑场景由 UI 取回内容） */
   const removeQueued = (id: string): ChatQueuedMessage | undefined => {
+    if (session()) return undefined
     const index = queue.value.findIndex((item) => item.id === id)
     if (index === -1) return undefined
     const [item] = queue.value.splice(index, 1)
@@ -287,9 +304,10 @@ export function useChat(options: UseChatOptions) {
 
   /** 单轮生成；存在工具调用时执行后递归进入下一轮（递归避免 await-in-loop） */
   const runRound = async (controller: AbortController, depth: number): Promise<void> => {
-    if (!props.transport) return
+    const transport = props.transport
+    if (typeof transport !== 'function') return
     const { signal } = controller
-    const tools = resolveTools(props.tools)
+    const tools = resolveTools(props.tools as ChatTool[] | undefined)
 
     const assistant = reactive<ChatMessage>({
       id: uid(),
@@ -303,7 +321,7 @@ export function useChat(options: UseChatOptions) {
     let requestError: Error | null = null
 
     try {
-      await props.transport(
+      await transport(
         {
           // 排除刚追加的 assistant 占位消息
           messages: messages.value.slice(0, -1),
@@ -395,17 +413,34 @@ export function useChat(options: UseChatOptions) {
 
   /** 中断当前生成，挂起的工具确认按拒绝处理 */
   const abort = () => {
+    const current = session()
+    if (current) {
+      void current.cancel()
+      return
+    }
     abortController?.abort()
   }
 
-  /** 响应 needsConfirm 工具的用户确认 */
+  /** 响应 needsConfirm 工具的用户确认；session 下按 callId 找到 rpcId 后 respond */
   const respondToolCall = (toolCallId: string, approved: boolean) => {
+    const current = session()
+    if (current) {
+      const pending = pendingApprovals.value.find((a) => a.callId === toolCallId)
+      if (pending) void current.respond(pending.rpcId, approved)
+      return
+    }
     confirmResolvers.get(toolCallId)?.(approved)
   }
 
+  /** session 审批横幅 / 提问提交：直接 respond(rpcId) */
+  const respondSession = (rpcId: string, ok: boolean, value?: unknown) => {
+    const current = session()
+    if (current) void current.respond(rpcId, ok, value)
+  }
+
   /** 重新生成：移除最后一条用户消息之后的所有消息，重新跑对话循环 */
   const regenerate = () => {
-    if (running.value) return
+    if (session() || running.value) return
 
     const list = messages.value
     let lastUserIndex = -1
@@ -424,6 +459,11 @@ export function useChat(options: UseChatOptions) {
 
   /** 清空消息、待发送队列与 token 统计，生成中则先中断 */
   const clear = () => {
+    if (session()) {
+      sessionRuntime.resetLocal()
+      lastTurnUsage.value = null
+      return
+    }
     abort()
     queue.value = []
     messages.value = []
@@ -438,13 +478,19 @@ export function useChat(options: UseChatOptions) {
     reasoningLevel,
     running,
     queue,
+    jobs,
     tokenUsage,
     lastTurnUsage,
+    projections,
+    title,
+    pendingApprovals,
+    pendingQuestion,
     send,
     abort,
     regenerate,
     clear,
     respondToolCall,
+    respondSession,
     enqueue,
     startQueued,
     removeQueued