pidriver 0.2.0__tar.gz → 0.4.1__tar.gz

{pidriver-0.2.0 → pidriver-0.4.1}/.gitignore

@@ -31,3 +31,4 @@ scratch/
 
 # Secrets (PyPI token, etc.)
 .env
+.empryo

{pidriver-0.2.0 → pidriver-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pidriver
-Version: 0.2.0
+Version: 0.4.1
 Summary: Async Python driver for the pi coding agent (pi --mode rpc), built for isolated, headless project work.
 Project-URL: Homepage, https://github.com/bobuk/pidriver
 Project-URL: Repository, https://github.com/bobuk/pidriver
@@ -20,6 +20,8 @@ Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: web
+Requires-Dist: uvicorn>=0.30; extra == 'web'
 Description-Content-Type: text/markdown
 
 # pidriver
@@ -152,7 +154,7 @@ PiConfig(provider="anthropic", model="claude-sonnet-4-6",
 | `install_dir` | `None` | Where to `npm install`/look for a managed `pi` binary. |
 | `auto_install` | `True` | `npm install` `pi` into `install_dir` if the binary can't be resolved. |
 | `npm_package` | `"@earendil-works/pi-coding-agent"` | The npm package that provides `pi`. |
-| `pi_version` | `"0.78.1"` | Pinned pi version to install (overridable). |
+| `pi_version` | `"0.87.1"` | Pinned pi version to install (overridable). |
 | `extensions` | `()` | Add-on sources (`npm:…`, `git:…`, path) installed via `pi install` before start. |
 
 **Model / provider**
@@ -240,6 +242,9 @@ You don't have to install a CLI yourself. Upstream `pi` is an npm package, and p
 When the transport starts, it resolves the binary in order — explicit `binary` path →
 `install_dir/bin/pi` → `PATH`. If none resolves and `auto_install=True` (default), it runs
 `npm install -g --prefix <install_dir> <npm_package>@<pi_version>` and runs `<install_dir>/bin/pi`.
+An existing managed copy is upgraded when its version differs from `pi_version` and
+`auto_install=True`. A `pi` already found on `PATH` (or set via an absolute `binary`)
+is used as-is; update that installation separately if needed.
 
 ```python
 from pidriver import ensure_binary, install_pi, ensure_extensions  # also exported for explicit use
@@ -522,6 +527,44 @@ handler = chain(
 )
 ```
 
+## Tasks in remote Git repositories
+
+Use `start_repository_task` with a trusted Git URL selected by the host. It clones the
+repository, creates a per-job worktree, and starts pi in that worktree. No changes are
+published until the host explicitly calls `merge()`; `discard()` deletes the local clone
+without changing the remote. For SSH, pass a private-key path; otherwise Git uses the host's credentials.
+
+```python
+from pathlib import Path
+from pidriver import PiClient, PiConfig, start_repository_task
+
+client = PiClient(PiConfig())
+session, workspace = await start_repository_task(
+    client, "Fix the failing tests", "git+ssh://git@github.com/org/project.git",
+    root=Path("/srv/pi-jobs"), job_id="task-123",
+    ssh_key=Path("/srv/keys/project_ed25519"),
+)
+# Drain the session's events, then close it before finalizing the workspace.
+async for event in session:
+    ...
+await session.aclose()
+
+print(workspace.diff())  # review before deciding
+state = workspace.to_state()  # save for approval after a host restart if needed
+# workspace = GitRepositoryWorkspace.from_state(state)
+workspace.merge()   # commits, merges and pushes to the cloned default branch
+workspace.cleanup() # remove the local clone after successful push
+# Or: workspace.discard()  # no changes to origin
+```
+
+If the remote branch has moved, the push is rejected with `MergeConflict`; the local
+workspace remains available for inspection. Never accept arbitrary repository URLs from
+untrusted requests: the caller must enforce an allowlist. Empty repositories and a
+second job with the same ID are rejected. SSH also accepts standard `ssh://` and
+`git@host:path` URLs. The key path (not its contents) is saved by `to_state()` for
+later pushes; the key must still exist then. SSH uses strict host-key checking and
+non-interactive authentication; configure `known_hosts` on the host in advance.
+
 ## Workspace jail
 
 Run an agent loose inside a project without letting it run anywhere on disk. `resolve_project`
@@ -574,6 +617,41 @@ await login.submit_code(info["session"], code)     # accepts a bare code or a ca
 locates pi's bundled Node libraries (package identity from `config.npm_package`, so the omp fork
 works too) — both exported for hosts building their own extension/auth tooling.
 
+## Web instance service
+
+The web subsystem is an optional layer over the same driver core. `pidriver` stays
+dependency-free by default; install the web extra only for the ASGI server:
+
+```sh
+uv pip install -e ".[web]"
+uv run pidriver-web --store pidriver.sqlite3 \
+  --projects-root /srv/projects --allow-project acme
+```
+
+Core pieces:
+
+- `PiInstanceSupervisor` drains every `PiSession` in one background task, persists event history,
+  broadcasts events to subscribers, and exposes `prompt` / `respond` / `cancel` / `stop`.
+- `PiInstanceStore` stores snapshots and event logs in SQLite. On service restart, previously live
+  subprocesses are marked `stale` because they cannot be reattached.
+- `PiWebApp` is a small ASGI app with JSON endpoints and SSE streaming.
+
+Useful routes:
+
+| Route | Purpose |
+| --- | --- |
+| `GET /` | Minimal dashboard for launching and watching instances. |
+| `GET /api/projects` | List project-jail candidates. |
+| `GET /api/models` | List models visible to this isolated pi config. |
+| `POST /api/instances` | Start an instance from `{prompt, project, model, approval_policy}`. |
+| `GET /api/instances` / `GET /api/instances/{id}` | List or inspect snapshots. |
+| `GET /api/instances/{id}/events` | Read persisted event history. |
+| `GET /api/instances/{id}/events/stream` | SSE stream for live events. |
+| `POST /api/instances/{id}/prompt` | Send a follow-up prompt. |
+| `POST /api/instances/{id}/respond` | Answer a pending interaction. |
+| `POST /api/instances/{id}/cancel` / `POST /api/instances/{id}/stop` | Interrupt or terminate. |
+| `GET /api/auth/providers` / `POST /api/auth/{provider}/start` | OAuth helper endpoints. |
+
 ## Development
 
 ```sh

{pidriver-0.2.0 → pidriver-0.4.1}/README.md

@@ -128,7 +128,7 @@ PiConfig(provider="anthropic", model="claude-sonnet-4-6",
 | `install_dir` | `None` | Where to `npm install`/look for a managed `pi` binary. |
 | `auto_install` | `True` | `npm install` `pi` into `install_dir` if the binary can't be resolved. |
 | `npm_package` | `"@earendil-works/pi-coding-agent"` | The npm package that provides `pi`. |
-| `pi_version` | `"0.78.1"` | Pinned pi version to install (overridable). |
+| `pi_version` | `"0.87.1"` | Pinned pi version to install (overridable). |
 | `extensions` | `()` | Add-on sources (`npm:…`, `git:…`, path) installed via `pi install` before start. |
 
 **Model / provider**
@@ -216,6 +216,9 @@ You don't have to install a CLI yourself. Upstream `pi` is an npm package, and p
 When the transport starts, it resolves the binary in order — explicit `binary` path →
 `install_dir/bin/pi` → `PATH`. If none resolves and `auto_install=True` (default), it runs
 `npm install -g --prefix <install_dir> <npm_package>@<pi_version>` and runs `<install_dir>/bin/pi`.
+An existing managed copy is upgraded when its version differs from `pi_version` and
+`auto_install=True`. A `pi` already found on `PATH` (or set via an absolute `binary`)
+is used as-is; update that installation separately if needed.
 
 ```python
 from pidriver import ensure_binary, install_pi, ensure_extensions  # also exported for explicit use
@@ -498,6 +501,44 @@ handler = chain(
 )
 ```
 
+## Tasks in remote Git repositories
+
+Use `start_repository_task` with a trusted Git URL selected by the host. It clones the
+repository, creates a per-job worktree, and starts pi in that worktree. No changes are
+published until the host explicitly calls `merge()`; `discard()` deletes the local clone
+without changing the remote. For SSH, pass a private-key path; otherwise Git uses the host's credentials.
+
+```python
+from pathlib import Path
+from pidriver import PiClient, PiConfig, start_repository_task
+
+client = PiClient(PiConfig())
+session, workspace = await start_repository_task(
+    client, "Fix the failing tests", "git+ssh://git@github.com/org/project.git",
+    root=Path("/srv/pi-jobs"), job_id="task-123",
+    ssh_key=Path("/srv/keys/project_ed25519"),
+)
+# Drain the session's events, then close it before finalizing the workspace.
+async for event in session:
+    ...
+await session.aclose()
+
+print(workspace.diff())  # review before deciding
+state = workspace.to_state()  # save for approval after a host restart if needed
+# workspace = GitRepositoryWorkspace.from_state(state)
+workspace.merge()   # commits, merges and pushes to the cloned default branch
+workspace.cleanup() # remove the local clone after successful push
+# Or: workspace.discard()  # no changes to origin
+```
+
+If the remote branch has moved, the push is rejected with `MergeConflict`; the local
+workspace remains available for inspection. Never accept arbitrary repository URLs from
+untrusted requests: the caller must enforce an allowlist. Empty repositories and a
+second job with the same ID are rejected. SSH also accepts standard `ssh://` and
+`git@host:path` URLs. The key path (not its contents) is saved by `to_state()` for
+later pushes; the key must still exist then. SSH uses strict host-key checking and
+non-interactive authentication; configure `known_hosts` on the host in advance.
+
 ## Workspace jail
 
 Run an agent loose inside a project without letting it run anywhere on disk. `resolve_project`
@@ -550,6 +591,41 @@ await login.submit_code(info["session"], code)     # accepts a bare code or a ca
 locates pi's bundled Node libraries (package identity from `config.npm_package`, so the omp fork
 works too) — both exported for hosts building their own extension/auth tooling.
 
+## Web instance service
+
+The web subsystem is an optional layer over the same driver core. `pidriver` stays
+dependency-free by default; install the web extra only for the ASGI server:
+
+```sh
+uv pip install -e ".[web]"
+uv run pidriver-web --store pidriver.sqlite3 \
+  --projects-root /srv/projects --allow-project acme
+```
+
+Core pieces:
+
+- `PiInstanceSupervisor` drains every `PiSession` in one background task, persists event history,
+  broadcasts events to subscribers, and exposes `prompt` / `respond` / `cancel` / `stop`.
+- `PiInstanceStore` stores snapshots and event logs in SQLite. On service restart, previously live
+  subprocesses are marked `stale` because they cannot be reattached.
+- `PiWebApp` is a small ASGI app with JSON endpoints and SSE streaming.
+
+Useful routes:
+
+| Route | Purpose |
+| --- | --- |
+| `GET /` | Minimal dashboard for launching and watching instances. |
+| `GET /api/projects` | List project-jail candidates. |
+| `GET /api/models` | List models visible to this isolated pi config. |
+| `POST /api/instances` | Start an instance from `{prompt, project, model, approval_policy}`. |
+| `GET /api/instances` / `GET /api/instances/{id}` | List or inspect snapshots. |
+| `GET /api/instances/{id}/events` | Read persisted event history. |
+| `GET /api/instances/{id}/events/stream` | SSE stream for live events. |
+| `POST /api/instances/{id}/prompt` | Send a follow-up prompt. |
+| `POST /api/instances/{id}/respond` | Answer a pending interaction. |
+| `POST /api/instances/{id}/cancel` / `POST /api/instances/{id}/stop` | Interrupt or terminate. |
+| `GET /api/auth/providers` / `POST /api/auth/{provider}/start` | OAuth helper endpoints. |
+
 ## Development
 
 ```sh

{pidriver-0.2.0 → pidriver-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pidriver"
-version = "0.2.0"
+version = "0.4.1"
 description = "Async Python driver for the pi coding agent (pi --mode rpc), built for isolated, headless project work."
 readme = "README.md"
 license = { text = "MIT" }
@@ -28,6 +28,12 @@ dev = [
     "mypy>=1.11",
     "ruff>=0.6",
 ]
+web = [
+    "uvicorn>=0.30",
+]
+
+[project.scripts]
+pidriver-web = "pidriver.web:main"
 
 [build-system]
 requires = ["hatchling"]

{pidriver-0.2.0 → pidriver-0.4.1}/src/pidriver/__init__.py

@@ -56,6 +56,7 @@ from .config import (
     PiConfig,
 )
 from .errors import (
+    MergeConflict,
     PiCommandError,
     PiDriverError,
     PiInstallError,
@@ -65,6 +66,7 @@ from .errors import (
     PiTimeoutError,
     ProjectError,
     SessionNotFoundError,
+    StagingError,
     TransportClosedError,
 )
 from .events import (
@@ -86,6 +88,15 @@ from .events import (
     is_freetext_option,
     parse_event,
 )
+from .instances import (
+    ApprovalPolicy,
+    EventEnvelope,
+    InstanceStatus,
+    PiInstanceSnapshot,
+    PiInstanceSpec,
+    event_to_dict,
+    interaction_to_dict,
+)
 from .interaction import (
     ASK_FIRST_SYSTEM_PROMPT,
     AskHost,
@@ -98,11 +109,21 @@ from .interaction import (
 )
 from .manager import ManagedSession, PiSessionManager
 from .models import ModelInfo, list_models, parse_models
+from .repository import GitRepositoryWorkspace, stage_repository, start_repository_task
 from .session import PiSession
+from .staging import (
+    DEFAULT_COPY_EXCLUDES,
+    DEFAULT_MAX_COPY_BYTES,
+    MergeResult,
+    StagedWorkspace,
+    stage_workspace,
+)
+from .store import PiInstanceStore
+from .supervisor import PiInstanceSupervisor
 from .usage import UsageTotals
 from .workspace import ProjectDir, list_candidate_projects, list_projects, resolve_project
 
-__version__ = "0.2.0"
+__version__ = "0.4.1"
 
 __all__ = [
     "__version__",
@@ -156,11 +177,30 @@ __all__ = [
     "chain",
     "response_to_wire",
     "ASK_FIRST_SYSTEM_PROMPT",
+    # instances / supervisor
+    "ApprovalPolicy",
+    "InstanceStatus",
+    "PiInstanceSpec",
+    "PiInstanceSnapshot",
+    "EventEnvelope",
+    "event_to_dict",
+    "interaction_to_dict",
+    "PiInstanceStore",
+    "PiInstanceSupervisor",
     # workspace
     "resolve_project",
     "list_projects",
     "list_candidate_projects",
     "ProjectDir",
+    # staging
+    "stage_workspace",
+    "stage_repository",
+    "start_repository_task",
+    "StagedWorkspace",
+    "GitRepositoryWorkspace",
+    "MergeResult",
+    "DEFAULT_COPY_EXCLUDES",
+    "DEFAULT_MAX_COPY_BYTES",
     # models
     "ModelInfo",
     "parse_models",
@@ -180,4 +220,6 @@ __all__ = [
     "TransportClosedError",
     "SessionNotFoundError",
     "ProjectError",
+    "StagingError",
+    "MergeConflict",
 ]

{pidriver-0.2.0 → pidriver-0.4.1}/src/pidriver/_install.py

@@ -131,7 +131,8 @@ def ensure_binary(config: PiConfig, *, runner: Runner = subprocess.run) -> str:
 
     Resolution order:
       1. ``config.binary`` — an absolute path that exists, or a name found on PATH.
-      2. ``<install_dir>/bin/pi`` — a previously-installed managed copy.
+      2. ``<install_dir>/bin/pi`` — a managed copy; if auto-installing, upgrade
+         it when its version differs from ``config.pi_version``.
       3. if still missing and ``auto_install`` with ``install_dir`` set → npm-install it.
     Raises :class:`PiNotFoundError` if it can't be resolved (and install isn't allowed).
     """
@@ -147,7 +148,14 @@ def ensure_binary(config: PiConfig, *, runner: Runner = subprocess.run) -> str:
     if config.install_dir is not None:
         managed = managed_binary_path(config.install_dir)
         if managed.exists():
-            return str(managed)
+            if not config.auto_install:
+                return str(managed)
+            try:
+                _verify_version(managed, config.pi_version, runner=runner)
+            except PiInstallError:
+                pass
+            else:
+                return str(managed)
 
     if config.auto_install and config.install_dir is not None:
         path = install_pi(

{pidriver-0.2.0 → pidriver-0.4.1}/src/pidriver/config.py

@@ -110,7 +110,7 @@ class PiConfig:
     install_dir: Path | None = None  # where to install/look for a managed pi
     auto_install: bool = True  # npm-install pi into install_dir if missing
     npm_package: str = "@earendil-works/pi-coding-agent"  # the npm package providing `pi`
-    pi_version: str = "0.78.1"  # known-good pin; overridable
+    pi_version: str = "0.87.1"  # known-good pin; overridable
 
     # --- extensions / skills / packages ------------------------------------
     # User-chosen add-ons installed into the (isolated) pi config dir via

{pidriver-0.2.0 → pidriver-0.4.1}/src/pidriver/errors.py

@@ -19,6 +19,8 @@ __all__ = [
     "TransportClosedError",
     "SessionNotFoundError",
     "ProjectError",
+    "StagingError",
+    "MergeConflict",
 ]
 
 
@@ -35,6 +37,43 @@ class ProjectError(PiDriverError, ValueError):
     """
 
 
+class StagingError(PiDriverError):
+    """A staging operation (stage/diff/merge/discard/cleanup) failed structurally.
+
+    Raised by :mod:`pidriver.staging` when a ``git`` command exits non-zero, the
+    staging root is unusable, the source/stage path is invalid, the source repo is
+    in a state that cannot be merged into (dirty working tree, detached HEAD), or a
+    non-git copy exceeds the size cap. Carries the failing git ``argv`` + ``stderr``
+    when the cause was a git invocation.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        argv: tuple[str, ...] | None = None,
+        stderr: str | None = None,
+    ) -> None:
+        self.argv = argv
+        self.stderr = stderr
+        super().__init__(message)
+
+
+class MergeConflict(StagingError):
+    """A staged change could not be landed into the source cleanly.
+
+    The ``pi/<job>`` branch (git) or the staged tree (non-git) is preserved
+    untouched and the source is left pristine, so the user can resolve by hand.
+    ``conflicts`` lists the conflicting paths; ``diff`` is the unified diff to
+    reconcile.
+    """
+
+    def __init__(self, message: str, *, conflicts: tuple[str, ...], diff: str) -> None:
+        self.conflicts = conflicts
+        self.diff = diff
+        super().__init__(message)
+
+
 class PiNotFoundError(PiDriverError):
     """The pi/omp executable could not be located or is not runnable."""
 

pidriver-0.4.1/src/pidriver/instances.py

@@ -0,0 +1,241 @@
+"""Typed instance records for service/web hosts.
+
+The low-level driver exposes a live :class:`pidriver.session.PiSession`; web and
+service hosts need a stable, serializable record around that subprocess: launch
+inputs, lifecycle status, pending interaction, usage, and event history.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from .events import (
+    AgentEnd,
+    AgentStart,
+    Channel,
+    Error,
+    Event,
+    InteractionRequest,
+    MessageComplete,
+    MessageDelta,
+    ToolEnd,
+    ToolStart,
+    ToolUpdate,
+    Usage,
+)
+from .usage import UsageTotals
+
+__all__ = [
+    "ApprovalPolicy",
+    "InstanceStatus",
+    "PiInstanceSpec",
+    "PiInstanceSnapshot",
+    "EventEnvelope",
+    "event_to_dict",
+    "interaction_to_dict",
+]
+
+
+class ApprovalPolicy(StrEnum):
+    """Host-side policy for answering permission prompts."""
+
+    ASK = "ask"
+    AUTO_APPROVE = "auto_approve"
+    AUTO_APPROVE_ALWAYS = "auto_approve_always"
+    DENY_ALL = "deny_all"
+
+
+class InstanceStatus(StrEnum):
+    """Durable lifecycle state for a managed pi instance."""
+
+    QUEUED = "queued"
+    STARTING = "starting"
+    RUNNING = "running"
+    WAITING = "waiting"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    STOPPED = "stopped"
+    STALE = "stale"
+
+    @property
+    def terminal(self) -> bool:
+        return self in {
+            InstanceStatus.COMPLETED,
+            InstanceStatus.FAILED,
+            InstanceStatus.CANCELLED,
+            InstanceStatus.STOPPED,
+            InstanceStatus.STALE,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PiInstanceSpec:
+    """Launch request for one managed pi instance.
+
+    ``project`` is the safe public selector. ``cwd`` is an internal/testing escape
+    hatch; web-facing callers should resolve projects through the supervisor jail.
+    """
+
+    prompt: str
+    project: str | None = None
+    cwd: Path | None = None
+    provider: str | None = None
+    model: str | None = None
+    thinking: str | None = None
+    approval_policy: ApprovalPolicy = ApprovalPolicy.ASK
+    session_id: str | None = None
+    resume: str | None = None
+    send_initial: bool = True
+    system_prompt: str | None = None
+    append_system_prompt: tuple[str, ...] = ()
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "prompt": self.prompt,
+            "project": self.project,
+            "cwd": str(self.cwd) if self.cwd is not None else None,
+            "provider": self.provider,
+            "model": self.model,
+            "thinking": self.thinking,
+            "approval_policy": self.approval_policy.value,
+            "session_id": self.session_id,
+            "resume": self.resume,
+            "send_initial": self.send_initial,
+            "system_prompt": self.system_prompt,
+            "append_system_prompt": list(self.append_system_prompt),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PiInstanceSnapshot:
+    """Serializable public state for an instance."""
+
+    instance_id: str
+    status: InstanceStatus
+    prompt: str
+    project: str | None = None
+    cwd: str | None = None
+    provider: str | None = None
+    model: str | None = None
+    thinking: str | None = None
+    approval_policy: ApprovalPolicy = ApprovalPolicy.ASK
+    pi_session_id: str = ""
+    pid: int | None = None
+    returncode: int | None = None
+    pending: dict[str, Any] | None = None
+    usage: UsageTotals = field(default_factory=UsageTotals)
+    final_text: str = ""
+    error: str = ""
+    created_at: float = 0.0
+    updated_at: float = 0.0
+    started_at: float | None = None
+    ended_at: float | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "instance_id": self.instance_id,
+            "status": self.status.value,
+            "prompt": self.prompt,
+            "project": self.project,
+            "cwd": self.cwd,
+            "provider": self.provider,
+            "model": self.model,
+            "thinking": self.thinking,
+            "approval_policy": self.approval_policy.value,
+            "pi_session_id": self.pi_session_id,
+            "pid": self.pid,
+            "returncode": self.returncode,
+            "pending": self.pending,
+            "usage": self.usage.as_dict(),
+            "final_text": self.final_text,
+            "error": self.error,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class EventEnvelope:
+    """One persisted/broadcast event for an instance."""
+
+    sequence: int
+    instance_id: str
+    timestamp: float
+    event: dict[str, Any]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "sequence": self.sequence,
+            "instance_id": self.instance_id,
+            "timestamp": self.timestamp,
+            "event": self.event,
+        }
+
+
+def interaction_to_dict(request: InteractionRequest) -> dict[str, Any]:
+    return {
+        "type": request.type,
+        "request_id": request.request_id,
+        "method": request.method,
+        "kind": request.kind.value,
+        "prompt": request.prompt,
+        "options": list(request.options),
+        "tool_call_id": request.tool_call_id,
+        "default": request.default,
+        "raw": request.raw,
+    }
+
+
+def event_to_dict(event: Event) -> dict[str, Any]:
+    """Convert a typed event to a JSON-friendly dict."""
+
+    common: dict[str, Any] = {"type": event.type, "raw": event.raw}
+    match event:
+        case AgentStart(session_id=session_id, model=model, cwd=cwd):
+            return {**common, "session_id": session_id, "model": model, "cwd": cwd}
+        case MessageDelta(text=text, channel=channel):
+            return {**common, "text": text, "channel": _channel_value(channel)}
+        case MessageComplete(text=text, channel=channel):
+            return {**common, "text": text, "channel": _channel_value(channel)}
+        case ToolStart(tool_call_id=tool_call_id, name=name, arguments=arguments):
+            return {
+                **common,
+                "tool_call_id": tool_call_id,
+                "name": name,
+                "arguments": arguments,
+            }
+        case ToolUpdate(tool_call_id=tool_call_id, name=name, output=output):
+            return {
+                **common,
+                "tool_call_id": tool_call_id,
+                "name": name,
+                "output": output,
+            }
+        case ToolEnd(tool_call_id=tool_call_id, name=name, result=result, is_error=is_error):
+            return {
+                **common,
+                "tool_call_id": tool_call_id,
+                "name": name,
+                "result": result,
+                "is_error": is_error,
+            }
+        case Usage(totals=totals):
+            return {**common, "totals": totals.as_dict()}
+        case AgentEnd(reason=reason, final_text=final_text):
+            return {**common, "reason": reason, "final_text": final_text}
+        case Error(message=message, code=code, fatal=fatal):
+            return {**common, "message": message, "code": code, "fatal": fatal}
+        case InteractionRequest() as request:
+            return interaction_to_dict(request)
+        case _:
+            return common
+
+
+def _channel_value(channel: Channel | str) -> str:
+    return channel.value if isinstance(channel, Channel) else str(channel)