@evolvingmachines/sdk 0.0.33 → 0.0.35

package/dist/index.d.ts

@@ -364,7 +364,7 @@ interface SandboxProvider {
     connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
 }
 /** Supported agent types (headless CLI agents only, no ACP) */
-type AgentType = "claude" | "codex" | "gemini" | "qwen" | "kimi" | "opencode";
+type AgentType = "claude" | "codex" | "gemini" | "qwen" | "kimi" | "opencode" | "droid";
 /** Agent type constants for use in code */
 declare const AGENT_TYPES: {
     readonly CLAUDE: "claude";
@@ -373,11 +373,53 @@ declare const AGENT_TYPES: {
     readonly QWEN: "qwen";
     readonly KIMI: "kimi";
     readonly OPENCODE: "opencode";
+    readonly DROID: "droid";
 };
 /** Workspace mode determines folder structure and system prompt */
 type WorkspaceMode = "knowledge" | "swe";
 /** Available skills that can be enabled */
 type SkillName = "pdf" | "dev-browser" | (string & {});
+/** Browser automation providers that can be enabled explicitly */
+type BrowserProvider = "browser-use" | "actionbook";
+/** Actionbook browser configuration. */
+interface ActionbookBrowserConfig {
+    provider: "actionbook";
+    /** Use Evolve-managed browser transport. Enabled by default for object config. */
+    superstealth?: boolean;
+}
+/** Browser automation configuration. */
+type BrowserConfig = BrowserProvider | ActionbookBrowserConfig;
+/** Marketplace plugin shape for CLIs with explicit plugin install commands. */
+interface MarketplaceAgentPluginConfig {
+    /** Marketplace URL/source to register in the sandbox user profile */
+    marketplace: string;
+    /** Plugin identifier, usually plugin@marketplace */
+    plugin: string;
+}
+/** Gemini extension install shape. */
+interface GeminiAgentPluginConfig {
+    /** GitHub URL or local path for the extension */
+    source: string;
+    /** Optional git ref to install */
+    ref?: string;
+    /** Enable extension auto-update */
+    autoUpdate?: boolean;
+    /** Enable pre-release versions */
+    preRelease?: boolean;
+    /** Skip extension settings prompts during install */
+    skipSettings?: boolean;
+}
+/** Codex marketplace registration shape. */
+interface CodexAgentPluginConfig {
+    /** Marketplace source to register */
+    marketplace: string;
+    /** Optional git ref to pin */
+    ref?: string;
+    /** Optional sparse checkout paths for Git-backed marketplaces */
+    sparse?: string[];
+}
+/** Agent plugin/extension config. Shape is validated against the selected agent at runtime. */
+type AgentPluginConfig = MarketplaceAgentPluginConfig | GeminiAgentPluginConfig | CodexAgentPluginConfig;
 /** Skills configuration for an agent */
 interface SkillsConfig {
     /** Source directory where skills are staged */
@@ -385,8 +427,8 @@ interface SkillsConfig {
     /** Target directory where skills are copied for this CLI */
     targetDir: string;
 }
-/** Reasoning effort for models that support it (Codex only) */
-type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
+/** Reasoning effort for CLIs/models that support it; valid values vary by model. */
+type ReasoningEffort = "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 /** MCP Server Configuration */
 interface McpServerConfig {
     command?: string;
@@ -460,7 +502,7 @@ interface AgentConfig {
     providerBaseUrl?: string;
     /** Model to use (optional, uses agent's default if omitted) */
     model?: string;
-    /** Reasoning effort for Codex models */
+    /** Reasoning effort for models that support it */
     reasoningEffort?: ReasoningEffort;
 }
 /** Resolved agent config (output of resolution, not an extension of input) */
@@ -495,6 +537,15 @@ interface AgentOptions {
     files?: FileMap;
     /** MCP server configurations */
     mcpServers?: Record<string, McpServerConfig>;
+    /** Runtime browser prompt fragment appended to the agent system prompt */
+    browserPrompt?: string;
+    /** Evolve-managed browser transport for browser automation */
+    managedBrowser?: {
+        apiKey: string;
+        dashboardUrl?: string;
+    };
+    /** Plugins/extensions to install in the sandbox user profile before first run */
+    plugins?: AgentPluginConfig[];
     /** Skills to enable (e.g., ["pdf", "dev-browser"]) */
     skills?: SkillName[];
     /**
@@ -557,7 +608,11 @@ type SandboxLifecycleState = "booting" | "error" | "ready" | "running" | "paused
 /** 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";
+type LifecycleReason = "browser_ready" | "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";
+/** Browser runtime info exposed to host applications. */
+interface BrowserRuntimeInfo {
+    liveUrl: string;
+}
 /** Lifecycle event emitted by the runtime */
 interface LifecycleEvent {
     sandboxId: string | null;
@@ -565,6 +620,7 @@ interface LifecycleEvent {
     agent: AgentRuntimeState;
     timestamp: string;
     reason: LifecycleReason;
+    browser?: BrowserRuntimeInfo;
 }
 /** Snapshot of current runtime status */
 interface SessionStatus {
@@ -574,6 +630,7 @@ interface SessionStatus {
     activeProcessId: string | null;
     hasRun: boolean;
     timestamp: string;
+    browser?: BrowserRuntimeInfo;
 }
 /** Response from run() and executeCommand() */
 interface AgentResponse {
@@ -939,6 +996,8 @@ declare class Agent {
     private interruptedOperations;
     private sandboxState;
     private agentState;
+    private droidSessionId?;
+    private managedBrowserSession?;
     private readonly skills?;
     private readonly storage?;
     private lastCheckpointId?;
@@ -947,6 +1006,7 @@ declare class Agent {
     private readonly schemaOptions?;
     private readonly compiledValidator?;
     constructor(agentConfig: ResolvedAgentConfig, options?: AgentOptions);
+    private browserRuntimeInfo;
     private emitLifecycle;
     private invalidateActiveOperation;
     private beginOperation;
@@ -964,6 +1024,8 @@ declare class Agent {
      * Build environment variables for sandbox
      */
     private buildEnvironmentVariables;
+    private ensureManagedBrowserSession;
+    private closeManagedBrowserSession;
     /**
      * Build the inline gateway config JSON for agents using gatewayConfigEnv
      * (e.g., OpenCode OPENCODE_CONFIG_CONTENT). Centralizes the provider config
@@ -983,10 +1045,18 @@ declare class Agent {
      * Passed to spawn() so each .run() gets a unique run tag.
      */
     private buildRunEnvs;
+    private captureDroidSession;
+    private extractDroidSessionId;
+    private findDroidSessionId;
+    private loadDroidSessionState;
+    private writeDroidSessionState;
+    private resolveGatewayModel;
+    private resolveCommandModel;
     /**
      * Agent-specific authentication setup
      */
     private setupAgentAuth;
+    private setupAgentPlugins;
     /**
      * Setup workspace structure and files
      *
@@ -1206,6 +1276,15 @@ declare function createClaudeParser(): (jsonLine: string) => OutputEvent[] | nul
  */
 declare function createCodexParser(): (jsonLine: string) => OutputEvent[] | null;
 
+/**
+ * Droid exec parser.
+ *
+ * Supports the documented headless `--output-format stream-json` lines and the
+ * raw `stream-jsonrpc` notification envelope used by Droid's low-level SDK.
+ */
+
+declare function createDroidParser(): (jsonLine: string) => OutputEvent[] | null;
+
 /**
  * Gemini JSONL → ACP-style events parser.
  *
@@ -1320,6 +1399,10 @@ interface EvolveConfig {
     context?: FileMap;
     files?: FileMap;
     mcpServers?: Record<string, McpServerConfig>;
+    /** Browser automation provider to enable explicitly */
+    browser?: BrowserConfig;
+    /** Agent plugins/extensions to install before first run */
+    plugins?: AgentPluginConfig[];
     /** Skills to enable (e.g., ["pdf", "dev-browser"]) */
     skills?: SkillName[];
     /** Schema for structured output (Zod or JSON Schema, auto-detected) */
@@ -1401,6 +1484,28 @@ declare class Evolve extends EventEmitter {
      * Configure MCP servers
      */
     withMcpServers(servers: Record<string, McpServerConfig>): this;
+    /**
+     * Enable browser automation.
+     *
+     * Default browser automation uses Actionbook with Evolve-managed browser
+     * transport in gateway mode. Pass "browser-use" to use the legacy MCP server.
+     *
+     * @example
+     * kit.withBrowser("browser-use") // legacy MCP provider
+     *
+     * @example
+     * kit.withBrowser() // defaults to managed Actionbook
+     */
+    withBrowser(provider?: BrowserConfig | false): this;
+    /**
+     * Install agent plugins/extensions in the sandbox user profile.
+     *
+     * The selected agent determines the installer:
+     * - droid/claude: { marketplace, plugin }
+     * - gemini: { source, ref? }
+     * - codex: { marketplace, ref?, sparse? }
+     */
+    withPlugins(plugins: AgentPluginConfig | AgentPluginConfig[]): this;
     /**
      * Enable skills for the agent
      *
@@ -2527,6 +2632,7 @@ interface BuildCommandOptions {
     prompt: string;
     model: string;
     isResume: boolean;
+    sessionId?: string;
     reasoningEffort?: string;
     isDirectMode?: boolean;
     /** Skills enabled for this run */
@@ -2546,8 +2652,8 @@ interface AgentRegistryEntry {
         key: string;
         value: string;
     };
-    /** Environment variable name for base URL */
-    baseUrlEnv: string;
+    /** Environment variable name for base URL, if this CLI supports one */
+    baseUrlEnv?: string;
     /** Default model alias */
     defaultModel: string;
     /** Available models for this agent */
@@ -2574,6 +2680,19 @@ interface AgentRegistryEntry {
     }>;
     /** Env var for inline config (e.g., OPENCODE_CONFIG_CONTENT) — used in gateway mode to set provider base URLs */
     gatewayConfigEnv?: string;
+    /** Gateway-only model aliases for CLIs whose native model IDs differ from LiteLLM route names */
+    gatewayModelAliases?: Record<string, string>;
+    /** Direct-mode model aliases for CLIs whose public model names differ from CLI-native model IDs */
+    directModelAliases?: Record<string, string>;
+    /** Do not set provider API key env in gateway mode (used when routing via generated settings instead) */
+    skipApiKeyEnvInGateway?: boolean;
+    /** Dedicated Droid settings file for Evolve gateway custom model routing */
+    droidGatewaySettings?: {
+        settingsPath: string;
+        displayName: string;
+        provider: "generic-chat-completion-api" | "openai" | "anthropic";
+        maxOutputTokens?: number;
+    };
     /** Environment variable that CLI reads for custom outbound HTTP headers */
     customHeadersEnv?: string;
     /** Format for custom headers env var: "newline" (Claude) or "comma" (Gemini). Default: "newline" */
@@ -2652,7 +2771,7 @@ declare function getMcpSettingsDir(agentType: AgentType): string;
 /**
  * MCP JSON Configuration Writer
  *
- * Handles MCP config for Claude, Gemini, Qwen, and Kimi agents.
+ * Handles MCP config for Claude, Gemini, Qwen, Kimi, Droid, and OpenCode agents.
  * Uses registry for paths - no hardcoded values.
  *
  * Transport formats by agent:
@@ -2674,6 +2793,29 @@ declare function writeClaudeMcpConfig(sandbox: SandboxInstance, workingDir: stri
 declare function writeGeminiMcpConfig(sandbox: SandboxInstance, servers: Record<string, McpServerConfig>): Promise<void>;
 /** Write MCP config for Qwen agent */
 declare function writeQwenMcpConfig(sandbox: SandboxInstance, servers: Record<string, McpServerConfig>): Promise<void>;
+/**
+ * Write MCP config for Droid agent
+ *
+ * Droid supports project-level `.factory/mcp.json`, which keeps MCP config
+ * scoped to the sandbox workspace instead of mutating global user config.
+ */
+declare function writeDroidMcpConfig(sandbox: SandboxInstance, workingDir: string, servers: Record<string, McpServerConfig>): Promise<void>;
+interface DroidGatewaySettingsConfig {
+    settingsPath: string;
+    displayName: string;
+    model: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    provider: "generic-chat-completion-api" | "openai" | "anthropic";
+    maxOutputTokens?: number;
+}
+/**
+ * Write an Evolve-owned Droid settings file for gateway custom-model routing.
+ *
+ * The command passes this file with `droid --settings`, so it does not alter the
+ * user's normal ~/.factory/settings.json inside the sandbox.
+ */
+declare function writeDroidGatewaySettings(sandbox: SandboxInstance, config: DroidGatewaySettingsConfig, headers: Record<string, string>): Promise<void>;
 
 /**
  * MCP TOML Configuration Writer
@@ -2705,6 +2847,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
+ * - Droid: JSON to ${workingDir}/.factory/mcp.json
  * - OpenCode: JSON to ${workingDir}/opencode.json (mcp key)
  */
 declare function writeMcpConfig(agentType: AgentType, sandbox: SandboxInstance, workingDir: string, servers: Record<string, McpServerConfig>): Promise<void>;
@@ -2744,6 +2887,10 @@ declare const SYSTEM_PROMPT: string;
  * - {{schema}} - JSON schema for the expected output
  */
 declare const SCHEMA_PROMPT: string;
+/**
+ * Actionbook browser automation prompt fragment
+ */
+declare const BROWSER_ACTIONBOOK_PROMPT: string;
 /**
  * Judge system prompt template (for Swarm best_of)
  *
@@ -2785,6 +2932,7 @@ declare function applyTemplate(template: string, variables: Record<string, strin
 declare function buildWorkerSystemPrompt(options: {
     workingDir: string;
     systemPrompt?: string;
+    browserPrompt?: string;
     schema?: z.ZodType<unknown> | Record<string, unknown>;
     mode?: "knowledge" | "swe";
 }): string;
@@ -2951,4 +3099,4 @@ interface SessionsClient {
  */
 declare function sessions(config?: SessionsConfig): SessionsClient;
 
-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 DownloadCheckpointOptions, type DownloadFilesOptions, type DownloadSessionOptions, type EmitOption, type EventHandler, type EventName, Evolve, type EvolveConfig, type EvolveEvents, type ExecuteCommandOptions, type FileMap, type FilterConfig, type FilterParams, type GetEventsOptions, type IndexedMeta, type ItemInput, type ItemRetryEvent, JUDGE_PROMPT, type JsonSchema, type JudgeCompleteEvent, type JudgeDecision, type JudgeMeta, type LifecycleEvent, type LifecycleReason, type ListSessionsOptions, 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 RunCost, 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 SessionCost, type SessionEvent, type SessionInfo, type SessionPage, type SessionStatus, type SessionsClient, type SessionsConfig, type SkillName, type SkillsConfig, type StepCompleteEvent, type StepErrorEvent, type StepEvent, type StepResult, type StepStartEvent, type StorageClient, 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, parseNdjsonLine, parseNdjsonOutput, parseQwenOutput, readLocalDir, resolveStorageConfig, saveLocalDir, sessions, storage, writeClaudeMcpConfig, writeCodexMcpConfig, writeGeminiMcpConfig, writeMcpConfig, writeQwenMcpConfig, zodSchemaToJson };
+export { AGENT_REGISTRY, AGENT_TYPES, type ActionbookBrowserConfig, Agent, type AgentConfig, type AgentOptions, type AgentOverride, type AgentParser, type AgentPluginConfig, type AgentRegistryEntry, type AgentResponse, type AgentRuntimeState, type AgentType, BROWSER_ACTIONBOOK_PROMPT, type BaseMeta, type BestOfConfig, type BestOfParams, type BestOfResult, type BrowserConfig, type BrowserProvider, type BrowserRuntimeInfo, type CandidateCompleteEvent, type CheckpointInfo, type CodexAgentPluginConfig, type ComposioAuthResult, type ComposioConfig, type ComposioConnectionStatus, type ComposioSetup, type DownloadCheckpointOptions, type DownloadFilesOptions, type DownloadSessionOptions, type EmitOption, type EventHandler, type EventName, Evolve, type EvolveConfig, type EvolveEvents, type ExecuteCommandOptions, type FileMap, type FilterConfig, type FilterParams, type GeminiAgentPluginConfig, type GetEventsOptions, type IndexedMeta, type ItemInput, type ItemRetryEvent, JUDGE_PROMPT, type JsonSchema, type JudgeCompleteEvent, type JudgeDecision, type JudgeMeta, type LifecycleEvent, type LifecycleReason, type ListSessionsOptions, type MapConfig, type MapParams, type MarketplaceAgentPluginConfig, 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 RunCost, 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 SessionCost, type SessionEvent, type SessionInfo, type SessionPage, type SessionStatus, type SessionsClient, type SessionsConfig, type SkillName, type SkillsConfig, type StepCompleteEvent, type StepErrorEvent, type StepEvent, type StepResult, type StepStartEvent, type StorageClient, 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, createDroidParser, createGeminiParser, executeWithRetry, expandPath, getAgentConfig, getMcpSettingsDir, getMcpSettingsPath, isValidAgentType, isZodSchema, jsonSchemaToString, parseNdjsonLine, parseNdjsonOutput, parseQwenOutput, readLocalDir, resolveStorageConfig, saveLocalDir, sessions, storage, writeClaudeMcpConfig, writeCodexMcpConfig, writeDroidGatewaySettings, writeDroidMcpConfig, writeGeminiMcpConfig, writeMcpConfig, writeQwenMcpConfig, zodSchemaToJson };