evolvingmachines-evolve 0.0.55.dev1355__py3-none-any.whl

evolve/agent.py

@@ -0,0 +1,896 @@
+"""Main Evolve class for Python SDK."""
+
+import asyncio
+import json
+from dataclasses import asdict, is_dataclass
+from typing import Any, Callable, Dict, List, Literal, Optional, Type, Union
+
+from .bridge import BridgeManager, SandboxNotFoundError
+from .config import AgentConfig, AgentPluginConfig, BrowserConfig, BrowserCredentialsConfig, IntegrationsSetup, ManagedSecretRef, SandboxCreateOptions, SandboxProvider, SchemaOptions, StorageConfig, WorkspaceMode
+from .results import AgentResponse, CheckpointInfo, ExecuteResult, OutputResult, RunCost, SessionCost, SessionStatus
+from .storage_client import StorageClient
+from . import integrations as integrations_helpers
+from .schema import is_pydantic_model, is_dataclass, to_json_schema, validate_and_parse
+from .utils import _encode_files_for_transport, _decode_files_from_transport, _filter_none, _parse_checkpoint, _require_checkpoint
+
+
+class Evolve:
+    """Evolve agent orchestrator.
+
+    Provides a Pythonic interface to the TypeScript Evolve SDK via JSON-RPC bridge.
+
+    Example:
+        >>> from evolve import Evolve
+        >>>
+        >>> # Minimal usage - uses EVOLVE_API_KEY and E2B_API_KEY env vars
+        >>> async with Evolve() as evolve:
+        ...     result = await evolve.run(prompt='Analyze data.csv')
+        ...     output = await evolve.get_output_files()
+        ...     for name, content in output.files.items():
+        ...         print(f'{name}: {len(content)} bytes')
+        >>>
+        >>> # Or with explicit config (E2B)
+        >>> from evolve import AgentConfig, E2BProvider
+        >>> evolve = Evolve(
+        ...     config=AgentConfig(type='codex', api_key='sk-...'),
+        ...     sandbox=E2BProvider(api_key='...')
+        ... )
+        >>>
+        >>> # Or with Daytona
+        >>> from evolve import DaytonaProvider
+        >>> evolve = Evolve(sandbox=DaytonaProvider(api_key='...'))
+        >>> # Or with Modal
+        >>> from evolve import ModalProvider
+        >>> evolve = Evolve(sandbox=ModalProvider())
+    """
+
+    # Static helpers for Integrations pre-auth flows (no instance required)
+    integrations = integrations_helpers
+
+    def __init__(
+        self,
+        config: Optional[AgentConfig] = None,
+        sandbox: Optional[SandboxProvider] = None,
+        working_directory: str = '/home/user/workspace',
+        workspace_mode: WorkspaceMode = 'knowledge',
+        system_prompt: Optional[str] = None,
+        context: Optional[Dict[str, Union[str, bytes]]] = None,
+        files: Optional[Dict[str, Union[str, bytes]]] = None,
+        mcp_servers: Optional[Dict[str, Any]] = None,
+        skills: Optional[List[str]] = None,
+        secrets: Optional[Dict[str, str]] = None,
+        managed_secrets: Optional[List[Union[ManagedSecretRef, Dict[str, Any]]]] = None,
+        sandbox_id: Optional[str] = None,
+        session_tag_prefix: Optional[str] = None,
+        schema: Optional[Union[Type, Dict[str, Any]]] = None,
+        schema_options: Optional[SchemaOptions] = None,
+        integrations: Optional[IntegrationsSetup] = None,
+        storage: Optional[StorageConfig] = None,
+        browser: Optional[BrowserConfig] = None,
+        browser_credentials: Optional[BrowserCredentialsConfig] = None,
+        plugins: Optional[Union[AgentPluginConfig, List[AgentPluginConfig]]] = None,
+        sandbox_create_options: Optional[SandboxCreateOptions] = None,
+    ):
+        """Initialize Evolve.
+
+        Args:
+            config: Agent configuration (optional - defaults to EVOLVE_API_KEY env var with 'claude' type)
+            sandbox: Sandbox provider (optional - auto-resolves from env vars:
+                     E2B_API_KEY → E2B direct, DAYTONA_API_KEY → Daytona direct,
+                     MODAL_TOKEN_ID+MODAL_TOKEN_SECRET → Modal direct,
+                     EVOLVE_API_KEY → E2B via gateway. User sandbox keys take priority.)
+            working_directory: Working directory in sandbox (default: /home/user/workspace)
+            workspace_mode: 'knowledge', 'swe', or 'task'. Task mode leaves the
+                task-owned working directory untouched.
+            system_prompt: Custom system prompt (appended to default in 'knowledge' mode, sole prompt in 'swe' mode)
+            context: Files to upload to context/ folder on first run - { "filename.txt": "content" }
+            files: Files to upload to working directory on first run - { "scripts/run.sh": "content" }
+            mcp_servers: MCP server configurations
+            skills: Skill references to mount into the sandbox — real references,
+                     no built-in catalog: 'skills.sh/<owner>/<repo>[/<skill>]',
+                     'org/repo[@ref]', an https git URL, or a local folder path
+                     containing SKILL.md. Resolved pinned + content-cached by the
+                     SDK's one resolver and mounted where the harness discovers them.
+            secrets: Environment variables for sandbox
+            managed_secrets: Dashboard-stored managed secrets to attach
+                     ({'name', 'label'?, 'as'?} or ManagedSecretRef). Brokered
+                     secrets ride as opaque placeholder env vars behind the
+                     egress proxy; direct secrets land as raw env values
+            sandbox_id: Existing sandbox ID to reconnect to
+            session_tag_prefix: Optional semantic label for observability log files (e.g., 'experiment-7')
+            schema: Schema for structured output - Pydantic model, dataclass, or JSON Schema dict
+            schema_options: Validation options (mode: 'strict' or 'loose', default: 'loose')
+            integrations: managed app integrations setup
+            storage: Storage configuration for checkpoint persistence (BYOK S3 or gateway mode)
+            browser: Browser automation provider. Use {'provider': 'agent-browser', 'remote': True}
+                for managed remote browser automation.
+            browser_credentials: Saved browser login MCP setup. Requires managed remote agent-browser.
+            plugins: Agent plugins/extensions to install in the sandbox user profile before first run.
+            sandbox_create_options: Provider-neutral image, env, metadata, timeout,
+                working-directory and outbound-network options for fresh sandbox creation.
+        """
+        self.config = config
+        self.sandbox = sandbox
+        self.sandbox_create_options = sandbox_create_options
+        self.working_directory = working_directory
+        self.workspace_mode = workspace_mode
+        self.system_prompt = system_prompt
+        self.context = context
+        self.files = files
+        self.mcp_servers = mcp_servers
+        self.browser = self._normalize_browser(browser)
+        self.browser_credentials = browser_credentials
+        self.skills = skills
+        self.secrets = secrets
+        self.managed_secrets = self._normalize_managed_secrets(managed_secrets)
+        self.sandbox_id = sandbox_id
+        self.session_tag_prefix = session_tag_prefix
+        self.schema_options = schema_options or SchemaOptions()
+        self._integrations = integrations
+        self._storage_config = storage
+        self.plugins = self._normalize_plugins(plugins)
+
+        # Schema handling: store original + convert to JSON Schema
+        self._schema = schema
+        self._schema_json = to_json_schema(schema)
+
+        self.bridge = BridgeManager()
+        self._initialized = False
+        self._init_lock = asyncio.Lock()
+
+    async def _ensure_initialized(self):
+        """Ensure bridge is started and agent is initialized."""
+        async with self._init_lock:
+            if self._initialized:
+                return
+
+            await self.bridge.start()
+
+            # Build params with _filter_none to exclude None values
+            # TS SDK resolves defaults from env vars when not provided
+            params = _filter_none({
+                # Agent config (optional - TS SDK resolves from env vars)
+                'agent_type': self.config.type if self.config else None,
+                'api_key': self.config.api_key if self.config else None,
+                'provider_api_key': self.config.provider_api_key if self.config else None,
+                'oauth_token': self.config.oauth_token if self.config else None,
+                'provider_base_url': self.config.provider_base_url if self.config else None,
+                'model': self.config.model if self.config else None,
+                'reasoning_effort': self.config.reasoning_effort if self.config else None,
+                'max_context_size': self.config.max_context_size if self.config else None,
+                'agent_config': self.config.config if self.config else None,
+                'agent_preset': self.config.preset if self.config else None,
+                # Sandbox (optional - TS SDK auto-resolves from EVOLVE_API_KEY/E2B_API_KEY/DAYTONA_API_KEY)
+                'sandbox_provider': {'type': self.sandbox.type, 'config': self.sandbox.config} if self.sandbox else None,
+                'sandbox_create_options': self.sandbox_create_options,
+                # Other settings
+                'working_directory': self.working_directory,
+                'workspace_mode': self.workspace_mode,
+                'system_prompt': self.system_prompt,
+                'context': _encode_files_for_transport(self.context) if self.context else None,
+                'files': _encode_files_for_transport(self.files) if self.files else None,
+                'mcp_servers': self.mcp_servers,
+                'browser': self.browser,
+                'browser_credentials': self.browser_credentials.to_dict() if self.browser_credentials else None,
+                'plugins': self.plugins,
+                'skills': self.skills,
+                'secrets': self.secrets,
+                'managed_secrets': self.managed_secrets,
+                'sandbox_id': self.sandbox_id,
+                'session_tag_prefix': self.session_tag_prefix,
+                'schema': self._schema_json,
+                'schema_options': {'mode': self.schema_options.mode} if self._schema_json else None,
+                # Managed integrations
+                'integrations': self._integrations.to_dict() if self._integrations else None,
+                # Storage / Checkpointing
+                'storage': self._storage_config.to_dict() if self._storage_config else None,
+                # Always forward events
+                'forward_stdout': True,
+                'forward_stderr': True,
+                'forward_content': True,
+                'forward_lifecycle': True,
+            })
+
+            await self.bridge.call('initialize', params, timeout_s=self._get_rpc_timeout_s(None))
+            self._initialized = True
+
+    @staticmethod
+    def _normalize_browser(browser: Optional[BrowserConfig]) -> Optional[BrowserConfig]:
+        """Normalize browser automation shorthand for bridge transport."""
+        if browser is None:
+            return None
+        if browser in ('browser-use', 'actionbook', 'agent-browser'):
+            return browser
+        if isinstance(browser, dict):
+            provider = browser.get('provider', 'agent-browser')
+            if provider not in ('actionbook', 'agent-browser'):
+                raise ValueError("browser provider must be 'actionbook' or 'agent-browser'")
+            normalized = dict(browser)
+            normalized['provider'] = provider
+            if 'profile' in normalized and 'remote' not in normalized and browser.get('provider') is None:
+                normalized['remote'] = True
+            if 'profile' in normalized and normalized.get('remote') is not True:
+                raise ValueError("browser profile requires managed remote browser mode")
+            return normalized
+        raise ValueError("browser must be 'browser-use', 'actionbook', 'agent-browser', a managed browser config dict, or None")
+
+    @staticmethod
+    def _normalize_managed_secrets(
+        managed_secrets: Optional[List[Union[ManagedSecretRef, Dict[str, Any]]]]
+    ) -> Optional[List[Dict[str, Any]]]:
+        if managed_secrets is None:
+            return None
+        if not managed_secrets:
+            raise ValueError('managed_secrets requires at least one secret')
+        normalized: List[Dict[str, Any]] = []
+        for secret in managed_secrets:
+            if isinstance(secret, ManagedSecretRef):
+                normalized.append(secret.to_dict())
+            elif isinstance(secret, dict):
+                item = dict(secret)
+                if 'as_name' in item:
+                    item['as'] = item.pop('as_name')
+                normalized.append(item)
+            else:
+                raise ValueError('managed_secrets entries must be ManagedSecretRef or dict')
+        return normalized
+
+    @staticmethod
+    def _normalize_plugins(
+        plugins: Optional[Union[AgentPluginConfig, List[AgentPluginConfig]]]
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Normalize plugin config and convert Python snake_case flags for TS transport."""
+        if plugins is None:
+            return None
+
+        if isinstance(plugins, dict) or is_dataclass(plugins):
+            raw_plugins: List[Any] = [plugins]
+        elif isinstance(plugins, list):
+            raw_plugins = plugins
+        else:
+            raise ValueError('plugins must be a plugin dict, list of plugin dicts, or None')
+
+        normalized: List[Dict[str, Any]] = []
+        for plugin in raw_plugins:
+            if is_dataclass(plugin):
+                item = asdict(plugin)
+            elif isinstance(plugin, dict):
+                item = dict(plugin)
+            else:
+                raise ValueError('each plugin must be a dict-like object')
+
+            for python_key, ts_key in (
+                ('auto_update', 'autoUpdate'),
+                ('pre_release', 'preRelease'),
+                ('skip_settings', 'skipSettings'),
+            ):
+                if python_key in item:
+                    item[ts_key] = item.pop(python_key)
+
+            normalized.append(item)
+
+        return normalized
+
+    def on(
+        self,
+        event_type: Literal['stdout', 'stderr', 'content', 'lifecycle'],
+        callback: Callable[[Any], None]
+    ):
+        """Register event callback.
+
+        Args:
+            event_type: Event type ('stdout' | 'stderr' | 'content' | 'lifecycle')
+            callback: Callback function invoked with the event payload
+                      (str for stdout/stderr, dict for content/lifecycle)
+
+        Example:
+            >>> evolve.on('stdout', lambda data: print(data, end=''))
+            >>> evolve.on('stderr', lambda data: print(f'[ERR] {data}', end=''))
+            >>> evolve.on('content', lambda event: print(event['update']['sessionUpdate']))
+            >>> evolve.on('lifecycle', lambda event: print(event['reason']))
+        """
+        self.bridge.on(event_type, callback)
+
+    def _get_rpc_timeout_s(self, timeout_ms: Optional[int]) -> float:
+        """Compute an RPC timeout aligned with sandbox execution timeout."""
+        if timeout_ms is None:
+            timeout_ms = getattr(self.sandbox, "timeout_ms", 3600000) if self.sandbox else 3600000
+        # Add small grace to allow bridge/agent cleanup after sandbox timeout.
+        return timeout_ms / 1000.0 + 30.0
+
+    async def run(
+        self,
+        prompt: str,
+        timeout_ms: Optional[int] = None,
+        background: bool = False,
+        from_checkpoint: Optional[str] = None,
+        checkpoint_comment: Optional[str] = None,
+        resume: Optional[bool] = None,
+    ) -> AgentResponse:
+        """Run AI-assisted task (agent decides and acts).
+
+        Args:
+            prompt: Task description
+            timeout_ms: Optional timeout in milliseconds (default: 1 hour)
+            background: Run in background (default: False). If True, returns
+                       immediately with a handshake response (`exit_code=0`).
+                       Final completion is delivered asynchronously via
+                       lifecycle events or status polling.
+            from_checkpoint: Restore from checkpoint ID before running (requires storage).
+                           Use 'latest' to restore the most recent checkpoint.
+            checkpoint_comment: Optional label for the auto-checkpoint after this run
+            resume: Whether this run continues the agent's previous conversation
+                   in this sandbox. Omitted, the first run in a sandbox is fresh
+                   and every run after it resumes. Pass False to force a FRESH
+                   conversation in a sandbox the agent has already run in — the
+                   shape a sequence of independent tasks against one shared
+                   sandbox needs, where the environment persists but the context
+                   should not.
+
+        Returns:
+            AgentResponse with sandbox_id, exit_code, stdout, stderr, checkpoint
+
+        Example:
+            >>> result = await evolve.run(prompt='Analyze data and create report', timeout_ms=600000)
+            >>> # Background execution
+            >>> result = await evolve.run(prompt='Long task', background=True)
+            >>> # Restore from checkpoint
+            >>> result = await evolve.run(prompt='Continue work', from_checkpoint='latest')
+            >>> # Independent tasks in one sandbox: keep the box, drop the context
+            >>> result = await evolve.run(prompt='Second, unrelated task', resume=False)
+        """
+        await self._ensure_initialized()
+
+        params: Dict[str, Any] = {
+            'prompt': prompt,
+        }
+        if timeout_ms is not None:
+            params['timeout_ms'] = timeout_ms
+        if background:
+            params['background'] = background
+        if from_checkpoint is not None:
+            params['from'] = from_checkpoint
+        if checkpoint_comment is not None:
+            params['checkpoint_comment'] = checkpoint_comment
+        if resume is not None:
+            params['resume'] = resume
+
+        response = await self.bridge.call(
+            'run',
+            params,
+            timeout_s=self._get_rpc_timeout_s(timeout_ms),
+        )
+
+        return AgentResponse(
+            sandbox_id=response['sandbox_id'],
+            exit_code=response['exit_code'],
+            stdout=response['stdout'],
+            stderr=response['stderr'],
+            session_id=response.get('session_id'),
+            browser=response.get('browser'),
+            run_id=response.get('run_id'),
+            checkpoint=_parse_checkpoint(response.get('checkpoint')),
+        )
+
+    async def execute_command(
+        self,
+        command: str,
+        timeout_ms: Optional[int] = None,
+        background: bool = False,
+    ) -> AgentResponse:
+        """Execute direct shell command.
+
+        Args:
+            command: Shell command to execute
+            timeout_ms: Optional timeout in milliseconds (default: 1 hour)
+            background: Run in background (default: False). If True, returns
+                       immediately with a handshake response (`exit_code=0`).
+                       Final completion is delivered via lifecycle events.
+
+        Returns:
+            AgentResponse with sandbox_id, exit_code, stdout, stderr
+
+        Example:
+            >>> result = await evolve.execute_command(command='python script.py')
+        """
+        await self._ensure_initialized()
+
+        response = await self.bridge.call(
+            'execute_command',
+            {
+                'command': command,
+                'timeout_ms': timeout_ms,
+                'background': background,
+            },
+            timeout_s=self._get_rpc_timeout_s(timeout_ms),
+        )
+
+        return AgentResponse(
+            sandbox_id=response['sandbox_id'],
+            exit_code=response['exit_code'],
+            stdout=response['stdout'],
+            stderr=response['stderr'],
+            session_id=response.get('session_id'),
+            browser=response.get('browser'),
+        )
+
+    async def seal_credentials(self) -> None:
+        """Irreversibly revoke Evolve-managed model credentials for this sandbox."""
+        await self._ensure_initialized()
+        await self.bridge.call('seal_credentials', {}, timeout_s=30)
+
+    async def collect_artifacts(
+        self,
+        paths: List[str],
+    ) -> Dict[str, Union[str, bytes]]:
+        """Collect declared task files after :meth:`seal_credentials`."""
+        await self._ensure_initialized()
+        response = await self.bridge.call(
+            'collect_artifacts',
+            {'paths': paths},
+            timeout_s=self._get_rpc_timeout_s(None),
+        )
+        return _decode_files_from_transport(response.get('files', {}))
+
+    async def upload_context(
+        self,
+        files: Dict[str, Union[str, bytes]],
+    ):
+        """Upload files to context/ folder (runtime - immediate upload).
+
+        Args:
+            files: Dict mapping filename to content - { "filename.txt": "content", "data.json": jsonStr }
+
+        Example:
+            >>> await evolve.upload_context({
+            ...     'spec.json': json.dumps(spec),
+            ...     'readme.txt': 'Project documentation...',
+            ... })
+        """
+        await self._ensure_initialized()
+        await self.bridge.call('upload_context', {
+            'files': _encode_files_for_transport(files),
+        }, timeout_s=self._get_rpc_timeout_s(None))
+
+    async def upload_files(
+        self,
+        files: Dict[str, Union[str, bytes]],
+    ):
+        """Upload files to working directory (runtime - immediate upload).
+
+        Args:
+            files: Dict mapping path to content - { "scripts/run.sh": "#!/bin/bash...", "data/input.csv": csvData }
+
+        Example:
+            >>> await evolve.upload_files({
+            ...     'scripts/setup.sh': '#!/bin/bash\\necho hello',
+            ...     'temp/cache.json': json.dumps(cache),
+            ... })
+        """
+        await self._ensure_initialized()
+        await self.bridge.call('upload_files', {
+            'files': _encode_files_for_transport(files),
+        }, timeout_s=self._get_rpc_timeout_s(None))
+
+    async def upload_file_from_path(
+        self,
+        sandbox_path: str,
+        local_path: str,
+    ):
+        """Upload one LOCAL file into the sandbox by path, without buffering it.
+
+        The memory-bounded counterpart to ``upload_files()``: that one takes the
+        bytes as a value, so a large artifact costs one full-size copy per
+        concurrent upload. This takes the path, and the provider streams it off
+        disk — peak memory is a chunk rather than the file.
+
+        Args:
+            sandbox_path: Destination in the sandbox. Absolute paths are used
+                as-is; relative paths resolve under the working directory.
+            local_path: Path on THIS machine to upload.
+
+        Example:
+            >>> await evolve.upload_file_from_path('/tmp/dataset.tgz', './dataset.tgz')
+        """
+        await self._ensure_initialized()
+        await self.bridge.call('upload_file_from_path', {
+            'sandbox_path': sandbox_path,
+            'local_path': local_path,
+        }, timeout_s=self._get_rpc_timeout_s(None))
+
+    async def get_output_files(self, recursive: bool = False) -> OutputResult:
+        """Get output files with optional schema validation result.
+
+        Returns files modified after the last run() call, along with schema
+        validation results if a schema was configured.
+
+        Matches TypeScript SDK's getOutputFiles() for exact parity.
+        Evidence: sdk-ts/src/types.ts OutputResult<T> interface
+
+        Args:
+            recursive: Include files in subdirectories (default: False)
+
+        Returns:
+            OutputResult containing:
+                - files: Dict mapping filename/path to content (str for text, bytes for binary)
+                - data: Parsed and validated result.json data (None if no schema or validation failed)
+                - error: Validation or parse error message, if any
+                - raw_data: Raw result.json string when parse or validation failed
+
+        Example:
+            >>> output = await evolve.get_output_files()
+            >>> for name, content in output.files.items():
+            ...     with open(f'./downloads/{name}', 'wb') as f:
+            ...         f.write(content if isinstance(content, bytes) else content.encode())
+            >>> if output.data:
+            ...     print(f"Validated data: {output.data}")
+            >>> if output.error:
+            ...     print(f"Validation error: {output.error}")
+        """
+        await self._ensure_initialized()
+
+        response = await self.bridge.call('get_output_files', {'recursive': recursive}, timeout_s=self._get_rpc_timeout_s(None))
+
+        files = _decode_files_from_transport(response.get('files', {}))
+
+        data = None
+        error = None
+        raw_data = None
+
+        # CASE 1: Pydantic model or dataclass → Native Python validation
+        if is_pydantic_model(self._schema) or is_dataclass(self._schema):
+            raw_json = files.get('result.json')
+            if raw_json is None:
+                error = "Schema provided but agent did not create output/result.json"
+            else:
+                if isinstance(raw_json, bytes):
+                    raw_json = raw_json.decode('utf-8')
+
+                try:
+                    strict = self.schema_options.mode == 'strict'
+                    data = validate_and_parse(raw_json, self._schema, strict=strict)
+                except Exception as e:
+                    error = f"Schema validation failed: {e}"
+                    raw_data = raw_json
+
+        # CASE 2: JSON Schema dict → Use TS validation (backward compatible)
+        elif self._schema_json is not None:
+            data = response.get('data')
+            error = response.get('error')
+            raw_data = response.get('raw_data')
+
+        # CASE 3: No schema → Just return files (data stays None)
+
+        return OutputResult(
+            files=files,
+            data=data,
+            error=error,
+            raw_data=raw_data,
+        )
+
+    # =========================================================================
+    # STORAGE / CHECKPOINTING
+    # =========================================================================
+
+    async def checkpoint(self, comment: Optional[str] = None) -> CheckpointInfo:
+        """Create an explicit checkpoint of the current sandbox state.
+
+        Requires a prior run() call (needs an active sandbox to snapshot).
+
+        Args:
+            comment: Optional label for this checkpoint
+
+        Returns:
+            CheckpointInfo with id, hash, tag, timestamp, etc.
+
+        Example:
+            >>> info = await evolve.checkpoint(comment='before refactor')
+            >>> print(f'Checkpoint: {info.id}')
+        """
+        await self._ensure_initialized()
+        params: Dict[str, Any] = {}
+        if comment is not None:
+            params['comment'] = comment
+        response = await self.bridge.call('checkpoint', params, timeout_s=self._get_rpc_timeout_s(None))
+        return _require_checkpoint(response)
+
+    async def list_checkpoints(
+        self,
+        limit: Optional[int] = None,
+        tag: Optional[str] = None,
+    ) -> List[CheckpointInfo]:
+        """List checkpoints (requires storage configuration).
+
+        Does not require a running sandbox — only storage configuration.
+
+        Args:
+            limit: Maximum number of checkpoints to return
+            tag: Filter by session tag
+
+        Returns:
+            List of CheckpointInfo sorted by newest first
+
+        Example:
+            >>> checkpoints = await evolve.list_checkpoints(limit=5)
+            >>> for cp in checkpoints:
+            ...     print(f'{cp.id} ({cp.comment})')
+        """
+        await self._ensure_initialized()
+        params: Dict[str, Any] = {}
+        if limit is not None:
+            params['limit'] = limit
+        if tag is not None:
+            params['tag'] = tag
+        response = await self.bridge.call('list_checkpoints', params, timeout_s=self._get_rpc_timeout_s(None))
+        return [_require_checkpoint(cp) for cp in response]
+
+    def storage(self) -> StorageClient:
+        """Get a StorageClient bound to this instance's storage configuration.
+
+        Same API surface as the standalone ``storage()`` factory, but uses
+        the Evolve instance's bridge and gateway credentials.
+
+        Returns:
+            StorageClient with list_checkpoints, get_checkpoint,
+            download_checkpoint, download_files methods
+
+        Raises:
+            RuntimeError: If storage is not configured
+
+        Example:
+            >>> store = evolve.storage()
+            >>> checkpoints = await store.list_checkpoints(limit=5)
+            >>> files = await store.download_files(checkpoints[0].id)
+        """
+        if self._storage_config is None:
+            raise RuntimeError("Storage not configured. Pass storage=StorageConfig() to Evolve().")
+        return StorageClient(self.bridge, storage_config=None, _init_fn=self._ensure_initialized)
+
+    async def get_session(self) -> Optional[str]:
+        """Get sandbox ID for reuse.
+
+        Returns:
+            Sandbox ID or None if not initialized
+
+        Example:
+            >>> sandbox_id = await evolve.get_session()
+            >>> print(f'Sandbox ID: {sandbox_id}')
+        """
+        await self._ensure_initialized()
+        return await self.bridge.call('get_session')
+
+    async def prepare_sandbox(self) -> str:
+        """Create and initialize the sandbox without starting the agent."""
+        await self._ensure_initialized()
+        sandbox_id = await self.bridge.call('prepare_sandbox')
+        if not isinstance(sandbox_id, str) or not sandbox_id:
+            raise RuntimeError('Sandbox preparation did not return a sandbox ID')
+        return sandbox_id
+
+    async def set_session(self, session_id: str):
+        """Change sandbox session.
+
+        Args:
+            session_id: New sandbox ID to connect to
+
+        Example:
+            >>> await evolve.set_session('existing-sandbox-id')
+        """
+        await self._ensure_initialized()
+        await self.bridge.call('set_session', {
+            'session_id': session_id,
+        })
+
+    async def pause(self):
+        """Pause sandbox to save costs while preserving state.
+
+        Example:
+            >>> await evolve.pause()
+        """
+        await self._ensure_initialized()
+        await self.bridge.call('pause')
+
+    async def interrupt(self) -> bool:
+        """Interrupt active process without killing the sandbox.
+
+        Returns:
+            True if an active process was interrupted; False otherwise.
+        """
+        await self._ensure_initialized()
+        interrupted = await self.bridge.call('interrupt')
+        return bool(interrupted)
+
+    async def status(self) -> SessionStatus:
+        """Get runtime status snapshot for sandbox and agent."""
+        await self._ensure_initialized()
+        response = await self.bridge.call('status')
+        return SessionStatus(
+            sandbox_id=response.get('sandbox_id'),
+            sandbox=response.get('sandbox', 'stopped'),
+            agent=response.get('agent', 'idle'),
+            active_process_id=response.get('active_process_id'),
+            has_run=bool(response.get('has_run', False)),
+            timestamp=response.get('timestamp', ''),
+            browser=response.get('browser'),
+        )
+
+    async def resume(self):
+        """Resume paused sandbox.
+
+        Example:
+            >>> await evolve.resume()
+        """
+        await self._ensure_initialized()
+        await self.bridge.call('resume')
+
+    async def kill(self):
+        """Terminate sandbox and release all resources.
+
+        Example:
+            >>> await evolve.kill()
+        """
+        await self._ensure_initialized()
+        try:
+            await self.bridge.call('kill')
+        finally:
+            # Always stop bridge even if RPC fails (e.g., sandbox already gone)
+            await self.bridge.stop()
+            self._initialized = False
+
+    async def get_host(self, port: int) -> str:
+        """Get public URL for sandbox port.
+
+        Args:
+            port: Port number to expose
+
+        Returns:
+            Public URL for the port
+
+        Example:
+            >>> url = await evolve.get_host(8000)
+            >>> print(f'Server available at: {url}')
+        """
+        await self._ensure_initialized()
+        response = await self.bridge.call('get_host', {
+            'port': port,
+        })
+        return response['url']
+
+    async def get_session_tag(self) -> Optional[str]:
+        """Get the observability session tag.
+
+        Returns the generated tag (e.g., 'my-prefix-a3f8b2c1') used for the
+        log file in ~/.evolve-sdk/observability/sessions/
+
+        Returns:
+            Session tag or None if not initialized
+
+        Example:
+            >>> tag = await evolve.get_session_tag()
+            >>> print(f'Log file tag: {tag}')
+            'experiment-7-a3f8b2c1'
+        """
+        await self._ensure_initialized()
+        return await self.bridge.call('get_session_tag')
+
+    async def get_session_timestamp(self) -> Optional[str]:
+        """Get the session start timestamp (ISO format).
+
+        Returns:
+            ISO timestamp when session was created or None if not initialized
+
+        Example:
+            >>> timestamp = await evolve.get_session_timestamp()
+            >>> print(f'Session started: {timestamp}')
+            '2025-01-15T10:30:45.123Z'
+        """
+        await self._ensure_initialized()
+        return await self.bridge.call('get_session_timestamp')
+
+    # =========================================================================
+    # COST
+    # =========================================================================
+
+    async def get_session_cost(self) -> SessionCost:
+        """Get cost breakdown for the current session (all runs).
+
+        Cost data can lag live usage by about a minute.
+        Note: after kill(), the bridge process is stopped. To query costs for a
+        completed session, create a new Evolve instance — the TS bridge handles
+        previousSessionTag fallback internally.
+
+        Requires gateway mode (EVOLVE_API_KEY).
+
+        Returns:
+            SessionCost with total cost, token counts, and per-run breakdown
+
+        Example:
+            >>> cost = await evolve.get_session_cost()
+            >>> print(f'Total: ${cost.total_cost:.4f}')
+            >>> for run in cost.runs:
+            ...     print(f'  Run {run.index}: ${run.cost:.4f} ({run.model})')
+        """
+        await self._ensure_initialized()
+        response = await self.bridge.call('get_session_cost')
+        return self._parse_session_cost(response)
+
+    async def get_run_cost(
+        self,
+        *,
+        run_id: Optional[str] = None,
+        index: Optional[int] = None,
+    ) -> RunCost:
+        """Get cost for a specific run by ID or index.
+
+        Args:
+            run_id: Run ID from AgentResponse.run_id
+            index: 1-based chronological position (negative = from end, e.g. -1 = last run)
+
+        Returns:
+            RunCost with cost, tokens, model, and completion status
+
+        Example:
+            >>> # By run ID
+            >>> result = await evolve.run('Analyze data')
+            >>> cost = await evolve.get_run_cost(run_id=result.run_id)
+            >>> # By index (last run)
+            >>> cost = await evolve.get_run_cost(index=-1)
+        """
+        if run_id is not None and index is not None:
+            raise ValueError('Specify run_id or index, not both')
+        if run_id is None and index is None:
+            raise ValueError('Specify either run_id or index')
+        await self._ensure_initialized()
+        params: Dict[str, Any] = {}
+        if run_id is not None:
+            params['run_id'] = run_id
+        if index is not None:
+            params['index'] = index
+        response = await self.bridge.call('get_run_cost', params)
+        return self._parse_run_cost(response)
+
+    @staticmethod
+    def _parse_run_cost(data: Dict[str, Any]) -> RunCost:
+        """Parse run cost dict from bridge response into RunCost."""
+        return RunCost(
+            run_id=data['run_id'],
+            index=data['index'],
+            cost=data['cost'],
+            tokens=data['tokens'],
+            model=data['model'],
+            requests=data['requests'],
+            as_of=data['as_of'],
+            is_complete=data['is_complete'],
+            truncated=data['truncated'],
+        )
+
+    @classmethod
+    def _parse_session_cost(cls, data: Dict[str, Any]) -> SessionCost:
+        """Parse session cost dict from bridge response into SessionCost."""
+        return SessionCost(
+            session_tag=data['session_tag'],
+            total_cost=data['total_cost'],
+            total_tokens=data['total_tokens'],
+            runs=[cls._parse_run_cost(r) for r in data.get('runs', [])],
+            as_of=data['as_of'],
+            is_complete=data['is_complete'],
+            truncated=data['truncated'],
+        )
+
+    async def __aenter__(self):
+        """Context manager entry."""
+        try:
+            await self._ensure_initialized()
+            return self
+        except Exception:
+            # Cleanup bridge process if initialization fails
+            await self.bridge.stop()
+            raise
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - cleanup resources."""
+        try:
+            await self.kill()
+        except Exception as e:
+            import warnings
+            warnings.warn(f"Error during cleanup: {e}", RuntimeWarning)