monkeybot-cli 0.2.1__tar.gz

monkeybot_cli-0.2.1/.gitignore

@@ -0,0 +1,64 @@
+# Internal (not shipped in OSS)
+internal/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Local scaffolded harness config (defaults ship in monkeybot-cli scaffold_defaults/)
+/monkeybot_config/
+
+# Demo agent live config (materialized from monkeybot_config_example/ by demo_agent/run.sh)
+demo_agent/monkeybot_config/
+
+# Live eval run artifacts (only evals/baselines/ is versioned)
+/evals/runs/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# uv
+.venv/
+.uv/
+
+# Data (SQLite DB + memory files — never commit)
+data/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# macOS
+.DS_Store
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Docker
+docker/data/
+
+# Planning Documents
+.prt/
+.monkeymode/
+
+# Reference clones (read-only)
+code/
+
+# Local venv for evals dependency experiments
+.evals-venv/

monkeybot_cli-0.2.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: monkeybot-cli
+Version: 0.2.1
+Summary: CLI to create, configure, validate, and chat with monkeybot agents.
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: monkeybot[cli]<3,>=2.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: textual>=8.2.8

monkeybot_cli-0.2.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "monkeybot-cli"
+version = "0.2.1"
+description = "CLI to create, configure, validate, and chat with monkeybot agents."
+requires-python = ">=3.11"
+dependencies = [
+    # `cli` pulls realtime + typer so `monkeybot talk` works out of the box (text mode).
+    # Audio mic/PTT needs the agent (or this env) to also install monkeybot[cli-realtime].
+    "monkeybot[cli]>=2.1.0,<3",
+    "httpx>=0.27.0",
+    "pyyaml>=6.0.2",
+    "python-dotenv>=1.0.0",
+    "textual>=8.2.8",
+]
+
+[project.scripts]
+monkeybot = "monkeybot_cli.main:main"
+
+[tool.uv.sources]
+monkeybot = { path = "..", editable = true }
+
+[dependency-groups]
+dev = [
+    "pexpect>=4.9.0",
+    "pytest>=8.3.0",
+    "ruff>=0.8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/monkeybot_cli"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]

monkeybot_cli-0.2.1/skills/monkeybot/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: monkeybot
+description: Entry point for monkeybot — install the CLI from PyPI if needed, then scaffold, configure, validate, and chat with an agent. Use when a user installs this skill via `npx skills add human-plus-machine/monkeybot --skill monkeybot`, sets up monkeybot for the first time, installs the monkeybot CLI, scaffolds monkeybot_config/, explains monkeybot.yaml options, or smoke-tests from the terminal.
+---
+
+# monkeybot
+
+Guide a new user from **only this skill** to a working agent. Installing the skill (`npx skills add …`) gives you these instructions — it does **not** install the monkeybot CLI. **Always run Tier 0 first** unless you already know the toolchain is ready. Day-1 users do **not** need to clone the monkeybot repo.
+
+## Tier 0 — Bootstrap toolchain
+
+Run these checks before anything else. Do not skip to Tier 1 until the CLI probe succeeds.
+
+### 0. Detect what's already installed
+
+```bash
+command -v monkeybot && monkeybot --help
+```
+
+If that works, skip to Tier 1.
+
+### 1. Install prerequisites (only if missing)
+
+| Tool | Check | Install |
+|---|---|---|
+| **uv** | `command -v uv` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` then `export PATH="$HOME/.local/bin:$PATH"` |
+| **Python 3.11+** | `uv python find 3.11` or `python3 --version` | `uv python install 3.12` |
+
+Tell the user what you're installing and why. On macOS/Linux you can run these yourself; on Windows, point them at [uv](https://docs.astral.sh/uv/).
+
+### 2. Install the global CLI
+
+```bash
+uv tool install monkeybot-cli
+monkeybot --help
+```
+
+Upgrade later with `uv tool upgrade monkeybot-cli`.
+
+**Do not** tell day-1 users to clone `human-plus-machine/monkeybot` unless they are contributing to the harness itself (see Contributing below).
+
+### 3. Skill-only users
+
+If the user arrived via skills.sh:
+
+```bash
+npx skills add human-plus-machine/monkeybot --skill monkeybot
+```
+
+…they have **this skill only**. Walk them through Tier 0: install `uv` → `uv tool install monkeybot-cli` → verify `monkeybot --help`. Then continue to Tier 1.
+
+## How config works (tell the user this first)
+
+- **CLI scaffolds, YAML customizes, then validate.** `monkeybot new` copies packaged defaults from the `monkeybot-cli` package (`monkeybot_cli.scaffold_defaults`) and sets `model.provider` / `model.name`. After that, customization happens by editing `monkeybot_config/monkeybot.yaml` and `.env`, then re-running `monkeybot validate --json`.
+- **Three config surfaces:**
+  - `monkeybot_config/monkeybot.yaml` — non-secret settings (model, paths, gateway, behavior).
+  - `.env` — secrets and machine-local paths (API keys, GCP project, DB URL).
+  - sidecars: `monkeybot_config/AGENT.md` (system prompt), `mcp.json` (MCP servers), `command_allowlist.yaml`.
+- **Precedence — important:** environment variables and `.env` win over `monkeybot.yaml`. If a user edits YAML but nothing changes, suspect a stale `.env` shadowing it (the YAML→env mapping lives in `runtime_env.py:ENV_MAP`).
+- **Defaults are fine on day one.** Most first-time users only touch `model`, `.env` credentials, and `AGENT.md`.
+
+## Running CLI commands
+
+After Tier 0, every command below uses `monkeybot` on PATH.
+
+## Tier 1 — Get it talking
+
+The minimum path to one successful chat turn. Do this for every new user.
+
+### 1. Quick interview
+
+Ask (or infer):
+
+- Bot purpose / name → goes in `AGENT.md`
+- Provider + model (see provider table below)
+- Optional features (postgres, sandbox, observability, …) → `--with` or interactive menus
+
+### 2. Scaffold
+
+```bash
+monkeybot new --dest /path/to/bot --provider openai --yes
+# Interactive (menus for provider + extras):
+# monkeybot new --dest /path/to/bot
+# Non-interactive extras:
+# monkeybot new --dest /path/to/bot --provider openai --with postgres,sandbox --yes
+```
+
+Creates `monkeybot_config/`, `workspace/` (file-tool sandbox), `workspace/skills` → `skills/`, `data/memory/`, `.env.example`, `scripts/setup-workspace.sh`, and an agent `pyproject.toml`. Use `--force` only when overwriting is explicitly requested.
+
+Then:
+
+```bash
+cd /path/to/bot
+uv sync
+```
+
+### 3. Credentials + system prompt
+
+- Copy `.env.example` → `.env` and fill in the keys for your provider (table below).
+- Edit `monkeybot_config/AGENT.md` with the bot's system prompt. **Never put secrets in YAML.**
+
+### Provider table
+
+| YAML `model.provider` | `.env` credentials (any one) | Add to agent `pyproject.toml` deps, then `uv sync` |
+|---|---|---|
+| `gemini` (or `vertex`) | `GEMINI_API_KEY`, or `GOOGLE_APPLICATION_CREDENTIALS`, or `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` (ADC) | `monkeybot[gemini]` |
+| `openai` | `OPENAI_API_KEY` | `monkeybot[openai]` |
+| `anthropic` | `ANTHROPIC_API_KEY` | `monkeybot[claude]` |
+| `vertex-claude` | `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` / `ANTHROPIC_VERTEX_PROJECT_ID` (ADC) | `monkeybot[vertex-claude]` |
+| `aws_bedrock` | `AWS_ACCESS_KEY_ID` / `AWS_PROFILE` + `AWS_REGION` | `monkeybot[bedrock]` |
+| `huggingface` | `HF_TOKEN` (or `HUGGINGFACE_API_KEY`) | `monkeybot[huggingface]` |
+| `ollama` | None required — `OLLAMA_BASE_URL` (default `http://localhost:11434`) for a non-default server | `monkeybot[ollama]` |
+
+**Agent-first dependencies.** The CLI is thin — it does **not** install provider/storage extras globally. `monkeybot new` scaffolds a `pyproject.toml` with the selected provider (and any `--with` extras). Run plain `uv sync` in the agent directory. `monkeybot run` / `chat` spawn the gateway from that project's interpreter (`.venv/bin/python`, else `uv run python`), and `doctor` checks extras in that same interpreter. For a config-only tree (just `monkeybot_config/`, no `pyproject.toml`) the gateway falls back to the CLI's interpreter, so extras must be installed in the CLI env (`uv tool install --with 'monkeybot[<extra>]' monkeybot-cli`).
+
+`doctor` is the source of truth for credentials and extras — when in doubt, run it and read the `remediation` field (add `monkeybot[<extra>]` to agent deps + `uv sync`).
+
+### 4. Validate (loop until clean)
+
+```bash
+monkeybot validate --json --cwd /path/to/bot
+```
+
+- Exit `0` + `"ok": true` → proceed.
+- On failure: read `checks[]` by stable `id`, apply `remediation`, re-run.
+
+### 5. Doctor
+
+```bash
+monkeybot doctor --json --cwd /path/to/bot
+```
+
+Confirms Python version, provider extra installed, credentials present, and port free.
+
+### 6. Smoke test
+
+```bash
+monkeybot chat --cwd /path/to/bot
+```
+
+Or split terminals: `monkeybot run --cwd /path/to/bot` then `monkeybot chat --attach --cwd /path/to/bot`.
+
+One successful turn confirms Tier 1.
+
+## Tier 2 — Customize (on demand)
+
+Only reach for these when the interview surfaces a need. Each maps to a `monkeybot.yaml` section. **For purpose, defaults, examples, and the `validate`/`doctor` check id of every option, read [`references/config-sections.md`](references/config-sections.md).** Don't inline that reference here.
+
+Decision → config map:
+
+| User says… | Change |
+|---|---|
+| "Run many subagents in parallel" | `paths.db_url` → Postgres (SQLite locks under concurrency) |
+| "I have a custom web UI" | `gateway.cors_allow_origins` |
+| "Search the web" | `web_search.backend` + `.env` keys (Tavily/Firecrawl) |
+| "Run untrusted code" | `sandbox.enabled` + `SANDBOX_API_KEY` |
+| "Use specialist agents" | `subagents[]` + `monkeybot_config/agents/*.md` |
+| "Connect external tools" | `mcp.json` (`mcpServers` object), then `validate --check-mcp` |
+| "Control cost / context size" | `model.*`, `context_curation.*` |
+| "Restrict dangerous commands" | `tools.denied_patterns`, `command_allowlist.yaml` |
+| "Multiple environments" | top-level `includes:` fragments |
+
+**Subagents (`task` tool):** share the parent `AGENT.md` (or `subagent.agent_md`). Relative paths resolve from the bot project root, not `workspace/`. Specialize via `task` / `context`, not separate agent type folders. For parallel `task` fan-out, prefer Postgres: add `monkeybot[postgres]` to the **agent** `pyproject.toml` dependencies, run `uv sync`, then set `DB_URL=postgresql://...` in `.env`.
+
+**Observability** is mostly env + add `monkeybot[observability]` to agent deps + `uv sync` + an OTel collector — not `monkeybot.yaml`. See `docs/observability-runbook.md`.
+
+## Contributing / developing the harness
+
+Only if the user is changing monkeybot itself (not creating an agent):
+
+```bash
+git clone https://github.com/human-plus-machine/monkeybot.git
+cd monkeybot && uv sync
+cd cli && uv sync
+uv tool install --editable .
+```
+
+## Rules
+
+- **Tier 0 before Tier 1** — verify or install the global CLI before scaffolding a bot.
+- **CLI owns scaffolding** — do not duplicate template files manually.
+- **Secrets in `.env` only** — never commit API keys to `monkeybot.yaml`.
+- **Validate after every edit** — re-run `validate --json` whenever you change config.
+- **Parse JSON** — key off `checks[].id`, not free-form messages.
+- **HTTP/SSE for chat** — the CLI talks to the gateway process; do not import harness gateway code.
+- **No clone for day-1 users** — clone is for harness contributors only.
+
+## Command reference
+
+| Command | Purpose |
+|---------|---------|
+| `new` | Scaffold `monkeybot_config/`, `workspace/`, `data/memory/`, `skills/`, `pyproject.toml`, `.env.example` |
+| `validate` | Config + paths + MCP shape (`--check-mcp` for network) |
+| `doctor` | Python, provider extra, credentials, port |
+| `run` | Start SSE gateway subprocess |
+| `chat` | Interactive terminal client (SSE) |
+| `talk` | Realtime WebSocket client (audio/text) |

monkeybot_cli-0.2.1/skills/monkeybot/references/config-sections.md

@@ -0,0 +1,160 @@
+# monkeybot.yaml configuration reference
+
+Deep reference for every `monkeybot.yaml` section. Load this only when a user needs to customize beyond Tier 1. The canonical, fully-commented template lives at `cli/src/monkeybot_cli/scaffold_defaults/monkeybot.example.yaml` in the monkeybot repo (copied to `monkeybot_config/monkeybot.example.yaml` when you scaffold); this file adds the **"when would I change this?"** context the comments don't.
+
+**Precedence:** env vars and `.env` win over YAML. The YAML→env mapping is `ENV_MAP` in `src/monkeybot/core/config/runtime_env.py`. If a YAML edit has no effect, check for a shadowing env var.
+
+---
+
+## `runtime`
+
+| Field | Default | When to change |
+|---|---|---|
+| `log_level` | `INFO` | `DEBUG` while troubleshooting; `WARNING`/`ERROR` to quiet logs |
+| `port` | `8080` | Port conflict, or running multiple bots locally |
+| `gateway_port` | (unset) | Only if a code path needs `GATEWAY_PORT` separate from `PORT` |
+
+Validate/doctor: `doctor` → `runtime.port.free`.
+
+## `paths`
+
+| Field | Default | When to change |
+|---|---|---|
+| `agent_md` | `./monkeybot_config/AGENT.md` | Alternate system-prompt location |
+| `memory_storage_uri` | `local://./data/memory` | `gcs://…` for shared/cloud memory (requires GCP project) |
+| `skills_path` | `./skills` | Point at a different skills tree |
+| `db_url` | `sqlite:///data/monkeybot.db` | **Postgres for parallel subagents** — SQLite hits `database is locked` under concurrency |
+| `auto_schema` | `true` | Set `false` when migrations own the schema (managed Postgres with DML-only runtime user) |
+| `mcp_config` | `./monkeybot_config/mcp.json` | Relocate MCP definitions |
+| `command_allowlist_config` | `./monkeybot_config/command_allowlist.yaml` | Relocate the shell allowlist |
+| `workspace_root` | `./workspace` (if present) | Change the file-tool sandbox root |
+
+Validate check ids: `paths.agent_md.exists`, `paths.skills_path.exists`, `paths.mcp_config.exists`, `paths.command_allowlist.exists`, `paths.db_url.writable`, `memory.backend.supported`, `gcp.project.required` (for `gcs://` memory).
+
+## `model`
+
+| Field | Default | When to change |
+|---|---|---|
+| `provider` | `gemini` | Switch LLM vendor (see provider table in SKILL.md) |
+| `name` | `gemini-3-flash` | Pick a specific model id |
+| `temperature` | `0.7` | Lower for deterministic output, higher for creative |
+| `max_tokens` | `60000` | Cap per-response length |
+| `thinking_budget` | `-1` | Gemini: `-1` model default, `0` off, `N` token budget. Ollama reasoning models: `-1` server default, `0` off (`reasoning_effort: none`) |
+| `context_window` | `1000000` | Summarization trigger threshold (tokens) |
+| `max_turns` | `50` | Hard cap on turns per run |
+| `summarization_model` | (main model) | Cheaper model for history summarization (env `CONTEXT_SUMMARIZATION_MODEL`) |
+
+Validate check ids: `model.provider.supported`, `model.name.present`. Supported YAML providers: `gemini`/`vertex`, `openai`, `anthropic`, `vertex-claude`, `huggingface`, `ollama`, `aws_bedrock`, `fake`.
+
+## `gcp` / `anthropic_vertex` (non-secret identifiers)
+
+Prefer `.env` for secrets and the ADC path; use these blocks only for non-secret project/region identifiers.
+
+```yaml
+gcp:
+  project_id: your-gcp-project
+  location: us-central1
+anthropic_vertex:
+  project_id: your-gcp-project
+  region: us-east5
+```
+
+Required when `memory_storage_uri` is `gcs://…` or `provider: vertex-claude` (validate `gcp.project.required`).
+
+## `gateway`
+
+| Field | Default | When to change |
+|---|---|---|
+| `pending_response_timeout_sec` | `300` | Long-running turns time out too early |
+| `sse_replay_max` | `256` | Tune SSE replay buffer |
+| `graceful_shutdown_timeout_sec` | `5` | Allow longer drain on shutdown |
+| `cors_allow_origins` | `http://localhost:5173` | **Custom web UI** — set its origin, or `"*"` for any |
+
+## `context_curation`
+
+Trims memory injected into context. `enabled: true` by default.
+
+Recent window by default; LLM curator only when the index is token-heavy. On curator failure, falls back to the window.
+
+| Field | Default | Notes |
+|---|---|---|
+| `memory_window_lines` | `12` | Recent index lines injected; also caps curator-selected lines |
+| `memory_index_cap` | `200` | Organizer keeps this many INDEX.md entries; older rows move to `INDEX.archive.md` |
+| `memory_token_threshold` | `2000` | Call curator when estimated index tokens exceed this |
+| `curator_model` | `gemini-3-flash` | Separate small model; empty = main model |
+| `timeout_sec` | `10` | Curator call timeout |
+
+When the prompt shows fewer entries than exist, a structural confidence score triggers a `search_memory` nudge. Skill names are always shown in full in the prompt; use `list_skills` to get the skills root path.
+
+## `memory_hook`
+
+`enabled: true` — automatic memory capture after turns. Disable to manage memory manually.
+
+## `subagent` and `subagents`
+
+`subagent` sets defaults for `task` calls:
+
+| Field | Default | Notes |
+|---|---|---|
+| `timeout_sec` | `600` | Per-subagent timeout |
+| `max_turns` | `25` | Per-subagent turn cap |
+| `vertex_google_search` | `false` | **Gemini only.** Enables native `google_search` grounding for subagent `task` runs. Config-file only. |
+| `agent_md` | (parent `AGENT.md`) | Default prompt when `task` omits `subagent_type` |
+
+`subagents[]` defines named personas the parent selects via `task(subagent_type=...)`:
+
+```yaml
+subagents:
+  - name: researcher
+    description: "Deep-dives a topic and returns a structured summary."
+    agent_md: ./monkeybot_config/agents/researcher.md
+```
+
+Relative paths resolve from the bot project root, not `workspace/`. For parallel fan-out, use Postgres (`db_url`).
+
+## `tools`
+
+| Field | Default | When to change |
+|---|---|---|
+| `denied_patterns` | (none) | Block substrings in tool args, e.g. `"rm -rf"` (also env `MONKEYBOT_TOOL_DENIED_PATTERNS`) |
+| `read_max_lines` / `read_default_lines` | (code defaults) | Tune file-read limits |
+| `spill_read_max_lines` / `spill_min_chars` | (code defaults) | Tune large-result spill behavior |
+| `result_budget_fraction` / `result_budget_floor_tokens` | (code defaults) | Advanced result-budgeting; rarely needed |
+
+For shell-command safety, pair `denied_patterns` with `monkeybot_config/command_allowlist.yaml`.
+
+## `web_search`
+
+| Field | Default | Notes |
+|---|---|---|
+| `backend` | `duckduckgo` | `duckduckgo` (no key) \| `tavily` \| `firecrawl` \| `none` |
+| `max_results` | `5` | Result cap |
+| `vertex_google_search` | `false` | **Gemini only.** Additive to `backend` — enables Vertex Gemini's native `google_search` grounding tool for **main agent** turns only (not summarization, memory organizer, or curator). Ignored for other model providers. Config-file only — no env var override (like `paths.auto_schema`). |
+
+Tavily/Firecrawl need `TAVILY_API_KEY` / `FIRECRAWL_API_KEY` in `.env`. Doctor check: `web_search.backend.ready` (`duckduckgo` needs the `web-search` extra).
+
+## `sandbox`
+
+| Field | Default | When to change |
+|---|---|---|
+| `enabled` | `false` | Enable to run untrusted code in isolation |
+| `server_url` | `http://localhost:8080` | Sandbox service endpoint |
+| `image` | `python:3.12` | Execution image |
+| `ttl_seconds` | `1800` | Sandbox lifetime |
+
+Needs `SANDBOX_API_KEY` in `.env`.
+
+## `includes`
+
+Top-level list of YAML fragments (paths relative to the config file's directory). Later files deep-merge over earlier ones — useful for per-environment overrides:
+
+```yaml
+includes:
+  - includes/local.yaml
+```
+
+Validate check: `config.includes.resolve`.
+
+## `fake_provider`
+
+Test-only. `events_json` feeds `MODEL_PROVIDER=fake` scripted runs (env `MONKEYBOT_FAKE_PROVIDER_EVENTS`). Not for production.

monkeybot_cli-0.2.1/src/monkeybot_cli/__init__.py

@@ -0,0 +1,3 @@
+"""monkeybot setup CLI — create, configure, validate, and chat with agents."""
+
+__version__ = "0.1.10"

monkeybot_cli-0.2.1/src/monkeybot_cli/chat_renderer.py

@@ -0,0 +1,87 @@
+"""Shared chat renderer contract and session controller protocol."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from monkeybot_cli.chat_session import ChatUiEvent, HitlAnswer
+    from monkeybot_cli.chat_status_bar import UsageStore
+
+# Every kind emitted by session controllers (and expected by renderers).
+EVENT_KINDS: frozenset[str] = frozenset(
+    {
+        "usage_updated",
+        "session_ready",
+        "connection_state",
+        "transcript_backfill",
+        "thinking",
+        "thinking_clear",
+        "turn_started",
+        "assistant_start",
+        "assistant_delta",
+        "tool_started",
+        "tool_finished",
+        "summarizing",
+        "summarized",
+        "grounding",
+        "turn_error",
+        "turn_complete",
+        "turn_aborted",
+        "hitl_required",
+        "hitl_failed",
+        "hitl_frontend_unsupported",
+        "session_busy",
+        "error",
+        "stream_failed",
+        "stream_ended",
+        "thinking_trace",
+        "thinking_block_delta",
+        "thinking_block_complete",
+        "voice_state",
+        "audio_chunk",
+        "device_error",
+        "user_transcript",
+    }
+)
+
+
+@runtime_checkable
+class SessionController(Protocol):
+    """Minimal surface the TUI / plain renderer need from a session backend."""
+
+    turn_based: bool
+    stream_alive: bool
+    stream_error: bool
+    reconnecting: bool
+    show_usage: bool
+    usage: UsageStore
+    session_id: str | None
+
+    async def connect(self, resume_session_id: str | None = None) -> None: ...
+
+    async def submit(self, message: str) -> None: ...
+
+    def abort_turn(self) -> None: ...
+
+    def provide_hitl_answer(self, answer: HitlAnswer) -> None: ...
+
+    def set_emit(self, emit: Any) -> None: ...
+
+    async def close(self) -> None: ...
+
+    async def restart_session(self) -> None: ...
+
+    async def resume_session(self, session_id: str) -> None: ...
+
+    async def refresh_usage(self) -> None: ...
+
+
+@runtime_checkable
+class ChatRenderer(Protocol):
+    """Sink for ``ChatUiEvent``s from a session controller."""
+
+    def on_event(self, event: ChatUiEvent, controller: SessionController) -> None: ...
+
+
+__all__ = ["EVENT_KINDS", "ChatRenderer", "SessionController"]