@witqq/agent-sdk 0.6.1 → 0.7.0

package/dist/chat/sessions.js

@@ -0,0 +1,394 @@
+import { existsSync, readdirSync, unlinkSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// src/chat/core.ts
+function createChatId() {
+  return crypto.randomUUID();
+}
+
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  /** @internal Marker for cross-bundle identity checks */
+  _agentSDKError = true;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+  }
+  /** Check if an error is an AgentSDKError (works across bundled copies) */
+  static is(error) {
+    return error instanceof Error && "_agentSDKError" in error && error._agentSDKError === true;
+  }
+};
+
+// src/chat/storage.ts
+var StorageError = class extends AgentSDKError {
+  /** Machine-readable error code */
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "StorageError";
+    this.code = code;
+  }
+};
+var InMemoryStorage = class {
+  data = /* @__PURE__ */ new Map();
+  /** @inheritdoc */
+  async get(key) {
+    const item = this.data.get(key);
+    return item !== void 0 ? structuredClone(item) : null;
+  }
+  /** @inheritdoc */
+  async list(options) {
+    let items = Array.from(this.data.values()).map((item) => structuredClone(item));
+    if (options?.filter) {
+      items = items.filter(options.filter);
+    }
+    if (options?.sort) {
+      items.sort(options.sort);
+    }
+    if (options?.offset !== void 0) {
+      items = items.slice(options.offset);
+    }
+    if (options?.limit !== void 0) {
+      items = items.slice(0, options.limit);
+    }
+    return items;
+  }
+  /** @inheritdoc */
+  async create(key, item) {
+    if (this.data.has(key)) {
+      throw new StorageError(
+        `Item with key "${key}" already exists`,
+        "DUPLICATE_KEY"
+      );
+    }
+    this.data.set(key, structuredClone(item));
+  }
+  /** @inheritdoc */
+  async update(key, item) {
+    if (!this.data.has(key)) {
+      throw new StorageError(
+        `Item with key "${key}" not found`,
+        "NOT_FOUND"
+      );
+    }
+    this.data.set(key, structuredClone(item));
+  }
+  /** @inheritdoc */
+  async delete(key) {
+    if (!this.data.has(key)) {
+      throw new StorageError(
+        `Item with key "${key}" not found`,
+        "NOT_FOUND"
+      );
+    }
+    this.data.delete(key);
+  }
+  /** @inheritdoc */
+  async has(key) {
+    return this.data.has(key);
+  }
+  /** @inheritdoc */
+  async count() {
+    return this.data.size;
+  }
+  /** @inheritdoc */
+  async clear() {
+    this.data.clear();
+  }
+};
+var FileStorage = class {
+  directory;
+  extension;
+  constructor(options) {
+    this.directory = options.directory;
+    this.extension = options.extension ?? ".json";
+    this.ensureDirectory();
+  }
+  /** @inheritdoc */
+  async get(key) {
+    const filePath = this.keyToPath(key);
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    return this.readFile(filePath);
+  }
+  /** @inheritdoc */
+  async list(options) {
+    this.ensureDirectory();
+    const files = readdirSync(this.directory).filter(
+      (f) => f.endsWith(this.extension)
+    );
+    let items = [];
+    for (const file of files) {
+      const item = this.readFile(join(this.directory, file));
+      items.push(item);
+    }
+    if (options?.filter) {
+      items = items.filter(options.filter);
+    }
+    if (options?.sort) {
+      items.sort(options.sort);
+    }
+    if (options?.offset !== void 0) {
+      items = items.slice(options.offset);
+    }
+    if (options?.limit !== void 0) {
+      items = items.slice(0, options.limit);
+    }
+    return items;
+  }
+  /** @inheritdoc */
+  async create(key, item) {
+    const filePath = this.keyToPath(key);
+    if (existsSync(filePath)) {
+      throw new StorageError(
+        `Item with key "${key}" already exists`,
+        "DUPLICATE_KEY"
+      );
+    }
+    this.writeFile(filePath, item);
+  }
+  /** @inheritdoc */
+  async update(key, item) {
+    const filePath = this.keyToPath(key);
+    if (!existsSync(filePath)) {
+      throw new StorageError(
+        `Item with key "${key}" not found`,
+        "NOT_FOUND"
+      );
+    }
+    this.writeFile(filePath, item);
+  }
+  /** @inheritdoc */
+  async delete(key) {
+    const filePath = this.keyToPath(key);
+    if (!existsSync(filePath)) {
+      throw new StorageError(
+        `Item with key "${key}" not found`,
+        "NOT_FOUND"
+      );
+    }
+    unlinkSync(filePath);
+  }
+  /** @inheritdoc */
+  async has(key) {
+    return existsSync(this.keyToPath(key));
+  }
+  /** @inheritdoc */
+  async count() {
+    this.ensureDirectory();
+    return readdirSync(this.directory).filter(
+      (f) => f.endsWith(this.extension)
+    ).length;
+  }
+  /** @inheritdoc */
+  async clear() {
+    this.ensureDirectory();
+    const files = readdirSync(this.directory).filter(
+      (f) => f.endsWith(this.extension)
+    );
+    for (const file of files) {
+      unlinkSync(join(this.directory, file));
+    }
+  }
+  keyToPath(key) {
+    const safeKey = key.replace(
+      /[^a-zA-Z0-9_-]/g,
+      (c) => "%" + c.charCodeAt(0).toString(16).padStart(2, "0")
+    );
+    return join(this.directory, `${safeKey}${this.extension}`);
+  }
+  ensureDirectory() {
+    if (!existsSync(this.directory)) {
+      mkdirSync(this.directory, { recursive: true });
+    }
+  }
+  readFile(filePath) {
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      return JSON.parse(content);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new StorageError(
+          `Failed to parse file: ${filePath}`,
+          "SERIALIZATION_ERROR"
+        );
+      }
+      throw new StorageError(
+        `Failed to read file: ${filePath}`,
+        "IO_ERROR"
+      );
+    }
+  }
+  writeFile(filePath, item) {
+    try {
+      const content = JSON.stringify(item, null, 2);
+      writeFileSync(filePath, content, "utf-8");
+    } catch {
+      throw new StorageError(
+        `Failed to write file: ${filePath}`,
+        "IO_ERROR"
+      );
+    }
+  }
+};
+
+// src/chat/sessions.ts
+var BaseSessionStore = class {
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+  async createSession(options) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const id = createChatId();
+    const session = {
+      id,
+      title: options.title ?? "Untitled",
+      messages: [],
+      config: {
+        model: options.config?.model ?? "",
+        backend: options.config?.backend ?? "",
+        ...options.config
+      },
+      metadata: {
+        messageCount: 0,
+        totalTokens: 0,
+        tags: options.tags ? [...options.tags] : void 0,
+        custom: options.custom ? { ...options.custom } : void 0
+      },
+      status: "active",
+      createdAt: now,
+      updatedAt: now
+    };
+    await this.adapter.create(id, session);
+    return structuredClone(session);
+  }
+  async getSession(id) {
+    return this.adapter.get(id);
+  }
+  async listSessions(options) {
+    return this.adapter.list(options);
+  }
+  async updateTitle(id, title) {
+    const session = await this.adapter.get(id);
+    if (!session) {
+      throw new StorageError(`Session "${id}" not found`, "NOT_FOUND");
+    }
+    session.title = title;
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.adapter.update(id, session);
+  }
+  async updateConfig(id, config) {
+    const session = await this.adapter.get(id);
+    if (!session) {
+      throw new StorageError(`Session "${id}" not found`, "NOT_FOUND");
+    }
+    session.config = { ...session.config, ...config };
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.adapter.update(id, session);
+  }
+  async deleteSession(id) {
+    await this.adapter.delete(id);
+  }
+  async appendMessage(sessionId, message) {
+    const session = await this.adapter.get(sessionId);
+    if (!session) {
+      throw new StorageError(`Session "${sessionId}" not found`, "NOT_FOUND");
+    }
+    session.messages.push(structuredClone(message));
+    session.metadata.messageCount = session.messages.length;
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.adapter.update(sessionId, session);
+  }
+  async saveMessages(sessionId, messages) {
+    if (messages.length === 0) return;
+    const session = await this.adapter.get(sessionId);
+    if (!session) {
+      throw new StorageError(`Session "${sessionId}" not found`, "NOT_FOUND");
+    }
+    for (const msg of messages) {
+      session.messages.push(structuredClone(msg));
+    }
+    session.metadata.messageCount = session.messages.length;
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.adapter.update(sessionId, session);
+  }
+  async loadMessages(sessionId, options) {
+    const session = await this.adapter.get(sessionId);
+    if (!session) {
+      throw new StorageError(`Session "${sessionId}" not found`, "NOT_FOUND");
+    }
+    const total = session.messages.length;
+    const offset = options?.offset ?? 0;
+    const limit = options?.limit ?? total;
+    const messages = session.messages.slice(offset, offset + limit);
+    return {
+      messages: structuredClone(messages),
+      total,
+      hasMore: offset + limit < total
+    };
+  }
+  async archiveSession(id) {
+    const session = await this.adapter.get(id);
+    if (!session) {
+      throw new StorageError(`Session "${id}" not found`, "NOT_FOUND");
+    }
+    session.status = "archived";
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.adapter.update(id, session);
+  }
+  async unarchiveSession(id) {
+    const session = await this.adapter.get(id);
+    if (!session) {
+      throw new StorageError(`Session "${id}" not found`, "NOT_FOUND");
+    }
+    session.status = "active";
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.adapter.update(id, session);
+  }
+  async searchSessions(options) {
+    const query = options.query.toLowerCase();
+    const limit = options.limit ?? 20;
+    return this.adapter.list({
+      filter: (session) => {
+        if (session.title?.toLowerCase().includes(query)) return true;
+        return session.messages.some((msg) => {
+          return msg.parts.some(
+            (part) => part.type === "text" && part.text.toLowerCase().includes(query)
+          );
+        });
+      },
+      limit
+    });
+  }
+  async count() {
+    return this.adapter.count();
+  }
+  async clear() {
+    return this.adapter.clear();
+  }
+  // ── Deprecated Aliases ──────────────────────────────────────
+  /** @deprecated Use `appendMessage()` instead */
+  async addMessage(sessionId, message) {
+    return this.appendMessage(sessionId, message);
+  }
+  /** @deprecated Use `loadMessages()` instead */
+  async getMessages(sessionId, options) {
+    return this.loadMessages(sessionId, options);
+  }
+};
+var InMemorySessionStore = class extends BaseSessionStore {
+  constructor() {
+    super(new InMemoryStorage());
+  }
+};
+var FileSessionStore = class extends BaseSessionStore {
+  constructor(options) {
+    super(new FileStorage({ directory: options.directory }));
+  }
+};
+
+export { FileSessionStore, InMemorySessionStore, StorageError };
+//# sourceMappingURL=sessions.js.map
+//# sourceMappingURL=sessions.js.map

package/dist/chat/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/chat/core.ts","../../src/errors.ts","../../src/chat/storage.ts","../../src/chat/sessions.ts"],"names":[],"mappings":"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","file":"sessions.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","/** Base error class for agent-sdk.\n *\n * Use `AgentSDKError.is(err)` for reliable cross-module `instanceof` checks\n * (works across separately bundled entry points where `instanceof` may fail). */\nexport class AgentSDKError extends Error {\n  /** @internal Marker for cross-bundle identity checks */\n  readonly _agentSDKError = true as const;\n\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"AgentSDKError\";\n  }\n\n  /** Check if an error is an AgentSDKError (works across bundled copies) */\n  static is(error: unknown): error is AgentSDKError {\n    return (\n      error instanceof Error &&\n      \"_agentSDKError\" in error &&\n      (error as AgentSDKError)._agentSDKError === true\n    );\n  }\n}\n\n/** Thrown when agent.run() is called while already running (M8 re-entrancy guard) */\nexport class ReentrancyError extends AgentSDKError {\n  constructor() {\n    super(\"Agent is already running. Await the current run before starting another.\");\n    this.name = \"ReentrancyError\";\n  }\n}\n\n/** Thrown when an operation is attempted on a disposed agent/service */\nexport class DisposedError extends AgentSDKError {\n  constructor(entity: string) {\n    super(`${entity} has been disposed and cannot be used.`);\n    this.name = \"DisposedError\";\n  }\n}\n\n/** Thrown when a backend is not found in the registry */\nexport class BackendNotFoundError extends AgentSDKError {\n  constructor(backend: string) {\n    super(\n      `Unknown backend: \"${backend}\". ` +\n      `Built-in: copilot, claude, vercel-ai. ` +\n      `Custom: use registerBackend() first.`,\n    );\n    this.name = \"BackendNotFoundError\";\n  }\n}\n\n/** Thrown when a backend is already registered */\nexport class BackendAlreadyRegisteredError extends AgentSDKError {\n  constructor(backend: string) {\n    super(`Backend \"${backend}\" is already registered. Use a different name or unregister first.`);\n    this.name = \"BackendAlreadyRegisteredError\";\n  }\n}\n\n/** Thrown when subprocess management fails */\nexport class SubprocessError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"SubprocessError\";\n  }\n}\n\n/** Thrown when a required peer dependency is not installed */\nexport class DependencyError extends AgentSDKError {\n  public readonly packageName: string;\n\n  constructor(packageName: string) {\n    super(`${packageName} is not installed. Install it: npm install ${packageName}`);\n    this.name = \"DependencyError\";\n    this.packageName = packageName;\n  }\n}\n\n/** Thrown when an agent run is aborted */\nexport class AbortError extends AgentSDKError {\n  constructor() {\n    super(\"Agent run was aborted.\");\n    this.name = \"AbortError\";\n  }\n}\n\n/** Thrown when a tool execution fails */\nexport class ToolExecutionError extends AgentSDKError {\n  public readonly toolName: string;\n\n  constructor(toolName: string, message: string, options?: ErrorOptions) {\n    super(`Tool \"${toolName}\" failed: ${message}`, options);\n    this.name = \"ToolExecutionError\";\n    this.toolName = toolName;\n  }\n}\n\n/** Thrown when structured output parsing fails */\nexport class StructuredOutputError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(`Structured output error: ${message}`, options);\n    this.name = \"StructuredOutputError\";\n  }\n}\n","/**\n * @witqq/agent-sdk/chat/storage\n *\n * Generic storage adapter layer with pluggable backends.\n * Provides CRUD operations for any data type via `IStorageAdapter<T>`.\n * Implementations: `InMemoryStorage` (Map-based) and `FileStorage` (JSON files).\n */\n\nimport { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { AgentSDKError } from \"../errors.js\";\n\n// ─── Storage Errors ────────────────────────────────────────────\n\n/**\n * Error thrown by storage operations.\n *\n * @example\n * ```typescript\n * try {\n *   await store.get(\"missing-id\");\n * } catch (e) {\n *   if (e instanceof StorageError && e.code === \"NOT_FOUND\") {\n *     // handle missing item\n *   }\n * }\n * ```\n */\nexport class StorageError extends AgentSDKError {\n  /** Machine-readable error code */\n  readonly code: StorageErrorCode;\n\n  constructor(message: string, code: StorageErrorCode) {\n    super(message);\n    this.name = \"StorageError\";\n    this.code = code;\n  }\n}\n\n/** Possible storage error codes */\nexport type StorageErrorCode =\n  | \"NOT_FOUND\"\n  | \"DUPLICATE_KEY\"\n  | \"IO_ERROR\"\n  | \"SERIALIZATION_ERROR\";\n\n// ─── Storage Adapter Interface ─────────────────────────────────\n\n/**\n * Options for listing stored items.\n *\n * @typeParam T - The type of stored items\n */\nexport interface ListOptions<T> {\n  /** Filter predicate — return `true` to include the item */\n  filter?: (item: T) => boolean;\n  /** Sort comparator — standard Array.sort semantics */\n  sort?: (a: T, b: T) => number;\n  /** Maximum number of items to return */\n  limit?: number;\n  /** Number of items to skip (for pagination) */\n  offset?: number;\n}\n\n/**\n * Generic storage adapter for CRUD operations on any data type.\n * Items are identified by a string key.\n *\n * @typeParam T - The type of stored items\n *\n * @example\n * ```typescript\n * const store: IStorageAdapter<{ name: string }> = new InMemoryStorage();\n * await store.create(\"key1\", { name: \"Alice\" });\n * const item = await store.get(\"key1\"); // { name: \"Alice\" }\n * ```\n */\nexport interface IStorageAdapter<T> {\n  /**\n   * Retrieve an item by key.\n   * @param key - Unique identifier\n   * @returns The item, or `null` if not found\n   */\n  get(key: string): Promise<T | null>;\n\n  /**\n   * List items with optional filtering, sorting, and pagination.\n   * @param options - Filter, sort, limit, offset options\n   * @returns Array of matching items\n   */\n  list(options?: ListOptions<T>): Promise<T[]>;\n\n  /**\n   * Create a new item. Throws `StorageError` with code `DUPLICATE_KEY` if key exists.\n   * @param key - Unique identifier\n   * @param item - Data to store\n   */\n  create(key: string, item: T): Promise<void>;\n\n  /**\n   * Update an existing item. Throws `StorageError` with code `NOT_FOUND` if key missing.\n   * @param key - Unique identifier\n   * @param item - Updated data\n   */\n  update(key: string, item: T): Promise<void>;\n\n  /**\n   * Delete an item by key. Throws `StorageError` with code `NOT_FOUND` if key missing.\n   * @param key - Unique identifier\n   */\n  delete(key: string): Promise<void>;\n\n  /**\n   * Check whether a key exists.\n   * @param key - Unique identifier\n   * @returns `true` if key exists\n   */\n  has(key: string): Promise<boolean>;\n\n  /**\n   * Return the number of stored items.\n   * @returns Count of items\n   */\n  count(): Promise<number>;\n\n  /**\n   * Remove all items from storage.\n   */\n  clear(): Promise<void>;\n}\n\n// ─── InMemoryStorage ───────────────────────────────────────────\n\n/**\n * In-memory storage adapter backed by a `Map`.\n * Suitable for development, testing, and short-lived processes.\n * Data is lost when the process exits.\n *\n * @typeParam T - The type of stored items\n *\n * @example\n * ```typescript\n * const store = new InMemoryStorage<{ name: string }>();\n * await store.create(\"k1\", { name: \"Alice\" });\n * await store.create(\"k2\", { name: \"Bob\" });\n * const items = await store.list({ filter: i => i.name.startsWith(\"A\") });\n * // [{ name: \"Alice\" }]\n * ```\n */\nexport class InMemoryStorage<T> implements IStorageAdapter<T> {\n  private readonly data = new Map<string, T>();\n\n  /** @inheritdoc */\n  async get(key: string): Promise<T | null> {\n    const item = this.data.get(key);\n    return item !== undefined ? structuredClone(item) : null;\n  }\n\n  /** @inheritdoc */\n  async list(options?: ListOptions<T>): Promise<T[]> {\n    let items = Array.from(this.data.values()).map((item) => structuredClone(item));\n\n    if (options?.filter) {\n      items = items.filter(options.filter);\n    }\n    if (options?.sort) {\n      items.sort(options.sort);\n    }\n    if (options?.offset !== undefined) {\n      items = items.slice(options.offset);\n    }\n    if (options?.limit !== undefined) {\n      items = items.slice(0, options.limit);\n    }\n\n    return items;\n  }\n\n  /** @inheritdoc */\n  async create(key: string, item: T): Promise<void> {\n    if (this.data.has(key)) {\n      throw new StorageError(\n        `Item with key \"${key}\" already exists`,\n        \"DUPLICATE_KEY\",\n      );\n    }\n    this.data.set(key, structuredClone(item));\n  }\n\n  /** @inheritdoc */\n  async update(key: string, item: T): Promise<void> {\n    if (!this.data.has(key)) {\n      throw new StorageError(\n        `Item with key \"${key}\" not found`,\n        \"NOT_FOUND\",\n      );\n    }\n    this.data.set(key, structuredClone(item));\n  }\n\n  /** @inheritdoc */\n  async delete(key: string): Promise<void> {\n    if (!this.data.has(key)) {\n      throw new StorageError(\n        `Item with key \"${key}\" not found`,\n        \"NOT_FOUND\",\n      );\n    }\n    this.data.delete(key);\n  }\n\n  /** @inheritdoc */\n  async has(key: string): Promise<boolean> {\n    return this.data.has(key);\n  }\n\n  /** @inheritdoc */\n  async count(): Promise<number> {\n    return this.data.size;\n  }\n\n  /** @inheritdoc */\n  async clear(): Promise<void> {\n    this.data.clear();\n  }\n}\n\n// ─── FileStorage ───────────────────────────────────────────────\n\n/**\n * Options for configuring `FileStorage`.\n */\nexport interface FileStorageOptions {\n  /** Directory path where JSON files are stored */\n  directory: string;\n  /** File extension (default: `.json`) */\n  extension?: string;\n}\n\n/**\n * File-based storage adapter that persists each item as a JSON file.\n * Suitable for local applications, CLI tools, and development.\n * Creates the storage directory if it doesn't exist.\n *\n * @typeParam T - The type of stored items (must be JSON-serializable)\n *\n * @example\n * ```typescript\n * const store = new FileStorage<ChatSession>({\n *   directory: \"./data/sessions\",\n * });\n * await store.create(\"session-1\", mySession);\n * ```\n */\nexport class FileStorage<T> implements IStorageAdapter<T> {\n  private readonly directory: string;\n  private readonly extension: string;\n\n  constructor(options: FileStorageOptions) {\n    this.directory = options.directory;\n    this.extension = options.extension ?? \".json\";\n    this.ensureDirectory();\n  }\n\n  /** @inheritdoc */\n  async get(key: string): Promise<T | null> {\n    const filePath = this.keyToPath(key);\n    if (!existsSync(filePath)) {\n      return null;\n    }\n    return this.readFile(filePath);\n  }\n\n  /** @inheritdoc */\n  async list(options?: ListOptions<T>): Promise<T[]> {\n    this.ensureDirectory();\n    const files = readdirSync(this.directory).filter((f) =>\n      f.endsWith(this.extension),\n    );\n\n    let items: T[] = [];\n    for (const file of files) {\n      const item = this.readFile(join(this.directory, file));\n      items.push(item);\n    }\n\n    if (options?.filter) {\n      items = items.filter(options.filter);\n    }\n    if (options?.sort) {\n      items.sort(options.sort);\n    }\n    if (options?.offset !== undefined) {\n      items = items.slice(options.offset);\n    }\n    if (options?.limit !== undefined) {\n      items = items.slice(0, options.limit);\n    }\n\n    return items;\n  }\n\n  /** @inheritdoc */\n  async create(key: string, item: T): Promise<void> {\n    const filePath = this.keyToPath(key);\n    if (existsSync(filePath)) {\n      throw new StorageError(\n        `Item with key \"${key}\" already exists`,\n        \"DUPLICATE_KEY\",\n      );\n    }\n    this.writeFile(filePath, item);\n  }\n\n  /** @inheritdoc */\n  async update(key: string, item: T): Promise<void> {\n    const filePath = this.keyToPath(key);\n    if (!existsSync(filePath)) {\n      throw new StorageError(\n        `Item with key \"${key}\" not found`,\n        \"NOT_FOUND\",\n      );\n    }\n    this.writeFile(filePath, item);\n  }\n\n  /** @inheritdoc */\n  async delete(key: string): Promise<void> {\n    const filePath = this.keyToPath(key);\n    if (!existsSync(filePath)) {\n      throw new StorageError(\n        `Item with key \"${key}\" not found`,\n        \"NOT_FOUND\",\n      );\n    }\n    unlinkSync(filePath);\n  }\n\n  /** @inheritdoc */\n  async has(key: string): Promise<boolean> {\n    return existsSync(this.keyToPath(key));\n  }\n\n  /** @inheritdoc */\n  async count(): Promise<number> {\n    this.ensureDirectory();\n    return readdirSync(this.directory).filter((f) =>\n      f.endsWith(this.extension),\n    ).length;\n  }\n\n  /** @inheritdoc */\n  async clear(): Promise<void> {\n    this.ensureDirectory();\n    const files = readdirSync(this.directory).filter((f) =>\n      f.endsWith(this.extension),\n    );\n    for (const file of files) {\n      unlinkSync(join(this.directory, file));\n    }\n  }\n\n  private keyToPath(key: string): string {\n    const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, (c) =>\n      \"%\" + c.charCodeAt(0).toString(16).padStart(2, \"0\"),\n    );\n    return join(this.directory, `${safeKey}${this.extension}`);\n  }\n\n  private ensureDirectory(): void {\n    if (!existsSync(this.directory)) {\n      mkdirSync(this.directory, { recursive: true });\n    }\n  }\n\n  private readFile(filePath: string): T {\n    try {\n      const content = readFileSync(filePath, \"utf-8\");\n      return JSON.parse(content) as T;\n    } catch (error) {\n      if (error instanceof SyntaxError) {\n        throw new StorageError(\n          `Failed to parse file: ${filePath}`,\n          \"SERIALIZATION_ERROR\",\n        );\n      }\n      throw new StorageError(\n        `Failed to read file: ${filePath}`,\n        \"IO_ERROR\",\n      );\n    }\n  }\n\n  private writeFile(filePath: string, item: T): void {\n    try {\n      const content = JSON.stringify(item, null, 2);\n      writeFileSync(filePath, content, \"utf-8\");\n    } catch {\n      throw new StorageError(\n        `Failed to write file: ${filePath}`,\n        \"IO_ERROR\",\n      );\n    }\n  }\n}\n","/**\n * @witqq/agent-sdk/chat/sessions\n *\n * Session store layer wrapping generic storage adapters.\n * Provides session-specific operations: message management,\n * paginated retrieval, search, and session lifecycle.\n */\n\nimport type {\n  ChatSession,\n  ChatMessage,\n  ChatId,\n  ChatSessionConfig,\n} from \"./core.js\";\nimport { createChatId } from \"./core.js\";\nimport type { IStorageAdapter, ListOptions } from \"./storage.js\";\nimport { InMemoryStorage, FileStorage, StorageError } from \"./storage.js\";\n\n// ─── Session Store Interface ───────────────────────────────────\n\n/** Options for creating a new session */\nexport interface CreateSessionOptions<TCustom extends Record<string, unknown> = Record<string, unknown>> {\n  /** Session title (defaults to \"Untitled\") */\n  title?: string;\n  /** Session configuration (optional — runtime defaults used when omitted) */\n  config?: Partial<ChatSessionConfig>;\n  /** Initial tags */\n  tags?: string[];\n  /** Custom metadata */\n  custom?: TCustom;\n}\n\n/** Paginated result of messages */\nexport interface PaginatedMessages {\n  /** Messages in this page */\n  messages: ChatMessage[];\n  /** Total number of messages in session */\n  total: number;\n  /** Whether there are more messages after this page */\n  hasMore: boolean;\n}\n\n/** Options for listing sessions */\nexport interface SessionListOptions {\n  /** Filter predicate */\n  filter?: (session: ChatSession) => boolean;\n  /** Sort comparator */\n  sort?: (a: ChatSession, b: ChatSession) => number;\n  /** Maximum number of sessions to return */\n  limit?: number;\n  /** Number of sessions to skip */\n  offset?: number;\n}\n\n/** Search options for finding sessions */\nexport interface SessionSearchOptions {\n  /** Text query to match against title and message content */\n  query: string;\n  /** Maximum results (default: 20) */\n  limit?: number;\n}\n\n/**\n * Session store interface for managing chat sessions.\n * Wraps a storage adapter with session-specific operations.\n *\n * @example\n * ```typescript\n * const store = new InMemorySessionStore();\n * const session = await store.createSession({ config: { model: \"gpt-4\", backend: \"vercel-ai\" } });\n * await store.appendMessage(session.id, message);\n * const page = await store.loadMessages(session.id, { limit: 20, offset: 0 });\n * ```\n */\nexport interface IChatSessionStore {\n  /**\n   * Create a new session with defaults.\n   * @param options - Session creation options\n   * @returns The created session\n   */\n  createSession(options: CreateSessionOptions): Promise<ChatSession>;\n\n  /**\n   * Retrieve a session by ID.\n   * @param id - Session ID\n   * @returns The session, or `null` if not found\n   */\n  getSession(id: ChatId): Promise<ChatSession | null>;\n\n  /**\n   * List sessions with optional filtering, sorting, and pagination.\n   * @param options - List options\n   * @returns Array of sessions\n   */\n  listSessions(options?: SessionListOptions): Promise<ChatSession[]>;\n\n  /**\n   * Update session title.\n   * @param id - Session ID\n   * @param title - New title\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  updateTitle(id: ChatId, title: string): Promise<void>;\n\n  /**\n   * Update session configuration.\n   * @param id - Session ID\n   * @param config - Partial config to merge\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  updateConfig(\n    id: ChatId,\n    config: Partial<ChatSessionConfig>,\n  ): Promise<void>;\n\n  /**\n   * Delete a session by ID.\n   * @param id - Session ID\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  deleteSession(id: ChatId): Promise<void>;\n\n  /**\n   * Append a single message to a session.\n   * Updates session metadata (messageCount, updatedAt).\n   * @param sessionId - Session ID\n   * @param message - Message to append\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;\n\n  /**\n   * Append multiple messages to a session in bulk.\n   * No-op if messages array is empty.\n   * @param sessionId - Session ID\n   * @param messages - Messages to append\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void>;\n\n  /**\n   * Get paginated messages from a session.\n   * @param sessionId - Session ID\n   * @param options - Pagination options (limit, offset)\n   * @returns Paginated messages result\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  loadMessages(\n    sessionId: ChatId,\n    options?: { limit?: number; offset?: number },\n  ): Promise<PaginatedMessages>;\n\n  /**\n   * Archive a session (set status to \"archived\").\n   * @param id - Session ID\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  archiveSession(id: ChatId): Promise<void>;\n\n  /**\n   * Unarchive a session (set status back to \"active\").\n   * @param id - Session ID\n   * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist\n   */\n  unarchiveSession(id: ChatId): Promise<void>;\n\n  /**\n   * Search sessions by title and message content.\n   * Case-insensitive substring match.\n   * @param options - Search query and limit\n   * @returns Matching sessions (without full message content)\n   */\n  searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;\n\n  /**\n   * Return the number of stored sessions.\n   */\n  count(): Promise<number>;\n\n  /**\n   * Remove all sessions.\n   */\n  clear(): Promise<void>;\n\n  // ── Deprecated Aliases ──────────────────────────────────────\n\n  /**\n   * @deprecated Use `appendMessage()` instead. Will be removed in next major.\n   */\n  addMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;\n\n  /**\n   * @deprecated Use `loadMessages()` instead. Will be removed in next major.\n   */\n  getMessages(\n    sessionId: ChatId,\n    options?: { limit?: number; offset?: number },\n  ): Promise<PaginatedMessages>;\n}\n\n// ─── Base Session Store ────────────────────────────────────────\n\n/**\n * Base session store implementation backed by any `IStorageAdapter<ChatSession>`.\n * Handles all session-specific logic; subclasses only need to provide the adapter.\n */\nclass BaseSessionStore implements IChatSessionStore {\n  constructor(protected readonly adapter: IStorageAdapter<ChatSession>) {}\n\n  async createSession(options: CreateSessionOptions): Promise<ChatSession> {\n    const now = new Date().toISOString();\n    const id = createChatId();\n    const session: ChatSession = {\n      id,\n      title: options.title ?? \"Untitled\",\n      messages: [],\n      config: {\n        model: options.config?.model ?? \"\",\n        backend: options.config?.backend ?? \"\",\n        ...options.config,\n      },\n      metadata: {\n        messageCount: 0,\n        totalTokens: 0,\n        tags: options.tags ? [...options.tags] : undefined,\n        custom: options.custom ? { ...options.custom } : undefined,\n      },\n      status: \"active\" as const,\n      createdAt: now,\n      updatedAt: now,\n    };\n    await this.adapter.create(id, session);\n    return structuredClone(session);\n  }\n\n  async getSession(id: ChatId): Promise<ChatSession | null> {\n    return this.adapter.get(id);\n  }\n\n  async listSessions(options?: SessionListOptions): Promise<ChatSession[]> {\n    return this.adapter.list(options as ListOptions<ChatSession>);\n  }\n\n  async updateTitle(id: ChatId, title: string): Promise<void> {\n    const session = await this.adapter.get(id);\n    if (!session) {\n      throw new StorageError(`Session \"${id}\" not found`, \"NOT_FOUND\");\n    }\n    session.title = title;\n    session.updatedAt = new Date().toISOString();\n    await this.adapter.update(id, session);\n  }\n\n  async updateConfig(\n    id: ChatId,\n    config: Partial<ChatSessionConfig>,\n  ): Promise<void> {\n    const session = await this.adapter.get(id);\n    if (!session) {\n      throw new StorageError(`Session \"${id}\" not found`, \"NOT_FOUND\");\n    }\n    session.config = { ...session.config, ...config };\n    session.updatedAt = new Date().toISOString();\n    await this.adapter.update(id, session);\n  }\n\n  async deleteSession(id: ChatId): Promise<void> {\n    await this.adapter.delete(id);\n  }\n\n  async appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void> {\n    const session = await this.adapter.get(sessionId);\n    if (!session) {\n      throw new StorageError(`Session \"${sessionId}\" not found`, \"NOT_FOUND\");\n    }\n    session.messages.push(structuredClone(message));\n    session.metadata.messageCount = session.messages.length;\n    session.updatedAt = new Date().toISOString();\n    await this.adapter.update(sessionId, session);\n  }\n\n  async saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void> {\n    if (messages.length === 0) return;\n    const session = await this.adapter.get(sessionId);\n    if (!session) {\n      throw new StorageError(`Session \"${sessionId}\" not found`, \"NOT_FOUND\");\n    }\n    for (const msg of messages) {\n      session.messages.push(structuredClone(msg));\n    }\n    session.metadata.messageCount = session.messages.length;\n    session.updatedAt = new Date().toISOString();\n    await this.adapter.update(sessionId, session);\n  }\n\n  async loadMessages(\n    sessionId: ChatId,\n    options?: { limit?: number; offset?: number },\n  ): Promise<PaginatedMessages> {\n    const session = await this.adapter.get(sessionId);\n    if (!session) {\n      throw new StorageError(`Session \"${sessionId}\" not found`, \"NOT_FOUND\");\n    }\n    const total = session.messages.length;\n    const offset = options?.offset ?? 0;\n    const limit = options?.limit ?? total;\n    const messages = session.messages.slice(offset, offset + limit);\n    return {\n      messages: structuredClone(messages),\n      total,\n      hasMore: offset + limit < total,\n    };\n  }\n\n  async archiveSession(id: ChatId): Promise<void> {\n    const session = await this.adapter.get(id);\n    if (!session) {\n      throw new StorageError(`Session \"${id}\" not found`, \"NOT_FOUND\");\n    }\n    session.status = \"archived\";\n    session.updatedAt = new Date().toISOString();\n    await this.adapter.update(id, session);\n  }\n\n  async unarchiveSession(id: ChatId): Promise<void> {\n    const session = await this.adapter.get(id);\n    if (!session) {\n      throw new StorageError(`Session \"${id}\" not found`, \"NOT_FOUND\");\n    }\n    session.status = \"active\";\n    session.updatedAt = new Date().toISOString();\n    await this.adapter.update(id, session);\n  }\n\n  async searchSessions(\n    options: SessionSearchOptions,\n  ): Promise<ChatSession[]> {\n    const query = options.query.toLowerCase();\n    const limit = options.limit ?? 20;\n    return this.adapter.list({\n      filter: (session) => {\n        if (session.title?.toLowerCase().includes(query)) return true;\n        return session.messages.some((msg) => {\n          return msg.parts.some(\n            (part) =>\n              part.type === \"text\" &&\n              part.text.toLowerCase().includes(query),\n          );\n        });\n      },\n      limit,\n    });\n  }\n\n  async count(): Promise<number> {\n    return this.adapter.count();\n  }\n\n  async clear(): Promise<void> {\n    return this.adapter.clear();\n  }\n\n  // ── Deprecated Aliases ──────────────────────────────────────\n\n  /** @deprecated Use `appendMessage()` instead */\n  async addMessage(sessionId: ChatId, message: ChatMessage): Promise<void> {\n    return this.appendMessage(sessionId, message);\n  }\n\n  /** @deprecated Use `loadMessages()` instead */\n  async getMessages(\n    sessionId: ChatId,\n    options?: { limit?: number; offset?: number },\n  ): Promise<PaginatedMessages> {\n    return this.loadMessages(sessionId, options);\n  }\n}\n\n// ─── InMemorySessionStore ──────────────────────────────────────\n\n/**\n * In-memory session store. Data is lost when the process exits.\n * Uses `InMemoryStorage` internally.\n *\n * @example\n * ```typescript\n * const store = new InMemorySessionStore();\n * const session = await store.createSession({\n *   config: { model: \"gpt-4\", backend: \"vercel-ai\" },\n * });\n * ```\n */\nexport class InMemorySessionStore extends BaseSessionStore {\n  constructor() {\n    super(new InMemoryStorage<ChatSession>());\n  }\n}\n\n// ─── FileSessionStore ──────────────────────────────────────────\n\n/** Configuration for FileSessionStore */\nexport interface FileSessionStoreOptions {\n  /** Directory to store session JSON files */\n  directory: string;\n}\n\n/**\n * File-based session store. Each session is a JSON file on disk.\n * Uses `FileStorage` internally.\n *\n * @example\n * ```typescript\n * const store = new FileSessionStore({ directory: \"./data/sessions\" });\n * const session = await store.createSession({\n *   config: { model: \"claude-3\", backend: \"claude\" },\n * });\n * ```\n */\nexport class FileSessionStore extends BaseSessionStore {\n  constructor(options: FileSessionStoreOptions) {\n    super(new FileStorage<ChatSession>({ directory: options.directory }));\n  }\n}\n\n// Re-export StorageError for consumers that only import from chat/sessions\nexport { StorageError } from \"./storage.js\";\n"]}