@witqq/agent-sdk 0.6.1 → 0.8.0

package/dist/chat/accumulator.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+// src/chat/types.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/types.ts","../../src/chat/accumulator.ts"],"names":[],"mappings":"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","file":"accumulator.cjs","sourcesContent":["/**\n * @witqq/agent-sdk — Chat domain types\n *\n * All type definitions and interfaces for the chat layer.\n * Pure types + ChatId generation (tightly coupled to branded type).\n */\n\nimport type { UsageData, ToolDefinition, ErrorCode } from \"../types.js\";\nimport type { AuthToken } from \"../auth/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 */\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\";\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  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// ─── Supporting Types ──────────────────────────────────────────\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/**\n * Session metadata tracking usage statistics and custom extensions.\n *\n * Updated automatically by session stores on each `addMessage()` call.\n * The generic `TCustom` parameter allows type-safe application-specific\n * metadata via the `custom` field.\n *\n * @typeParam TCustom - Shape of the `custom` field (defaults to `Record<string, unknown>`)\n */\nexport interface ChatSessionMetadata<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  /** Number of messages in the session (updated by session store) */\n  messageCount: number;\n  /** Total token count across all messages in the session */\n  totalTokens: number;\n  /** Optional tags for session categorization and filtering */\n  tags?: string[];\n  /** Application-specific metadata — typed via the TCustom generic parameter */\n  custom?: TCustom;\n}\n\n/** Chat session — a conversation with ordered messages (pure serializable data) */\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}\n\n/**\n * Reactive wrapper around ChatSession — provides subscribe/getSnapshot for\n * React useSyncExternalStore integration and lastMessage convenience getter.\n * Session stores may optionally return ObservableSession instances.\n */\nexport interface ObservableSession<TCustom extends Record<string, unknown> = Record<string, unknown>>\n  extends ChatSession<TCustom> {\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 | undefined;\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      code?: ErrorCode;\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. Return null to reject the send. */\n  onBeforeSend?(message: ChatMessage, context: ChatMiddlewareContext): ChatMessage | null | Promise<ChatMessage | null>;\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 to use for this request. Required for server-side runtime.send(). */\n  model?: string;\n  /** Per-call system prompt override (forwarded to the backend agent) */\n  systemPrompt?: string;\n  context?: Record<string, unknown>;\n  /** Additional tools to include in this request */\n  tools?: ToolDefinition[];\n}\n\n/** Options for runtime.send() — requires backend routing info */\nexport interface RuntimeSendOptions {\n  /** Backend to route this request to (key in backends map) */\n  backend: string;\n  /** Authentication credentials for the backend factory */\n  credentials: AuthToken;\n  /** Model to use for this request */\n  model: string;\n  /** Per-call system prompt override (forwarded to the backend agent) */\n  systemPrompt?: string;\n  /** Abort signal */\n  signal?: AbortSignal;\n  /** Request-scoped context */\n  context?: Record<string, unknown>;\n  /** Additional tools */\n  tools?: ToolDefinition[];\n}\n\n/**\n * @deprecated IChatProvider has been inlined into IChatBackend.\n * Import IChatBackend from \"@witqq/agent-sdk/chat/backends\" instead.\n * Kept as type alias for backward compatibility.\n */\nexport type IChatProvider = import(\"./backends/types.js\").IChatBackend;\n\n// ─── Factory Functions ─────────────────────────────────────────\n\n/**\n * Create a simple text ChatMessage.\n *\n * @param text - Message text content\n * @param role - Message role (default: \"user\")\n * @returns A complete ChatMessage with a single TextPart\n */\nexport function createTextMessage(text: string, role: ChatRole = \"user\"): ChatMessage {\n  return {\n    id: createChatId(),\n    role,\n    parts: [{ type: \"text\", text, status: \"complete\" }],\n    createdAt: new Date().toISOString(),\n    status: \"complete\",\n  };\n}\n\n/** Type guard: checks if a session has reactive API (subscribe/getSnapshot) */\nexport function isObservableSession<TCustom extends Record<string, unknown> = Record<string, unknown>>(\n  session: ChatSession<TCustom>,\n): session is ObservableSession<TCustom> {\n  return \"subscribe\" in session && typeof (session as ObservableSession<TCustom>).subscribe === \"function\"\n    && \"getSnapshot\" in session && typeof (session as ObservableSession<TCustom>).getSnapshot === \"function\";\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,64 @@
+import { A as AgentEvent } from '../agent-DxY68NZL.cjs';
+import { b as ChatId, c as ChatMessage } from '../types-DRgd_9R7.cjs';
+import 'zod';
+import '../errors-C-so0M4t.cjs';
+import '../types-4vbcmPTp.cjs';
+import '../errors-CmVvczxZ.cjs';
+
+/**
+ * @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,64 @@
+import { A as AgentEvent } from '../agent-CW9XbmG_.js';
+import { b as ChatId, c as ChatMessage } from '../types-ajANVzf7.js';
+import 'zod';
+import '../errors-C-so0M4t.js';
+import '../types-BxggH0Yh.js';
+import '../errors-CmVvczxZ.js';
+
+/**
+ * @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/types.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/types.ts","../../src/chat/accumulator.ts"],"names":[],"mappings":"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","file":"accumulator.js","sourcesContent":["/**\n * @witqq/agent-sdk — Chat domain types\n *\n * All type definitions and interfaces for the chat layer.\n * Pure types + ChatId generation (tightly coupled to branded type).\n */\n\nimport type { UsageData, ToolDefinition, ErrorCode } from \"../types.js\";\nimport type { AuthToken } from \"../auth/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 */\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\";\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  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// ─── Supporting Types ──────────────────────────────────────────\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/**\n * Session metadata tracking usage statistics and custom extensions.\n *\n * Updated automatically by session stores on each `addMessage()` call.\n * The generic `TCustom` parameter allows type-safe application-specific\n * metadata via the `custom` field.\n *\n * @typeParam TCustom - Shape of the `custom` field (defaults to `Record<string, unknown>`)\n */\nexport interface ChatSessionMetadata<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  /** Number of messages in the session (updated by session store) */\n  messageCount: number;\n  /** Total token count across all messages in the session */\n  totalTokens: number;\n  /** Optional tags for session categorization and filtering */\n  tags?: string[];\n  /** Application-specific metadata — typed via the TCustom generic parameter */\n  custom?: TCustom;\n}\n\n/** Chat session — a conversation with ordered messages (pure serializable data) */\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}\n\n/**\n * Reactive wrapper around ChatSession — provides subscribe/getSnapshot for\n * React useSyncExternalStore integration and lastMessage convenience getter.\n * Session stores may optionally return ObservableSession instances.\n */\nexport interface ObservableSession<TCustom extends Record<string, unknown> = Record<string, unknown>>\n  extends ChatSession<TCustom> {\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 | undefined;\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      code?: ErrorCode;\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. Return null to reject the send. */\n  onBeforeSend?(message: ChatMessage, context: ChatMiddlewareContext): ChatMessage | null | Promise<ChatMessage | null>;\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 to use for this request. Required for server-side runtime.send(). */\n  model?: string;\n  /** Per-call system prompt override (forwarded to the backend agent) */\n  systemPrompt?: string;\n  context?: Record<string, unknown>;\n  /** Additional tools to include in this request */\n  tools?: ToolDefinition[];\n}\n\n/** Options for runtime.send() — requires backend routing info */\nexport interface RuntimeSendOptions {\n  /** Backend to route this request to (key in backends map) */\n  backend: string;\n  /** Authentication credentials for the backend factory */\n  credentials: AuthToken;\n  /** Model to use for this request */\n  model: string;\n  /** Per-call system prompt override (forwarded to the backend agent) */\n  systemPrompt?: string;\n  /** Abort signal */\n  signal?: AbortSignal;\n  /** Request-scoped context */\n  context?: Record<string, unknown>;\n  /** Additional tools */\n  tools?: ToolDefinition[];\n}\n\n/**\n * @deprecated IChatProvider has been inlined into IChatBackend.\n * Import IChatBackend from \"@witqq/agent-sdk/chat/backends\" instead.\n * Kept as type alias for backward compatibility.\n */\nexport type IChatProvider = import(\"./backends/types.js\").IChatBackend;\n\n// ─── Factory Functions ─────────────────────────────────────────\n\n/**\n * Create a simple text ChatMessage.\n *\n * @param text - Message text content\n * @param role - Message role (default: \"user\")\n * @returns A complete ChatMessage with a single TextPart\n */\nexport function createTextMessage(text: string, role: ChatRole = \"user\"): ChatMessage {\n  return {\n    id: createChatId(),\n    role,\n    parts: [{ type: \"text\", text, status: \"complete\" }],\n    createdAt: new Date().toISOString(),\n    status: \"complete\",\n  };\n}\n\n/** Type guard: checks if a session has reactive API (subscribe/getSnapshot) */\nexport function isObservableSession<TCustom extends Record<string, unknown> = Record<string, unknown>>(\n  session: ChatSession<TCustom>,\n): session is ObservableSession<TCustom> {\n  return \"subscribe\" in session && typeof (session as ObservableSession<TCustom>).subscribe === \"function\"\n    && \"getSnapshot\" in session && typeof (session as ObservableSession<TCustom>).getSnapshot === \"function\";\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"]}