@evolvingmachines/sdk 0.0.20 → 0.0.22

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.
@@ -532,6 +532,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 +543,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 {
@@ -549,6 +555,29 @@ interface ExecuteCommandOptions {
     /** Run in background (default: false) */
     background?: boolean;
 }
+/** High-level sandbox lifecycle state */
+type SandboxLifecycleState = "booting" | "error" | "ready" | "running" | "paused" | "stopped";
+/** High-level agent runtime state */
+type AgentRuntimeState = "idle" | "running" | "interrupted" | "error";
+/** Lifecycle transition reason */
+type LifecycleReason = "sandbox_boot" | "sandbox_connected" | "sandbox_ready" | "sandbox_pause" | "sandbox_resume" | "sandbox_killed" | "sandbox_error" | "run_start" | "run_complete" | "run_interrupted" | "run_failed" | "run_background_complete" | "run_background_failed" | "command_start" | "command_complete" | "command_interrupted" | "command_failed" | "command_background_complete" | "command_background_failed";
+/** Lifecycle event emitted by the runtime */
+interface LifecycleEvent {
+    sandboxId: string | null;
+    sandbox: SandboxLifecycleState;
+    agent: AgentRuntimeState;
+    timestamp: string;
+    reason: LifecycleReason;
+}
+/** Snapshot of current runtime status */
+interface SessionStatus {
+    sandboxId: string | null;
+    sandbox: SandboxLifecycleState;
+    agent: AgentRuntimeState;
+    activeProcessId: string | null;
+    hasRun: boolean;
+    timestamp: string;
+}
 /** Response from run() and executeCommand() */
 interface AgentResponse {
     /** Sandbox ID for session management */
@@ -559,6 +588,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> {
@@ -579,6 +610,8 @@ interface StreamCallbacks {
     onStderr?: (data: string) => void;
     /** Called for each parsed content event */
     onContent?: (event: OutputEvent) => void;
+    /** Called for sandbox/agent lifecycle transitions */
+    onLifecycle?: (event: LifecycleEvent) => void;
 }
 /**
  * Configuration for Composio Tool Router integration
@@ -641,6 +674,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
@@ -740,12 +847,27 @@ declare class Agent {
     private lastRunTimestamp?;
     private readonly registry;
     private sessionLogger?;
+    private activeCommand?;
+    private activeProcessId;
+    private activeOperationId;
+    private activeOperationKind;
+    private nextOperationId;
+    private interruptedOperations;
+    private sandboxState;
+    private agentState;
     private readonly skills?;
+    private readonly storage?;
+    private lastCheckpointId?;
     private readonly zodSchema?;
     private readonly jsonSchema?;
     private readonly schemaOptions?;
     private readonly compiledValidator?;
     constructor(agentConfig: ResolvedAgentConfig, options?: AgentOptions);
+    private emitLifecycle;
+    private invalidateActiveOperation;
+    private beginOperation;
+    private finalizeOperation;
+    private watchBackgroundOperation;
     /**
      * Create Ajv validator instance with configured options
      */
@@ -753,7 +875,7 @@ declare class Agent {
     /**
      * Get or create sandbox instance
      */
-    getSandbox(): Promise<SandboxInstance>;
+    getSandbox(callbacks?: StreamCallbacks): Promise<SandboxInstance>;
     /**
      * Build environment variables for sandbox
      */
@@ -764,6 +886,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;
     /**
@@ -812,6 +937,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)
      */
@@ -827,15 +962,23 @@ declare class Agent {
     /**
      * Pause sandbox
      */
-    pause(): Promise<void>;
+    pause(callbacks?: StreamCallbacks): Promise<void>;
     /**
      * Resume sandbox
      */
-    resume(): Promise<void>;
+    resume(callbacks?: StreamCallbacks): Promise<void>;
+    /**
+     * Interrupt active command without killing the sandbox.
+     */
+    interrupt(callbacks?: StreamCallbacks): Promise<boolean>;
+    /**
+     * Get current runtime status for sandbox and agent.
+     */
+    status(): SessionStatus;
     /**
      * Kill sandbox (terminates all processes)
      */
-    kill(): Promise<void>;
+    kill(callbacks?: StreamCallbacks): Promise<void>;
     /**
      * Get host URL for a port
      */
@@ -995,17 +1138,17 @@ declare function parseNdjsonOutput(agentType: AgentType, output: string): Output
 /**
  * Evolve events
  *
- * Reduced from 5 to 3:
+ * Runtime streams:
  * - stdout: Raw NDJSON lines
  * - stderr: Process stderr
  * - content: Parsed OutputEvent
- *
- * Removed: update, error (see sdk-rewrite-v3.md)
+ * - lifecycle: Sandbox/agent lifecycle transitions
  */
 interface EvolveEvents {
     stdout: (chunk: string) => void;
     stderr: (chunk: string) => void;
     content: (event: OutputEvent) => void;
+    lifecycle: (event: LifecycleEvent) => void;
 }
 interface EvolveConfig {
     agent?: AgentConfig;
@@ -1029,6 +1172,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
@@ -1047,6 +1192,9 @@ interface EvolveConfig {
 declare class Evolve extends EventEmitter {
     private config;
     private agent?;
+    private fallbackSandboxState;
+    private fallbackAgentState;
+    private fallbackHasRun;
     constructor();
     on<K extends keyof EvolveEvents>(event: K, listener: EvolveEvents[K]): this;
     off<K extends keyof EvolveEvents>(event: K, listener: EvolveEvents[K]): this;
@@ -1169,6 +1317,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
      *
@@ -1203,13 +1368,18 @@ declare class Evolve extends EventEmitter {
      * Create stream callbacks based on registered listeners
      */
     private createStreamCallbacks;
+    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
@@ -1218,6 +1388,10 @@ declare class Evolve extends EventEmitter {
         timeoutMs?: number;
         background?: boolean;
     }): Promise<AgentResponse>;
+    /**
+     * Interrupt active process without killing sandbox.
+     */
+    interrupt(): Promise<boolean>;
     /**
      * Upload context files (runtime - immediate upload)
      */
@@ -1232,6 +1406,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)
      */
@@ -1240,6 +1436,10 @@ declare class Evolve extends EventEmitter {
      * Set session to connect to
      */
     setSession(sandboxId: string): Promise<void>;
+    /**
+     * Get runtime status for sandbox and agent.
+     */
+    status(): SessionStatus;
     /**
      * Pause sandbox
      */
@@ -2404,4 +2604,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 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 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 SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type SchemaValidationOptions, Semaphore, 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 };