@veltra/ai 2.1.6 → 2.1.8

package/README.md

@@ -0,0 +1,42 @@
+# @veltra/ai
+
+对话 UI（`UAiChat`）与 UI 无关的 `useChat` 状态机。按 transport 形态接入两种工具来源。
+
+## 客户端驱动
+
+传入函数型 `ChatTransport`（通常 `createOpenAITransport`）和带 `execute` 的 `ChatTool[]`。前端持有历史，每轮把全量消息发给 OpenAI 兼容 SSE 端点，并在本地执行工具、维护队列与 `needsConfirm`。
+
+```ts
+import { createOpenAITransport, type ChatTool } from '@veltra/ai'
+
+const transport = createOpenAITransport({
+  providers: [{ id: 'openai', label: 'OpenAI', endpoint: '/ai/chat/completions', models: [...] }]
+})
+
+const tools: ChatTool[] = [
+  {
+    name: 'ping',
+    description: '探测',
+    parameters: { type: 'object', properties: {} },
+    execute: async () => ({ ok: true })
+  }
+]
+```
+
+已有调用方无需改代码：`ChatTransport` / `ChatTool.execute` 必填签名不变。
+
+## 服务端驱动
+
+传入 `createServerTransport(adapter)`。`adapter` 只做协议翻译（订阅事件流、把 `send` / `cancel` / `respond` / `selectModel` / `fetchHistory` 打到远端）。包内完成 seq 校验、断线补拉、动作去重，再 fold 成消息 / 队列 / 作业。
+
+```ts
+import { createServerTransport, type ChatSessionAdapter } from '@veltra/ai'
+
+const transport = createServerTransport(adapter)
+```
+
+此模式下 `tools` 只作按 `name` 的可选渲染元信息（`ChatToolMeta`），前端不定义、不执行工具。未注册的工具名走通用工具卡片。
+
+## 本包不含 bedrock / DSH 桥
+
+不实现、不导出 `createBedrockTransport`。DeepSeek harness（DSH）的 HTTP/WS 与 bedrock 适配由其它仓库提供 `ChatSessionAdapter`。

package/dist/chat/fold.d.ts

@@ -0,0 +1,41 @@
+import { ChatJob, ChatMessage, ChatQueuedMessage, ChatTokenUsage } from "./types.js";
+import { AskQuestionItem } from "../tools/ask-question/ask-question.js";
+import "../tools/index.js";
+import { ChatSessionEvent } from "./session.js";
+//#region src/chat/fold.d.ts
+interface ChatPendingApproval {
+  approvalId: string;
+  toolName: string;
+  callId?: string;
+  reason?: string;
+  rpcId: string;
+}
+/** 历史回放与实时 onEvent 共用的折叠状态 */
+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;
+}
+declare function createFoldState(): ChatFoldState;
+/**
+ * 纯函数 fold：历史回放与实时 onEvent 走同一套。
+ * 后到的更小/重复 seq 不覆盖已应用事件。
+ */
+declare function foldSessionEvent(state: ChatFoldState, event: ChatSessionEvent): ChatFoldState;
+//#endregion
+export { ChatFoldState, ChatPendingApproval, createFoldState, foldSessionEvent };
+//# sourceMappingURL=fold.d.ts.map

package/dist/chat/fold.js

@@ -0,0 +1,208 @@
+//#region src/chat/fold.ts
+function eventSeq(event) {
+	return "seq" in event ? event.seq : void 0;
+}
+function createFoldState() {
+	return {
+		lastSeq: null,
+		messages: [],
+		queue: [],
+		jobs: [],
+		tokenUsage: null,
+		projections: {},
+		title: null,
+		running: false,
+		pendingApprovals: [],
+		pendingQuestion: null,
+		error: null
+	};
+}
+function mergeOptionalCount(a, b) {
+	if (a == null && b == null) return void 0;
+	return (a ?? 0) + (b ?? 0);
+}
+function addTokenUsage(a, b) {
+	const usage = {
+		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) {
+	if (value == null || typeof value !== "object") return false;
+	const usage = value;
+	return typeof usage.promptTokens === "number" && typeof usage.completionTokens === "number" && typeof usage.totalTokens === "number";
+}
+function replaceAt(list, idx, item) {
+	const next = list.slice();
+	next[idx] = item;
+	return next;
+}
+function patchMessage(messages, id, patch) {
+	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, call) {
+	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, callId, patch) {
+	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 不覆盖已应用事件。
+*/
+function foldSessionEvent(state, event) {
+	const seq = eventSeq(event);
+	if (seq != null && state.lastSeq != null && seq <= state.lastSeq) return state;
+	const next = {
+		...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 = {
+				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 = {
+				id: event.callId,
+				name: event.name,
+				arguments: event.arguments,
+				status: "pending"
+			};
+			if (event.view !== void 0) call.view = event.view;
+			next.messages = appendToolCall(next.messages, call);
+			break;
+		}
+		case "tool/result": {
+			const patch = { status: event.status };
+			if (event.result !== void 0) patch.result = event.result;
+			if (event.error !== void 0) patch.error = event.error;
+			if (event.view !== void 0) 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;
+	}
+	return next;
+}
+//#endregion
+export { createFoldState, foldSessionEvent };
+
+//# sourceMappingURL=fold.js.map

package/dist/chat/fold.js.map

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

package/dist/chat/index.d.ts

@@ -1,5 +1,7 @@
-import { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus } from "./types.js";
+import { ChatAttachment, ChatJob, ChatJobStatus, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolMeta, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus } from "./types.js";
+import { ChatSessionAdapter, ChatSessionEvent, ChatSessionTransport, createServerTransport, isServerTransport } from "./session.js";
+import { ChatFoldState, ChatPendingApproval, createFoldState, foldSessionEvent } from "./fold.js";
 import { UseChatOptions, useChat } from "./use-chat.js";
 import { OpenAITransport, OpenAITransportOptions, createOpenAITransport } from "./transports/openai.js";
 import "./transports/index.js";
-export { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, OpenAITransport, OpenAITransportOptions, ToolCallStatus, UseChatOptions, createOpenAITransport, useChat };
+export { ChatAttachment, ChatFoldState, ChatJob, ChatJobStatus, ChatMessage, ChatPendingApproval, ChatQueuedMessage, ChatSessionAdapter, ChatSessionEvent, ChatSessionTransport, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolMeta, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, OpenAITransport, OpenAITransportOptions, ToolCallStatus, UseChatOptions, createFoldState, createOpenAITransport, createServerTransport, foldSessionEvent, isServerTransport, useChat };

package/dist/chat/session.d.ts

@@ -0,0 +1,123 @@
+import { ChatAttachment, ChatJob, ChatQueuedMessage, ChatToolCall } from "./types.js";
+import { AskQuestionItem } from "../tools/ask-question/ask-question.js";
+import "../tools/index.js";
+//#region src/chat/session.d.ts
+/** 归一化后的服务端会话事件（协议无关） */
+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 互斥 */
+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 完成。
+ */
+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>;
+}
+/** 仅带 kind: 'session' 的对象为 true；函数 / null / 无 kind 均为 false */
+declare function isServerTransport(t: unknown): t is ChatSessionTransport;
+/**
+ * 用 adapter 包出 ChatSessionTransport。
+ * 包内完成 seq 校验、disposer、断线补拉、动作 in-flight 去重。
+ */
+declare function createServerTransport(adapter: ChatSessionAdapter): ChatSessionTransport;
+//#endregion
+export { ChatSessionAdapter, ChatSessionEvent, ChatSessionTransport, createServerTransport, isServerTransport };
+//# sourceMappingURL=session.d.ts.map

package/dist/chat/session.js

@@ -0,0 +1,79 @@
+//#region src/chat/session.ts
+function eventSeq(event) {
+	return "seq" in event ? event.seq : void 0;
+}
+/** 仅带 kind: 'session' 的对象为 true；函数 / null / 无 kind 均为 false */
+function isServerTransport(t) {
+	return typeof t === "object" && t !== null && t.kind === "session";
+}
+function runExclusive(gate, action) {
+	if (gate.busy) return Promise.resolve();
+	gate.busy = true;
+	return action().finally(() => {
+		gate.busy = false;
+	});
+}
+/**
+* 用 adapter 包出 ChatSessionTransport。
+* 包内完成 seq 校验、disposer、断线补拉、动作 in-flight 去重。
+*/
+function createServerTransport(adapter) {
+	let lastSeq;
+	const sendGate = { busy: false };
+	const cancelGate = { busy: false };
+	const respondGate = { busy: false };
+	const selectModelGate = { busy: false };
+	const deliver = (event, onEvent) => {
+		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;
+					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));
+		}
+	};
+}
+//#endregion
+export { createServerTransport, isServerTransport };
+
+//# sourceMappingURL=session.js.map

package/dist/chat/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","names":[],"sources":["../../src/chat/session.ts"],"sourcesContent":["import type { AskQuestionItem } from '../tools'\nimport type { ChatAttachment, ChatJob, ChatQueuedMessage, ChatToolCall } from './types'\n\n/** 归一化后的服务端会话事件（协议无关） */\nexport type ChatSessionEvent =\n  | {\n      type: 'user/message'\n      messageId: string\n      seq: number\n      content: string\n      attachments?: ChatAttachment[]\n    }\n  | {\n      type: 'assistant/chunk'\n      messageId: string\n      seq: number\n      delta: string\n      reasoningDelta?: string\n    }\n  | {\n      type: 'assistant/message'\n      messageId: string\n      seq: number\n      content: string\n      reasoning?: string\n      toolCalls?: ChatToolCall[]\n    }\n  | {\n      type: 'tool/call'\n      callId: string\n      name: string\n      arguments: string\n      seq: number\n      view?: unknown\n    }\n  | {\n      type: 'tool/result'\n      callId: string\n      status: 'success' | 'error' | 'rejected'\n      result?: string\n      error?: string\n      seq: number\n      view?: unknown\n    }\n  | {\n      type: 'approval/requested'\n      approvalId: string\n      toolName: string\n      callId?: string\n      reason?: string\n      rpcId: string\n    }\n  | { type: 'approval/resolved'; approvalId: string; outcome: string }\n  | { type: 'question/requested'; questions: AskQuestionItem[]; rpcId: string }\n  | { type: 'question/resolved'; questionRpcId: string; outcome: 'answered' | 'cancelled' }\n  | { type: 'queue/snapshot'; items: ChatQueuedMessage[] }\n  | { type: 'jobs/snapshot'; jobs: ChatJob[] }\n  | { type: 'projection'; key: string; value: unknown; seq: number }\n  | { type: 'running'; running: boolean }\n  | { type: 'finish' }\n  | { type: 'error'; code: string; message: string }\n\n/** 服务端会话 transport：对象形态，与函数型 ChatTransport 互斥 */\nexport interface ChatSessionTransport {\n  readonly kind: 'session'\n  open(handlers: { onEvent(event: ChatSessionEvent): void; onDisconnect?(): void }): () => void\n  send(content: string, attachments?: ChatAttachment[]): Promise<void>\n  cancel(): Promise<void>\n  respond(rpcId: string, ok: boolean, value?: unknown): Promise<void>\n  fetchHistory(beforeSeq?: number): Promise<{ events: ChatSessionEvent[]; hasMore: boolean }>\n  selectModel(provider: string, model: string): Promise<void>\n}\n\n/**\n * 协议翻译层：订阅事件流、把动作打到远端、拉历史。\n * 时序校验 / dispose / 断线补拉 / in-flight 去重由 createServerTransport 完成。\n */\nexport interface ChatSessionAdapter {\n  subscribe(handlers: { onEvent(event: ChatSessionEvent): void; onDisconnect?(): void }): () => void\n  send(content: string, attachments?: ChatAttachment[]): Promise<void>\n  cancel(): Promise<void>\n  respond(rpcId: string, ok: boolean, value?: unknown): Promise<void>\n  fetchHistory(beforeSeq?: number): Promise<{ events: ChatSessionEvent[]; hasMore: boolean }>\n  selectModel(provider: string, model: string): Promise<void>\n}\n\nfunction eventSeq(event: ChatSessionEvent): number | undefined {\n  return 'seq' in event ? event.seq : undefined\n}\n\n/** 仅带 kind: 'session' 的对象为 true；函数 / null / 无 kind 均为 false */\nexport function isServerTransport(t: unknown): t is ChatSessionTransport {\n  return typeof t === 'object' && t !== null && (t as { kind?: unknown }).kind === 'session'\n}\n\nfunction runExclusive(gate: { busy: boolean }, action: () => Promise<void>): Promise<void> {\n  if (gate.busy) return Promise.resolve()\n  gate.busy = true\n  return action().finally(() => {\n    gate.busy = false\n  })\n}\n\n/**\n * 用 adapter 包出 ChatSessionTransport。\n * 包内完成 seq 校验、disposer、断线补拉、动作 in-flight 去重。\n */\nexport function createServerTransport(adapter: ChatSessionAdapter): ChatSessionTransport {\n  let lastSeq: number | undefined\n  const sendGate = { busy: false }\n  const cancelGate = { busy: false }\n  const respondGate = { busy: false }\n  const selectModelGate = { busy: false }\n\n  const deliver = (event: ChatSessionEvent, onEvent: (e: ChatSessionEvent) => void) => {\n    const seq = eventSeq(event)\n    if (seq != null && lastSeq != null && seq <= lastSeq) {\n      console.warn(`[ChatSessionTransport] 丢弃乱序事件 seq=${seq} lastSeq=${lastSeq}`)\n      return\n    }\n    if (seq != null) lastSeq = seq\n    onEvent(event)\n  }\n\n  return {\n    kind: 'session',\n    open(handlers) {\n      let disposed = false\n      const unsubscribe = adapter.subscribe({\n        onEvent(event) {\n          if (!disposed) deliver(event, handlers.onEvent)\n        },\n        onDisconnect() {\n          if (disposed) return\n          void adapter.fetchHistory(lastSeq).then(\n            ({ events }) => {\n              if (disposed) return\n              for (const event of events) deliver(event, handlers.onEvent)\n              handlers.onDisconnect?.()\n            },\n            () => {\n              if (!disposed) handlers.onDisconnect?.()\n            }\n          )\n        }\n      })\n      return () => {\n        disposed = true\n        unsubscribe()\n      }\n    },\n    send(content, attachments) {\n      return runExclusive(sendGate, () => adapter.send(content, attachments))\n    },\n    cancel() {\n      return runExclusive(cancelGate, () => adapter.cancel())\n    },\n    respond(rpcId, ok, value) {\n      return runExclusive(respondGate, () => adapter.respond(rpcId, ok, value))\n    },\n    fetchHistory(beforeSeq) {\n      return adapter.fetchHistory(beforeSeq)\n    },\n    selectModel(provider, model) {\n      return runExclusive(selectModelGate, () => adapter.selectModel(provider, model))\n    }\n  }\n}\n"],"mappings":";AAsFA,SAAS,SAAS,OAA6C;CAC7D,OAAO,SAAS,QAAQ,MAAM,MAAM,KAAA;AACtC;;AAGA,SAAgB,kBAAkB,GAAuC;CACvE,OAAO,OAAO,MAAM,YAAY,MAAM,QAAS,EAAyB,SAAS;AACnF;AAEA,SAAS,aAAa,MAAyB,QAA4C;CACzF,IAAI,KAAK,MAAM,OAAO,QAAQ,QAAQ;CACtC,KAAK,OAAO;CACZ,OAAO,OAAO,CAAC,CAAC,cAAc;EAC5B,KAAK,OAAO;CACd,CAAC;AACH;;;;;AAMA,SAAgB,sBAAsB,SAAmD;CACvF,IAAI;CACJ,MAAM,WAAW,EAAE,MAAM,MAAM;CAC/B,MAAM,aAAa,EAAE,MAAM,MAAM;CACjC,MAAM,cAAc,EAAE,MAAM,MAAM;CAClC,MAAM,kBAAkB,EAAE,MAAM,MAAM;CAEtC,MAAM,WAAW,OAAyB,YAA2C;EACnF,MAAM,MAAM,SAAS,KAAK;EAC1B,IAAI,OAAO,QAAQ,WAAW,QAAQ,OAAO,SAAS;GACpD,QAAQ,KAAK,qCAAqC,IAAI,WAAW,SAAS;GAC1E;EACF;EACA,IAAI,OAAO,MAAM,UAAU;EAC3B,QAAQ,KAAK;CACf;CAEA,OAAO;EACL,MAAM;EACN,KAAK,UAAU;GACb,IAAI,WAAW;GACf,MAAM,cAAc,QAAQ,UAAU;IACpC,QAAQ,OAAO;KACb,IAAI,CAAC,UAAU,QAAQ,OAAO,SAAS,OAAO;IAChD;IACA,eAAe;KACb,IAAI,UAAU;KACd,QAAa,aAAa,OAAO,CAAC,CAAC,MAChC,EAAE,aAAa;MACd,IAAI,UAAU;MACd,KAAK,MAAM,SAAS,QAAQ,QAAQ,OAAO,SAAS,OAAO;MAC3D,SAAS,eAAe;KAC1B,SACM;MACJ,IAAI,CAAC,UAAU,SAAS,eAAe;KACzC,CACF;IACF;GACF,CAAC;GACD,aAAa;IACX,WAAW;IACX,YAAY;GACd;EACF;EACA,KAAK,SAAS,aAAa;GACzB,OAAO,aAAa,gBAAgB,QAAQ,KAAK,SAAS,WAAW,CAAC;EACxE;EACA,SAAS;GACP,OAAO,aAAa,kBAAkB,QAAQ,OAAO,CAAC;EACxD;EACA,QAAQ,OAAO,IAAI,OAAO;GACxB,OAAO,aAAa,mBAAmB,QAAQ,QAAQ,OAAO,IAAI,KAAK,CAAC;EAC1E;EACA,aAAa,WAAW;GACtB,OAAO,QAAQ,aAAa,SAAS;EACvC;EACA,YAAY,UAAU,OAAO;GAC3B,OAAO,aAAa,uBAAuB,QAAQ,YAAY,UAAU,KAAK,CAAC;EACjF;CACF;AACF"}

package/dist/chat/types.d.ts

@@ -27,6 +27,8 @@ interface ChatToolCall {
   result?: string;
   /** 执行失败信息 */
   error?: string;
+  /** 服务端下发的展示视图原文（session 模式可选） */
+  view?: unknown;
 }
 /** 聊天消息 */
 interface ChatMessage {
@@ -116,6 +118,41 @@ interface ChatTool<A = any> {
   /** 工具实现，返回值（或 Promise 返回值）会被 JSON 序列化后回灌给模型 */
   execute: (args: A, ctx: ChatToolContext) => unknown;
 }
+/**
+ * 服务端驱动模式下 tools 的合法形态：纯渲染元信息（执行在服务端）。
+ * 没有 execute / description / parameters / needsConfirm / terminal。
+ */
+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;
+}
+/** 作业条项状态：至少区分进行中与终态 */
+type ChatJobStatus = 'running' | 'done' | 'error';
+/** 服务端下发的作业条项 */
+interface ChatJob {
+  /** 稳定 id */
+  id: string;
+  /** 作业类型（用于图标映射） */
+  kind: string;
+  /** 展示文案 */
+  label: string;
+  /** 进行中或终态 */
+  status: ChatJobStatus;
+}
 /** 工具自定义渲染组件 / 渲染函数的 props */
 interface ChatToolRenderProps {
   /** 本次工具调用（含 status/arguments/result/error，可自行渲染进度与错误） */
@@ -190,5 +227,5 @@ interface ChatTransportHandlers {
  */
 type ChatTransport = (request: ChatTransportRequest, handlers: ChatTransportHandlers) => Promise<void> | void;
 //#endregion
-export { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus };
+export { ChatAttachment, ChatJob, ChatJobStatus, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolMeta, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus };
 //# sourceMappingURL=types.d.ts.map

package/dist/chat/use-chat-helpers.js

@@ -0,0 +1,39 @@
+import { createBuiltinTools } from "../tools/index.js";
+//#region src/chat/use-chat-helpers.ts
+function serializeResult(result) {
+	if (typeof result === "string") return result;
+	try {
+		return JSON.stringify(result) ?? "null";
+	} catch {
+		return String(result);
+	}
+}
+/** 内置工具 + 用户工具，同名时内置优先 */
+function resolveTools(userTools) {
+	const builtins = createBuiltinTools();
+	const names = new Set(builtins.map((t) => t.name));
+	return [...builtins, ...(userTools ?? []).filter((t) => !names.has(t.name))];
+}
+function mergeOptionalCount(a, b) {
+	if (a == null && b == null) return void 0;
+	return (a ?? 0) + (b ?? 0);
+}
+/** 累加两次 usage；缓存字段只在至少一侧有值时保留 */
+function addTokenUsage(a, b) {
+	const usage = {
+		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;
+}
+//#endregion
+export { addTokenUsage, resolveTools, serializeResult };
+
+//# sourceMappingURL=use-chat-helpers.js.map

package/dist/chat/use-chat-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-chat-helpers.js","names":[],"sources":["../../src/chat/use-chat-helpers.ts"],"sourcesContent":["import { createBuiltinTools } from '../tools'\nimport type { ChatTokenUsage, ChatTool } from './types'\n\nexport function serializeResult(result: unknown): string {\n  if (typeof result === 'string') return result\n  try {\n    return JSON.stringify(result) ?? 'null'\n  } catch {\n    return String(result)\n  }\n}\n\n/** 内置工具 + 用户工具，同名时内置优先 */\nexport function resolveTools(userTools?: ChatTool[]): ChatTool[] {\n  const builtins = createBuiltinTools()\n  const names = new Set(builtins.map((t) => t.name))\n  return [...builtins, ...(userTools ?? []).filter((t) => !names.has(t.name))]\n}\n\nfunction mergeOptionalCount(a?: number, b?: number): number | undefined {\n  if (a == null && b == null) return undefined\n  return (a ?? 0) + (b ?? 0)\n}\n\n/** 累加两次 usage；缓存字段只在至少一侧有值时保留 */\nexport function addTokenUsage(a: ChatTokenUsage, b: ChatTokenUsage): ChatTokenUsage {\n  const usage: ChatTokenUsage = {\n    promptTokens: a.promptTokens + b.promptTokens,\n    completionTokens: a.completionTokens + b.completionTokens,\n    totalTokens: a.totalTokens + b.totalTokens\n  }\n  const cacheHitTokens = mergeOptionalCount(a.cacheHitTokens, b.cacheHitTokens)\n  if (cacheHitTokens != null) usage.cacheHitTokens = cacheHitTokens\n  const cacheMissTokens = mergeOptionalCount(a.cacheMissTokens, b.cacheMissTokens)\n  if (cacheMissTokens != null) usage.cacheMissTokens = cacheMissTokens\n  const cacheCreationTokens = mergeOptionalCount(a.cacheCreationTokens, b.cacheCreationTokens)\n  if (cacheCreationTokens != null) usage.cacheCreationTokens = cacheCreationTokens\n  return usage\n}\n"],"mappings":";;AAGA,SAAgB,gBAAgB,QAAyB;CACvD,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,IAAI;EACF,OAAO,KAAK,UAAU,MAAM,KAAK;CACnC,QAAQ;EACN,OAAO,OAAO,MAAM;CACtB;AACF;;AAGA,SAAgB,aAAa,WAAoC;CAC/D,MAAM,WAAW,mBAAmB;CACpC,MAAM,QAAQ,IAAI,IAAI,SAAS,KAAK,MAAM,EAAE,IAAI,CAAC;CACjD,OAAO,CAAC,GAAG,UAAU,IAAI,aAAa,CAAC,EAAA,CAAG,QAAQ,MAAM,CAAC,MAAM,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7E;AAEA,SAAS,mBAAmB,GAAY,GAAgC;CACtE,IAAI,KAAK,QAAQ,KAAK,MAAM,OAAO,KAAA;CACnC,QAAQ,KAAK,MAAM,KAAK;AAC1B;;AAGA,SAAgB,cAAc,GAAmB,GAAmC;CAClF,MAAM,QAAwB;EAC5B,cAAc,EAAE,eAAe,EAAE;EACjC,kBAAkB,EAAE,mBAAmB,EAAE;EACzC,aAAa,EAAE,cAAc,EAAE;CACjC;CACA,MAAM,iBAAiB,mBAAmB,EAAE,gBAAgB,EAAE,cAAc;CAC5E,IAAI,kBAAkB,MAAM,MAAM,iBAAiB;CACnD,MAAM,kBAAkB,mBAAmB,EAAE,iBAAiB,EAAE,eAAe;CAC/E,IAAI,mBAAmB,MAAM,MAAM,kBAAkB;CACrD,MAAM,sBAAsB,mBAAmB,EAAE,qBAAqB,EAAE,mBAAmB;CAC3F,IAAI,uBAAuB,MAAM,MAAM,sBAAsB;CAC7D,OAAO;AACT"}