@witqq/agent-sdk 0.6.0 → 0.7.0

package/dist/chat/accumulator.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+// src/chat/core.ts
+function createChatId() {
+  return crypto.randomUUID();
+}
+
+// src/chat/accumulator.ts
+var MessageAccumulator = class {
+  messageId;
+  parts = [];
+  status = "pending";
+  currentTextPart = null;
+  currentReasoningPart = null;
+  toolCallParts = /* @__PURE__ */ new Map();
+  _finalized = false;
+  constructor(messageId) {
+    this.messageId = messageId ?? createChatId();
+  }
+  /** Get current message ID */
+  get id() {
+    return this.messageId;
+  }
+  /**
+   * Apply an AgentEvent to accumulate into the message
+   * @param event - AgentEvent to process
+   * @throws Error if accumulator is already finalized
+   */
+  apply(event) {
+    if (this._finalized) throw new Error("Cannot apply events to finalized accumulator");
+    if (this.status === "pending") {
+      this.status = "streaming";
+    }
+    switch (event.type) {
+      case "text_delta":
+        this.handleTextDelta(event.text);
+        break;
+      case "thinking_start":
+        this.finalizeCurrentText();
+        this.currentReasoningPart = { type: "reasoning", text: "", status: "streaming" };
+        this.parts.push(this.currentReasoningPart);
+        break;
+      case "thinking_delta":
+        if (this.currentReasoningPart) {
+          this.currentReasoningPart.text += event.text;
+        }
+        break;
+      case "thinking_end":
+        if (this.currentReasoningPart) {
+          this.currentReasoningPart.status = "complete";
+          this.currentReasoningPart = null;
+        }
+        break;
+      case "tool_call_start": {
+        this.finalizeCurrentText();
+        const toolPart = {
+          type: "tool_call",
+          toolCallId: event.toolCallId,
+          name: event.toolName,
+          args: event.args,
+          status: "running"
+        };
+        this.toolCallParts.set(event.toolCallId, toolPart);
+        this.parts.push(toolPart);
+        break;
+      }
+      case "tool_call_end": {
+        const existing = this.toolCallParts.get(event.toolCallId);
+        if (existing) {
+          existing.result = event.result;
+          existing.status = "complete";
+        }
+        break;
+      }
+      case "error":
+        this.status = "error";
+        break;
+    }
+  }
+  handleTextDelta(text) {
+    if (!this.currentTextPart) {
+      this.currentTextPart = { type: "text", text: "", status: "streaming" };
+      this.parts.push(this.currentTextPart);
+    }
+    this.currentTextPart.text += text;
+  }
+  finalizeCurrentText() {
+    if (this.currentTextPart) {
+      this.currentTextPart.status = "complete";
+      this.currentTextPart = null;
+    }
+  }
+  /**
+   * Get a snapshot of the current accumulated message (for streaming UI)
+   * @returns ChatMessage with current parts and "streaming" status
+   */
+  snapshot() {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: this.messageId,
+      role: "assistant",
+      parts: this.parts.map((p) => ({ ...p })),
+      status: this.status === "pending" ? "pending" : "streaming",
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  /**
+   * Finalize the accumulator and return the complete ChatMessage
+   * @returns Completed ChatMessage with all parts finalized
+   * @throws Error if accumulator is already finalized
+   */
+  finalize() {
+    if (this._finalized) throw new Error("Accumulator already finalized");
+    this._finalized = true;
+    this.finalizeCurrentText();
+    if (this.currentReasoningPart) {
+      this.currentReasoningPart.status = "complete";
+      this.currentReasoningPart = null;
+    }
+    for (const [, toolPart] of this.toolCallParts) {
+      if (toolPart.status === "running" || toolPart.status === "pending") {
+        toolPart.status = "error";
+      }
+    }
+    if (this.status !== "error" && this.status !== "cancelled") {
+      this.status = "complete";
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: this.messageId,
+      role: "assistant",
+      parts: this.parts,
+      status: this.status,
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  /** Check if the accumulator has been finalized */
+  get finalized() {
+    return this._finalized;
+  }
+};
+
+exports.MessageAccumulator = MessageAccumulator;
+//# sourceMappingURL=accumulator.cjs.map
+//# sourceMappingURL=accumulator.cjs.map

package/dist/chat/accumulator.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/chat/core.ts","../../src/chat/accumulator.ts"],"names":[],"mappings":"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","file":"accumulator.cjs","sourcesContent":["/**\n * @witqq/agent-sdk/chat/core\n *\n * Foundational chat types and utilities: ChatMessage, ChatSession, ChatEvent,\n * IChatProvider, type guards, and AgentEvent↔ChatEvent bridge functions.\n */\n\nimport type {\n  AgentEvent,\n  Message,\n  ToolCall,\n  ToolResult,\n  ToolDefinition,\n  UsageData,\n  ModelInfo,\n  JSONValue,\n} from \"../types.js\";\n\n// ─── Unique ID ─────────────────────────────────────────────────\n\n/** Branded type for unique identifiers */\nexport type ChatId = string & { readonly __brand: \"ChatId\" };\n\n/**\n * Generate a new unique ChatId (crypto.randomUUID-based)\n * @returns Branded ChatId string\n */\nexport function createChatId(): ChatId {\n  return crypto.randomUUID() as ChatId;\n}\n\n/** UUID v4 pattern for ChatId validation */\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/**\n * Cast a string to ChatId with UUID format validation.\n * Use this instead of manual `as ChatId` type assertions.\n *\n * @param value - String to validate and cast\n * @returns Branded ChatId\n * @throws {TypeError} If value is not a valid UUID v4 format\n *\n * @example\n * ```ts\n * const id = toChatId(\"550e8400-e29b-41d4-a716-446655440000\");\n * ```\n */\nexport function toChatId(value: string): ChatId {\n  if (!UUID_RE.test(value)) {\n    throw new TypeError(`Invalid ChatId: \"${value}\" is not a valid UUID`);\n  }\n  return value as ChatId;\n}\n\n/**\n * Accepts either a plain string or branded ChatId for API convenience.\n * Use this in public API signatures so consumers don't need `as ChatId` casts.\n */\nexport type ChatIdLike = string | ChatId;\n\n// ─── Status Types ──────────────────────────────────────────────\n\n/** Lifecycle status of a message part (text, reasoning, etc.) */\nexport type PartStatus = \"pending\" | \"streaming\" | \"complete\" | \"error\";\n/** Lifecycle status of a tool call within a message */\nexport type ToolCallStatus = \"pending\" | \"running\" | \"requires_approval\" | \"complete\" | \"error\" | \"denied\";\n/** Lifecycle status of an entire message */\nexport type MessageStatus = \"pending\" | \"streaming\" | \"complete\" | \"error\" | \"cancelled\";\n/** Lifecycle status of a chat session */\nexport type SessionStatus = \"active\" | \"archived\";\n/** Lifecycle status of the chat runtime */\nexport type RuntimeStatus = \"idle\" | \"streaming\" | \"error\" | \"disposed\";\n\n// ─── Message Parts (union) ─────────────────────────────────────\n\n/** Plain text content part */\nexport interface TextPart { type: \"text\"; text: string; status: PartStatus; }\n/** Model reasoning/thinking content part */\nexport interface ReasoningPart { type: \"reasoning\"; text: string; status: PartStatus; }\n/** Tool invocation part with call ID, arguments, optional result */\nexport interface ToolCallPart { type: \"tool_call\"; toolCallId: string; name: string; args: unknown; result?: unknown; status: ToolCallStatus; error?: string; }\n/** Source reference part (URL citation) */\nexport interface SourcePart { type: \"source\"; url: string; title?: string; status: PartStatus; }\n/** File attachment part (base64-encoded data) */\nexport interface FilePart { type: \"file\"; name: string; mimeType: string; data: string; status: PartStatus; }\n/** Union of all message part types */\nexport type MessagePart = TextPart | ReasoningPart | ToolCallPart | SourcePart | FilePart;\n\n// ─── Chat Message ──────────────────────────────────────────────\n\n/** Role of message author */\nexport type ChatRole = \"user\" | \"assistant\" | \"system\";\n\n/** Metadata attached to messages — useful preset for the TMetadata generic */\nexport interface ChatMessageMetadata {\n  model?: string;\n  backend?: string;\n  usage?: UsageData;\n  isSummary?: boolean;\n  isArchived?: boolean;\n  estimatedTokens?: number;\n  custom?: Record<string, unknown>;\n}\n\n/** Message status */\nexport type ChatMessageStatus = MessageStatus;\n\n/** A single chat message — the fundamental unit of conversation */\nexport interface ChatMessage<TMetadata = unknown> {\n  id: ChatId;\n  role: ChatRole;\n  parts: MessagePart[];\n  metadata?: TMetadata;\n  createdAt: string;\n  updatedAt?: string;\n  status: MessageStatus;\n}\n\n// ─── Convenience Getters ───────────────────────────────────────\n\n/**\n * Join all TextPart texts in a message\n * @param message - The chat message to extract text from\n * @returns Concatenated text content\n */\nexport function getMessageText(message: ChatMessage): string {\n  return message.parts\n    .filter((p): p is TextPart => p.type === \"text\")\n    .map((p) => p.text)\n    .join(\"\");\n}\n\n/**\n * Filter all ToolCallParts from a message\n * @param message - The chat message to extract tool calls from\n * @returns Array of ToolCallPart\n */\nexport function getMessageToolCalls(message: ChatMessage): ToolCallPart[] {\n  return message.parts.filter((p): p is ToolCallPart => p.type === \"tool_call\");\n}\n\n/**\n * Join all ReasoningPart texts in a message\n * @param message - The chat message to extract reasoning from\n * @returns Concatenated reasoning content\n */\nexport function getMessageReasoning(message: ChatMessage): string {\n  return message.parts\n    .filter((p): p is ReasoningPart => p.type === \"reasoning\")\n    .map((p) => p.text)\n    .join(\"\");\n}\n\n// ─── Supporting Types ──────────────────────────────────────────\n\n/** Options for sending a message */\nexport interface SendOpts { sessionId?: string; model?: string; signal?: AbortSignal; metadata?: Record<string, unknown>; }\n/** Options for creating a new session */\nexport interface CreateSessionOpts { id?: string; title?: string; model?: string; metadata?: Record<string, unknown>; }\n/** Options for listing sessions with pagination */\nexport interface ListOpts { limit?: number; offset?: number; status?: SessionStatus; }\n/** Options for backend execution (model, tokens, tools) */\nexport interface BackendOpts { model: string; signal?: AbortSignal; systemPrompt?: string; temperature?: number; maxTokens?: number; tools?: Record<string, unknown>; providerOptions?: Record<string, unknown>; }\n/** Context passed to tool execute functions */\nexport interface ToolContext { sessionId: string; userId?: string; signal: AbortSignal; }\n/** Configuration for creating a chat runtime */\nexport interface ChatRuntimeConfig { backend: string; model?: string; apiKey?: string; baseUrl?: string; context?: { maxTokens?: number; reserveTokens?: number; strategy?: \"sliding\" | \"summarize\" | \"truncate\"; }; retry?: { maxRetries?: number; initialDelay?: number; backoffFactor?: number; }; providerOptions?: Record<string, unknown>; }\n\n// ─── Chat Session ──────────────────────────────────────────────\n\n/** Session configuration snapshot */\nexport interface ChatSessionConfig {\n  model: string;\n  backend: string;\n  systemPrompt?: string;\n  temperature?: number;\n  maxTokens?: number;\n}\n\n/** Session metadata */\nexport interface ChatSessionMetadata<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  messageCount: number;\n  totalTokens: number;\n  tags?: string[];\n  custom?: TCustom;\n}\n\n/** Chat session — a conversation with ordered messages */\nexport interface ChatSession<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  id: ChatId;\n  title?: string;\n  messages: ChatMessage[];\n  config: ChatSessionConfig;\n  metadata: ChatSessionMetadata<TCustom>;\n  status: SessionStatus;\n  createdAt: string;\n  updatedAt: string;\n  backendSessionId?: string;\n  /** Subscribe to session changes (for React useSyncExternalStore) */\n  subscribe?(callback: () => void): () => void;\n  /** Get immutable snapshot of session state (for React useSyncExternalStore) */\n  getSnapshot?(): ChatSession<TCustom>;\n  /** Last message in the session */\n  readonly lastMessage?: ChatMessage;\n}\n\n/** Lightweight session info for listing (without full message array) */\nexport interface SessionInfo {\n  id: ChatId;\n  title?: string;\n  status: SessionStatus;\n  messageCount: number;\n  lastMessage?: ChatMessage;\n  createdAt: string;\n  updatedAt: string;\n}\n\n// ─── Chat Events ───────────────────────────────────────────────\n\n/** Events emitted during chat operation */\nexport type ChatEvent =\n  | { type: \"message:start\"; messageId: ChatId; role: ChatRole }\n  | { type: \"message:delta\"; messageId: ChatId; text: string }\n  | { type: \"message:complete\"; messageId: ChatId; message: ChatMessage }\n  | {\n      type: \"tool:start\";\n      messageId: ChatId;\n      toolCallId: string;\n      toolName: string;\n      args: Record<string, unknown>;\n    }\n  | {\n      type: \"tool:complete\";\n      messageId: ChatId;\n      toolCallId: string;\n      toolName: string;\n      result: unknown;\n      isError?: boolean;\n    }\n  | { type: \"thinking:start\"; messageId: ChatId }\n  | { type: \"thinking:delta\"; messageId: ChatId; text: string }\n  | { type: \"thinking:end\"; messageId: ChatId }\n  | {\n      type: \"permission:request\";\n      messageId: ChatId;\n      toolName: string;\n      toolArgs: Record<string, unknown>;\n    }\n  | {\n      type: \"permission:response\";\n      messageId: ChatId;\n      toolName: string;\n      allowed: boolean;\n    }\n  | {\n      type: \"usage\";\n      promptTokens: number;\n      completionTokens: number;\n      model?: string;\n    }\n  | { type: \"session:created\"; sessionId: ChatId }\n  | { type: \"session:updated\"; sessionId: ChatId }\n  | {\n      type: \"error\";\n      error: string;\n      recoverable: boolean;\n      messageId?: ChatId;\n    }\n  | { type: \"typing:start\" }\n  | { type: \"typing:end\" }\n  | { type: \"heartbeat\" }\n  | { type: \"done\"; finalOutput?: string };\n\n/** All possible ChatEvent type strings */\nexport type ChatEventType = ChatEvent[\"type\"];\n\n// ─── Chat Middleware ───────────────────────────────────────────\n\n/** Context passed to ChatMiddleware hooks */\nexport interface ChatMiddlewareContext {\n  sessionId: ChatId;\n  signal: AbortSignal;\n}\n\n/** Runtime-level middleware for the send/receive lifecycle.\n *  Different from EventMiddleware which operates at the event bus level. */\nexport interface ChatMiddleware {\n  /** Transform message before sending to backend */\n  onBeforeSend?(message: ChatMessage, context: ChatMiddlewareContext): ChatMessage | Promise<ChatMessage>;\n  /** Transform/intercept stream events */\n  onEvent?(event: ChatEvent, context: ChatMiddlewareContext): ChatEvent | null | Promise<ChatEvent | null>;\n  /** Transform completed message after receiving from backend */\n  onAfterReceive?(message: ChatMessage, context: ChatMiddlewareContext): ChatMessage | Promise<ChatMessage>;\n  /** Intercept errors — return null to suppress, return error to propagate */\n  onError?(error: Error, context: ChatMiddlewareContext): Error | null | Promise<Error | null>;\n}\n\n// ─── Chat Provider Abstraction ─────────────────────────────────\n\n/** Options for sending a message to a provider */\nexport interface SendMessageOptions {\n  signal?: AbortSignal;\n  model?: string;\n  context?: Record<string, unknown>;\n  /** Additional tools to include in this request */\n  tools?: ToolDefinition[];\n}\n\n/** Abstract chat provider — wraps an IAgentService for chat use */\nexport interface IChatProvider {\n  readonly name: string;\n  sendMessage(\n    session: ChatSession,\n    message: string,\n    options?: SendMessageOptions,\n  ): Promise<ChatMessage>;\n  streamMessage(\n    session: ChatSession,\n    message: string,\n    options?: SendMessageOptions,\n  ): AsyncIterable<ChatEvent>;\n  listModels(): Promise<ModelInfo[]>;\n  validate(): Promise<{ valid: boolean; errors: string[] }>;\n  dispose(): Promise<void>;\n}\n\n// ─── Type Guards ───────────────────────────────────────────────\n\n/**\n * Check if a value is a ChatMessage\n * @param value - Value to check\n * @returns True if value has ChatMessage shape\n */\nexport function isChatMessage(value: unknown): value is ChatMessage {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.id === \"string\" &&\n    typeof obj.role === \"string\" &&\n    (obj.role === \"user\" ||\n      obj.role === \"assistant\" ||\n      obj.role === \"system\") &&\n    Array.isArray(obj.parts) &&\n    typeof obj.createdAt === \"string\" &&\n    typeof obj.status === \"string\"\n  );\n}\n\n/**\n * Check if a value is a ChatSession\n * @param value - Value to check\n * @returns True if value has ChatSession shape\n */\nexport function isChatSession(value: unknown): value is ChatSession {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.id === \"string\" &&\n    Array.isArray(obj.messages) &&\n    typeof obj.config === \"object\" &&\n    obj.config !== null &&\n    typeof obj.createdAt === \"string\" &&\n    typeof obj.updatedAt === \"string\" &&\n    typeof obj.status === \"string\"\n  );\n}\n\n/**\n * Check if a value is a MessagePart\n * @param value - Value to check\n * @returns True if value has MessagePart shape\n */\nexport function isMessagePart(value: unknown): value is MessagePart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.type === \"string\" &&\n    (obj.type === \"text\" ||\n      obj.type === \"reasoning\" ||\n      obj.type === \"tool_call\" ||\n      obj.type === \"source\" ||\n      obj.type === \"file\")\n  );\n}\n\n/**\n * Check if a value is a TextPart\n * @param value - Value to check\n * @returns True if value is a TextPart\n */\nexport function isTextPart(value: unknown): value is TextPart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"text\" && typeof obj.text === \"string\";\n}\n\n/**\n * Check if a value is a ToolCallPart\n * @param value - Value to check\n * @returns True if value is a ToolCallPart\n */\nexport function isToolCallPart(value: unknown): value is ToolCallPart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"tool_call\" && typeof obj.toolCallId === \"string\" && typeof obj.name === \"string\";\n}\n\n/**\n * Check if a value is a ReasoningPart\n * @param value - Value to check\n * @returns True if value is a ReasoningPart\n */\nexport function isReasoningPart(value: unknown): value is ReasoningPart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"reasoning\" && typeof obj.text === \"string\";\n}\n\n/**\n * Check if a value is a SourcePart\n * @param value - Value to check\n * @returns True if value is a SourcePart\n */\nexport function isSourcePart(value: unknown): value is SourcePart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"source\" && typeof obj.url === \"string\";\n}\n\n/**\n * Check if a value is a FilePart\n * @param value - Value to check\n * @returns True if value is a FilePart\n */\nexport function isFilePart(value: unknown): value is FilePart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"file\" && typeof obj.name === \"string\" && typeof obj.mimeType === \"string\";\n}\n\n/**\n * Check if a value is a ChatEvent\n * @param value - Value to check\n * @returns True if value has a valid ChatEvent type\n */\nexport function isChatEvent(value: unknown): value is ChatEvent {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  const validTypes: ChatEventType[] = [\n    \"message:start\",\n    \"message:delta\",\n    \"message:complete\",\n    \"tool:start\",\n    \"tool:complete\",\n    \"thinking:start\",\n    \"thinking:delta\",\n    \"thinking:end\",\n    \"permission:request\",\n    \"permission:response\",\n    \"usage\",\n    \"session:created\",\n    \"session:updated\",\n    \"error\",\n    \"typing:start\",\n    \"typing:end\",\n    \"heartbeat\",\n    \"done\",\n  ];\n  return validTypes.includes(obj.type as ChatEventType);\n}\n\n// ─── Agent Event Adapter ───────────────────────────────────────\n\n/**\n * Map a single AgentEvent to a ChatEvent (or null if no mapping)\n * @param event - The AgentEvent to convert\n * @param messageId - ChatId to associate with the event\n * @returns Corresponding ChatEvent or null if unmappable\n */\nexport function agentEventToChatEvent(\n  event: AgentEvent,\n  messageId: ChatId,\n): ChatEvent | null {\n  switch (event.type) {\n    case \"text_delta\":\n      return { type: \"message:delta\", messageId, text: event.text };\n    case \"thinking_start\":\n      return { type: \"thinking:start\", messageId };\n    case \"thinking_delta\":\n      return { type: \"thinking:delta\", messageId, text: event.text };\n    case \"thinking_end\":\n      return { type: \"thinking:end\", messageId };\n    case \"tool_call_start\":\n      return {\n        type: \"tool:start\",\n        messageId,\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        args: event.args as Record<string, unknown>,\n      };\n    case \"tool_call_end\":\n      return {\n        type: \"tool:complete\",\n        messageId,\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        result: event.result,\n      };\n    case \"permission_request\":\n      return {\n        type: \"permission:request\",\n        messageId,\n        toolName: event.request.toolName,\n        toolArgs: event.request.toolArgs,\n      };\n    case \"permission_response\":\n      return {\n        type: \"permission:response\",\n        messageId,\n        toolName: event.toolName,\n        allowed: event.decision.allowed,\n      };\n    case \"usage_update\":\n      return {\n        type: \"usage\",\n        promptTokens: event.promptTokens,\n        completionTokens: event.completionTokens,\n        model: event.model,\n      };\n    case \"error\":\n      return {\n        type: \"error\",\n        error: event.error,\n        recoverable: event.recoverable,\n        messageId,\n      };\n    case \"heartbeat\":\n      return { type: \"heartbeat\" };\n    case \"ask_user\":\n    case \"ask_user_response\":\n    case \"session_info\":\n    case \"done\":\n      return null;\n    default:\n      return null;\n  }\n}\n\n/**\n * Convert AgentEvent async iterable to ChatEvent async iterable\n * @param events - Source agent events\n * @param messageId - ChatId to associate with converted events\n * @returns Async iterable of ChatEvent (nulls filtered out)\n */\nexport async function* adaptAgentEvents(\n  events: AsyncIterable<AgentEvent>,\n  messageId: ChatId,\n): AsyncIterable<ChatEvent> {\n  for await (const event of events) {\n    const chatEvent = agentEventToChatEvent(event, messageId);\n    if (chatEvent !== null) {\n      yield chatEvent;\n    }\n  }\n}\n\n/**\n * Map a ChatEvent back to an AgentEvent for accumulator consumption.\n * Returns null for events that don't map to accumulator-relevant AgentEvents\n * (e.g. message:start, message:complete, usage, permission:*, heartbeat).\n *\n * @param event - The ChatEvent to convert\n * @returns Corresponding AgentEvent or null if not accumulator-relevant\n */\nexport function chatEventToAgentEvent(event: ChatEvent): AgentEvent | null {\n  switch (event.type) {\n    case \"message:delta\":\n      return { type: \"text_delta\", text: event.text };\n    case \"thinking:start\":\n      return { type: \"thinking_start\" };\n    case \"thinking:delta\":\n      return { type: \"thinking_delta\", text: event.text };\n    case \"thinking:end\":\n      return { type: \"thinking_end\" };\n    case \"tool:start\":\n      return {\n        type: \"tool_call_start\",\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        args: event.args as JSONValue,\n      };\n    case \"tool:complete\":\n      return {\n        type: \"tool_call_end\",\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        result: event.result as JSONValue,\n      };\n    case \"error\":\n      return { type: \"error\", error: event.error, recoverable: event.recoverable };\n    default:\n      return null;\n  }\n}\n\n// ─── Message Conversion ────────────────────────────────────────\n\n/**\n * Convert a ChatMessage to agent-sdk Message format\n * @param message - The ChatMessage to convert\n * @returns agent-sdk Message\n */\nexport function toAgentMessage(message: ChatMessage): Message {\n  const textContent = getMessageText(message);\n  const toolCallParts = getMessageToolCalls(message);\n\n  switch (message.role) {\n    case \"user\":\n      return { role: \"user\", content: textContent };\n    case \"assistant\": {\n      const toolCalls: ToolCall[] | undefined = toolCallParts.length > 0\n        ? toolCallParts.map((p) => ({ id: p.toolCallId, name: p.name, args: p.args as JSONValue }))\n        : undefined;\n      return {\n        role: \"assistant\",\n        content: textContent,\n        toolCalls,\n      };\n    }\n    case \"system\":\n      return { role: \"system\", content: textContent };\n  }\n}\n\n/**\n * Convert an agent-sdk Message to ChatMessage\n * @param message - The agent-sdk Message to convert\n * @param id - Optional ChatId (auto-generated if omitted)\n * @returns ChatMessage with status \"complete\"\n */\nexport function fromAgentMessage(message: Message, id?: ChatId): ChatMessage {\n  const chatId = id ?? createChatId();\n  const now = new Date().toISOString();\n\n  const parts: MessagePart[] = [];\n\n  // Build text content\n  const textContent =\n    typeof message.content === \"string\"\n      ? message.content\n      : Array.isArray(message.content)\n        ? message.content\n            .filter((part) => part.type === \"text\")\n            .map((part) => part.text)\n            .join(\"\\n\")\n        : (message.content ?? \"\");\n\n  if (textContent) {\n    parts.push({ type: \"text\", text: textContent, status: \"complete\" });\n  }\n\n  // Add tool calls from assistant messages\n  if (message.role === \"assistant\" && message.toolCalls) {\n    for (const tc of message.toolCalls) {\n      parts.push({\n        type: \"tool_call\",\n        toolCallId: tc.id,\n        name: tc.name,\n        args: tc.args,\n        status: \"complete\",\n      });\n    }\n  }\n\n  // Add tool results — map 'tool' role to 'assistant'\n  if (message.role === \"tool\" && message.toolResults) {\n    for (const tr of message.toolResults) {\n      parts.push({\n        type: \"tool_call\",\n        toolCallId: tr.toolCallId,\n        name: tr.name,\n        args: {},\n        result: tr.result,\n        status: \"complete\",\n      });\n    }\n  }\n\n  // Ensure at least an empty text part for empty messages\n  if (parts.length === 0) {\n    parts.push({ type: \"text\", text: \"\", status: \"complete\" });\n  }\n\n  const role: ChatRole = message.role === \"tool\" ? \"assistant\" : message.role;\n\n  return {\n    id: chatId,\n    role,\n    parts,\n    createdAt: now,\n    status: \"complete\",\n  };\n}\n\n/**\n * Extract ToolResults from ToolCallParts that have results\n * @param message - The ChatMessage to extract results from\n * @returns Array of ToolResult for completed tool calls\n */\nexport function extractToolResults(message: ChatMessage): ToolResult[] {\n  return getMessageToolCalls(message)\n    .filter((p) => p.result !== undefined)\n    .map((p) => ({\n      toolCallId: p.toolCallId,\n      name: p.name,\n      result: p.result as JSONValue,\n      isError: p.status === \"error\" ? true : undefined,\n    }));\n}\n","/**\n * @witqq/agent-sdk/chat/accumulator\n *\n * MessageAccumulator converts a stream of AgentEvent objects into a ChatMessage\n * with correct MessagePart array. Handles text, reasoning, and tool call\n * accumulation with proper status transitions.\n */\n\nimport type { AgentEvent } from \"../types.js\";\nimport type { ChatMessage, ChatId, MessagePart, TextPart, ReasoningPart, ToolCallPart } from \"./core.js\";\nimport { createChatId } from \"./core.js\";\n\n/**\n * Converts a stream of AgentEvent objects into a complete ChatMessage.\n * Tracks text, reasoning, and tool call parts with proper status transitions.\n *\n * @example\n * ```typescript\n * const acc = new MessageAccumulator();\n * for await (const event of agentEvents) {\n *   acc.apply(event);\n *   renderMessage(acc.snapshot()); // in-progress UI update\n * }\n * const message = acc.finalize();\n * ```\n */\nexport class MessageAccumulator {\n  private readonly messageId: ChatId;\n  private readonly parts: MessagePart[] = [];\n  private status: \"pending\" | \"streaming\" | \"complete\" | \"error\" | \"cancelled\" = \"pending\";\n  private currentTextPart: TextPart | null = null;\n  private currentReasoningPart: ReasoningPart | null = null;\n  private toolCallParts = new Map<string, ToolCallPart>();\n  private _finalized = false;\n\n  constructor(messageId?: ChatId) {\n    this.messageId = messageId ?? createChatId();\n  }\n\n  /** Get current message ID */\n  get id(): ChatId { return this.messageId; }\n\n  /**\n   * Apply an AgentEvent to accumulate into the message\n   * @param event - AgentEvent to process\n   * @throws Error if accumulator is already finalized\n   */\n  apply(event: AgentEvent): void {\n    if (this._finalized) throw new Error(\"Cannot apply events to finalized accumulator\");\n\n    if (this.status === \"pending\") {\n      this.status = \"streaming\";\n    }\n\n    switch (event.type) {\n      case \"text_delta\":\n        this.handleTextDelta(event.text);\n        break;\n      case \"thinking_start\":\n        this.finalizeCurrentText();\n        this.currentReasoningPart = { type: \"reasoning\", text: \"\", status: \"streaming\" };\n        this.parts.push(this.currentReasoningPart);\n        break;\n      case \"thinking_delta\":\n        if (this.currentReasoningPart) {\n          this.currentReasoningPart.text += event.text;\n        }\n        break;\n      case \"thinking_end\":\n        if (this.currentReasoningPart) {\n          this.currentReasoningPart.status = \"complete\";\n          this.currentReasoningPart = null;\n        }\n        break;\n      case \"tool_call_start\": {\n        this.finalizeCurrentText();\n        const toolPart: ToolCallPart = {\n          type: \"tool_call\",\n          toolCallId: event.toolCallId,\n          name: event.toolName,\n          args: event.args,\n          status: \"running\",\n        };\n        this.toolCallParts.set(event.toolCallId, toolPart);\n        this.parts.push(toolPart);\n        break;\n      }\n      case \"tool_call_end\": {\n        const existing = this.toolCallParts.get(event.toolCallId);\n        if (existing) {\n          existing.result = event.result;\n          existing.status = \"complete\";\n        }\n        break;\n      }\n      case \"error\":\n        this.status = \"error\";\n        break;\n      case \"done\":\n        break;\n      // Other events (heartbeat, ask_user, etc.) — ignore\n    }\n  }\n\n  private handleTextDelta(text: string): void {\n    if (!this.currentTextPart) {\n      this.currentTextPart = { type: \"text\", text: \"\", status: \"streaming\" };\n      this.parts.push(this.currentTextPart);\n    }\n    this.currentTextPart.text += text;\n  }\n\n  private finalizeCurrentText(): void {\n    if (this.currentTextPart) {\n      this.currentTextPart.status = \"complete\";\n      this.currentTextPart = null;\n    }\n  }\n\n  /**\n   * Get a snapshot of the current accumulated message (for streaming UI)\n   * @returns ChatMessage with current parts and \"streaming\" status\n   */\n  snapshot(): ChatMessage {\n    const now = new Date().toISOString();\n    return {\n      id: this.messageId,\n      role: \"assistant\",\n      parts: this.parts.map(p => ({ ...p })),\n      status: this.status === \"pending\" ? \"pending\" : \"streaming\",\n      createdAt: now,\n      updatedAt: now,\n    };\n  }\n\n  /**\n   * Finalize the accumulator and return the complete ChatMessage\n   * @returns Completed ChatMessage with all parts finalized\n   * @throws Error if accumulator is already finalized\n   */\n  finalize(): ChatMessage {\n    if (this._finalized) throw new Error(\"Accumulator already finalized\");\n    this._finalized = true;\n\n    // Finalize any open parts\n    this.finalizeCurrentText();\n    if (this.currentReasoningPart) {\n      this.currentReasoningPart.status = \"complete\";\n      this.currentReasoningPart = null;\n    }\n\n    // Mark incomplete tool calls as error\n    for (const [, toolPart] of this.toolCallParts) {\n      if (toolPart.status === \"running\" || toolPart.status === \"pending\") {\n        toolPart.status = \"error\";\n      }\n    }\n\n    // Set final message status\n    if (this.status !== \"error\" && this.status !== \"cancelled\") {\n      this.status = \"complete\";\n    }\n\n    const now = new Date().toISOString();\n    return {\n      id: this.messageId,\n      role: \"assistant\",\n      parts: this.parts,\n      status: this.status,\n      createdAt: now,\n      updatedAt: now,\n    };\n  }\n\n  /** Check if the accumulator has been finalized */\n  get finalized(): boolean { return this._finalized; }\n}\n"]}

package/dist/chat/accumulator.d.cts

@@ -0,0 +1,61 @@
+import { A as AgentEvent } from '../types-CqvUAYxt.cjs';
+import { ChatId, ChatMessage } from './core.cjs';
+import 'zod';
+
+/**
+ * @witqq/agent-sdk/chat/accumulator
+ *
+ * MessageAccumulator converts a stream of AgentEvent objects into a ChatMessage
+ * with correct MessagePart array. Handles text, reasoning, and tool call
+ * accumulation with proper status transitions.
+ */
+
+/**
+ * Converts a stream of AgentEvent objects into a complete ChatMessage.
+ * Tracks text, reasoning, and tool call parts with proper status transitions.
+ *
+ * @example
+ * ```typescript
+ * const acc = new MessageAccumulator();
+ * for await (const event of agentEvents) {
+ *   acc.apply(event);
+ *   renderMessage(acc.snapshot()); // in-progress UI update
+ * }
+ * const message = acc.finalize();
+ * ```
+ */
+declare class MessageAccumulator {
+    private readonly messageId;
+    private readonly parts;
+    private status;
+    private currentTextPart;
+    private currentReasoningPart;
+    private toolCallParts;
+    private _finalized;
+    constructor(messageId?: ChatId);
+    /** Get current message ID */
+    get id(): ChatId;
+    /**
+     * Apply an AgentEvent to accumulate into the message
+     * @param event - AgentEvent to process
+     * @throws Error if accumulator is already finalized
+     */
+    apply(event: AgentEvent): void;
+    private handleTextDelta;
+    private finalizeCurrentText;
+    /**
+     * Get a snapshot of the current accumulated message (for streaming UI)
+     * @returns ChatMessage with current parts and "streaming" status
+     */
+    snapshot(): ChatMessage;
+    /**
+     * Finalize the accumulator and return the complete ChatMessage
+     * @returns Completed ChatMessage with all parts finalized
+     * @throws Error if accumulator is already finalized
+     */
+    finalize(): ChatMessage;
+    /** Check if the accumulator has been finalized */
+    get finalized(): boolean;
+}
+
+export { MessageAccumulator };

package/dist/chat/accumulator.d.ts

@@ -0,0 +1,61 @@
+import { A as AgentEvent } from '../types-CqvUAYxt.js';
+import { ChatId, ChatMessage } from './core.js';
+import 'zod';
+
+/**
+ * @witqq/agent-sdk/chat/accumulator
+ *
+ * MessageAccumulator converts a stream of AgentEvent objects into a ChatMessage
+ * with correct MessagePart array. Handles text, reasoning, and tool call
+ * accumulation with proper status transitions.
+ */
+
+/**
+ * Converts a stream of AgentEvent objects into a complete ChatMessage.
+ * Tracks text, reasoning, and tool call parts with proper status transitions.
+ *
+ * @example
+ * ```typescript
+ * const acc = new MessageAccumulator();
+ * for await (const event of agentEvents) {
+ *   acc.apply(event);
+ *   renderMessage(acc.snapshot()); // in-progress UI update
+ * }
+ * const message = acc.finalize();
+ * ```
+ */
+declare class MessageAccumulator {
+    private readonly messageId;
+    private readonly parts;
+    private status;
+    private currentTextPart;
+    private currentReasoningPart;
+    private toolCallParts;
+    private _finalized;
+    constructor(messageId?: ChatId);
+    /** Get current message ID */
+    get id(): ChatId;
+    /**
+     * Apply an AgentEvent to accumulate into the message
+     * @param event - AgentEvent to process
+     * @throws Error if accumulator is already finalized
+     */
+    apply(event: AgentEvent): void;
+    private handleTextDelta;
+    private finalizeCurrentText;
+    /**
+     * Get a snapshot of the current accumulated message (for streaming UI)
+     * @returns ChatMessage with current parts and "streaming" status
+     */
+    snapshot(): ChatMessage;
+    /**
+     * Finalize the accumulator and return the complete ChatMessage
+     * @returns Completed ChatMessage with all parts finalized
+     * @throws Error if accumulator is already finalized
+     */
+    finalize(): ChatMessage;
+    /** Check if the accumulator has been finalized */
+    get finalized(): boolean;
+}
+
+export { MessageAccumulator };

package/dist/chat/accumulator.js

@@ -0,0 +1,145 @@
+// src/chat/core.ts
+function createChatId() {
+  return crypto.randomUUID();
+}
+
+// src/chat/accumulator.ts
+var MessageAccumulator = class {
+  messageId;
+  parts = [];
+  status = "pending";
+  currentTextPart = null;
+  currentReasoningPart = null;
+  toolCallParts = /* @__PURE__ */ new Map();
+  _finalized = false;
+  constructor(messageId) {
+    this.messageId = messageId ?? createChatId();
+  }
+  /** Get current message ID */
+  get id() {
+    return this.messageId;
+  }
+  /**
+   * Apply an AgentEvent to accumulate into the message
+   * @param event - AgentEvent to process
+   * @throws Error if accumulator is already finalized
+   */
+  apply(event) {
+    if (this._finalized) throw new Error("Cannot apply events to finalized accumulator");
+    if (this.status === "pending") {
+      this.status = "streaming";
+    }
+    switch (event.type) {
+      case "text_delta":
+        this.handleTextDelta(event.text);
+        break;
+      case "thinking_start":
+        this.finalizeCurrentText();
+        this.currentReasoningPart = { type: "reasoning", text: "", status: "streaming" };
+        this.parts.push(this.currentReasoningPart);
+        break;
+      case "thinking_delta":
+        if (this.currentReasoningPart) {
+          this.currentReasoningPart.text += event.text;
+        }
+        break;
+      case "thinking_end":
+        if (this.currentReasoningPart) {
+          this.currentReasoningPart.status = "complete";
+          this.currentReasoningPart = null;
+        }
+        break;
+      case "tool_call_start": {
+        this.finalizeCurrentText();
+        const toolPart = {
+          type: "tool_call",
+          toolCallId: event.toolCallId,
+          name: event.toolName,
+          args: event.args,
+          status: "running"
+        };
+        this.toolCallParts.set(event.toolCallId, toolPart);
+        this.parts.push(toolPart);
+        break;
+      }
+      case "tool_call_end": {
+        const existing = this.toolCallParts.get(event.toolCallId);
+        if (existing) {
+          existing.result = event.result;
+          existing.status = "complete";
+        }
+        break;
+      }
+      case "error":
+        this.status = "error";
+        break;
+    }
+  }
+  handleTextDelta(text) {
+    if (!this.currentTextPart) {
+      this.currentTextPart = { type: "text", text: "", status: "streaming" };
+      this.parts.push(this.currentTextPart);
+    }
+    this.currentTextPart.text += text;
+  }
+  finalizeCurrentText() {
+    if (this.currentTextPart) {
+      this.currentTextPart.status = "complete";
+      this.currentTextPart = null;
+    }
+  }
+  /**
+   * Get a snapshot of the current accumulated message (for streaming UI)
+   * @returns ChatMessage with current parts and "streaming" status
+   */
+  snapshot() {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: this.messageId,
+      role: "assistant",
+      parts: this.parts.map((p) => ({ ...p })),
+      status: this.status === "pending" ? "pending" : "streaming",
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  /**
+   * Finalize the accumulator and return the complete ChatMessage
+   * @returns Completed ChatMessage with all parts finalized
+   * @throws Error if accumulator is already finalized
+   */
+  finalize() {
+    if (this._finalized) throw new Error("Accumulator already finalized");
+    this._finalized = true;
+    this.finalizeCurrentText();
+    if (this.currentReasoningPart) {
+      this.currentReasoningPart.status = "complete";
+      this.currentReasoningPart = null;
+    }
+    for (const [, toolPart] of this.toolCallParts) {
+      if (toolPart.status === "running" || toolPart.status === "pending") {
+        toolPart.status = "error";
+      }
+    }
+    if (this.status !== "error" && this.status !== "cancelled") {
+      this.status = "complete";
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: this.messageId,
+      role: "assistant",
+      parts: this.parts,
+      status: this.status,
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  /** Check if the accumulator has been finalized */
+  get finalized() {
+    return this._finalized;
+  }
+};
+
+export { MessageAccumulator };
+//# sourceMappingURL=accumulator.js.map
+//# sourceMappingURL=accumulator.js.map

package/dist/chat/accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/chat/core.ts","../../src/chat/accumulator.ts"],"names":[],"mappings":"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","file":"accumulator.js","sourcesContent":["/**\n * @witqq/agent-sdk/chat/core\n *\n * Foundational chat types and utilities: ChatMessage, ChatSession, ChatEvent,\n * IChatProvider, type guards, and AgentEvent↔ChatEvent bridge functions.\n */\n\nimport type {\n  AgentEvent,\n  Message,\n  ToolCall,\n  ToolResult,\n  ToolDefinition,\n  UsageData,\n  ModelInfo,\n  JSONValue,\n} from \"../types.js\";\n\n// ─── Unique ID ─────────────────────────────────────────────────\n\n/** Branded type for unique identifiers */\nexport type ChatId = string & { readonly __brand: \"ChatId\" };\n\n/**\n * Generate a new unique ChatId (crypto.randomUUID-based)\n * @returns Branded ChatId string\n */\nexport function createChatId(): ChatId {\n  return crypto.randomUUID() as ChatId;\n}\n\n/** UUID v4 pattern for ChatId validation */\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/**\n * Cast a string to ChatId with UUID format validation.\n * Use this instead of manual `as ChatId` type assertions.\n *\n * @param value - String to validate and cast\n * @returns Branded ChatId\n * @throws {TypeError} If value is not a valid UUID v4 format\n *\n * @example\n * ```ts\n * const id = toChatId(\"550e8400-e29b-41d4-a716-446655440000\");\n * ```\n */\nexport function toChatId(value: string): ChatId {\n  if (!UUID_RE.test(value)) {\n    throw new TypeError(`Invalid ChatId: \"${value}\" is not a valid UUID`);\n  }\n  return value as ChatId;\n}\n\n/**\n * Accepts either a plain string or branded ChatId for API convenience.\n * Use this in public API signatures so consumers don't need `as ChatId` casts.\n */\nexport type ChatIdLike = string | ChatId;\n\n// ─── Status Types ──────────────────────────────────────────────\n\n/** Lifecycle status of a message part (text, reasoning, etc.) */\nexport type PartStatus = \"pending\" | \"streaming\" | \"complete\" | \"error\";\n/** Lifecycle status of a tool call within a message */\nexport type ToolCallStatus = \"pending\" | \"running\" | \"requires_approval\" | \"complete\" | \"error\" | \"denied\";\n/** Lifecycle status of an entire message */\nexport type MessageStatus = \"pending\" | \"streaming\" | \"complete\" | \"error\" | \"cancelled\";\n/** Lifecycle status of a chat session */\nexport type SessionStatus = \"active\" | \"archived\";\n/** Lifecycle status of the chat runtime */\nexport type RuntimeStatus = \"idle\" | \"streaming\" | \"error\" | \"disposed\";\n\n// ─── Message Parts (union) ─────────────────────────────────────\n\n/** Plain text content part */\nexport interface TextPart { type: \"text\"; text: string; status: PartStatus; }\n/** Model reasoning/thinking content part */\nexport interface ReasoningPart { type: \"reasoning\"; text: string; status: PartStatus; }\n/** Tool invocation part with call ID, arguments, optional result */\nexport interface ToolCallPart { type: \"tool_call\"; toolCallId: string; name: string; args: unknown; result?: unknown; status: ToolCallStatus; error?: string; }\n/** Source reference part (URL citation) */\nexport interface SourcePart { type: \"source\"; url: string; title?: string; status: PartStatus; }\n/** File attachment part (base64-encoded data) */\nexport interface FilePart { type: \"file\"; name: string; mimeType: string; data: string; status: PartStatus; }\n/** Union of all message part types */\nexport type MessagePart = TextPart | ReasoningPart | ToolCallPart | SourcePart | FilePart;\n\n// ─── Chat Message ──────────────────────────────────────────────\n\n/** Role of message author */\nexport type ChatRole = \"user\" | \"assistant\" | \"system\";\n\n/** Metadata attached to messages — useful preset for the TMetadata generic */\nexport interface ChatMessageMetadata {\n  model?: string;\n  backend?: string;\n  usage?: UsageData;\n  isSummary?: boolean;\n  isArchived?: boolean;\n  estimatedTokens?: number;\n  custom?: Record<string, unknown>;\n}\n\n/** Message status */\nexport type ChatMessageStatus = MessageStatus;\n\n/** A single chat message — the fundamental unit of conversation */\nexport interface ChatMessage<TMetadata = unknown> {\n  id: ChatId;\n  role: ChatRole;\n  parts: MessagePart[];\n  metadata?: TMetadata;\n  createdAt: string;\n  updatedAt?: string;\n  status: MessageStatus;\n}\n\n// ─── Convenience Getters ───────────────────────────────────────\n\n/**\n * Join all TextPart texts in a message\n * @param message - The chat message to extract text from\n * @returns Concatenated text content\n */\nexport function getMessageText(message: ChatMessage): string {\n  return message.parts\n    .filter((p): p is TextPart => p.type === \"text\")\n    .map((p) => p.text)\n    .join(\"\");\n}\n\n/**\n * Filter all ToolCallParts from a message\n * @param message - The chat message to extract tool calls from\n * @returns Array of ToolCallPart\n */\nexport function getMessageToolCalls(message: ChatMessage): ToolCallPart[] {\n  return message.parts.filter((p): p is ToolCallPart => p.type === \"tool_call\");\n}\n\n/**\n * Join all ReasoningPart texts in a message\n * @param message - The chat message to extract reasoning from\n * @returns Concatenated reasoning content\n */\nexport function getMessageReasoning(message: ChatMessage): string {\n  return message.parts\n    .filter((p): p is ReasoningPart => p.type === \"reasoning\")\n    .map((p) => p.text)\n    .join(\"\");\n}\n\n// ─── Supporting Types ──────────────────────────────────────────\n\n/** Options for sending a message */\nexport interface SendOpts { sessionId?: string; model?: string; signal?: AbortSignal; metadata?: Record<string, unknown>; }\n/** Options for creating a new session */\nexport interface CreateSessionOpts { id?: string; title?: string; model?: string; metadata?: Record<string, unknown>; }\n/** Options for listing sessions with pagination */\nexport interface ListOpts { limit?: number; offset?: number; status?: SessionStatus; }\n/** Options for backend execution (model, tokens, tools) */\nexport interface BackendOpts { model: string; signal?: AbortSignal; systemPrompt?: string; temperature?: number; maxTokens?: number; tools?: Record<string, unknown>; providerOptions?: Record<string, unknown>; }\n/** Context passed to tool execute functions */\nexport interface ToolContext { sessionId: string; userId?: string; signal: AbortSignal; }\n/** Configuration for creating a chat runtime */\nexport interface ChatRuntimeConfig { backend: string; model?: string; apiKey?: string; baseUrl?: string; context?: { maxTokens?: number; reserveTokens?: number; strategy?: \"sliding\" | \"summarize\" | \"truncate\"; }; retry?: { maxRetries?: number; initialDelay?: number; backoffFactor?: number; }; providerOptions?: Record<string, unknown>; }\n\n// ─── Chat Session ──────────────────────────────────────────────\n\n/** Session configuration snapshot */\nexport interface ChatSessionConfig {\n  model: string;\n  backend: string;\n  systemPrompt?: string;\n  temperature?: number;\n  maxTokens?: number;\n}\n\n/** Session metadata */\nexport interface ChatSessionMetadata<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  messageCount: number;\n  totalTokens: number;\n  tags?: string[];\n  custom?: TCustom;\n}\n\n/** Chat session — a conversation with ordered messages */\nexport interface ChatSession<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  id: ChatId;\n  title?: string;\n  messages: ChatMessage[];\n  config: ChatSessionConfig;\n  metadata: ChatSessionMetadata<TCustom>;\n  status: SessionStatus;\n  createdAt: string;\n  updatedAt: string;\n  backendSessionId?: string;\n  /** Subscribe to session changes (for React useSyncExternalStore) */\n  subscribe?(callback: () => void): () => void;\n  /** Get immutable snapshot of session state (for React useSyncExternalStore) */\n  getSnapshot?(): ChatSession<TCustom>;\n  /** Last message in the session */\n  readonly lastMessage?: ChatMessage;\n}\n\n/** Lightweight session info for listing (without full message array) */\nexport interface SessionInfo {\n  id: ChatId;\n  title?: string;\n  status: SessionStatus;\n  messageCount: number;\n  lastMessage?: ChatMessage;\n  createdAt: string;\n  updatedAt: string;\n}\n\n// ─── Chat Events ───────────────────────────────────────────────\n\n/** Events emitted during chat operation */\nexport type ChatEvent =\n  | { type: \"message:start\"; messageId: ChatId; role: ChatRole }\n  | { type: \"message:delta\"; messageId: ChatId; text: string }\n  | { type: \"message:complete\"; messageId: ChatId; message: ChatMessage }\n  | {\n      type: \"tool:start\";\n      messageId: ChatId;\n      toolCallId: string;\n      toolName: string;\n      args: Record<string, unknown>;\n    }\n  | {\n      type: \"tool:complete\";\n      messageId: ChatId;\n      toolCallId: string;\n      toolName: string;\n      result: unknown;\n      isError?: boolean;\n    }\n  | { type: \"thinking:start\"; messageId: ChatId }\n  | { type: \"thinking:delta\"; messageId: ChatId; text: string }\n  | { type: \"thinking:end\"; messageId: ChatId }\n  | {\n      type: \"permission:request\";\n      messageId: ChatId;\n      toolName: string;\n      toolArgs: Record<string, unknown>;\n    }\n  | {\n      type: \"permission:response\";\n      messageId: ChatId;\n      toolName: string;\n      allowed: boolean;\n    }\n  | {\n      type: \"usage\";\n      promptTokens: number;\n      completionTokens: number;\n      model?: string;\n    }\n  | { type: \"session:created\"; sessionId: ChatId }\n  | { type: \"session:updated\"; sessionId: ChatId }\n  | {\n      type: \"error\";\n      error: string;\n      recoverable: boolean;\n      messageId?: ChatId;\n    }\n  | { type: \"typing:start\" }\n  | { type: \"typing:end\" }\n  | { type: \"heartbeat\" }\n  | { type: \"done\"; finalOutput?: string };\n\n/** All possible ChatEvent type strings */\nexport type ChatEventType = ChatEvent[\"type\"];\n\n// ─── Chat Middleware ───────────────────────────────────────────\n\n/** Context passed to ChatMiddleware hooks */\nexport interface ChatMiddlewareContext {\n  sessionId: ChatId;\n  signal: AbortSignal;\n}\n\n/** Runtime-level middleware for the send/receive lifecycle.\n *  Different from EventMiddleware which operates at the event bus level. */\nexport interface ChatMiddleware {\n  /** Transform message before sending to backend */\n  onBeforeSend?(message: ChatMessage, context: ChatMiddlewareContext): ChatMessage | Promise<ChatMessage>;\n  /** Transform/intercept stream events */\n  onEvent?(event: ChatEvent, context: ChatMiddlewareContext): ChatEvent | null | Promise<ChatEvent | null>;\n  /** Transform completed message after receiving from backend */\n  onAfterReceive?(message: ChatMessage, context: ChatMiddlewareContext): ChatMessage | Promise<ChatMessage>;\n  /** Intercept errors — return null to suppress, return error to propagate */\n  onError?(error: Error, context: ChatMiddlewareContext): Error | null | Promise<Error | null>;\n}\n\n// ─── Chat Provider Abstraction ─────────────────────────────────\n\n/** Options for sending a message to a provider */\nexport interface SendMessageOptions {\n  signal?: AbortSignal;\n  model?: string;\n  context?: Record<string, unknown>;\n  /** Additional tools to include in this request */\n  tools?: ToolDefinition[];\n}\n\n/** Abstract chat provider — wraps an IAgentService for chat use */\nexport interface IChatProvider {\n  readonly name: string;\n  sendMessage(\n    session: ChatSession,\n    message: string,\n    options?: SendMessageOptions,\n  ): Promise<ChatMessage>;\n  streamMessage(\n    session: ChatSession,\n    message: string,\n    options?: SendMessageOptions,\n  ): AsyncIterable<ChatEvent>;\n  listModels(): Promise<ModelInfo[]>;\n  validate(): Promise<{ valid: boolean; errors: string[] }>;\n  dispose(): Promise<void>;\n}\n\n// ─── Type Guards ───────────────────────────────────────────────\n\n/**\n * Check if a value is a ChatMessage\n * @param value - Value to check\n * @returns True if value has ChatMessage shape\n */\nexport function isChatMessage(value: unknown): value is ChatMessage {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.id === \"string\" &&\n    typeof obj.role === \"string\" &&\n    (obj.role === \"user\" ||\n      obj.role === \"assistant\" ||\n      obj.role === \"system\") &&\n    Array.isArray(obj.parts) &&\n    typeof obj.createdAt === \"string\" &&\n    typeof obj.status === \"string\"\n  );\n}\n\n/**\n * Check if a value is a ChatSession\n * @param value - Value to check\n * @returns True if value has ChatSession shape\n */\nexport function isChatSession(value: unknown): value is ChatSession {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.id === \"string\" &&\n    Array.isArray(obj.messages) &&\n    typeof obj.config === \"object\" &&\n    obj.config !== null &&\n    typeof obj.createdAt === \"string\" &&\n    typeof obj.updatedAt === \"string\" &&\n    typeof obj.status === \"string\"\n  );\n}\n\n/**\n * Check if a value is a MessagePart\n * @param value - Value to check\n * @returns True if value has MessagePart shape\n */\nexport function isMessagePart(value: unknown): value is MessagePart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.type === \"string\" &&\n    (obj.type === \"text\" ||\n      obj.type === \"reasoning\" ||\n      obj.type === \"tool_call\" ||\n      obj.type === \"source\" ||\n      obj.type === \"file\")\n  );\n}\n\n/**\n * Check if a value is a TextPart\n * @param value - Value to check\n * @returns True if value is a TextPart\n */\nexport function isTextPart(value: unknown): value is TextPart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"text\" && typeof obj.text === \"string\";\n}\n\n/**\n * Check if a value is a ToolCallPart\n * @param value - Value to check\n * @returns True if value is a ToolCallPart\n */\nexport function isToolCallPart(value: unknown): value is ToolCallPart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"tool_call\" && typeof obj.toolCallId === \"string\" && typeof obj.name === \"string\";\n}\n\n/**\n * Check if a value is a ReasoningPart\n * @param value - Value to check\n * @returns True if value is a ReasoningPart\n */\nexport function isReasoningPart(value: unknown): value is ReasoningPart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"reasoning\" && typeof obj.text === \"string\";\n}\n\n/**\n * Check if a value is a SourcePart\n * @param value - Value to check\n * @returns True if value is a SourcePart\n */\nexport function isSourcePart(value: unknown): value is SourcePart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"source\" && typeof obj.url === \"string\";\n}\n\n/**\n * Check if a value is a FilePart\n * @param value - Value to check\n * @returns True if value is a FilePart\n */\nexport function isFilePart(value: unknown): value is FilePart {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  return obj.type === \"file\" && typeof obj.name === \"string\" && typeof obj.mimeType === \"string\";\n}\n\n/**\n * Check if a value is a ChatEvent\n * @param value - Value to check\n * @returns True if value has a valid ChatEvent type\n */\nexport function isChatEvent(value: unknown): value is ChatEvent {\n  if (typeof value !== \"object\" || value === null) return false;\n  const obj = value as Record<string, unknown>;\n  const validTypes: ChatEventType[] = [\n    \"message:start\",\n    \"message:delta\",\n    \"message:complete\",\n    \"tool:start\",\n    \"tool:complete\",\n    \"thinking:start\",\n    \"thinking:delta\",\n    \"thinking:end\",\n    \"permission:request\",\n    \"permission:response\",\n    \"usage\",\n    \"session:created\",\n    \"session:updated\",\n    \"error\",\n    \"typing:start\",\n    \"typing:end\",\n    \"heartbeat\",\n    \"done\",\n  ];\n  return validTypes.includes(obj.type as ChatEventType);\n}\n\n// ─── Agent Event Adapter ───────────────────────────────────────\n\n/**\n * Map a single AgentEvent to a ChatEvent (or null if no mapping)\n * @param event - The AgentEvent to convert\n * @param messageId - ChatId to associate with the event\n * @returns Corresponding ChatEvent or null if unmappable\n */\nexport function agentEventToChatEvent(\n  event: AgentEvent,\n  messageId: ChatId,\n): ChatEvent | null {\n  switch (event.type) {\n    case \"text_delta\":\n      return { type: \"message:delta\", messageId, text: event.text };\n    case \"thinking_start\":\n      return { type: \"thinking:start\", messageId };\n    case \"thinking_delta\":\n      return { type: \"thinking:delta\", messageId, text: event.text };\n    case \"thinking_end\":\n      return { type: \"thinking:end\", messageId };\n    case \"tool_call_start\":\n      return {\n        type: \"tool:start\",\n        messageId,\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        args: event.args as Record<string, unknown>,\n      };\n    case \"tool_call_end\":\n      return {\n        type: \"tool:complete\",\n        messageId,\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        result: event.result,\n      };\n    case \"permission_request\":\n      return {\n        type: \"permission:request\",\n        messageId,\n        toolName: event.request.toolName,\n        toolArgs: event.request.toolArgs,\n      };\n    case \"permission_response\":\n      return {\n        type: \"permission:response\",\n        messageId,\n        toolName: event.toolName,\n        allowed: event.decision.allowed,\n      };\n    case \"usage_update\":\n      return {\n        type: \"usage\",\n        promptTokens: event.promptTokens,\n        completionTokens: event.completionTokens,\n        model: event.model,\n      };\n    case \"error\":\n      return {\n        type: \"error\",\n        error: event.error,\n        recoverable: event.recoverable,\n        messageId,\n      };\n    case \"heartbeat\":\n      return { type: \"heartbeat\" };\n    case \"ask_user\":\n    case \"ask_user_response\":\n    case \"session_info\":\n    case \"done\":\n      return null;\n    default:\n      return null;\n  }\n}\n\n/**\n * Convert AgentEvent async iterable to ChatEvent async iterable\n * @param events - Source agent events\n * @param messageId - ChatId to associate with converted events\n * @returns Async iterable of ChatEvent (nulls filtered out)\n */\nexport async function* adaptAgentEvents(\n  events: AsyncIterable<AgentEvent>,\n  messageId: ChatId,\n): AsyncIterable<ChatEvent> {\n  for await (const event of events) {\n    const chatEvent = agentEventToChatEvent(event, messageId);\n    if (chatEvent !== null) {\n      yield chatEvent;\n    }\n  }\n}\n\n/**\n * Map a ChatEvent back to an AgentEvent for accumulator consumption.\n * Returns null for events that don't map to accumulator-relevant AgentEvents\n * (e.g. message:start, message:complete, usage, permission:*, heartbeat).\n *\n * @param event - The ChatEvent to convert\n * @returns Corresponding AgentEvent or null if not accumulator-relevant\n */\nexport function chatEventToAgentEvent(event: ChatEvent): AgentEvent | null {\n  switch (event.type) {\n    case \"message:delta\":\n      return { type: \"text_delta\", text: event.text };\n    case \"thinking:start\":\n      return { type: \"thinking_start\" };\n    case \"thinking:delta\":\n      return { type: \"thinking_delta\", text: event.text };\n    case \"thinking:end\":\n      return { type: \"thinking_end\" };\n    case \"tool:start\":\n      return {\n        type: \"tool_call_start\",\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        args: event.args as JSONValue,\n      };\n    case \"tool:complete\":\n      return {\n        type: \"tool_call_end\",\n        toolCallId: event.toolCallId,\n        toolName: event.toolName,\n        result: event.result as JSONValue,\n      };\n    case \"error\":\n      return { type: \"error\", error: event.error, recoverable: event.recoverable };\n    default:\n      return null;\n  }\n}\n\n// ─── Message Conversion ────────────────────────────────────────\n\n/**\n * Convert a ChatMessage to agent-sdk Message format\n * @param message - The ChatMessage to convert\n * @returns agent-sdk Message\n */\nexport function toAgentMessage(message: ChatMessage): Message {\n  const textContent = getMessageText(message);\n  const toolCallParts = getMessageToolCalls(message);\n\n  switch (message.role) {\n    case \"user\":\n      return { role: \"user\", content: textContent };\n    case \"assistant\": {\n      const toolCalls: ToolCall[] | undefined = toolCallParts.length > 0\n        ? toolCallParts.map((p) => ({ id: p.toolCallId, name: p.name, args: p.args as JSONValue }))\n        : undefined;\n      return {\n        role: \"assistant\",\n        content: textContent,\n        toolCalls,\n      };\n    }\n    case \"system\":\n      return { role: \"system\", content: textContent };\n  }\n}\n\n/**\n * Convert an agent-sdk Message to ChatMessage\n * @param message - The agent-sdk Message to convert\n * @param id - Optional ChatId (auto-generated if omitted)\n * @returns ChatMessage with status \"complete\"\n */\nexport function fromAgentMessage(message: Message, id?: ChatId): ChatMessage {\n  const chatId = id ?? createChatId();\n  const now = new Date().toISOString();\n\n  const parts: MessagePart[] = [];\n\n  // Build text content\n  const textContent =\n    typeof message.content === \"string\"\n      ? message.content\n      : Array.isArray(message.content)\n        ? message.content\n            .filter((part) => part.type === \"text\")\n            .map((part) => part.text)\n            .join(\"\\n\")\n        : (message.content ?? \"\");\n\n  if (textContent) {\n    parts.push({ type: \"text\", text: textContent, status: \"complete\" });\n  }\n\n  // Add tool calls from assistant messages\n  if (message.role === \"assistant\" && message.toolCalls) {\n    for (const tc of message.toolCalls) {\n      parts.push({\n        type: \"tool_call\",\n        toolCallId: tc.id,\n        name: tc.name,\n        args: tc.args,\n        status: \"complete\",\n      });\n    }\n  }\n\n  // Add tool results — map 'tool' role to 'assistant'\n  if (message.role === \"tool\" && message.toolResults) {\n    for (const tr of message.toolResults) {\n      parts.push({\n        type: \"tool_call\",\n        toolCallId: tr.toolCallId,\n        name: tr.name,\n        args: {},\n        result: tr.result,\n        status: \"complete\",\n      });\n    }\n  }\n\n  // Ensure at least an empty text part for empty messages\n  if (parts.length === 0) {\n    parts.push({ type: \"text\", text: \"\", status: \"complete\" });\n  }\n\n  const role: ChatRole = message.role === \"tool\" ? \"assistant\" : message.role;\n\n  return {\n    id: chatId,\n    role,\n    parts,\n    createdAt: now,\n    status: \"complete\",\n  };\n}\n\n/**\n * Extract ToolResults from ToolCallParts that have results\n * @param message - The ChatMessage to extract results from\n * @returns Array of ToolResult for completed tool calls\n */\nexport function extractToolResults(message: ChatMessage): ToolResult[] {\n  return getMessageToolCalls(message)\n    .filter((p) => p.result !== undefined)\n    .map((p) => ({\n      toolCallId: p.toolCallId,\n      name: p.name,\n      result: p.result as JSONValue,\n      isError: p.status === \"error\" ? true : undefined,\n    }));\n}\n","/**\n * @witqq/agent-sdk/chat/accumulator\n *\n * MessageAccumulator converts a stream of AgentEvent objects into a ChatMessage\n * with correct MessagePart array. Handles text, reasoning, and tool call\n * accumulation with proper status transitions.\n */\n\nimport type { AgentEvent } from \"../types.js\";\nimport type { ChatMessage, ChatId, MessagePart, TextPart, ReasoningPart, ToolCallPart } from \"./core.js\";\nimport { createChatId } from \"./core.js\";\n\n/**\n * Converts a stream of AgentEvent objects into a complete ChatMessage.\n * Tracks text, reasoning, and tool call parts with proper status transitions.\n *\n * @example\n * ```typescript\n * const acc = new MessageAccumulator();\n * for await (const event of agentEvents) {\n *   acc.apply(event);\n *   renderMessage(acc.snapshot()); // in-progress UI update\n * }\n * const message = acc.finalize();\n * ```\n */\nexport class MessageAccumulator {\n  private readonly messageId: ChatId;\n  private readonly parts: MessagePart[] = [];\n  private status: \"pending\" | \"streaming\" | \"complete\" | \"error\" | \"cancelled\" = \"pending\";\n  private currentTextPart: TextPart | null = null;\n  private currentReasoningPart: ReasoningPart | null = null;\n  private toolCallParts = new Map<string, ToolCallPart>();\n  private _finalized = false;\n\n  constructor(messageId?: ChatId) {\n    this.messageId = messageId ?? createChatId();\n  }\n\n  /** Get current message ID */\n  get id(): ChatId { return this.messageId; }\n\n  /**\n   * Apply an AgentEvent to accumulate into the message\n   * @param event - AgentEvent to process\n   * @throws Error if accumulator is already finalized\n   */\n  apply(event: AgentEvent): void {\n    if (this._finalized) throw new Error(\"Cannot apply events to finalized accumulator\");\n\n    if (this.status === \"pending\") {\n      this.status = \"streaming\";\n    }\n\n    switch (event.type) {\n      case \"text_delta\":\n        this.handleTextDelta(event.text);\n        break;\n      case \"thinking_start\":\n        this.finalizeCurrentText();\n        this.currentReasoningPart = { type: \"reasoning\", text: \"\", status: \"streaming\" };\n        this.parts.push(this.currentReasoningPart);\n        break;\n      case \"thinking_delta\":\n        if (this.currentReasoningPart) {\n          this.currentReasoningPart.text += event.text;\n        }\n        break;\n      case \"thinking_end\":\n        if (this.currentReasoningPart) {\n          this.currentReasoningPart.status = \"complete\";\n          this.currentReasoningPart = null;\n        }\n        break;\n      case \"tool_call_start\": {\n        this.finalizeCurrentText();\n        const toolPart: ToolCallPart = {\n          type: \"tool_call\",\n          toolCallId: event.toolCallId,\n          name: event.toolName,\n          args: event.args,\n          status: \"running\",\n        };\n        this.toolCallParts.set(event.toolCallId, toolPart);\n        this.parts.push(toolPart);\n        break;\n      }\n      case \"tool_call_end\": {\n        const existing = this.toolCallParts.get(event.toolCallId);\n        if (existing) {\n          existing.result = event.result;\n          existing.status = \"complete\";\n        }\n        break;\n      }\n      case \"error\":\n        this.status = \"error\";\n        break;\n      case \"done\":\n        break;\n      // Other events (heartbeat, ask_user, etc.) — ignore\n    }\n  }\n\n  private handleTextDelta(text: string): void {\n    if (!this.currentTextPart) {\n      this.currentTextPart = { type: \"text\", text: \"\", status: \"streaming\" };\n      this.parts.push(this.currentTextPart);\n    }\n    this.currentTextPart.text += text;\n  }\n\n  private finalizeCurrentText(): void {\n    if (this.currentTextPart) {\n      this.currentTextPart.status = \"complete\";\n      this.currentTextPart = null;\n    }\n  }\n\n  /**\n   * Get a snapshot of the current accumulated message (for streaming UI)\n   * @returns ChatMessage with current parts and \"streaming\" status\n   */\n  snapshot(): ChatMessage {\n    const now = new Date().toISOString();\n    return {\n      id: this.messageId,\n      role: \"assistant\",\n      parts: this.parts.map(p => ({ ...p })),\n      status: this.status === \"pending\" ? \"pending\" : \"streaming\",\n      createdAt: now,\n      updatedAt: now,\n    };\n  }\n\n  /**\n   * Finalize the accumulator and return the complete ChatMessage\n   * @returns Completed ChatMessage with all parts finalized\n   * @throws Error if accumulator is already finalized\n   */\n  finalize(): ChatMessage {\n    if (this._finalized) throw new Error(\"Accumulator already finalized\");\n    this._finalized = true;\n\n    // Finalize any open parts\n    this.finalizeCurrentText();\n    if (this.currentReasoningPart) {\n      this.currentReasoningPart.status = \"complete\";\n      this.currentReasoningPart = null;\n    }\n\n    // Mark incomplete tool calls as error\n    for (const [, toolPart] of this.toolCallParts) {\n      if (toolPart.status === \"running\" || toolPart.status === \"pending\") {\n        toolPart.status = \"error\";\n      }\n    }\n\n    // Set final message status\n    if (this.status !== \"error\" && this.status !== \"cancelled\") {\n      this.status = \"complete\";\n    }\n\n    const now = new Date().toISOString();\n    return {\n      id: this.messageId,\n      role: \"assistant\",\n      parts: this.parts,\n      status: this.status,\n      createdAt: now,\n      updatedAt: now,\n    };\n  }\n\n  /** Check if the accumulator has been finalized */\n  get finalized(): boolean { return this._finalized; }\n}\n"]}