steerdev 0.4.27__py3-none-any.whl

steerdev_agent/runner.py

@@ -0,0 +1,829 @@
+"""Simplified runner for steerdev using direct subprocess execution."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+from uuid import UUID, uuid4
+
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+
+from steerdev_agent.api.events import EventsClient
+from steerdev_agent.api.runs import RunCreateRequest, RunsClient
+from steerdev_agent.api.sessions import SessionCreateRequest, SessionsClient
+from steerdev_agent.api.tasks import TasksClient
+from steerdev_agent.config.models import ExecutorConfig
+from steerdev_agent.executor import ExecutorFactory
+from steerdev_agent.executor.base import AgentExecutor, EventType, StreamEvent
+from steerdev_agent.executor.claude import ClaudeExecutorError
+from steerdev_agent.prompt.builder import (
+    ProjectContext,
+    PromptBuilder,
+    PromptContext,
+    TaskContext,
+    WaveContext,
+)
+
+console = Console()
+
+
+class RunnerError(Exception):
+    """Error during runner execution."""
+
+
+class RunState(str, Enum):
+    """State machine states for the runner."""
+
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+
+
+class Runner:
+    """Simplified runner that executes CLI agents via subprocess.
+
+    This class:
+    - Fetches tasks from the steerdev.com API
+    - Builds prompts using PromptBuilder
+    - Creates sessions via the API
+    - Executes agents (Claude Code) as subprocesses
+    - Streams events to the API for storage
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        working_directory: str | Path | None = None,
+        api_key: str | None = None,
+        agent_type: str = "claude",
+        agent_name: str | None = None,
+        model: str | None = None,
+        max_turns: int | None = None,
+        max_tasks: int = 1,
+        timeout_seconds: int = 3600,
+        enable_worktrees: bool = False,
+        executor_config: ExecutorConfig | None = None,
+        workflow_id: str | None = None,
+        dry_run: bool = False,
+    ) -> None:
+        """Initialize the runner.
+
+        Args:
+            project_id: SteerDev project ID.
+            working_directory: Directory to run the agent in.
+            api_key: API key for authentication.
+            agent_type: Type of agent to use (claude, codex, aider).
+            agent_name: Name of the agent (creates agent if needed).
+            model: Model to use for the agent.
+            max_turns: Maximum number of agent turns per task.
+            max_tasks: Maximum number of tasks to process (0 for unlimited).
+            timeout_seconds: Timeout for the entire run.
+            enable_worktrees: Enable Claude CLI --worktree isolation.
+            executor_config: Executor configuration (tools, permissions).
+            workflow_id: Workflow ID for multi-phase execution.
+            dry_run: If True, print the command without executing it.
+        """
+        self.project_id = project_id
+        self.working_directory = Path(working_directory or Path.cwd())
+        self._api_key = api_key
+        self.agent_type = agent_type
+        self.agent_name = agent_name
+        self.model = model
+        self.max_turns = max_turns
+        self.max_tasks = max_tasks if max_tasks != 0 else None  # 0 = unlimited
+        self.timeout_seconds = timeout_seconds
+        self.workflow_id = workflow_id
+        self.dry_run = dry_run
+
+        # Executor configuration
+        self._executor_config = executor_config or ExecutorConfig()
+
+        # Worktree configuration
+        self._enable_worktrees = enable_worktrees
+
+        # State
+        self._state = RunState.STOPPED
+        self._run_id = uuid4()
+        self._db_run_id: str | None = None  # Database primary key for the run record
+        self._session_id: str | None = None
+        self._started_at: datetime | None = None
+        self._stopped_at: datetime | None = None
+
+        # Stats
+        self._tasks_executed = 0
+        self._tasks_succeeded = 0
+        self._tasks_failed = 0
+        self._events_sent = 0
+
+        # Components
+        self._sessions_client: SessionsClient | None = None
+        self._events_client: EventsClient | None = None
+        self._executor: AgentExecutor | None = None
+        self._prompt_builder = PromptBuilder()
+
+    @property
+    def run_id(self) -> UUID:
+        """Get the run ID."""
+        return self._run_id
+
+    @property
+    def session_id(self) -> str | None:
+        """Get the current session ID."""
+        return self._session_id
+
+    async def _create_session(
+        self,
+        task_id: str | None,
+        prompt: str,
+    ) -> str | None:
+        """Create a session via the API.
+
+        Args:
+            task_id: Optional task ID being executed.
+            prompt: The prompt being sent to the agent.
+
+        Returns:
+            Session ID or None on failure.
+        """
+        if self._sessions_client is None:
+            self._sessions_client = SessionsClient(api_key=self._api_key)
+
+        request = SessionCreateRequest(
+            project_id=self.project_id,
+            task_id=task_id,
+            agent_name=self.agent_name,
+            agent_type=self.agent_type,
+            prompt=prompt,
+            working_directory=str(self.working_directory),
+        )
+
+        session = await self._sessions_client.create_session(request)
+        if session:
+            self._session_id = session.id
+            logger.info(f"Session created: {session.id}")
+            return session.id
+
+        logger.warning("Failed to create session")
+        return None
+
+    async def _create_run_record(self) -> str | None:
+        """Create a run record in the API and return the database ID.
+
+        Returns:
+            The database primary key (id) for the run, or None on failure.
+        """
+        runs_client = RunsClient(api_key=self._api_key)
+
+        try:
+            request = RunCreateRequest(
+                run_id=str(self._run_id),
+                session_name=f"steerdev-{str(self._run_id)[:8]}",
+                working_directory=str(self.working_directory),
+                application=self.agent_type,
+            )
+
+            run = await runs_client.create_run(request)
+            if run:
+                logger.info(f"Run record created: {run.id}")
+                return run.id
+
+            logger.warning("Failed to create run record")
+            return None
+        finally:
+            await runs_client.close()
+
+    async def _stream_events_to_api(self, event: StreamEvent) -> None:
+        """Stream an event to the API.
+
+        Args:
+            event: The event to stream.
+        """
+        if self._events_client is None:
+            return
+
+        await self._events_client.add_event(
+            event_type=event.event_type.value,
+            data=event.data,
+            raw_json=event.raw_json,
+            timestamp=event.timestamp,
+        )
+        self._events_sent += 1
+
+    async def _execute_task(
+        self,
+        task: dict[str, Any],
+        project: dict[str, Any] | None = None,
+        wave_context: WaveContext | None = None,
+    ) -> dict[str, Any]:
+        """Execute a single task.
+
+        Args:
+            task: Task data from the API.
+            project: Optional project data.
+            wave_context: Optional wave context for wave-aware execution.
+
+        Returns:
+            Execution result.
+        """
+        task_id = task.get("id", "")
+        task_title = task.get("title", "Unknown")
+
+        console.print(f"\n[bold cyan]Starting task: {task_title}[/bold cyan]")
+        console.print(f"[dim]Task ID: {task_id}[/dim]")
+
+        # Check if workflow execution is enabled
+        if self.workflow_id:
+            return await self._execute_task_with_workflow(task)
+
+        # Build prompt
+        context = PromptContext(
+            project=ProjectContext(**project) if project else None,
+            task=TaskContext(
+                id=task_id,
+                title=task_title,
+                prompt=task.get("prompt", ""),
+                status=task.get("status", "unstarted"),
+                priority=task.get("priority", 3),
+                working_directory=task.get("working_directory"),
+                wave=wave_context,
+            ),
+        )
+        prompt = self._prompt_builder.build(context)
+
+        # Create session (skip in dry run mode)
+        if not self.dry_run:
+            session_id = await self._create_session(task_id, prompt)
+            if not session_id:
+                return {"success": False, "error": "Failed to create session"}
+        else:
+            session_id = "dry-run-session"
+
+        # Initialize events client (skip in dry run mode)
+        if not self.dry_run:
+            self._events_client = EventsClient(
+                session_id=session_id,
+                api_key=self._api_key,
+            )
+            await self._events_client.start()
+
+        # Mark session as running (skip in dry run mode)
+        if self._sessions_client and not self.dry_run:
+            await self._sessions_client.mark_running(session_id)
+
+        # Compute worktree name if enabled
+        worktree_name: str | None = None
+        if self._enable_worktrees and not self.dry_run:
+            if wave_context:
+                worktree_name = f"wave-{wave_context.wave_number}"
+            else:
+                task_short = task_id[:8] if len(task_id) > 8 else task_id
+                worktree_name = f"task-{task_short}"
+            console.print(f"[dim]Using worktree: {worktree_name}[/dim]")
+
+        # Create executor using factory
+        self._executor = ExecutorFactory.create(
+            config=self._executor_config,
+            working_directory=str(self.working_directory),
+            model=self.model,
+            max_turns=self.max_turns,
+            dry_run=self.dry_run,
+            worktree_name=worktree_name,
+        )
+
+        try:
+            # Start the agent
+            await self._executor.start(prompt)
+            console.print("[dim]Agent started, streaming output...[/dim]")
+
+            # Stream events
+            async for event in self._executor.stream_events():
+                await self._stream_events_to_api(event)
+
+                # Log key events
+                if event.event_type == EventType.ASSISTANT:
+                    message = event.data.get("message", {})
+                    content = message.get("content", "")
+                    if isinstance(content, str):
+                        preview = content[:100] + "..." if len(content) > 100 else content
+                        console.print(f"[cyan]Assistant:[/cyan] {preview}")
+
+                if event.is_final:
+                    console.print("[green]Agent completed[/green]")
+
+            # Wait for completion
+            exit_code = await self._executor.wait()
+
+            # Update session with agent session ID (skip in dry run mode)
+            agent_session_id = self._executor.session_id
+
+            # Check for failure and get stderr
+            if exit_code != 0:
+                stderr = await self._executor.get_stderr()
+                error_msg = stderr.strip() if stderr else f"Process exited with code {exit_code}"
+                logger.error(f"Claude failed with exit code {exit_code}: {error_msg}")
+                if self._sessions_client and not self.dry_run:
+                    await self._sessions_client.mark_failed(
+                        session_id,
+                        metadata={"error": error_msg, "exit_code": exit_code},
+                    )
+                return {
+                    "success": False,
+                    "exit_code": exit_code,
+                    "error": error_msg,
+                    "agent_session_id": agent_session_id,
+                    "events_sent": self._events_sent,
+                }
+
+            if self._sessions_client and agent_session_id and not self.dry_run:
+                await self._sessions_client.mark_completed(
+                    session_id,
+                    agent_session_id=agent_session_id,
+                )
+
+            return {
+                "success": True,
+                "exit_code": exit_code,
+                "agent_session_id": agent_session_id,
+                "events_sent": self._events_sent,
+            }
+
+        except ClaudeExecutorError as e:
+            logger.error(f"Executor error: {e}")
+            if self._sessions_client and not self.dry_run:
+                await self._sessions_client.mark_failed(
+                    session_id,
+                    metadata={"error": str(e)},
+                )
+            return {"success": False, "error": str(e)}
+
+        finally:
+            # Stop events client
+            if self._events_client:
+                await self._events_client.close()
+                self._events_client = None
+
+            # Stop executor if still running
+            if self._executor and self._executor.is_running:
+                await self._executor.stop()
+            self._executor = None
+
+    async def _execute_task_with_workflow(
+        self,
+        task: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Execute a task using workflow-based multi-phase execution.
+
+        Args:
+            task: Task data from the API.
+
+        Returns:
+            Execution result.
+        """
+        from steerdev_agent.workflow import WorkflowExecutor
+
+        task_id = task.get("id", "")
+        task_title = task.get("title", "Unknown")
+
+        console.print(f"[dim]Using workflow: {self.workflow_id}[/dim]")
+
+        # Build task context for workflow
+        task_context = {
+            "task_id": task_id,
+            "task_title": task_title,
+            "task_prompt": task.get("prompt", ""),
+            "task_status": task.get("status", "unstarted"),
+            "task_priority": task.get("priority", 3),
+        }
+
+        # Create workflow executor
+        workflow_executor = WorkflowExecutor(
+            working_directory=self.working_directory,
+            api_key=self._api_key,
+            executor_config=self._executor_config,
+            model=self.model,
+            max_turns=self.max_turns,
+            dry_run=self.dry_run,
+            project_id=self.project_id,
+            agent_type=self.agent_type,
+        )
+
+        try:
+            result = await workflow_executor.execute_workflow(
+                workflow_id=self.workflow_id,  # type: ignore  # workflow_id is checked before call
+                task_context=task_context,
+                run_id=self._db_run_id,  # Pass the database ID, not the client-generated UUID
+            )
+
+            return {
+                "success": result.get("success", False),
+                "workflow_run_id": result.get("workflow_run_id"),
+                "phases_completed": result.get("phases_completed", 0),
+                "phases_failed": result.get("phases_failed", 0),
+                "total_phases": result.get("total_phases", 0),
+            }
+
+        except Exception as e:
+            logger.error(f"Workflow execution failed: {e}")
+            return {"success": False, "error": str(e)}
+
+    async def run(
+        self,
+        task_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Run the agent.
+
+        If task_id is provided, runs that specific task.
+        Otherwise, fetches the next available task.
+
+        Args:
+            task_id: Optional specific task ID to run.
+
+        Returns:
+            Run result metadata.
+        """
+        self._state = RunState.STARTING
+        self._started_at = datetime.now(UTC)
+        run_error: Exception | None = None
+
+        console.print(
+            Panel(
+                f"[bold blue]SteerDev Agent[/bold blue]\n"
+                f"Project ID: {self.project_id}\n"
+                f"Working Directory: {self.working_directory}\n"
+                f"Agent Type: {self.agent_type}\n"
+                f"Timeout: {self.timeout_seconds}s",
+                title="Starting",
+            )
+        )
+
+        try:
+            self._state = RunState.RUNNING
+
+            # Create run record for tracking (only needed for workflow execution)
+            if self.workflow_id and not self.dry_run:
+                self._db_run_id = await self._create_run_record()
+                if not self._db_run_id:
+                    logger.warning(
+                        "Could not create run record, workflow associations will be null"
+                    )
+
+            # If specific task_id provided, just run that one task
+            if task_id:
+                with TasksClient(api_key=self._api_key) as client:
+                    task = client.get_task(task_id)
+                    if not task:
+                        raise RunnerError(f"Task not found: {task_id}")
+
+                self._tasks_executed += 1
+                result = await self._execute_task(task)
+
+                if result.get("success"):
+                    self._tasks_succeeded += 1
+                    console.print("[green]Task completed successfully[/green]")
+                else:
+                    self._tasks_failed += 1
+                    console.print(f"[red]Task failed: {result.get('error', 'Unknown')}[/red]")
+            else:
+                # Multi-task loop
+                tasks_remaining = self.max_tasks  # None = unlimited
+
+                while tasks_remaining is None or tasks_remaining > 0:
+                    # Try wave-aware fetch first, then fall back to single-task
+                    task = None
+                    wave_ctx: WaveContext | None = None
+
+                    with TasksClient(api_key=self._api_key) as client:
+                        wave_response = client.get_next_wave(project_id=self.project_id)
+                        if wave_response and "context" in wave_response:
+                            next_task_data = wave_response.get("context", {}).get("next_task")
+                            if next_task_data:
+                                task = next_task_data
+                                # Build wave context for the prompt
+                                wave_info = wave_response.get("wave", {})
+                                ctx = wave_response.get("context", {})
+                                wave_tasks = wave_response.get("tasks", [])
+
+                                # Build tasks summary
+                                task_lines = []
+                                for wt in wave_tasks:
+                                    status_icon = {
+                                        "completed": "[done]",
+                                        "started": "[in-progress]",
+                                        "canceled": "[canceled]",
+                                    }.get(wt.get("status", ""), "[todo]")
+                                    task_lines.append(
+                                        f"  {status_icon} {wt.get('title', 'Unknown')}"
+                                    )
+                                tasks_summary = "\n".join(task_lines)
+
+                                # Build completed waves summary
+                                completed = ctx.get("completed_waves", [])
+                                completed_lines = [
+                                    f"  - Wave {cw.get('wave_number', '?')}: {cw.get('description', '')}"
+                                    for cw in completed
+                                ]
+                                completed_summary = (
+                                    "\n".join(completed_lines) if completed_lines else ""
+                                )
+
+                                wave_ctx = WaveContext(
+                                    wave_number=wave_info.get("wave_number", 1),
+                                    total_waves=wave_info.get("total_waves", 1),
+                                    wave_description=wave_info.get("description", ""),
+                                    wave_tasks_summary=tasks_summary,
+                                    completed_waves_summary=completed_summary,
+                                )
+
+                        if not task:
+                            task = client.get_next_task(project_id=self.project_id)
+
+                    if not task:
+                        if self._tasks_executed == 0:
+                            console.print("[yellow]No tasks available[/yellow]")
+                        else:
+                            console.print("[yellow]No more tasks available[/yellow]")
+                        break
+
+                    # Execute task
+                    self._tasks_executed += 1
+                    task_title = task.get("title", "Unknown")
+                    console.print(f"\n[bold]Task {self._tasks_executed}: {task_title}[/bold]")
+
+                    result = await self._execute_task(task, wave_context=wave_ctx)
+
+                    if result.get("success"):
+                        self._tasks_succeeded += 1
+                        console.print("[green]Task completed successfully[/green]")
+                    else:
+                        self._tasks_failed += 1
+                        console.print(f"[red]Task failed: {result.get('error', 'Unknown')}[/red]")
+                        # Continue to next task on failure
+
+                    # Decrement counter if not unlimited
+                    if tasks_remaining is not None:
+                        tasks_remaining -= 1
+
+        except Exception as e:
+            logger.exception(f"Error during run: {e}")
+            console.print(f"\n[red]Error during run: {e}[/red]")
+            run_error = e
+
+        finally:
+            self._state = RunState.STOPPING
+            self._stopped_at = datetime.now(UTC)
+
+            # Complete or fail the run record
+            if self._db_run_id:
+                runs_client = RunsClient(api_key=self._api_key)
+                try:
+                    if run_error:
+                        await runs_client.fail_run(
+                            self._db_run_id,
+                            error_message=str(run_error),
+                        )
+                    else:
+                        await runs_client.complete_run(
+                            self._db_run_id,
+                            tasks_executed=self._tasks_executed,
+                            tasks_succeeded=self._tasks_succeeded,
+                            tasks_failed=self._tasks_failed,
+                        )
+                finally:
+                    await runs_client.close()
+
+            # Cleanup
+            if self._sessions_client:
+                await self._sessions_client.close()
+                self._sessions_client = None
+
+            self._state = RunState.STOPPED
+
+        # Calculate duration
+        duration = 0.0
+        if self._started_at and self._stopped_at:
+            duration = (self._stopped_at - self._started_at).total_seconds()
+
+        # Show summary
+        console.print("\n" + "=" * 60)
+        console.print("[bold]Run Summary[/bold]")
+        console.print(f"  Run ID: {self._run_id}")
+        console.print(f"  Tasks Executed: {self._tasks_executed}")
+        console.print(f"  Succeeded: {self._tasks_succeeded}")
+        console.print(f"  Failed: {self._tasks_failed}")
+        console.print(f"  Events Sent: {self._events_sent}")
+        console.print(f"  Duration: {duration:.1f}s")
+
+        return {
+            "run_id": str(self._run_id),
+            "session_id": self._session_id,
+            "started_at": self._started_at.isoformat() if self._started_at else None,
+            "stopped_at": self._stopped_at.isoformat() if self._stopped_at else None,
+            "duration_seconds": duration,
+            "tasks_executed": self._tasks_executed,
+            "tasks_succeeded": self._tasks_succeeded,
+            "tasks_failed": self._tasks_failed,
+            "events_sent": self._events_sent,
+            "error": str(run_error) if run_error else None,
+        }
+
+    async def resume(
+        self,
+        session_id: str,
+        message: str,
+    ) -> dict[str, Any]:
+        """Resume an existing session with a new message.
+
+        Args:
+            session_id: The session ID to resume.
+            message: The message to continue with.
+
+        Returns:
+            Run result metadata.
+        """
+        self._state = RunState.STARTING
+        self._started_at = datetime.now(UTC)
+
+        console.print(
+            Panel(
+                f"[bold blue]Resuming Session[/bold blue]\n"
+                f"Session ID: {session_id}\n"
+                f"Message: {message[:100]}...",
+                title="Resume",
+            )
+        )
+
+        try:
+            self._state = RunState.RUNNING
+
+            # Get session details
+            self._sessions_client = SessionsClient(api_key=self._api_key)
+            session = await self._sessions_client.get_session(session_id)
+
+            if not session:
+                raise RunnerError(f"Session not found: {session_id}")
+
+            if not session.agent_session_id:
+                raise RunnerError("Session has no agent_session_id for resume")
+
+            # Initialize events client
+            self._events_client = EventsClient(
+                session_id=session_id,
+                api_key=self._api_key,
+            )
+            await self._events_client.start()
+
+            # Create executor using factory
+            self._executor = ExecutorFactory.create(
+                config=self._executor_config,
+                working_directory=session.working_directory,
+                model=self.model,
+                dry_run=self.dry_run,
+            )
+
+            # Resume the session
+            await self._executor.resume(session.agent_session_id, message)
+            console.print("[dim]Session resumed, streaming output...[/dim]")
+
+            # Stream events
+            async for event in self._executor.stream_events():
+                await self._stream_events_to_api(event)
+
+                if event.event_type == EventType.ASSISTANT:
+                    msg = event.data.get("message", {})
+                    content = msg.get("content", "")
+                    if isinstance(content, str):
+                        preview = content[:100] + "..." if len(content) > 100 else content
+                        console.print(f"[cyan]Assistant:[/cyan] {preview}")
+
+            # Wait for completion
+            exit_code = await self._executor.wait()
+
+            # Update session
+            new_agent_session_id = self._executor.session_id
+            if new_agent_session_id:
+                await self._sessions_client.mark_completed(
+                    session_id,
+                    agent_session_id=new_agent_session_id,
+                )
+
+            return {
+                "success": exit_code == 0,
+                "exit_code": exit_code,
+                "agent_session_id": new_agent_session_id,
+                "events_sent": self._events_sent,
+            }
+
+        except Exception as e:
+            logger.exception(f"Error during resume: {e}")
+            console.print(f"\n[red]Error during resume: {e}[/red]")
+            return {"success": False, "error": str(e)}
+
+        finally:
+            self._state = RunState.STOPPING
+            self._stopped_at = datetime.now(UTC)
+
+            if self._events_client:
+                await self._events_client.close()
+            if self._sessions_client:
+                await self._sessions_client.close()
+            if self._executor and self._executor.is_running:
+                await self._executor.stop()
+
+            self._state = RunState.STOPPED
+
+
+async def run_agent(
+    project_id: str,
+    task_id: str | None = None,
+    working_directory: str | None = None,
+    api_key: str | None = None,
+    agent_type: str = "claude",
+    agent_name: str | None = None,
+    model: str | None = None,
+    max_turns: int | None = None,
+    max_tasks: int = 1,
+    timeout_seconds: int = 3600,
+    enable_worktrees: bool = False,
+    executor_config: ExecutorConfig | None = None,
+    workflow_id: str | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Run the steerdev agent.
+
+    Convenience function for running the agent with minimal setup.
+
+    Args:
+        project_id: SteerDev project ID.
+        task_id: Optional specific task ID to run.
+        working_directory: Directory to run the agent in.
+        api_key: API key for authentication.
+        agent_type: Type of agent to use.
+        agent_name: Name of the agent (creates agent if needed).
+        model: Model to use for the agent.
+        max_turns: Maximum number of agent turns per task.
+        max_tasks: Maximum number of tasks to process (0 for unlimited).
+        timeout_seconds: Timeout for the entire run.
+        enable_worktrees: Enable Claude CLI --worktree isolation.
+        executor_config: Executor configuration (tools, permissions).
+        workflow_id: Workflow ID for multi-phase execution.
+        dry_run: If True, print the command without executing it.
+
+    Returns:
+        Run result metadata.
+    """
+    runner = Runner(
+        project_id=project_id,
+        working_directory=working_directory,
+        api_key=api_key,
+        agent_type=agent_type,
+        agent_name=agent_name,
+        model=model,
+        max_turns=max_turns,
+        max_tasks=max_tasks,
+        timeout_seconds=timeout_seconds,
+        enable_worktrees=enable_worktrees,
+        executor_config=executor_config,
+        workflow_id=workflow_id,
+        dry_run=dry_run,
+    )
+    return await runner.run(task_id=task_id)
+
+
+async def resume_session(
+    session_id: str,
+    message: str,
+    api_key: str | None = None,
+    model: str | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Resume an existing session.
+
+    Args:
+        session_id: The session ID to resume.
+        message: The message to continue with.
+        api_key: API key for authentication.
+        model: Model to use for the agent.
+        dry_run: If True, print the command without executing it.
+
+    Returns:
+        Run result metadata.
+    """
+    # Get session to find project_id
+    async with SessionsClient(api_key=api_key) as client:
+        session = await client.get_session(session_id)
+        if not session:
+            raise RunnerError(f"Session not found: {session_id}")
+
+        runner = Runner(
+            project_id=session.project_id,
+            working_directory=session.working_directory,
+            api_key=api_key,
+            model=model,
+            dry_run=dry_run,
+        )
+        return await runner.resume(session_id, message)