deepagents 1.7.0 → 1.7.1

package/dist/index.d.cts

@@ -346,119 +346,61 @@ interface SandboxDeleteOptions {
   sandboxId: string;
 }
 /**
- * Abstract interface for sandbox provider implementations.
+ * Common error codes shared across all sandbox provider implementations.
  *
- * Defines the lifecycle management interface for sandbox providers. Implementations
- * should integrate with their respective SDKs to provide standardized sandbox
- * lifecycle operations (list, getOrCreate, delete).
- *
- * This interface separates lifecycle management from sandbox execution:
- * - `SandboxProvider` handles lifecycle (list, create, delete)
- * - `SandboxBackendProtocol` handles execution (execute, file operations)
- *
- * @typeParam MetadataT - Type of the metadata field in sandbox listings.
- *   Providers can define their own interface for type-safe metadata access.
+ * These represent the core error conditions that any sandbox provider may encounter.
+ * Provider-specific error codes should extend this type with additional codes.
  *
  * @example
  * ```typescript
- * interface MyMetadata {
- *   status: "running" | "stopped";
- *   template: string;
- * }
+ * // Provider-specific error code type extending the common codes:
+ * type MySandboxErrorCode = SandboxErrorCode | "CUSTOM_ERROR";
+ * ```
+ */
+type SandboxErrorCode = /** Sandbox has not been initialized - call initialize() first */"NOT_INITIALIZED" /** Sandbox is already initialized - cannot initialize twice */ | "ALREADY_INITIALIZED" /** Command execution timed out */ | "COMMAND_TIMEOUT" /** Command execution failed */ | "COMMAND_FAILED" /** File operation (read/write) failed */ | "FILE_OPERATION_FAILED";
+declare const SANDBOX_ERROR_SYMBOL: unique symbol;
+/**
+ * Custom error class for sandbox operations.
  *
- * class MySandboxProvider implements SandboxProvider<MyMetadata> {
- *   async list(options?: SandboxListOptions): Promise<SandboxListResponse<MyMetadata>> {
- *     // Query provider API
- *     return { items: [...], cursor: null };
- *   }
+ * @param message - Human-readable error description
+ * @param code - Structured error code for programmatic handling
+ * @returns SandboxError with message and code
  *
- *   async getOrCreate(options?: SandboxGetOrCreateOptions): Promise<SandboxBackendProtocol> {
- *     if (options?.sandboxId) {
- *       return this.get(options.sandboxId);
+ * @example
+ * ```typescript
+ * try {
+ *   await sandbox.execute("some command");
+ * } catch (error) {
+ *   if (error instanceof SandboxError) {
+ *     switch (error.code) {
+ *       case "NOT_INITIALIZED":
+ *         await sandbox.initialize();
+ *         break;
+ *       case "COMMAND_TIMEOUT":
+ *         console.error("Command took too long");
+ *         break;
+ *       default:
+ *         throw error;
  *     }
- *     return this.create();
- *   }
- *
- *   async delete(options: SandboxDeleteOptions): Promise<void> {
- *     // Idempotent - no error if already deleted
- *     await this.client.delete(options.sandboxId);
  *   }
  * }
- *
- * // Usage
- * const provider = new MySandboxProvider();
- * const sandbox = await provider.getOrCreate();
- * const result = await sandbox.execute("echo hello");
- * await provider.delete({ sandboxId: sandbox.id });
  * ```
  */
-interface SandboxProvider<MetadataT = Record<string, unknown>> {
+declare class SandboxError extends Error {
+  readonly code: string;
+  readonly cause?: Error | undefined;
+  /** Symbol for identifying sandbox error instances */
+  [SANDBOX_ERROR_SYMBOL]: true;
+  /** Error name for instanceof checks and logging */
+  readonly name: string;
   /**
-   * List available sandboxes with optional pagination.
-   *
-   * @param options - Optional list options including cursor for pagination
-   * @returns Paginated list of sandbox metadata
+   * Creates a new SandboxError.
    *
-   * @example
-   * ```typescript
-   * // First page
-   * const response = await provider.list();
-   * for (const sandbox of response.items) {
-   *   console.log(sandbox.sandboxId);
-   * }
-   *
-   * // Next page if available
-   * if (response.cursor) {
-   *   const nextPage = await provider.list({ cursor: response.cursor });
-   * }
-   * ```
-   */
-  list(options?: SandboxListOptions): Promise<SandboxListResponse<MetadataT>>;
-  /**
-   * Get an existing sandbox or create a new one.
-   *
-   * If sandboxId is provided, retrieves the existing sandbox. If the sandbox
-   * doesn't exist, throws an error (does NOT create a new one).
-   *
-   * If sandboxId is undefined, creates a new sandbox instance.
-   *
-   * @param options - Optional options including sandboxId to retrieve
-   * @returns A sandbox instance implementing SandboxBackendProtocol
-   * @throws Error if sandboxId is provided but the sandbox doesn't exist
-   *
-   * @example
-   * ```typescript
-   * // Create a new sandbox
-   * const sandbox = await provider.getOrCreate();
-   * console.log(sandbox.id); // "sb_new123"
-   *
-   * // Reconnect to existing sandbox
-   * const existing = await provider.getOrCreate({ sandboxId: "sb_new123" });
-   *
-   * // Use the sandbox
-   * const result = await sandbox.execute("node --version");
-   * ```
-   */
-  getOrCreate(options?: SandboxGetOrCreateOptions): Promise<SandboxBackendProtocol>;
-  /**
-   * Delete a sandbox instance.
-   *
-   * This permanently destroys the sandbox and all its associated data.
-   * The operation is idempotent - calling delete on a non-existent sandbox
-   * should succeed without raising an error.
-   *
-   * @param options - Options including the sandboxId to delete
-   *
-   * @example
-   * ```typescript
-   * // Simple deletion
-   * await provider.delete({ sandboxId: "sb_123" });
-   *
-   * // Safe to call multiple times (idempotent)
-   * await provider.delete({ sandboxId: "sb_123" }); // No error
-   * ```
+   * @param message - Human-readable error description
+   * @param code - Structured error code for programmatic handling
    */
-  delete(options: SandboxDeleteOptions): Promise<void>;
+  constructor(message: string, code: string, cause?: Error | undefined);
+  static isInstance(error: unknown): error is SandboxError;
 }
 /**
  * State and store container for backend initialization.
@@ -2196,5 +2138,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type SandboxProvider, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, TASK_SYSTEM_PROMPT, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, TASK_SYSTEM_PROMPT, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -346,119 +346,61 @@ interface SandboxDeleteOptions {
   sandboxId: string;
 }
 /**
- * Abstract interface for sandbox provider implementations.
+ * Common error codes shared across all sandbox provider implementations.
  *
- * Defines the lifecycle management interface for sandbox providers. Implementations
- * should integrate with their respective SDKs to provide standardized sandbox
- * lifecycle operations (list, getOrCreate, delete).
- *
- * This interface separates lifecycle management from sandbox execution:
- * - `SandboxProvider` handles lifecycle (list, create, delete)
- * - `SandboxBackendProtocol` handles execution (execute, file operations)
- *
- * @typeParam MetadataT - Type of the metadata field in sandbox listings.
- *   Providers can define their own interface for type-safe metadata access.
+ * These represent the core error conditions that any sandbox provider may encounter.
+ * Provider-specific error codes should extend this type with additional codes.
  *
  * @example
  * ```typescript
- * interface MyMetadata {
- *   status: "running" | "stopped";
- *   template: string;
- * }
+ * // Provider-specific error code type extending the common codes:
+ * type MySandboxErrorCode = SandboxErrorCode | "CUSTOM_ERROR";
+ * ```
+ */
+type SandboxErrorCode = /** Sandbox has not been initialized - call initialize() first */"NOT_INITIALIZED" /** Sandbox is already initialized - cannot initialize twice */ | "ALREADY_INITIALIZED" /** Command execution timed out */ | "COMMAND_TIMEOUT" /** Command execution failed */ | "COMMAND_FAILED" /** File operation (read/write) failed */ | "FILE_OPERATION_FAILED";
+declare const SANDBOX_ERROR_SYMBOL: unique symbol;
+/**
+ * Custom error class for sandbox operations.
  *
- * class MySandboxProvider implements SandboxProvider<MyMetadata> {
- *   async list(options?: SandboxListOptions): Promise<SandboxListResponse<MyMetadata>> {
- *     // Query provider API
- *     return { items: [...], cursor: null };
- *   }
+ * @param message - Human-readable error description
+ * @param code - Structured error code for programmatic handling
+ * @returns SandboxError with message and code
  *
- *   async getOrCreate(options?: SandboxGetOrCreateOptions): Promise<SandboxBackendProtocol> {
- *     if (options?.sandboxId) {
- *       return this.get(options.sandboxId);
+ * @example
+ * ```typescript
+ * try {
+ *   await sandbox.execute("some command");
+ * } catch (error) {
+ *   if (error instanceof SandboxError) {
+ *     switch (error.code) {
+ *       case "NOT_INITIALIZED":
+ *         await sandbox.initialize();
+ *         break;
+ *       case "COMMAND_TIMEOUT":
+ *         console.error("Command took too long");
+ *         break;
+ *       default:
+ *         throw error;
  *     }
- *     return this.create();
- *   }
- *
- *   async delete(options: SandboxDeleteOptions): Promise<void> {
- *     // Idempotent - no error if already deleted
- *     await this.client.delete(options.sandboxId);
  *   }
  * }
- *
- * // Usage
- * const provider = new MySandboxProvider();
- * const sandbox = await provider.getOrCreate();
- * const result = await sandbox.execute("echo hello");
- * await provider.delete({ sandboxId: sandbox.id });
  * ```
  */
-interface SandboxProvider<MetadataT = Record<string, unknown>> {
+declare class SandboxError extends Error {
+  readonly code: string;
+  readonly cause?: Error | undefined;
+  /** Symbol for identifying sandbox error instances */
+  [SANDBOX_ERROR_SYMBOL]: true;
+  /** Error name for instanceof checks and logging */
+  readonly name: string;
   /**
-   * List available sandboxes with optional pagination.
-   *
-   * @param options - Optional list options including cursor for pagination
-   * @returns Paginated list of sandbox metadata
+   * Creates a new SandboxError.
    *
-   * @example
-   * ```typescript
-   * // First page
-   * const response = await provider.list();
-   * for (const sandbox of response.items) {
-   *   console.log(sandbox.sandboxId);
-   * }
-   *
-   * // Next page if available
-   * if (response.cursor) {
-   *   const nextPage = await provider.list({ cursor: response.cursor });
-   * }
-   * ```
-   */
-  list(options?: SandboxListOptions): Promise<SandboxListResponse<MetadataT>>;
-  /**
-   * Get an existing sandbox or create a new one.
-   *
-   * If sandboxId is provided, retrieves the existing sandbox. If the sandbox
-   * doesn't exist, throws an error (does NOT create a new one).
-   *
-   * If sandboxId is undefined, creates a new sandbox instance.
-   *
-   * @param options - Optional options including sandboxId to retrieve
-   * @returns A sandbox instance implementing SandboxBackendProtocol
-   * @throws Error if sandboxId is provided but the sandbox doesn't exist
-   *
-   * @example
-   * ```typescript
-   * // Create a new sandbox
-   * const sandbox = await provider.getOrCreate();
-   * console.log(sandbox.id); // "sb_new123"
-   *
-   * // Reconnect to existing sandbox
-   * const existing = await provider.getOrCreate({ sandboxId: "sb_new123" });
-   *
-   * // Use the sandbox
-   * const result = await sandbox.execute("node --version");
-   * ```
-   */
-  getOrCreate(options?: SandboxGetOrCreateOptions): Promise<SandboxBackendProtocol>;
-  /**
-   * Delete a sandbox instance.
-   *
-   * This permanently destroys the sandbox and all its associated data.
-   * The operation is idempotent - calling delete on a non-existent sandbox
-   * should succeed without raising an error.
-   *
-   * @param options - Options including the sandboxId to delete
-   *
-   * @example
-   * ```typescript
-   * // Simple deletion
-   * await provider.delete({ sandboxId: "sb_123" });
-   *
-   * // Safe to call multiple times (idempotent)
-   * await provider.delete({ sandboxId: "sb_123" }); // No error
-   * ```
+   * @param message - Human-readable error description
+   * @param code - Structured error code for programmatic handling
    */
-  delete(options: SandboxDeleteOptions): Promise<void>;
+  constructor(message: string, code: string, cause?: Error | undefined);
+  static isInstance(error: unknown): error is SandboxError;
 }
 /**
  * State and store container for backend initialization.
@@ -2196,5 +2138,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type SandboxProvider, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, TASK_SYSTEM_PROMPT, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, TASK_SYSTEM_PROMPT, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -26,6 +26,55 @@ import os from "node:os";
 function isSandboxBackend(backend) {
 	return typeof backend.execute === "function" && typeof backend.id === "string";
 }
+const SANDBOX_ERROR_SYMBOL = Symbol.for("sandbox.error");
+/**
+* Custom error class for sandbox operations.
+*
+* @param message - Human-readable error description
+* @param code - Structured error code for programmatic handling
+* @returns SandboxError with message and code
+*
+* @example
+* ```typescript
+* try {
+*   await sandbox.execute("some command");
+* } catch (error) {
+*   if (error instanceof SandboxError) {
+*     switch (error.code) {
+*       case "NOT_INITIALIZED":
+*         await sandbox.initialize();
+*         break;
+*       case "COMMAND_TIMEOUT":
+*         console.error("Command took too long");
+*         break;
+*       default:
+*         throw error;
+*     }
+*   }
+* }
+* ```
+*/
+var SandboxError = class SandboxError extends Error {
+	/** Symbol for identifying sandbox error instances */
+	[SANDBOX_ERROR_SYMBOL] = true;
+	/** Error name for instanceof checks and logging */
+	name = "SandboxError";
+	/**
+	* Creates a new SandboxError.
+	*
+	* @param message - Human-readable error description
+	* @param code - Structured error code for programmatic handling
+	*/
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, SandboxError.prototype);
+	}
+	static isInstance(error) {
+		return typeof error === "object" && error !== null && error[SANDBOX_ERROR_SYMBOL] === true;
+	}
+};
 
 //#endregion
 //#region src/backends/utils.ts
@@ -4274,5 +4323,5 @@ function listSkills(options) {
 }
 
 //#endregion
-export { BaseSandbox, CompositeBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { BaseSandbox, CompositeBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.js.map