@evolvingmachines/sdk 0.0.21 → 0.0.23

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import * as zod from 'zod';
 import { z } from 'zod';
 import { EventEmitter } from 'events';
-export { E2BProvider } from '@evolvingmachines/e2b';
-export { DaytonaProvider } from '@evolvingmachines/daytona';
-export { ModalProvider } from '@evolvingmachines/modal';
+export { E2BProvider, createE2BProvider } from '@evolvingmachines/e2b';
+export { DaytonaProvider, createDaytonaProvider } from '@evolvingmachines/daytona';
+export { ModalProvider, createModalProvider } from '@evolvingmachines/modal';
 
 /**
  * ACP-inspired output types for unified agent event streaming.
@@ -364,13 +364,15 @@ interface SandboxProvider {
     connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
 }
 /** Supported agent types (headless CLI agents only, no ACP) */
-type AgentType = "claude" | "codex" | "gemini" | "qwen";
+type AgentType = "claude" | "codex" | "gemini" | "qwen" | "kimi" | "opencode";
 /** Agent type constants for use in code */
 declare const AGENT_TYPES: {
     readonly CLAUDE: "claude";
     readonly CODEX: "codex";
     readonly GEMINI: "gemini";
     readonly QWEN: "qwen";
+    readonly KIMI: "kimi";
+    readonly OPENCODE: "opencode";
 };
 /** Workspace mode determines folder structure and system prompt */
 type WorkspaceMode = "knowledge" | "swe";
@@ -532,6 +534,8 @@ interface AgentOptions {
      * Set via withComposio() - provides access to 1000+ tools
      */
     composio?: ComposioSetup;
+    /** Resolved storage configuration (set via Evolve.withStorage()) */
+    storage?: ResolvedStorageConfig;
 }
 /** Options for run() */
 interface RunOptions {
@@ -541,6 +545,10 @@ interface RunOptions {
     timeoutMs?: number;
     /** Run in background (returns immediately, process continues) */
     background?: boolean;
+    /** Restore from checkpoint ID or "latest" before running (requires .withStorage()) */
+    from?: string;
+    /** Optional comment for the auto-checkpoint created after this run */
+    checkpointComment?: string;
 }
 /** Options for executeCommand() */
 interface ExecuteCommandOptions {
@@ -582,6 +590,8 @@ interface AgentResponse {
     stdout: string;
     /** Standard error */
     stderr: string;
+    /** Checkpoint info if storage configured and run succeeded (undefined otherwise) */
+    checkpoint?: CheckpointInfo;
 }
 /** Result from getOutputFiles() with optional schema validation */
 interface OutputResult<T = unknown> {
@@ -666,6 +676,80 @@ interface ComposioSetup {
     /** Optional Composio configuration */
     config?: ComposioConfig;
 }
+/**
+ * Storage configuration for .withStorage()
+ *
+ * BYOK mode: provide url (e.g., "s3://my-bucket/prefix/")
+ * Gateway mode: omit url (uses Evolve-managed storage)
+ *
+ * @example
+ * // BYOK — user's own S3 bucket
+ * .withStorage({ url: "s3://my-bucket/agent-snapshots/" })
+ *
+ * // BYOK — Cloudflare R2
+ * .withStorage({ url: "s3://my-bucket/prefix/", endpoint: "https://acct.r2.cloudflarestorage.com" })
+ *
+ * // Gateway — Evolve-managed storage
+ * .withStorage()
+ */
+interface StorageConfig {
+    /** S3 URL: "s3://bucket/prefix" or "https://endpoint/bucket/prefix" */
+    url?: string;
+    /** Explicit bucket name (overrides URL parsing) */
+    bucket?: string;
+    /** Key prefix (overrides URL parsing) */
+    prefix?: string;
+    /** AWS region (default from env or us-east-1) */
+    region?: string;
+    /** Custom S3 endpoint (R2, MinIO, GCS) */
+    endpoint?: string;
+    /** Explicit credentials (default: AWS SDK credential chain) */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+/** Resolved storage configuration (internal) */
+interface ResolvedStorageConfig {
+    bucket: string;
+    prefix: string;
+    region: string;
+    endpoint?: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    mode: "byok" | "gateway";
+    gatewayUrl?: string;
+    gatewayApiKey?: string;
+}
+/**
+ * Checkpoint info returned after a successful run
+ *
+ * Pass `checkpoint.id` as `from` to restore into a fresh sandbox.
+ */
+interface CheckpointInfo {
+    /** Checkpoint ID — pass as `from` to restore */
+    id: string;
+    /** SHA-256 of tar.gz — integrity verification */
+    hash: string;
+    /** Session tag at checkpoint time — lineage tracking */
+    tag: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Archive size in bytes */
+    sizeBytes?: number;
+    /** Agent type that produced this checkpoint */
+    agentType?: string;
+    /** Model that produced this checkpoint */
+    model?: string;
+    /** Workspace mode used when checkpoint was created */
+    workspaceMode?: string;
+    /** Parent checkpoint ID — the checkpoint this was restored from (lineage tracking) */
+    parentId?: string;
+    /** User-provided label for this checkpoint */
+    comment?: string;
+}
 
 /**
  * Composio Auth Helpers
@@ -774,6 +858,8 @@ declare class Agent {
     private sandboxState;
     private agentState;
     private readonly skills?;
+    private readonly storage?;
+    private lastCheckpointId?;
     private readonly zodSchema?;
     private readonly jsonSchema?;
     private readonly schemaOptions?;
@@ -802,6 +888,9 @@ declare class Agent {
     private setupAgentAuth;
     /**
      * Setup workspace structure and files
+     *
+     * @param opts.skipSystemPrompt - When true, skip writing the system prompt file.
+     *   Used on restore from checkpoint: the tar already contains the correct file.
      */
     private setupWorkspace;
     /**
@@ -850,6 +939,16 @@ declare class Agent {
      * @param recursive - Include files in subdirectories (default: false)
      */
     getOutputFiles<T = unknown>(recursive?: boolean): Promise<OutputResult<T>>;
+    /**
+     * Create an explicit checkpoint of the current sandbox state.
+     *
+     * Requires an active sandbox (call run() first).
+     *
+     * @param options.comment - Optional label for this checkpoint
+     */
+    checkpoint(options?: {
+        comment?: string;
+    }): Promise<CheckpointInfo>;
     /**
      * Get current session (sandbox ID)
      */
@@ -1075,6 +1174,8 @@ interface EvolveConfig {
     observability?: Record<string, unknown>;
     /** Composio user ID and config */
     composio?: ComposioSetup;
+    /** Storage configuration for checkpointing */
+    storage?: StorageConfig;
 }
 /**
  * Evolve orchestrator with builder pattern
@@ -1218,6 +1319,23 @@ declare class Evolve extends EventEmitter {
      * })
      */
     withComposio(userId: string, config?: ComposioConfig): this;
+    /**
+     * Configure storage for checkpoint persistence
+     *
+     * BYOK mode: provide URL to your S3-compatible bucket.
+     * Gateway mode: omit config (uses Evolve-managed storage, requires EVOLVE_API_KEY).
+     *
+     * @example
+     * // BYOK — user's own S3 bucket
+     * kit.withStorage({ url: "s3://my-bucket/agent-snapshots/" })
+     *
+     * // BYOK — Cloudflare R2
+     * kit.withStorage({ url: "s3://my-bucket/prefix/", endpoint: "https://acct.r2.cloudflarestorage.com" })
+     *
+     * // Gateway — Evolve-managed storage
+     * kit.withStorage()
+     */
+    withStorage(config?: StorageConfig): this;
     /**
      * Static helpers for Composio auth management
      *
@@ -1255,11 +1373,15 @@ declare class Evolve extends EventEmitter {
     private emitLifecycleFromStatus;
     /**
      * Run agent with prompt
+     *
+     * @param from - Restore from checkpoint ID before running (requires .withStorage())
      */
-    run({ prompt, timeoutMs, background, }: {
+    run({ prompt, timeoutMs, background, from, checkpointComment, }: {
         prompt: string;
         timeoutMs?: number;
         background?: boolean;
+        from?: string;
+        checkpointComment?: string;
     }): Promise<AgentResponse>;
     /**
      * Execute arbitrary command in sandbox
@@ -1286,6 +1408,28 @@ declare class Evolve extends EventEmitter {
      * @param recursive - Include files in subdirectories (default: false)
      */
     getOutputFiles<T = unknown>(recursive?: boolean): Promise<OutputResult<T>>;
+    /**
+     * Create an explicit checkpoint of the current sandbox state.
+     *
+     * Requires a prior run() call (needs an active sandbox to snapshot).
+     *
+     * @param options.comment - Optional label for this checkpoint
+     */
+    checkpoint(options?: {
+        comment?: string;
+    }): Promise<CheckpointInfo>;
+    /**
+     * List checkpoints (requires .withStorage()).
+     *
+     * Does not require an agent or sandbox — only storage configuration.
+     *
+     * @param options.limit - Maximum number of checkpoints to return
+     * @param options.tag - Filter by session tag (gateway mode: server-side, BYOK: post-filter)
+     */
+    listCheckpoints(options?: {
+        limit?: number;
+        tag?: string;
+    }): Promise<CheckpointInfo[]>;
     /**
      * Get current session (sandbox ID)
      */
@@ -2239,6 +2383,15 @@ interface AgentRegistryEntry {
     availableBetas?: Record<string, string>;
     /** Skills configuration for this agent */
     skillsConfig: SkillsConfig;
+    /** Multi-provider env mapping: model prefix → keyEnv (for CLIs like OpenCode that resolve provider from model string) */
+    providerEnvMap?: Record<string, {
+        keyEnv: string;
+    }>;
+    /** Env var for inline config (e.g., OPENCODE_CONFIG_CONTENT) — used in gateway mode to set provider base URLs */
+    gatewayConfigEnv?: string;
+    /** Additional directories to include in checkpoint tar (beyond mcpConfig.settingsDir).
+     *  Used for agents like OpenCode that spread state across XDG directories. */
+    checkpointDirs?: string[];
 }
 /**
  * Registry of all supported agents.
@@ -2323,6 +2476,7 @@ declare function writeCodexMcpConfig(sandbox: SandboxInstance, servers: Record<s
  * - Codex: TOML to ~/.codex/config.toml
  * - Gemini: JSON to ~/.gemini/settings.json
  * - Qwen: JSON to ~/.qwen/settings.json
+ * - OpenCode: JSON to ${workingDir}/opencode.json (mcp key)
  */
 declare function writeMcpConfig(agentType: AgentType, sandbox: SandboxInstance, workingDir: string, servers: Record<string, McpServerConfig>): Promise<void>;
 
@@ -2462,4 +2616,38 @@ declare function readLocalDir(localPath: string, recursive?: boolean): FileMap;
  */
 declare function saveLocalDir(localPath: string, files: FileMap): void;
 
-export { AGENT_REGISTRY, AGENT_TYPES, Agent, type AgentConfig, type AgentOptions, type AgentOverride, type AgentParser, type AgentRegistryEntry, type AgentResponse, type AgentRuntimeState, type AgentType, type BaseMeta, type BestOfConfig, type BestOfParams, type BestOfResult, type CandidateCompleteEvent, type ComposioAuthResult, type ComposioConfig, type ComposioConnectionStatus, type ComposioSetup, type EmitOption, type EventHandler, type EventName, Evolve, type EvolveConfig, type EvolveEvents, type ExecuteCommandOptions, type FileMap, type FilterConfig, type FilterParams, type IndexedMeta, type ItemInput, type ItemRetryEvent, JUDGE_PROMPT, type JsonSchema, type JudgeCompleteEvent, type JudgeDecision, type JudgeMeta, type LifecycleEvent, type LifecycleReason, type MapConfig, type MapParams, type McpConfigInfo, type McpServerConfig, type ModelInfo, type OnCandidateCompleteCallback, type OnItemRetryCallback, type OnJudgeCompleteCallback, type OnVerifierCompleteCallback, type OnWorkerCompleteCallback, type OperationType, type OutputEvent, type OutputResult, Pipeline, type PipelineContext, type PipelineEventMap, type PipelineEvents, type PipelineResult, type ProcessInfo, type Prompt, type PromptFn, RETRY_FEEDBACK_PROMPT, type ReasoningEffort, type ReduceConfig, type ReduceMeta, type ReduceParams, type ReduceResult, type RetryConfig, type RunOptions, SCHEMA_PROMPT, SWARM_RESULT_BRAND, SYSTEM_PROMPT, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxCreateOptions, type SandboxFiles, type SandboxInstance, type SandboxLifecycleState, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type SchemaValidationOptions, Semaphore, type SessionStatus, type SkillName, type SkillsConfig, type StepCompleteEvent, type StepErrorEvent, type StepEvent, type StepResult, type StepStartEvent, type StreamCallbacks, Swarm, type SwarmConfig, type SwarmResult, SwarmResultList, TerminalPipeline, type ToolsFilter, VALIDATION_PRESETS, VERIFY_PROMPT, type ValidationMode, type VerifierCompleteEvent, type VerifyConfig, type VerifyDecision, type VerifyInfo, type VerifyMeta, WORKSPACE_PROMPT, WORKSPACE_SWE_PROMPT, type WorkerCompleteEvent, type WorkspaceMode, applyTemplate, buildWorkerSystemPrompt, createAgentParser, createClaudeParser, createCodexParser, createGeminiParser, executeWithRetry, expandPath, getAgentConfig, getMcpSettingsDir, getMcpSettingsPath, isValidAgentType, isZodSchema, jsonSchemaToString, parseNdjsonLine, parseNdjsonOutput, parseQwenOutput, readLocalDir, saveLocalDir, writeClaudeMcpConfig, writeCodexMcpConfig, writeGeminiMcpConfig, writeMcpConfig, writeQwenMcpConfig, zodSchemaToJson };
+/**
+ * Storage & Checkpointing Module
+ *
+ * Provides durable persistence for agent workspaces beyond sandbox lifetime.
+ * Supports BYOK (user's S3 bucket) and Gateway (Evolve-managed) modes.
+ *
+ * Evidence: storage-checkpointing plan v2.2
+ */
+
+/**
+ * Resolve storage configuration from user input.
+ *
+ * BYOK mode: URL provided → parse into bucket/prefix, use S3 client directly
+ * Gateway mode: no URL → use dashboard API endpoints
+ */
+declare function resolveStorageConfig(config: StorageConfig | undefined, isGateway: boolean, gatewayUrl?: string, gatewayApiKey?: string): ResolvedStorageConfig;
+/**
+ * List checkpoints (standalone — no Evolve instance needed).
+ *
+ * BYOK mode: reads directly from S3.
+ * Gateway mode: reads EVOLVE_API_KEY from env, calls dashboard API.
+ *
+ * @example
+ * // BYOK
+ * const all = await listCheckpoints({ url: "s3://my-bucket/project/" });
+ *
+ * // Gateway
+ * const all = await listCheckpoints({});
+ */
+declare function listCheckpoints(config: StorageConfig, options?: {
+    limit?: number;
+    tag?: string;
+}): Promise<CheckpointInfo[]>;
+
+export { AGENT_REGISTRY, AGENT_TYPES, Agent, type AgentConfig, type AgentOptions, type AgentOverride, type AgentParser, type AgentRegistryEntry, type AgentResponse, type AgentRuntimeState, type AgentType, type BaseMeta, type BestOfConfig, type BestOfParams, type BestOfResult, type CandidateCompleteEvent, type CheckpointInfo, type ComposioAuthResult, type ComposioConfig, type ComposioConnectionStatus, type ComposioSetup, type EmitOption, type EventHandler, type EventName, Evolve, type EvolveConfig, type EvolveEvents, type ExecuteCommandOptions, type FileMap, type FilterConfig, type FilterParams, type IndexedMeta, type ItemInput, type ItemRetryEvent, JUDGE_PROMPT, type JsonSchema, type JudgeCompleteEvent, type JudgeDecision, type JudgeMeta, type LifecycleEvent, type LifecycleReason, type MapConfig, type MapParams, type McpConfigInfo, type McpServerConfig, type ModelInfo, type OnCandidateCompleteCallback, type OnItemRetryCallback, type OnJudgeCompleteCallback, type OnVerifierCompleteCallback, type OnWorkerCompleteCallback, type OperationType, type OutputEvent, type OutputResult, Pipeline, type PipelineContext, type PipelineEventMap, type PipelineEvents, type PipelineResult, type ProcessInfo, type Prompt, type PromptFn, RETRY_FEEDBACK_PROMPT, type ReasoningEffort, type ReduceConfig, type ReduceMeta, type ReduceParams, type ReduceResult, type ResolvedStorageConfig, type RetryConfig, type RunOptions, SCHEMA_PROMPT, SWARM_RESULT_BRAND, SYSTEM_PROMPT, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxCreateOptions, type SandboxFiles, type SandboxInstance, type SandboxLifecycleState, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type SchemaValidationOptions, Semaphore, type SessionStatus, type SkillName, type SkillsConfig, type StepCompleteEvent, type StepErrorEvent, type StepEvent, type StepResult, type StepStartEvent, type StorageConfig, type StreamCallbacks, Swarm, type SwarmConfig, type SwarmResult, SwarmResultList, TerminalPipeline, type ToolsFilter, VALIDATION_PRESETS, VERIFY_PROMPT, type ValidationMode, type VerifierCompleteEvent, type VerifyConfig, type VerifyDecision, type VerifyInfo, type VerifyMeta, WORKSPACE_PROMPT, WORKSPACE_SWE_PROMPT, type WorkerCompleteEvent, type WorkspaceMode, applyTemplate, buildWorkerSystemPrompt, createAgentParser, createClaudeParser, createCodexParser, createGeminiParser, executeWithRetry, expandPath, getAgentConfig, getMcpSettingsDir, getMcpSettingsPath, isValidAgentType, isZodSchema, jsonSchemaToString, listCheckpoints, parseNdjsonLine, parseNdjsonOutput, parseQwenOutput, readLocalDir, resolveStorageConfig, saveLocalDir, writeClaudeMcpConfig, writeCodexMcpConfig, writeGeminiMcpConfig, writeMcpConfig, writeQwenMcpConfig, zodSchemaToJson };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as zod from 'zod';
 import { z } from 'zod';
 import { EventEmitter } from 'events';
-export { E2BProvider } from '@evolvingmachines/e2b';
-export { DaytonaProvider } from '@evolvingmachines/daytona';
-export { ModalProvider } from '@evolvingmachines/modal';
+export { E2BProvider, createE2BProvider } from '@evolvingmachines/e2b';
+export { DaytonaProvider, createDaytonaProvider } from '@evolvingmachines/daytona';
+export { ModalProvider, createModalProvider } from '@evolvingmachines/modal';
 
 /**
  * ACP-inspired output types for unified agent event streaming.
@@ -364,13 +364,15 @@ interface SandboxProvider {
     connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
 }
 /** Supported agent types (headless CLI agents only, no ACP) */
-type AgentType = "claude" | "codex" | "gemini" | "qwen";
+type AgentType = "claude" | "codex" | "gemini" | "qwen" | "kimi" | "opencode";
 /** Agent type constants for use in code */
 declare const AGENT_TYPES: {
     readonly CLAUDE: "claude";
     readonly CODEX: "codex";
     readonly GEMINI: "gemini";
     readonly QWEN: "qwen";
+    readonly KIMI: "kimi";
+    readonly OPENCODE: "opencode";
 };
 /** Workspace mode determines folder structure and system prompt */
 type WorkspaceMode = "knowledge" | "swe";
@@ -532,6 +534,8 @@ interface AgentOptions {
      * Set via withComposio() - provides access to 1000+ tools
      */
     composio?: ComposioSetup;
+    /** Resolved storage configuration (set via Evolve.withStorage()) */
+    storage?: ResolvedStorageConfig;
 }
 /** Options for run() */
 interface RunOptions {
@@ -541,6 +545,10 @@ interface RunOptions {
     timeoutMs?: number;
     /** Run in background (returns immediately, process continues) */
     background?: boolean;
+    /** Restore from checkpoint ID or "latest" before running (requires .withStorage()) */
+    from?: string;
+    /** Optional comment for the auto-checkpoint created after this run */
+    checkpointComment?: string;
 }
 /** Options for executeCommand() */
 interface ExecuteCommandOptions {
@@ -582,6 +590,8 @@ interface AgentResponse {
     stdout: string;
     /** Standard error */
     stderr: string;
+    /** Checkpoint info if storage configured and run succeeded (undefined otherwise) */
+    checkpoint?: CheckpointInfo;
 }
 /** Result from getOutputFiles() with optional schema validation */
 interface OutputResult<T = unknown> {
@@ -666,6 +676,80 @@ interface ComposioSetup {
     /** Optional Composio configuration */
     config?: ComposioConfig;
 }
+/**
+ * Storage configuration for .withStorage()
+ *
+ * BYOK mode: provide url (e.g., "s3://my-bucket/prefix/")
+ * Gateway mode: omit url (uses Evolve-managed storage)
+ *
+ * @example
+ * // BYOK — user's own S3 bucket
+ * .withStorage({ url: "s3://my-bucket/agent-snapshots/" })
+ *
+ * // BYOK — Cloudflare R2
+ * .withStorage({ url: "s3://my-bucket/prefix/", endpoint: "https://acct.r2.cloudflarestorage.com" })
+ *
+ * // Gateway — Evolve-managed storage
+ * .withStorage()
+ */
+interface StorageConfig {
+    /** S3 URL: "s3://bucket/prefix" or "https://endpoint/bucket/prefix" */
+    url?: string;
+    /** Explicit bucket name (overrides URL parsing) */
+    bucket?: string;
+    /** Key prefix (overrides URL parsing) */
+    prefix?: string;
+    /** AWS region (default from env or us-east-1) */
+    region?: string;
+    /** Custom S3 endpoint (R2, MinIO, GCS) */
+    endpoint?: string;
+    /** Explicit credentials (default: AWS SDK credential chain) */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+/** Resolved storage configuration (internal) */
+interface ResolvedStorageConfig {
+    bucket: string;
+    prefix: string;
+    region: string;
+    endpoint?: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    mode: "byok" | "gateway";
+    gatewayUrl?: string;
+    gatewayApiKey?: string;
+}
+/**
+ * Checkpoint info returned after a successful run
+ *
+ * Pass `checkpoint.id` as `from` to restore into a fresh sandbox.
+ */
+interface CheckpointInfo {
+    /** Checkpoint ID — pass as `from` to restore */
+    id: string;
+    /** SHA-256 of tar.gz — integrity verification */
+    hash: string;
+    /** Session tag at checkpoint time — lineage tracking */
+    tag: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Archive size in bytes */
+    sizeBytes?: number;
+    /** Agent type that produced this checkpoint */
+    agentType?: string;
+    /** Model that produced this checkpoint */
+    model?: string;
+    /** Workspace mode used when checkpoint was created */
+    workspaceMode?: string;
+    /** Parent checkpoint ID — the checkpoint this was restored from (lineage tracking) */
+    parentId?: string;
+    /** User-provided label for this checkpoint */
+    comment?: string;
+}
 
 /**
  * Composio Auth Helpers
@@ -774,6 +858,8 @@ declare class Agent {
     private sandboxState;
     private agentState;
     private readonly skills?;
+    private readonly storage?;
+    private lastCheckpointId?;
     private readonly zodSchema?;
     private readonly jsonSchema?;
     private readonly schemaOptions?;
@@ -802,6 +888,9 @@ declare class Agent {
     private setupAgentAuth;
     /**
      * Setup workspace structure and files
+     *
+     * @param opts.skipSystemPrompt - When true, skip writing the system prompt file.
+     *   Used on restore from checkpoint: the tar already contains the correct file.
      */
     private setupWorkspace;
     /**
@@ -850,6 +939,16 @@ declare class Agent {
      * @param recursive - Include files in subdirectories (default: false)
      */
     getOutputFiles<T = unknown>(recursive?: boolean): Promise<OutputResult<T>>;
+    /**
+     * Create an explicit checkpoint of the current sandbox state.
+     *
+     * Requires an active sandbox (call run() first).
+     *
+     * @param options.comment - Optional label for this checkpoint
+     */
+    checkpoint(options?: {
+        comment?: string;
+    }): Promise<CheckpointInfo>;
     /**
      * Get current session (sandbox ID)
      */
@@ -1075,6 +1174,8 @@ interface EvolveConfig {
     observability?: Record<string, unknown>;
     /** Composio user ID and config */
     composio?: ComposioSetup;
+    /** Storage configuration for checkpointing */
+    storage?: StorageConfig;
 }
 /**
  * Evolve orchestrator with builder pattern
@@ -1218,6 +1319,23 @@ declare class Evolve extends EventEmitter {
      * })
      */
     withComposio(userId: string, config?: ComposioConfig): this;
+    /**
+     * Configure storage for checkpoint persistence
+     *
+     * BYOK mode: provide URL to your S3-compatible bucket.
+     * Gateway mode: omit config (uses Evolve-managed storage, requires EVOLVE_API_KEY).
+     *
+     * @example
+     * // BYOK — user's own S3 bucket
+     * kit.withStorage({ url: "s3://my-bucket/agent-snapshots/" })
+     *
+     * // BYOK — Cloudflare R2
+     * kit.withStorage({ url: "s3://my-bucket/prefix/", endpoint: "https://acct.r2.cloudflarestorage.com" })
+     *
+     * // Gateway — Evolve-managed storage
+     * kit.withStorage()
+     */
+    withStorage(config?: StorageConfig): this;
     /**
      * Static helpers for Composio auth management
      *
@@ -1255,11 +1373,15 @@ declare class Evolve extends EventEmitter {
     private emitLifecycleFromStatus;
     /**
      * Run agent with prompt
+     *
+     * @param from - Restore from checkpoint ID before running (requires .withStorage())
      */
-    run({ prompt, timeoutMs, background, }: {
+    run({ prompt, timeoutMs, background, from, checkpointComment, }: {
         prompt: string;
         timeoutMs?: number;
         background?: boolean;
+        from?: string;
+        checkpointComment?: string;
     }): Promise<AgentResponse>;
     /**
      * Execute arbitrary command in sandbox
@@ -1286,6 +1408,28 @@ declare class Evolve extends EventEmitter {
      * @param recursive - Include files in subdirectories (default: false)
      */
     getOutputFiles<T = unknown>(recursive?: boolean): Promise<OutputResult<T>>;
+    /**
+     * Create an explicit checkpoint of the current sandbox state.
+     *
+     * Requires a prior run() call (needs an active sandbox to snapshot).
+     *
+     * @param options.comment - Optional label for this checkpoint
+     */
+    checkpoint(options?: {
+        comment?: string;
+    }): Promise<CheckpointInfo>;
+    /**
+     * List checkpoints (requires .withStorage()).
+     *
+     * Does not require an agent or sandbox — only storage configuration.
+     *
+     * @param options.limit - Maximum number of checkpoints to return
+     * @param options.tag - Filter by session tag (gateway mode: server-side, BYOK: post-filter)
+     */
+    listCheckpoints(options?: {
+        limit?: number;
+        tag?: string;
+    }): Promise<CheckpointInfo[]>;
     /**
      * Get current session (sandbox ID)
      */
@@ -2239,6 +2383,15 @@ interface AgentRegistryEntry {
     availableBetas?: Record<string, string>;
     /** Skills configuration for this agent */
     skillsConfig: SkillsConfig;
+    /** Multi-provider env mapping: model prefix → keyEnv (for CLIs like OpenCode that resolve provider from model string) */
+    providerEnvMap?: Record<string, {
+        keyEnv: string;
+    }>;
+    /** Env var for inline config (e.g., OPENCODE_CONFIG_CONTENT) — used in gateway mode to set provider base URLs */
+    gatewayConfigEnv?: string;
+    /** Additional directories to include in checkpoint tar (beyond mcpConfig.settingsDir).
+     *  Used for agents like OpenCode that spread state across XDG directories. */
+    checkpointDirs?: string[];
 }
 /**
  * Registry of all supported agents.
@@ -2323,6 +2476,7 @@ declare function writeCodexMcpConfig(sandbox: SandboxInstance, servers: Record<s
  * - Codex: TOML to ~/.codex/config.toml
  * - Gemini: JSON to ~/.gemini/settings.json
  * - Qwen: JSON to ~/.qwen/settings.json
+ * - OpenCode: JSON to ${workingDir}/opencode.json (mcp key)
  */
 declare function writeMcpConfig(agentType: AgentType, sandbox: SandboxInstance, workingDir: string, servers: Record<string, McpServerConfig>): Promise<void>;
 
@@ -2462,4 +2616,38 @@ declare function readLocalDir(localPath: string, recursive?: boolean): FileMap;
  */
 declare function saveLocalDir(localPath: string, files: FileMap): void;
 
-export { AGENT_REGISTRY, AGENT_TYPES, Agent, type AgentConfig, type AgentOptions, type AgentOverride, type AgentParser, type AgentRegistryEntry, type AgentResponse, type AgentRuntimeState, type AgentType, type BaseMeta, type BestOfConfig, type BestOfParams, type BestOfResult, type CandidateCompleteEvent, type ComposioAuthResult, type ComposioConfig, type ComposioConnectionStatus, type ComposioSetup, type EmitOption, type EventHandler, type EventName, Evolve, type EvolveConfig, type EvolveEvents, type ExecuteCommandOptions, type FileMap, type FilterConfig, type FilterParams, type IndexedMeta, type ItemInput, type ItemRetryEvent, JUDGE_PROMPT, type JsonSchema, type JudgeCompleteEvent, type JudgeDecision, type JudgeMeta, type LifecycleEvent, type LifecycleReason, type MapConfig, type MapParams, type McpConfigInfo, type McpServerConfig, type ModelInfo, type OnCandidateCompleteCallback, type OnItemRetryCallback, type OnJudgeCompleteCallback, type OnVerifierCompleteCallback, type OnWorkerCompleteCallback, type OperationType, type OutputEvent, type OutputResult, Pipeline, type PipelineContext, type PipelineEventMap, type PipelineEvents, type PipelineResult, type ProcessInfo, type Prompt, type PromptFn, RETRY_FEEDBACK_PROMPT, type ReasoningEffort, type ReduceConfig, type ReduceMeta, type ReduceParams, type ReduceResult, type RetryConfig, type RunOptions, SCHEMA_PROMPT, SWARM_RESULT_BRAND, SYSTEM_PROMPT, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxCreateOptions, type SandboxFiles, type SandboxInstance, type SandboxLifecycleState, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type SchemaValidationOptions, Semaphore, type SessionStatus, type SkillName, type SkillsConfig, type StepCompleteEvent, type StepErrorEvent, type StepEvent, type StepResult, type StepStartEvent, type StreamCallbacks, Swarm, type SwarmConfig, type SwarmResult, SwarmResultList, TerminalPipeline, type ToolsFilter, VALIDATION_PRESETS, VERIFY_PROMPT, type ValidationMode, type VerifierCompleteEvent, type VerifyConfig, type VerifyDecision, type VerifyInfo, type VerifyMeta, WORKSPACE_PROMPT, WORKSPACE_SWE_PROMPT, type WorkerCompleteEvent, type WorkspaceMode, applyTemplate, buildWorkerSystemPrompt, createAgentParser, createClaudeParser, createCodexParser, createGeminiParser, executeWithRetry, expandPath, getAgentConfig, getMcpSettingsDir, getMcpSettingsPath, isValidAgentType, isZodSchema, jsonSchemaToString, parseNdjsonLine, parseNdjsonOutput, parseQwenOutput, readLocalDir, saveLocalDir, writeClaudeMcpConfig, writeCodexMcpConfig, writeGeminiMcpConfig, writeMcpConfig, writeQwenMcpConfig, zodSchemaToJson };
+/**
+ * Storage & Checkpointing Module
+ *
+ * Provides durable persistence for agent workspaces beyond sandbox lifetime.
+ * Supports BYOK (user's S3 bucket) and Gateway (Evolve-managed) modes.
+ *
+ * Evidence: storage-checkpointing plan v2.2
+ */
+
+/**
+ * Resolve storage configuration from user input.
+ *
+ * BYOK mode: URL provided → parse into bucket/prefix, use S3 client directly
+ * Gateway mode: no URL → use dashboard API endpoints
+ */
+declare function resolveStorageConfig(config: StorageConfig | undefined, isGateway: boolean, gatewayUrl?: string, gatewayApiKey?: string): ResolvedStorageConfig;
+/**
+ * List checkpoints (standalone — no Evolve instance needed).
+ *
+ * BYOK mode: reads directly from S3.
+ * Gateway mode: reads EVOLVE_API_KEY from env, calls dashboard API.
+ *
+ * @example
+ * // BYOK
+ * const all = await listCheckpoints({ url: "s3://my-bucket/project/" });
+ *
+ * // Gateway
+ * const all = await listCheckpoints({});
+ */
+declare function listCheckpoints(config: StorageConfig, options?: {
+    limit?: number;
+    tag?: string;
+}): Promise<CheckpointInfo[]>;
+
+export { AGENT_REGISTRY, AGENT_TYPES, Agent, type AgentConfig, type AgentOptions, type AgentOverride, type AgentParser, type AgentRegistryEntry, type AgentResponse, type AgentRuntimeState, type AgentType, type BaseMeta, type BestOfConfig, type BestOfParams, type BestOfResult, type CandidateCompleteEvent, type CheckpointInfo, type ComposioAuthResult, type ComposioConfig, type ComposioConnectionStatus, type ComposioSetup, type EmitOption, type EventHandler, type EventName, Evolve, type EvolveConfig, type EvolveEvents, type ExecuteCommandOptions, type FileMap, type FilterConfig, type FilterParams, type IndexedMeta, type ItemInput, type ItemRetryEvent, JUDGE_PROMPT, type JsonSchema, type JudgeCompleteEvent, type JudgeDecision, type JudgeMeta, type LifecycleEvent, type LifecycleReason, type MapConfig, type MapParams, type McpConfigInfo, type McpServerConfig, type ModelInfo, type OnCandidateCompleteCallback, type OnItemRetryCallback, type OnJudgeCompleteCallback, type OnVerifierCompleteCallback, type OnWorkerCompleteCallback, type OperationType, type OutputEvent, type OutputResult, Pipeline, type PipelineContext, type PipelineEventMap, type PipelineEvents, type PipelineResult, type ProcessInfo, type Prompt, type PromptFn, RETRY_FEEDBACK_PROMPT, type ReasoningEffort, type ReduceConfig, type ReduceMeta, type ReduceParams, type ReduceResult, type ResolvedStorageConfig, type RetryConfig, type RunOptions, SCHEMA_PROMPT, SWARM_RESULT_BRAND, SYSTEM_PROMPT, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxCreateOptions, type SandboxFiles, type SandboxInstance, type SandboxLifecycleState, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type SchemaValidationOptions, Semaphore, type SessionStatus, type SkillName, type SkillsConfig, type StepCompleteEvent, type StepErrorEvent, type StepEvent, type StepResult, type StepStartEvent, type StorageConfig, type StreamCallbacks, Swarm, type SwarmConfig, type SwarmResult, SwarmResultList, TerminalPipeline, type ToolsFilter, VALIDATION_PRESETS, VERIFY_PROMPT, type ValidationMode, type VerifierCompleteEvent, type VerifyConfig, type VerifyDecision, type VerifyInfo, type VerifyMeta, WORKSPACE_PROMPT, WORKSPACE_SWE_PROMPT, type WorkerCompleteEvent, type WorkspaceMode, applyTemplate, buildWorkerSystemPrompt, createAgentParser, createClaudeParser, createCodexParser, createGeminiParser, executeWithRetry, expandPath, getAgentConfig, getMcpSettingsDir, getMcpSettingsPath, isValidAgentType, isZodSchema, jsonSchemaToString, listCheckpoints, parseNdjsonLine, parseNdjsonOutput, parseQwenOutput, readLocalDir, resolveStorageConfig, saveLocalDir, writeClaudeMcpConfig, writeCodexMcpConfig, writeGeminiMcpConfig, writeMcpConfig, writeQwenMcpConfig, zodSchemaToJson };