@witqq/agent-sdk 0.7.0 → 0.8.0

package/dist/chat/sessions.d.cts

@@ -1,9 +1,11 @@
-import { ChatSessionConfig, ChatSession, ChatId, ChatMessage } from './core.cjs';
+import { b as ChatId, g as ChatSession, c as ChatMessage, j as ChatSessionConfig } from '../types-DRgd_9R7.cjs';
 import { IStorageAdapter } from './storage.cjs';
 export { StorageError } from './storage.cjs';
-import '../types-CqvUAYxt.cjs';
+import '../agent-DxY68NZL.cjs';
 import 'zod';
-import '../errors-BDLbNu9w.cjs';
+import '../errors-C-so0M4t.cjs';
+import '../types-4vbcmPTp.cjs';
+import '../errors-CmVvczxZ.cjs';
 
 /**
  * @witqq/agent-sdk/chat/sessions
@@ -52,121 +54,47 @@ interface SessionSearchOptions {
     limit?: number;
 }
 /**
- * Session store interface for managing chat sessions.
- * Wraps a storage adapter with session-specific operations.
- *
- * @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 });
- * ```
+ * Read-only session operations.
+ * Consumers needing read-only access (dashboards, analytics) implement only this.
  */
-interface IChatSessionStore {
-    /**
-     * Create a new session with defaults.
-     * @param options - Session creation options
-     * @returns The created session
-     */
-    createSession(options: CreateSessionOptions): Promise<ChatSession>;
-    /**
-     * Retrieve a session by ID.
-     * @param id - Session ID
-     * @returns The session, or `null` if not found
-     */
+interface ISessionReader {
     getSession(id: ChatId): Promise<ChatSession | null>;
-    /**
-     * List sessions with optional filtering, sorting, and pagination.
-     * @param options - List options
-     * @returns Array of sessions
-     */
     listSessions(options?: SessionListOptions): Promise<ChatSession[]>;
-    /**
-     * Update session title.
-     * @param id - Session ID
-     * @param title - New title
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    updateTitle(id: ChatId, title: string): Promise<void>;
-    /**
-     * Update session configuration.
-     * @param id - Session ID
-     * @param config - Partial config to merge
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    updateConfig(id: ChatId, config: Partial<ChatSessionConfig>): Promise<void>;
-    /**
-     * Delete a session by ID.
-     * @param id - Session ID
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    deleteSession(id: ChatId): Promise<void>;
-    /**
-     * Append a single message to a session.
-     * Updates session metadata (messageCount, updatedAt).
-     * @param sessionId - Session ID
-     * @param message - Message to append
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
-    /**
-     * Append multiple messages to a session in bulk.
-     * No-op if messages array is empty.
-     * @param sessionId - Session ID
-     * @param messages - Messages to append
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void>;
-    /**
-     * Get paginated messages from a session.
-     * @param sessionId - Session ID
-     * @param options - Pagination options (limit, offset)
-     * @returns Paginated messages result
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
     loadMessages(sessionId: ChatId, options?: {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedMessages>;
-    /**
-     * Archive a session (set status to "archived").
-     * @param id - Session ID
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    archiveSession(id: ChatId): Promise<void>;
-    /**
-     * Unarchive a session (set status back to "active").
-     * @param id - Session ID
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    unarchiveSession(id: ChatId): Promise<void>;
-    /**
-     * Search sessions by title and message content.
-     * Case-insensitive substring match.
-     * @param options - Search query and limit
-     * @returns Matching sessions (without full message content)
-     */
     searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;
-    /**
-     * Return the number of stored sessions.
-     */
     count(): Promise<number>;
-    /**
-     * Remove all sessions.
-     */
+}
+/**
+ * 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>;
-    /**
-     * @deprecated Use `appendMessage()` instead. Will be removed in next major.
-     */
-    addMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
-    /**
-     * @deprecated Use `loadMessages()` instead. Will be removed in next major.
-     */
-    getMessages(sessionId: ChatId, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedMessages>;
+    /** 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>`.
@@ -187,18 +115,9 @@ declare class BaseSessionStore implements IChatSessionStore {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedMessages>;
-    archiveSession(id: ChatId): Promise<void>;
-    unarchiveSession(id: ChatId): Promise<void>;
     searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;
     count(): Promise<number>;
     clear(): Promise<void>;
-    /** @deprecated Use `appendMessage()` instead */
-    addMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
-    /** @deprecated Use `loadMessages()` instead */
-    getMessages(sessionId: ChatId, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedMessages>;
 }
 /**
  * In-memory session store. Data is lost when the process exits.
@@ -236,4 +155,4 @@ declare class FileSessionStore extends BaseSessionStore {
     constructor(options: FileSessionStoreOptions);
 }
 
-export { type CreateSessionOptions, FileSessionStore, type FileSessionStoreOptions, type IChatSessionStore, InMemorySessionStore, type PaginatedMessages, type SessionListOptions, type SessionSearchOptions };
+export { type CreateSessionOptions, FileSessionStore, type FileSessionStoreOptions, type IChatSessionStore, type ISessionReader, type ISessionWriter, InMemorySessionStore, type PaginatedMessages, type SessionListOptions, type SessionSearchOptions };

package/dist/chat/sessions.d.ts

@@ -1,9 +1,11 @@
-import { ChatSessionConfig, ChatSession, ChatId, ChatMessage } from './core.js';
+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 '../types-CqvUAYxt.js';
+import '../agent-CW9XbmG_.js';
 import 'zod';
-import '../errors-BDLbNu9w.js';
+import '../errors-C-so0M4t.js';
+import '../types-BxggH0Yh.js';
+import '../errors-CmVvczxZ.js';
 
 /**
  * @witqq/agent-sdk/chat/sessions
@@ -52,121 +54,47 @@ interface SessionSearchOptions {
     limit?: number;
 }
 /**
- * Session store interface for managing chat sessions.
- * Wraps a storage adapter with session-specific operations.
- *
- * @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 });
- * ```
+ * Read-only session operations.
+ * Consumers needing read-only access (dashboards, analytics) implement only this.
  */
-interface IChatSessionStore {
-    /**
-     * Create a new session with defaults.
-     * @param options - Session creation options
-     * @returns The created session
-     */
-    createSession(options: CreateSessionOptions): Promise<ChatSession>;
-    /**
-     * Retrieve a session by ID.
-     * @param id - Session ID
-     * @returns The session, or `null` if not found
-     */
+interface ISessionReader {
     getSession(id: ChatId): Promise<ChatSession | null>;
-    /**
-     * List sessions with optional filtering, sorting, and pagination.
-     * @param options - List options
-     * @returns Array of sessions
-     */
     listSessions(options?: SessionListOptions): Promise<ChatSession[]>;
-    /**
-     * Update session title.
-     * @param id - Session ID
-     * @param title - New title
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    updateTitle(id: ChatId, title: string): Promise<void>;
-    /**
-     * Update session configuration.
-     * @param id - Session ID
-     * @param config - Partial config to merge
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    updateConfig(id: ChatId, config: Partial<ChatSessionConfig>): Promise<void>;
-    /**
-     * Delete a session by ID.
-     * @param id - Session ID
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    deleteSession(id: ChatId): Promise<void>;
-    /**
-     * Append a single message to a session.
-     * Updates session metadata (messageCount, updatedAt).
-     * @param sessionId - Session ID
-     * @param message - Message to append
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    appendMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
-    /**
-     * Append multiple messages to a session in bulk.
-     * No-op if messages array is empty.
-     * @param sessionId - Session ID
-     * @param messages - Messages to append
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    saveMessages(sessionId: ChatId, messages: ChatMessage[]): Promise<void>;
-    /**
-     * Get paginated messages from a session.
-     * @param sessionId - Session ID
-     * @param options - Pagination options (limit, offset)
-     * @returns Paginated messages result
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
     loadMessages(sessionId: ChatId, options?: {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedMessages>;
-    /**
-     * Archive a session (set status to "archived").
-     * @param id - Session ID
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    archiveSession(id: ChatId): Promise<void>;
-    /**
-     * Unarchive a session (set status back to "active").
-     * @param id - Session ID
-     * @throws {StorageError} with code `NOT_FOUND` if session doesn't exist
-     */
-    unarchiveSession(id: ChatId): Promise<void>;
-    /**
-     * Search sessions by title and message content.
-     * Case-insensitive substring match.
-     * @param options - Search query and limit
-     * @returns Matching sessions (without full message content)
-     */
     searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;
-    /**
-     * Return the number of stored sessions.
-     */
     count(): Promise<number>;
-    /**
-     * Remove all sessions.
-     */
+}
+/**
+ * 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>;
-    /**
-     * @deprecated Use `appendMessage()` instead. Will be removed in next major.
-     */
-    addMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
-    /**
-     * @deprecated Use `loadMessages()` instead. Will be removed in next major.
-     */
-    getMessages(sessionId: ChatId, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedMessages>;
+    /** 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>`.
@@ -187,18 +115,9 @@ declare class BaseSessionStore implements IChatSessionStore {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedMessages>;
-    archiveSession(id: ChatId): Promise<void>;
-    unarchiveSession(id: ChatId): Promise<void>;
     searchSessions(options: SessionSearchOptions): Promise<ChatSession[]>;
     count(): Promise<number>;
     clear(): Promise<void>;
-    /** @deprecated Use `appendMessage()` instead */
-    addMessage(sessionId: ChatId, message: ChatMessage): Promise<void>;
-    /** @deprecated Use `loadMessages()` instead */
-    getMessages(sessionId: ChatId, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedMessages>;
 }
 /**
  * In-memory session store. Data is lost when the process exits.
@@ -236,4 +155,4 @@ declare class FileSessionStore extends BaseSessionStore {
     constructor(options: FileSessionStoreOptions);
 }
 
-export { type CreateSessionOptions, FileSessionStore, type FileSessionStoreOptions, type IChatSessionStore, InMemorySessionStore, type PaginatedMessages, type SessionListOptions, type SessionSearchOptions };
+export { type CreateSessionOptions, FileSessionStore, type FileSessionStoreOptions, type IChatSessionStore, type ISessionReader, type ISessionWriter, InMemorySessionStore, type PaginatedMessages, type SessionListOptions, type SessionSearchOptions };

package/dist/chat/sessions.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, unlinkSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
-// src/chat/core.ts
+// src/chat/types.ts
 function createChatId() {
   return crypto.randomUUID();
 }
@@ -10,9 +10,18 @@ function createChatId() {
 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) {
@@ -22,7 +31,7 @@ var AgentSDKError = class extends Error {
 
 // src/chat/storage.ts
 var StorageError = class extends AgentSDKError {
-  /** Machine-readable error code */
+  /** Machine-readable error code from the unified ErrorCode enum */
   code;
   constructor(message, code) {
     super(message);
@@ -59,7 +68,7 @@ var InMemoryStorage = class {
     if (this.data.has(key)) {
       throw new StorageError(
         `Item with key "${key}" already exists`,
-        "DUPLICATE_KEY"
+        "STORAGE_DUPLICATE_KEY" /* STORAGE_DUPLICATE_KEY */
       );
     }
     this.data.set(key, structuredClone(item));
@@ -69,7 +78,7 @@ var InMemoryStorage = class {
     if (!this.data.has(key)) {
       throw new StorageError(
         `Item with key "${key}" not found`,
-        "NOT_FOUND"
+        "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */
       );
     }
     this.data.set(key, structuredClone(item));
@@ -79,7 +88,7 @@ var InMemoryStorage = class {
     if (!this.data.has(key)) {
       throw new StorageError(
         `Item with key "${key}" not found`,
-        "NOT_FOUND"
+        "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */
       );
     }
     this.data.delete(key);
@@ -144,7 +153,7 @@ var FileStorage = class {
     if (existsSync(filePath)) {
       throw new StorageError(
         `Item with key "${key}" already exists`,
-        "DUPLICATE_KEY"
+        "STORAGE_DUPLICATE_KEY" /* STORAGE_DUPLICATE_KEY */
       );
     }
     this.writeFile(filePath, item);
@@ -155,7 +164,7 @@ var FileStorage = class {
     if (!existsSync(filePath)) {
       throw new StorageError(
         `Item with key "${key}" not found`,
-        "NOT_FOUND"
+        "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */
       );
     }
     this.writeFile(filePath, item);
@@ -166,7 +175,7 @@ var FileStorage = class {
     if (!existsSync(filePath)) {
       throw new StorageError(
         `Item with key "${key}" not found`,
-        "NOT_FOUND"
+        "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */
       );
     }
     unlinkSync(filePath);
@@ -212,12 +221,12 @@ var FileStorage = class {
       if (error instanceof SyntaxError) {
         throw new StorageError(
           `Failed to parse file: ${filePath}`,
-          "SERIALIZATION_ERROR"
+          "STORAGE_SERIALIZATION_ERROR" /* STORAGE_SERIALIZATION_ERROR */
         );
       }
       throw new StorageError(
         `Failed to read file: ${filePath}`,
-        "IO_ERROR"
+        "STORAGE_IO_ERROR" /* STORAGE_IO_ERROR */
       );
     }
   }
@@ -228,7 +237,7 @@ var FileStorage = class {
     } catch {
       throw new StorageError(
         `Failed to write file: ${filePath}`,
-        "IO_ERROR"
+        "STORAGE_IO_ERROR" /* STORAGE_IO_ERROR */
       );
     }
   }
@@ -273,7 +282,7 @@ var BaseSessionStore = class {
   async updateTitle(id, title) {
     const session = await this.adapter.get(id);
     if (!session) {
-      throw new StorageError(`Session "${id}" not found`, "NOT_FOUND");
+      throw new StorageError(`Session "${id}" not found`, "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */);
     }
     session.title = title;
     session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -282,7 +291,7 @@ var BaseSessionStore = class {
   async updateConfig(id, config) {
     const session = await this.adapter.get(id);
     if (!session) {
-      throw new StorageError(`Session "${id}" not found`, "NOT_FOUND");
+      throw new StorageError(`Session "${id}" not found`, "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */);
     }
     session.config = { ...session.config, ...config };
     session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -294,7 +303,7 @@ var BaseSessionStore = class {
   async appendMessage(sessionId, message) {
     const session = await this.adapter.get(sessionId);
     if (!session) {
-      throw new StorageError(`Session "${sessionId}" not found`, "NOT_FOUND");
+      throw new StorageError(`Session "${sessionId}" not found`, "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */);
     }
     session.messages.push(structuredClone(message));
     session.metadata.messageCount = session.messages.length;
@@ -305,7 +314,7 @@ var BaseSessionStore = class {
     if (messages.length === 0) return;
     const session = await this.adapter.get(sessionId);
     if (!session) {
-      throw new StorageError(`Session "${sessionId}" not found`, "NOT_FOUND");
+      throw new StorageError(`Session "${sessionId}" not found`, "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */);
     }
     for (const msg of messages) {
       session.messages.push(structuredClone(msg));
@@ -317,7 +326,7 @@ var BaseSessionStore = class {
   async loadMessages(sessionId, options) {
     const session = await this.adapter.get(sessionId);
     if (!session) {
-      throw new StorageError(`Session "${sessionId}" not found`, "NOT_FOUND");
+      throw new StorageError(`Session "${sessionId}" not found`, "STORAGE_NOT_FOUND" /* STORAGE_NOT_FOUND */);
     }
     const total = session.messages.length;
     const offset = options?.offset ?? 0;
@@ -329,24 +338,6 @@ var BaseSessionStore = class {
       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;
@@ -368,15 +359,6 @@ var BaseSessionStore = class {
   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() {