@evolvingmachines/sdk 0.0.20 → 0.0.21

package/dist/index.d.cts

@@ -549,6 +549,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 */
@@ -579,6 +602,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
@@ -740,12 +765,25 @@ 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 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 +791,7 @@ declare class Agent {
     /**
      * Get or create sandbox instance
      */
-    getSandbox(): Promise<SandboxInstance>;
+    getSandbox(callbacks?: StreamCallbacks): Promise<SandboxInstance>;
     /**
      * Build environment variables for sandbox
      */
@@ -827,15 +865,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 +1041,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;
@@ -1047,6 +1093,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;
@@ -1203,6 +1252,7 @@ declare class Evolve extends EventEmitter {
      * Create stream callbacks based on registered listeners
      */
     private createStreamCallbacks;
+    private emitLifecycleFromStatus;
     /**
      * Run agent with prompt
      */
@@ -1218,6 +1268,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)
      */
@@ -1240,6 +1294,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 +2462,4 @@ 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 };
+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 };

package/dist/index.d.ts

@@ -549,6 +549,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 */
@@ -579,6 +602,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
@@ -740,12 +765,25 @@ 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 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 +791,7 @@ declare class Agent {
     /**
      * Get or create sandbox instance
      */
-    getSandbox(): Promise<SandboxInstance>;
+    getSandbox(callbacks?: StreamCallbacks): Promise<SandboxInstance>;
     /**
      * Build environment variables for sandbox
      */
@@ -827,15 +865,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 +1041,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;
@@ -1047,6 +1093,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;
@@ -1203,6 +1252,7 @@ declare class Evolve extends EventEmitter {
      * Create stream callbacks based on registered listeners
      */
     private createStreamCallbacks;
+    private emitLifecycleFromStatus;
     /**
      * Run agent with prompt
      */
@@ -1218,6 +1268,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)
      */
@@ -1240,6 +1294,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 +2462,4 @@ 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 };
+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 };