opendot 0.0.1__tar.gz

opendot-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[office,dev]"
+      - name: Run tests
+        run: pytest -q

opendot-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+# Publish to PyPI when you push a version tag, e.g.:
+#   git tag v0.1.0 && git push origin v0.1.0
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored in GitHub.
+# One-time setup on PyPI: project → Publishing → add a trusted publisher for
+# this repo + workflow file `release.yml` + environment `pypi`.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check artifacts
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # PyPI trusted-publisher environment
+    permissions:
+      id-token: write          # required for OIDC (Trusted Publishing)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opendot-0.0.1/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging / build
+*.whl
+pip-wheel-metadata/
+
+# Test / coverage / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# opendot local state (snapshot store lives in ~/.opendot; never commit any local copy)
+.opendot/
+
+# Environment / secrets
+.env

opendot-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to opendot
+
+Thanks for your interest! opendot is an interactive terminal AI agent whose
+defining feature is **trustworthy reversibility** — you can see and cleanly undo
+everything it does. Contributions are welcome; please keep that guarantee intact.
+
+## Setup
+
+```bash
+git clone https://github.com/vedaant00/opendot
+cd opendot
+uv venv && uv pip install -e ".[office,dev]"   # or: python -m venv .venv && pip install -e ".[office,dev]"
+pytest                                          # should be all green
+```
+
+## Project layout
+
+```
+src/opendot/
+  cli.py           entry point (subcommands, one-shot, REPL)
+  tui.py           the full-screen Textual TUI
+  agent/           the model-agnostic ReAct loop (LiteLLM), events, prompt, usage
+  tools/           local file/shell tools + office (.xlsx/.pptx)
+  reversibility/   THE MOAT: content-addressed snapshots, ledger, undo, classifier
+  mcp/             MCP client (connect external MCP servers)
+```
+
+## The one rule: don't break reversibility
+
+`reversibility/` is the reason opendot exists. If you touch it, or add a tool
+that mutates the filesystem:
+
+- Every mutating action **must** snapshot before it runs (so `undo` restores
+  exact prior bytes).
+- Anything whose effect can escape the workspace (network, `sudo`, deletes
+  outside the working dir, external/MCP calls) **must** be routed through the
+  confirmation gate and recorded as irreversible in the ledger.
+- The snapshot round-trip must be exact — see `tests/test_snapshots.py`. Add
+  tests for any change here; a lying `undo` defeats the whole project.
+
+## Tests
+
+Please add tests for changes. Run `pytest` before opening a PR — CI runs it on
+Python 3.10–3.12.
+
+## Style
+
+Match the surrounding code: small, clear functions; comments explain *why*, not
+*what*. Keep the tool/UI honest — don't add UI affordances or hints for features
+that don't actually work.
+
+## Opening a PR
+
+Describe the change and why. If it's non-trivial, an issue first to align on the
+approach is appreciated.

opendot-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vedaant Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opendot-0.0.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: opendot
+Version: 0.0.1
+Summary: An interactive terminal AI agent you can fully undo — any model, acts on your real files, every action reversible.
+Project-URL: Repository, https://github.com/vedaant00/opendot
+Author: Vedaant Singh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,coding-agent,litellm,llm,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: litellm>=1.50
+Requires-Dist: mcp>=1.2
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.60
+Provides-Extra: dev
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-pptx>=0.6; extra == 'dev'
+Provides-Extra: office
+Requires-Dist: openpyxl>=3.1; extra == 'office'
+Requires-Dist: python-pptx>=0.6; extra == 'office'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+```
+                          _       _
+  ___  _ __   ___ _ __   __| | ___ | |_
+ / _ \| '_ \ / _ \ '_ \ / _` |/ _ \| __|
+| (_) | |_) |  __/ | | | (_| | (_) | |_
+ \___/| .__/ \___|_| |_|\__,_|\___/ \__|
+      |_|
+```
+
+**An interactive terminal AI agent you can fully undo.**
+
+[![CI](https://github.com/vedaant00/opendot/actions/workflows/ci.yml/badge.svg)](https://github.com/vedaant00/opendot/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/opendot.svg)](https://pypi.org/project/opendot/)
+[![Downloads](https://static.pepy.tech/badge/opendot)](https://pepy.tech/project/opendot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+</div>
+
+
+opendot works directly on your real files and shell — but unlike other terminal
+agents, **every action it takes is snapshotted first**, so you can see exactly
+what it did and cleanly walk it back. Files *and* shell commands, not just
+in-repo edits. Commands whose effects escape your workspace (network, sudo,
+`git push`, deleting outside the working dir) are flagged and confirmed before
+they run, with an honest note about what can't be undone.
+
+That's the point of opendot: an agent you can let loose because nothing it does
+is a surprise, and (almost) nothing is irreversible.
+
+## Install
+
+```bash
+# try it instantly, no install
+uvx opendot
+
+# recommended (isolated global CLI)
+uv tool install opendot        # or: pipx install opendot
+
+# also works
+pip install opendot
+```
+
+## Use
+
+```bash
+opendot                              # open an interactive chat
+opendot -p "summarize this project"  # one-shot, for scripts / CI
+opendot --model claude-sonnet-4-5    # any model (see below)
+
+opendot log                          # audit: what has the agent done here?
+opendot undo                         # revert the last action
+opendot undo 000004                  # restore the workspace to before action #4
+```
+
+Inside the chat, slash-commands: `/log`, `/undo`, `/clear`, `/compact`,
+`/model`, `/help`.
+
+## Any model
+
+opendot uses [LiteLLM](https://docs.litellm.ai), so any model works — cloud,
+local, or Hugging Face. Set the provider's API key in your environment and pass
+`--model`:
+
+| Provider | Env var | Example `--model` |
+|----------|---------|-------------------|
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5` |
+| Google | `GEMINI_API_KEY` | `gemini/gemini-2.0-flash` |
+| Ollama (local) | — | `ollama/qwen2.5` |
+
+Reasoning models stream their thinking live.
+
+## Connect MCP servers
+
+opendot is an [MCP](https://modelcontextprotocol.io) client: connect any MCP
+server and its tools become available to the agent alongside the built-in ones.
+
+```bash
+# a stdio server — put its launch command after `--`
+opendot mcp add <name> --env KEY=VALUE -- <command> [args...]
+
+# a remote server (http/sse)
+opendot mcp add <name> --url <https url>
+
+opendot mcp list           # show configured servers
+opendot mcp remove <name>  # remove one
+```
+
+Servers are stored in `~/.opendot/mcp.json` and connect automatically on the
+next launch; connected servers appear in the sidebar.
+
+Because opendot can't know what an external tool does, **every MCP tool call is
+treated as irreversible** — it's confirmed before running and marked ✗ in the
+ledger. Your built-in file/shell actions stay snapshotted and undoable as usual.
+
+## Project rules — `OPENDOT.md`
+
+Drop an `OPENDOT.md` in your project. Its prose is given to the agent as
+context. You can also control what gets snapshotted with an `opendot` block:
+
+````markdown
+```opendot
+# snapshot these even though they'd normally be skipped:
+snapshot: dist
+# never snapshot these:
+skip: data, *.log
+```
+````
+
+By default opendot skips `.git`, `node_modules`, virtualenvs, and build caches
+when snapshotting — your rules override those in either direction.
+
+## How the reversibility works
+
+- Before every file write or shell command, opendot snapshots the working
+  directory into a **content-addressed store** in `~/.opendot` (each unique file
+  stored once, so snapshots are cheap).
+- Every action is recorded in an **append-only ledger** you can inspect with
+  `opendot log`.
+- `opendot undo` restores the workspace to a chosen point, exactly.
+- A conservative **classifier** decides which shell commands are workspace-
+  contained (auto-run, undoable) vs. escaping (confirmed first, marked
+  irreversible). When unsure, it asks.
+
+Honest boundary: opendot cannot undo effects that leave your machine (a sent
+email, a dropped remote database, a `git push`). It tells you *before* running
+those, rather than pretending otherwise.
+
+## Status
+
+Early (alpha). The interactive agent, local tools, and the full reversibility
+engine work and are tested. Streaming, slash-commands, and `OPENDOT.md` rules
+are in. A richer TUI and more tools are coming.
+
+MIT licensed.

opendot-0.0.1/README.md

@@ -0,0 +1,137 @@
+<div align="center">
+
+```
+                          _       _
+  ___  _ __   ___ _ __   __| | ___ | |_
+ / _ \| '_ \ / _ \ '_ \ / _` |/ _ \| __|
+| (_) | |_) |  __/ | | | (_| | (_) | |_
+ \___/| .__/ \___|_| |_|\__,_|\___/ \__|
+      |_|
+```
+
+**An interactive terminal AI agent you can fully undo.**
+
+[![CI](https://github.com/vedaant00/opendot/actions/workflows/ci.yml/badge.svg)](https://github.com/vedaant00/opendot/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/opendot.svg)](https://pypi.org/project/opendot/)
+[![Downloads](https://static.pepy.tech/badge/opendot)](https://pepy.tech/project/opendot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+</div>
+
+
+opendot works directly on your real files and shell — but unlike other terminal
+agents, **every action it takes is snapshotted first**, so you can see exactly
+what it did and cleanly walk it back. Files *and* shell commands, not just
+in-repo edits. Commands whose effects escape your workspace (network, sudo,
+`git push`, deleting outside the working dir) are flagged and confirmed before
+they run, with an honest note about what can't be undone.
+
+That's the point of opendot: an agent you can let loose because nothing it does
+is a surprise, and (almost) nothing is irreversible.
+
+## Install
+
+```bash
+# try it instantly, no install
+uvx opendot
+
+# recommended (isolated global CLI)
+uv tool install opendot        # or: pipx install opendot
+
+# also works
+pip install opendot
+```
+
+## Use
+
+```bash
+opendot                              # open an interactive chat
+opendot -p "summarize this project"  # one-shot, for scripts / CI
+opendot --model claude-sonnet-4-5    # any model (see below)
+
+opendot log                          # audit: what has the agent done here?
+opendot undo                         # revert the last action
+opendot undo 000004                  # restore the workspace to before action #4
+```
+
+Inside the chat, slash-commands: `/log`, `/undo`, `/clear`, `/compact`,
+`/model`, `/help`.
+
+## Any model
+
+opendot uses [LiteLLM](https://docs.litellm.ai), so any model works — cloud,
+local, or Hugging Face. Set the provider's API key in your environment and pass
+`--model`:
+
+| Provider | Env var | Example `--model` |
+|----------|---------|-------------------|
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5` |
+| Google | `GEMINI_API_KEY` | `gemini/gemini-2.0-flash` |
+| Ollama (local) | — | `ollama/qwen2.5` |
+
+Reasoning models stream their thinking live.
+
+## Connect MCP servers
+
+opendot is an [MCP](https://modelcontextprotocol.io) client: connect any MCP
+server and its tools become available to the agent alongside the built-in ones.
+
+```bash
+# a stdio server — put its launch command after `--`
+opendot mcp add <name> --env KEY=VALUE -- <command> [args...]
+
+# a remote server (http/sse)
+opendot mcp add <name> --url <https url>
+
+opendot mcp list           # show configured servers
+opendot mcp remove <name>  # remove one
+```
+
+Servers are stored in `~/.opendot/mcp.json` and connect automatically on the
+next launch; connected servers appear in the sidebar.
+
+Because opendot can't know what an external tool does, **every MCP tool call is
+treated as irreversible** — it's confirmed before running and marked ✗ in the
+ledger. Your built-in file/shell actions stay snapshotted and undoable as usual.
+
+## Project rules — `OPENDOT.md`
+
+Drop an `OPENDOT.md` in your project. Its prose is given to the agent as
+context. You can also control what gets snapshotted with an `opendot` block:
+
+````markdown
+```opendot
+# snapshot these even though they'd normally be skipped:
+snapshot: dist
+# never snapshot these:
+skip: data, *.log
+```
+````
+
+By default opendot skips `.git`, `node_modules`, virtualenvs, and build caches
+when snapshotting — your rules override those in either direction.
+
+## How the reversibility works
+
+- Before every file write or shell command, opendot snapshots the working
+  directory into a **content-addressed store** in `~/.opendot` (each unique file
+  stored once, so snapshots are cheap).
+- Every action is recorded in an **append-only ledger** you can inspect with
+  `opendot log`.
+- `opendot undo` restores the workspace to a chosen point, exactly.
+- A conservative **classifier** decides which shell commands are workspace-
+  contained (auto-run, undoable) vs. escaping (confirmed first, marked
+  irreversible). When unsure, it asks.
+
+Honest boundary: opendot cannot undo effects that leave your machine (a sent
+email, a dropped remote database, a `git push`). It tells you *before* running
+those, rather than pretending otherwise.
+
+## Status
+
+Early (alpha). The interactive agent, local tools, and the full reversibility
+engine work and are tested. Streaming, slash-commands, and `OPENDOT.md` rules
+are in. A richer TUI and more tools are coming.
+
+MIT licensed.

opendot-0.0.1/SECURITY.md

@@ -0,0 +1,47 @@
+# Security
+
+## Threat model
+
+### Overview
+
+opendot is an AI-powered agent that runs **locally on your machine**. It gives a
+model access to real tools: shell execution, file read/write/edit, and — if you
+configure them — external MCP servers.
+
+### No sandbox
+
+opendot does **not** sandbox the agent. Two features exist to keep you in
+control, but neither is a security boundary:
+
+- **Confirmation prompts** ask before running commands opendot judges
+  irreversible or workspace-escaping (network, `sudo`, deletes outside the
+  working dir, external MCP calls). This is a UX safety net, not isolation.
+- **Reversibility** snapshots the workspace before each action so you can `undo`
+  file/shell changes. This lets you *walk back* mistakes made inside the
+  workspace — it does **not** prevent an action, and it cannot undo effects that
+  leave your machine (a sent request, a dropped remote database, `git push`).
+
+If you need true isolation, run opendot inside a Docker container or VM.
+
+### Out of scope
+
+| Category | Rationale |
+|----------|-----------|
+| Sandbox escapes | opendot is not a sandbox — the confirm/undo system is a UX layer (see above). |
+| Effects outside the workspace | Actions that leave your machine are flagged as irreversible before running, but cannot be undone; running them is your decision. |
+| LLM provider data handling | Data sent to your configured model provider is governed by their policies. |
+| MCP server behavior | External MCP servers you configure are outside opendot's trust boundary. |
+| Malicious config files | You control your own `~/.opendot` config; modifying it is not an attack vector. |
+
+## Reporting a vulnerability
+
+> [!IMPORTANT]
+> We do not accept AI-generated security reports. Please only submit findings you
+> have personally verified.
+
+To report a security issue, use the repository's **GitHub Security Advisory
+"Report a Vulnerability"** tab. We'll acknowledge your report and keep you
+informed of progress toward a fix, and may ask for additional detail.
+
+We appreciate responsible disclosure and will make every effort to acknowledge
+your contribution.

opendot-0.0.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opendot"
+version = "0.0.1"
+description = "An interactive terminal AI agent you can fully undo — any model, acts on your real files, every action reversible."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Vedaant Singh" }]
+keywords = ["ai", "agent", "cli", "llm", "litellm", "coding-agent", "terminal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "litellm>=1.50",     # any model: cloud, local, HF, through one interface
+    "rich>=13.0",        # pretty terminal output (plain REPL fallback)
+    "textual>=0.60",     # full-screen TUI (main pane + live ledger sidebar)
+    "prompt_toolkit>=3.0",  # plain REPL input (history, editing)
+    "mcp>=1.2",          # MCP client: connect to external MCP servers' tools
+]
+
+[project.optional-dependencies]
+office = ["openpyxl>=3.1", "python-pptx>=0.6"]  # xlsx / pptx read+edit tools
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "openpyxl>=3.1", "python-pptx>=0.6"]
+
+[project.scripts]
+opendot = "opendot.cli:main"
+
+[project.urls]
+Repository = "https://github.com/vedaant00/opendot"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opendot"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"   # pytest-asyncio runs `async def test_*` without per-test markers

opendot-0.0.1/src/opendot/__init__.py

@@ -0,0 +1,18 @@
+"""opendot — an interactive terminal AI agent you can fully undo.
+
+Public SDK surface (so CLI, and future clients, are thin layers over this):
+
+    from opendot import Agent, AgentConfig
+
+    agent = Agent(AgentConfig(model="gpt-4o"))
+    async for event in agent.run("list the python files and summarize them"):
+        ...
+"""
+
+from opendot.agent.loop import Agent
+from opendot.agent.config import AgentConfig
+from opendot.agent.events import Event
+
+__version__ = "0.0.1"
+
+__all__ = ["Agent", "AgentConfig", "Event", "__version__"]

opendot-0.0.1/src/opendot/agent/__init__.py

@@ -0,0 +1 @@
+"""The opendot agent: the model-agnostic ReAct loop, config, events, prompt."""

opendot-0.0.1/src/opendot/agent/config.py

@@ -0,0 +1,27 @@
+"""Agent configuration.
+
+Model IDs are whatever LiteLLM accepts (``gpt-4o``, ``claude-sonnet-4-5``,
+``ollama/qwen2.5``, ``huggingface/...``, etc.) — opendot is model-agnostic and
+does not maintain its own provider list. API keys are read from the environment
+by LiteLLM in the usual way (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+# A sensible default that works if the user has an OpenAI key; over/ridden via
+# --model, the OPENDOT_MODEL env var, or config.
+DEFAULT_MODEL = os.environ.get("OPENDOT_MODEL", "gpt-4o")
+
+
+@dataclass
+class AgentConfig:
+    """Everything the agent loop needs. Kept minimal for v1."""
+
+    model: str = DEFAULT_MODEL
+    workdir: str = field(default_factory=os.getcwd)
+    max_steps: int = 40  # hard bound on tool-calling turns per user message
+    temperature: float | None = None
+    system_prompt: str | None = None  # None => use the built-in default

opendot-0.0.1/src/opendot/agent/events.py

@@ -0,0 +1,34 @@
+"""Events streamed by the agent loop.
+
+The loop is an async generator of these. The CLI renders them; a future SDK
+consumer or remote client can consume them just as easily. Keeping this a small,
+stable vocabulary is what lets other surfaces (TUI, web, Slack) be thin adapters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+EventType = Literal[
+    "thinking",    # a streamed chunk of the model's reasoning (reasoning models)
+    "text",        # a streamed chunk of the assistant's answer
+    "tool_start",  # the agent is about to run a tool
+    "tool_end",    # a tool finished (result attached)
+    "final",       # the assistant's turn is complete
+    "error",       # something went wrong
+    # parallel read-only explorers
+    "explorer_start",  # a subagent lane started (text=task, lane=index)
+    "explorer_step",   # a subagent did something (text=summary, lane=index)
+    "explorer_done",   # a subagent finished (text=finding summary, lane=index)
+]
+
+
+@dataclass
+class Event:
+    type: EventType
+    text: str = ""                       # for "text" / "error" / explorer_*
+    tool: str = ""                       # for tool_start / tool_end
+    args: dict[str, Any] = field(default_factory=dict)  # tool_start
+    result: str = ""                     # tool_end
+    lane: int = -1                       # explorer lane index (-1 = main agent)