@witqq/agent-sdk 0.6.1 → 0.8.0

package/dist/chat/storage.d.cts

@@ -0,0 +1,197 @@
+import { A as AgentSDKError } from '../errors-CmVvczxZ.cjs';
+import { E as ErrorCode } from '../errors-C-so0M4t.cjs';
+
+/**
+ * @witqq/agent-sdk/chat/storage
+ *
+ * Generic storage adapter layer with pluggable backends.
+ * Provides CRUD operations for any data type via `IStorageAdapter<T>`.
+ * Implementations: `InMemoryStorage` (Map-based) and `FileStorage` (JSON files).
+ */
+
+/**
+ * Error thrown by storage operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await store.get("missing-id");
+ * } catch (e) {
+ *   if (e instanceof StorageError && e.code === ErrorCode.STORAGE_NOT_FOUND) {
+ *     // handle missing item
+ *   }
+ * }
+ * ```
+ */
+declare class StorageError extends AgentSDKError {
+    /** Machine-readable error code from the unified ErrorCode enum */
+    readonly code: StorageErrorCode;
+    constructor(message: string, code: StorageErrorCode);
+}
+/** Storage-specific subset of ErrorCode */
+type StorageErrorCode = ErrorCode.STORAGE_NOT_FOUND | ErrorCode.STORAGE_DUPLICATE_KEY | ErrorCode.STORAGE_IO_ERROR | ErrorCode.STORAGE_SERIALIZATION_ERROR;
+/**
+ * Options for listing stored items.
+ *
+ * @typeParam T - The type of stored items
+ */
+interface ListOptions<T> {
+    /** Filter predicate — return `true` to include the item */
+    filter?: (item: T) => boolean;
+    /** Sort comparator — standard Array.sort semantics */
+    sort?: (a: T, b: T) => number;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Number of items to skip (for pagination) */
+    offset?: number;
+}
+/**
+ * Generic storage adapter for CRUD operations on any data type.
+ * Items are identified by a string key.
+ *
+ * @typeParam T - The type of stored items
+ *
+ * @example
+ * ```typescript
+ * const store: IStorageAdapter<{ name: string }> = new InMemoryStorage();
+ * await store.create("key1", { name: "Alice" });
+ * const item = await store.get("key1"); // { name: "Alice" }
+ * ```
+ */
+interface IStorageAdapter<T> {
+    /**
+     * Retrieve an item by key.
+     * @param key - Unique identifier
+     * @returns The item, or `null` if not found
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * List items with optional filtering, sorting, and pagination.
+     * @param options - Filter, sort, limit, offset options
+     * @returns Array of matching items
+     */
+    list(options?: ListOptions<T>): Promise<T[]>;
+    /**
+     * Create a new item. Throws `StorageError` with code `DUPLICATE_KEY` if key exists.
+     * @param key - Unique identifier
+     * @param item - Data to store
+     */
+    create(key: string, item: T): Promise<void>;
+    /**
+     * Update an existing item. Throws `StorageError` with code `NOT_FOUND` if key missing.
+     * @param key - Unique identifier
+     * @param item - Updated data
+     */
+    update(key: string, item: T): Promise<void>;
+    /**
+     * Delete an item by key. Throws `StorageError` with code `NOT_FOUND` if key missing.
+     * @param key - Unique identifier
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check whether a key exists.
+     * @param key - Unique identifier
+     * @returns `true` if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Return the number of stored items.
+     * @returns Count of items
+     */
+    count(): Promise<number>;
+    /**
+     * Remove all items from storage.
+     */
+    clear(): Promise<void>;
+    /**
+     * Release any resources held by this adapter (DB connections, file handles).
+     * Optional — adapters that don't hold resources need not implement this.
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * In-memory storage adapter backed by a `Map`.
+ * Suitable for development, testing, and short-lived processes.
+ * Data is lost when the process exits.
+ *
+ * @typeParam T - The type of stored items
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryStorage<{ name: string }>();
+ * await store.create("k1", { name: "Alice" });
+ * await store.create("k2", { name: "Bob" });
+ * const items = await store.list({ filter: i => i.name.startsWith("A") });
+ * // [{ name: "Alice" }]
+ * ```
+ */
+declare class InMemoryStorage<T> implements IStorageAdapter<T> {
+    private readonly data;
+    /** @inheritdoc */
+    get(key: string): Promise<T | null>;
+    /** @inheritdoc */
+    list(options?: ListOptions<T>): Promise<T[]>;
+    /** @inheritdoc */
+    create(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    update(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    delete(key: string): Promise<void>;
+    /** @inheritdoc */
+    has(key: string): Promise<boolean>;
+    /** @inheritdoc */
+    count(): Promise<number>;
+    /** @inheritdoc */
+    clear(): Promise<void>;
+}
+/**
+ * Options for configuring `FileStorage`.
+ */
+interface FileStorageOptions {
+    /** Directory path where JSON files are stored */
+    directory: string;
+    /** File extension (default: `.json`) */
+    extension?: string;
+}
+/**
+ * File-based storage adapter that persists each item as a JSON file.
+ * Suitable for local applications, CLI tools, and development.
+ * Creates the storage directory if it doesn't exist.
+ *
+ * @typeParam T - The type of stored items (must be JSON-serializable)
+ *
+ * @example
+ * ```typescript
+ * const store = new FileStorage<ChatSession>({
+ *   directory: "./data/sessions",
+ * });
+ * await store.create("session-1", mySession);
+ * ```
+ */
+declare class FileStorage<T> implements IStorageAdapter<T> {
+    private readonly directory;
+    private readonly extension;
+    constructor(options: FileStorageOptions);
+    /** @inheritdoc */
+    get(key: string): Promise<T | null>;
+    /** @inheritdoc */
+    list(options?: ListOptions<T>): Promise<T[]>;
+    /** @inheritdoc */
+    create(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    update(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    delete(key: string): Promise<void>;
+    /** @inheritdoc */
+    has(key: string): Promise<boolean>;
+    /** @inheritdoc */
+    count(): Promise<number>;
+    /** @inheritdoc */
+    clear(): Promise<void>;
+    private keyToPath;
+    private ensureDirectory;
+    private readFile;
+    private writeFile;
+}
+
+export { FileStorage, type FileStorageOptions, type IStorageAdapter, InMemoryStorage, type ListOptions, StorageError, type StorageErrorCode };

package/dist/chat/storage.d.ts

@@ -0,0 +1,197 @@
+import { A as AgentSDKError } from '../errors-CmVvczxZ.js';
+import { E as ErrorCode } from '../errors-C-so0M4t.js';
+
+/**
+ * @witqq/agent-sdk/chat/storage
+ *
+ * Generic storage adapter layer with pluggable backends.
+ * Provides CRUD operations for any data type via `IStorageAdapter<T>`.
+ * Implementations: `InMemoryStorage` (Map-based) and `FileStorage` (JSON files).
+ */
+
+/**
+ * Error thrown by storage operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await store.get("missing-id");
+ * } catch (e) {
+ *   if (e instanceof StorageError && e.code === ErrorCode.STORAGE_NOT_FOUND) {
+ *     // handle missing item
+ *   }
+ * }
+ * ```
+ */
+declare class StorageError extends AgentSDKError {
+    /** Machine-readable error code from the unified ErrorCode enum */
+    readonly code: StorageErrorCode;
+    constructor(message: string, code: StorageErrorCode);
+}
+/** Storage-specific subset of ErrorCode */
+type StorageErrorCode = ErrorCode.STORAGE_NOT_FOUND | ErrorCode.STORAGE_DUPLICATE_KEY | ErrorCode.STORAGE_IO_ERROR | ErrorCode.STORAGE_SERIALIZATION_ERROR;
+/**
+ * Options for listing stored items.
+ *
+ * @typeParam T - The type of stored items
+ */
+interface ListOptions<T> {
+    /** Filter predicate — return `true` to include the item */
+    filter?: (item: T) => boolean;
+    /** Sort comparator — standard Array.sort semantics */
+    sort?: (a: T, b: T) => number;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Number of items to skip (for pagination) */
+    offset?: number;
+}
+/**
+ * Generic storage adapter for CRUD operations on any data type.
+ * Items are identified by a string key.
+ *
+ * @typeParam T - The type of stored items
+ *
+ * @example
+ * ```typescript
+ * const store: IStorageAdapter<{ name: string }> = new InMemoryStorage();
+ * await store.create("key1", { name: "Alice" });
+ * const item = await store.get("key1"); // { name: "Alice" }
+ * ```
+ */
+interface IStorageAdapter<T> {
+    /**
+     * Retrieve an item by key.
+     * @param key - Unique identifier
+     * @returns The item, or `null` if not found
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * List items with optional filtering, sorting, and pagination.
+     * @param options - Filter, sort, limit, offset options
+     * @returns Array of matching items
+     */
+    list(options?: ListOptions<T>): Promise<T[]>;
+    /**
+     * Create a new item. Throws `StorageError` with code `DUPLICATE_KEY` if key exists.
+     * @param key - Unique identifier
+     * @param item - Data to store
+     */
+    create(key: string, item: T): Promise<void>;
+    /**
+     * Update an existing item. Throws `StorageError` with code `NOT_FOUND` if key missing.
+     * @param key - Unique identifier
+     * @param item - Updated data
+     */
+    update(key: string, item: T): Promise<void>;
+    /**
+     * Delete an item by key. Throws `StorageError` with code `NOT_FOUND` if key missing.
+     * @param key - Unique identifier
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check whether a key exists.
+     * @param key - Unique identifier
+     * @returns `true` if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Return the number of stored items.
+     * @returns Count of items
+     */
+    count(): Promise<number>;
+    /**
+     * Remove all items from storage.
+     */
+    clear(): Promise<void>;
+    /**
+     * Release any resources held by this adapter (DB connections, file handles).
+     * Optional — adapters that don't hold resources need not implement this.
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * In-memory storage adapter backed by a `Map`.
+ * Suitable for development, testing, and short-lived processes.
+ * Data is lost when the process exits.
+ *
+ * @typeParam T - The type of stored items
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryStorage<{ name: string }>();
+ * await store.create("k1", { name: "Alice" });
+ * await store.create("k2", { name: "Bob" });
+ * const items = await store.list({ filter: i => i.name.startsWith("A") });
+ * // [{ name: "Alice" }]
+ * ```
+ */
+declare class InMemoryStorage<T> implements IStorageAdapter<T> {
+    private readonly data;
+    /** @inheritdoc */
+    get(key: string): Promise<T | null>;
+    /** @inheritdoc */
+    list(options?: ListOptions<T>): Promise<T[]>;
+    /** @inheritdoc */
+    create(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    update(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    delete(key: string): Promise<void>;
+    /** @inheritdoc */
+    has(key: string): Promise<boolean>;
+    /** @inheritdoc */
+    count(): Promise<number>;
+    /** @inheritdoc */
+    clear(): Promise<void>;
+}
+/**
+ * Options for configuring `FileStorage`.
+ */
+interface FileStorageOptions {
+    /** Directory path where JSON files are stored */
+    directory: string;
+    /** File extension (default: `.json`) */
+    extension?: string;
+}
+/**
+ * File-based storage adapter that persists each item as a JSON file.
+ * Suitable for local applications, CLI tools, and development.
+ * Creates the storage directory if it doesn't exist.
+ *
+ * @typeParam T - The type of stored items (must be JSON-serializable)
+ *
+ * @example
+ * ```typescript
+ * const store = new FileStorage<ChatSession>({
+ *   directory: "./data/sessions",
+ * });
+ * await store.create("session-1", mySession);
+ * ```
+ */
+declare class FileStorage<T> implements IStorageAdapter<T> {
+    private readonly directory;
+    private readonly extension;
+    constructor(options: FileStorageOptions);
+    /** @inheritdoc */
+    get(key: string): Promise<T | null>;
+    /** @inheritdoc */
+    list(options?: ListOptions<T>): Promise<T[]>;
+    /** @inheritdoc */
+    create(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    update(key: string, item: T): Promise<void>;
+    /** @inheritdoc */
+    delete(key: string): Promise<void>;
+    /** @inheritdoc */
+    has(key: string): Promise<boolean>;
+    /** @inheritdoc */
+    count(): Promise<number>;
+    /** @inheritdoc */
+    clear(): Promise<void>;
+    private keyToPath;
+    private ensureDirectory;
+    private readFile;
+    private writeFile;
+}
+
+export { FileStorage, type FileStorageOptions, type IStorageAdapter, InMemoryStorage, type ListOptions, StorageError, type StorageErrorCode };

package/dist/chat/storage.js

@@ -0,0 +1,245 @@
+import { existsSync, readdirSync, unlinkSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// src/chat/storage.ts
+
+// 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 */
+      );
+    }
+  }
+};
+
+export { FileStorage, InMemoryStorage, StorageError };
+//# sourceMappingURL=storage.js.map
+//# sourceMappingURL=storage.js.map

package/dist/chat/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/chat/storage.ts"],"names":[],"mappings":"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","file":"storage.js","sourcesContent":["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"]}