@witqq/agent-sdk 0.6.1 → 0.8.0

package/dist/chat/sessions.d.ts

@@ -0,0 +1,158 @@
+import { b as ChatId, g as ChatSession, c as ChatMessage, j as ChatSessionConfig } from '../types-ajANVzf7.js';
+import { IStorageAdapter } from './storage.js';
+export { StorageError } from './storage.js';
+import '../agent-CW9XbmG_.js';
+import 'zod';
+import '../errors-C-so0M4t.js';
+import '../types-BxggH0Yh.js';
+import '../errors-CmVvczxZ.js';
+
+/**
+ * @witqq/agent-sdk/chat/sessions
+ *
+ * Session store layer wrapping generic storage adapters.
+ * Provides session-specific operations: message management,
+ * paginated retrieval, search, and session lifecycle.
+ */
+
+/** Options for creating a new session */
+interface CreateSessionOptions<TCustom extends Record<string, unknown> = Record<string, unknown>> {
+    /** Session title (defaults to "Untitled") */
+    title?: string;
+    /** Session configuration (optional — runtime defaults used when omitted) */
+    config?: Partial<ChatSessionConfig>;
+    /** Initial tags */
+    tags?: string[];
+    /** Custom metadata */
+    custom?: TCustom;
+}
+/** Paginated result of messages */
+interface PaginatedMessages {
+    /** Messages in this page */
+    messages: ChatMessage[];
+    /** Total number of messages in session */
+    total: number;
+    /** Whether there are more messages after this page */
+    hasMore: boolean;
+}
+/** Options for listing sessions */
+interface SessionListOptions {
+    /** Filter predicate */
+    filter?: (session: ChatSession) => boolean;
+    /** Sort comparator */
+    sort?: (a: ChatSession, b: ChatSession) => number;
+    /** Maximum number of sessions to return */
+    limit?: number;
+    /** Number of sessions to skip */
+    offset?: number;
+}
+/** Search options for finding sessions */
+interface SessionSearchOptions {
+    /** Text query to match against title and message content */
+    query: string;
+    /** Maximum results (default: 20) */
+    limit?: number;
+}
+/**
+ * Read-only session operations.
+ * Consumers needing read-only access (dashboards, analytics) implement only this.
+ */
+interface ISessionReader {
+    getSession(id: ChatId): Promise<ChatSession | null>;
+    listSessions(options?: SessionListOptions): Promise<ChatSession[]>;
+    loadMessages(sessionId: ChatId, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedMessages>;
+    searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;
+    count(): Promise<number>;
+}
+/**
+ * Write/mutate session operations.
+ * Consumers needing full access implement both ISessionReader & ISessionWriter.
+ */
+interface ISessionWriter {
+    createSession(options: CreateSessionOptions): Promise<ChatSession>;
+    updateTitle(id: ChatId, title: string): Promise<void>;
+    updateConfig(id: ChatId, config: Partial<ChatSessionConfig>): Promise<void>;
+    deleteSession(id: ChatId): Promise<void>;
+    appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
+    saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void>;
+    clear(): Promise<void>;
+    /** Release any resources held by this store (optional). */
+    dispose?(): Promise<void>;
+}
+/**
+ * Full session store interface — union of reader and writer.
+ * Backward-compatible: all existing implementations continue to work.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemorySessionStore();
+ * const session = await store.createSession({ config: { model: "gpt-4", backend: "vercel-ai" } });
+ * await store.appendMessage(session.id, message);
+ * const page = await store.loadMessages(session.id, { limit: 20, offset: 0 });
+ * ```
+ */
+interface IChatSessionStore extends ISessionReader, ISessionWriter {
+}
+/**
+ * Base session store implementation backed by any `IStorageAdapter<ChatSession>`.
+ * Handles all session-specific logic; subclasses only need to provide the adapter.
+ */
+declare class BaseSessionStore implements IChatSessionStore {
+    protected readonly adapter: IStorageAdapter<ChatSession>;
+    constructor(adapter: IStorageAdapter<ChatSession>);
+    createSession(options: CreateSessionOptions): Promise<ChatSession>;
+    getSession(id: ChatId): Promise<ChatSession | null>;
+    listSessions(options?: SessionListOptions): Promise<ChatSession[]>;
+    updateTitle(id: ChatId, title: string): Promise<void>;
+    updateConfig(id: ChatId, config: Partial<ChatSessionConfig>): Promise<void>;
+    deleteSession(id: ChatId): Promise<void>;
+    appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
+    saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void>;
+    loadMessages(sessionId: ChatId, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedMessages>;
+    searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;
+    count(): Promise<number>;
+    clear(): Promise<void>;
+}
+/**
+ * In-memory session store. Data is lost when the process exits.
+ * Uses `InMemoryStorage` internally.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemorySessionStore();
+ * const session = await store.createSession({
+ *   config: { model: "gpt-4", backend: "vercel-ai" },
+ * });
+ * ```
+ */
+declare class InMemorySessionStore extends BaseSessionStore {
+    constructor();
+}
+/** Configuration for FileSessionStore */
+interface FileSessionStoreOptions {
+    /** Directory to store session JSON files */
+    directory: string;
+}
+/**
+ * File-based session store. Each session is a JSON file on disk.
+ * Uses `FileStorage` internally.
+ *
+ * @example
+ * ```typescript
+ * const store = new FileSessionStore({ directory: "./data/sessions" });
+ * const session = await store.createSession({
+ *   config: { model: "claude-3", backend: "claude" },
+ * });
+ * ```
+ */
+declare class FileSessionStore extends BaseSessionStore {
+    constructor(options: FileSessionStoreOptions);
+}
+
+export { type CreateSessionOptions, FileSessionStore, type FileSessionStoreOptions, type IChatSessionStore, type ISessionReader, type ISessionWriter, InMemorySessionStore, type PaginatedMessages, type SessionListOptions, type SessionSearchOptions };

package/dist/chat/sessions.js

@@ -0,0 +1,376 @@
+import { existsSync, readdirSync, unlinkSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// src/chat/types.ts
+function createChatId() {
+  return crypto.randomUUID();
+}
+
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  /** @internal Marker for cross-bundle identity checks */
+  _agentSDKError = true;
+  /** Machine-readable error code. Prefer values from the ErrorCode enum. */
+  code;
+  /** Whether this error is safe to retry */
+  retryable;
+  /** HTTP status code hint for error classification */
+  httpStatus;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+    this.code = options?.code;
+    this.retryable = options?.retryable ?? false;
+    this.httpStatus = options?.httpStatus;
+  }
+  /** 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 from the unified ErrorCode enum */
+  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`,
+        "STORAGE_DUPLICATE_KEY" /* STORAGE_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`,
+        "STORAGE_NOT_FOUND" /* STORAGE_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`,
+        "STORAGE_NOT_FOUND" /* STORAGE_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`,
+        "STORAGE_DUPLICATE_KEY" /* STORAGE_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`,
+        "STORAGE_NOT_FOUND" /* STORAGE_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`,
+        "STORAGE_NOT_FOUND" /* STORAGE_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}`,
+          "STORAGE_SERIALIZATION_ERROR" /* STORAGE_SERIALIZATION_ERROR */
+        );
+      }
+      throw new StorageError(
+        `Failed to read file: ${filePath}`,
+        "STORAGE_IO_ERROR" /* STORAGE_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}`,
+        "STORAGE_IO_ERROR" /* STORAGE_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`, "STORAGE_NOT_FOUND" /* STORAGE_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`, "STORAGE_NOT_FOUND" /* STORAGE_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`, "STORAGE_NOT_FOUND" /* STORAGE_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`, "STORAGE_NOT_FOUND" /* STORAGE_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`, "STORAGE_NOT_FOUND" /* STORAGE_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 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();
+  }
+};
+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/types.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 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","import { ErrorCode } from \"./types/errors.js\";\n\n/** Options for constructing an AgentSDKError */\nexport interface AgentSDKErrorOptions extends ErrorOptions {\n  /** Machine-readable error code */\n  code?: string;\n  /** Whether this error is retryable (default: false) */\n  retryable?: boolean;\n  /** HTTP status code hint (e.g. 401, 429, 500) */\n  httpStatus?: number;\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  /** Machine-readable error code. Prefer values from the ErrorCode enum. */\n  readonly code?: string;\n  /** Whether this error is safe to retry */\n  readonly retryable: boolean;\n  /** HTTP status code hint for error classification */\n  readonly httpStatus?: number;\n\n  constructor(message: string, options?: AgentSDKErrorOptions) {\n    super(message, options);\n    this.name = \"AgentSDKError\";\n    this.code = options?.code;\n    this.retryable = options?.retryable ?? false;\n    this.httpStatus = options?.httpStatus;\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      code: ErrorCode.REENTRANCY,\n    });\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      code: ErrorCode.DISPOSED,\n    });\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      { code: ErrorCode.BACKEND_NOT_INSTALLED },\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, code: ErrorCode.DEPENDENCY_MISSING });\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      code: ErrorCode.DEPENDENCY_MISSING,\n    });\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.\", { code: ErrorCode.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, code: ErrorCode.TOOL_EXECUTION });\n    this.name = \"ToolExecutionError\";\n    this.toolName = toolName;\n  }\n}\n\n/** Thrown when a stream has no activity within the configured timeout */\nexport class ActivityTimeoutError extends AgentSDKError {\n  constructor(timeoutMs: number) {\n    super(`Stream activity timeout: no event received within ${timeoutMs}ms.`, {\n      code: ErrorCode.TIMEOUT,\n      retryable: true,\n    });\n    this.name = \"ActivityTimeoutError\";\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, code: ErrorCode.INVALID_RESPONSE });\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\";\nimport { ErrorCode } from \"../types/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 === ErrorCode.STORAGE_NOT_FOUND) {\n *     // handle missing item\n *   }\n * }\n * ```\n */\nexport class StorageError extends AgentSDKError {\n  /** Machine-readable error code from the unified ErrorCode enum */\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/** Storage-specific subset of ErrorCode */\nexport type StorageErrorCode =\n  | ErrorCode.STORAGE_NOT_FOUND\n  | ErrorCode.STORAGE_DUPLICATE_KEY\n  | ErrorCode.STORAGE_IO_ERROR\n  | ErrorCode.STORAGE_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   * Release any resources held by this adapter (DB connections, file handles).\n   * Optional — adapters that don't hold resources need not implement this.\n   */\n  dispose?(): 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        ErrorCode.STORAGE_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        ErrorCode.STORAGE_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        ErrorCode.STORAGE_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        ErrorCode.STORAGE_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        ErrorCode.STORAGE_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        ErrorCode.STORAGE_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          ErrorCode.STORAGE_SERIALIZATION_ERROR,\n        );\n      }\n      throw new StorageError(\n        `Failed to read file: ${filePath}`,\n        ErrorCode.STORAGE_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        ErrorCode.STORAGE_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\";\nimport { ErrorCode } from \"../types/errors.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 * Read-only session operations.\n * Consumers needing read-only access (dashboards, analytics) implement only this.\n */\nexport interface ISessionReader {\n  getSession(id: ChatId): Promise<ChatSession | null>;\n  listSessions(options?: SessionListOptions): Promise<ChatSession[]>;\n  loadMessages(\n    sessionId: ChatId,\n    options?: { limit?: number; offset?: number },\n  ): Promise<PaginatedMessages>;\n  searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;\n  count(): Promise<number>;\n}\n\n/**\n * Write/mutate session operations.\n * Consumers needing full access implement both ISessionReader & ISessionWriter.\n */\nexport interface ISessionWriter {\n  createSession(options: CreateSessionOptions): Promise<ChatSession>;\n  updateTitle(id: ChatId, title: string): Promise<void>;\n  updateConfig(id: ChatId, config: Partial<ChatSessionConfig>): Promise<void>;\n  deleteSession(id: ChatId): Promise<void>;\n  appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;\n  saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void>;\n  clear(): Promise<void>;\n  /** Release any resources held by this store (optional). */\n  dispose?(): Promise<void>;\n}\n\n/**\n * Full session store interface — union of reader and writer.\n * Backward-compatible: all existing implementations continue to work.\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 extends ISessionReader, ISessionWriter {}\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`, ErrorCode.STORAGE_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`, ErrorCode.STORAGE_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`, ErrorCode.STORAGE_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`, ErrorCode.STORAGE_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`, ErrorCode.STORAGE_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 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\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"]}