cao-plugin

# CAO Plugin Creator

Guide for creating a new CAO plugin. A "plugin" is a Python package installed alongside CAO that subscribes to CAO lifecycle and messaging events via typed async hooks.

## What You're Building

A CAO plugin is a standalone Python package that:

1. **Subclasses `CaoPlugin`** from `cli_agent_orchestrator.plugins`
2. **Registers async hook methods** with `@hook("<event_type>")` decorators
3. **Is discovered via the `cao.plugins` Python entry-point group** at `cao-server` startup
4. **Runs fire-and-forget** — plugin exceptions are caught and logged as warnings, never propagated back into CAO

Typical uses: forwarding inter-agent messages to chat apps, logging/observability, external dashboards, metrics export, alerting on session or terminal lifecycle.

## Before You Start

Gather this information:

- Which events do you need? See `references/hook-events.md` for the full catalog.
- Does the plugin need persistent state across events? (HTTP client, DB connection, buffer) — if so, use `setup()` / `teardown()`.
- How is it configured? v1 has no injected config API — read env vars in `setup()`, optionally via `python-dotenv`.
- What are the failure semantics of your integration? Remember CAO swallows hook exceptions — you must decide whether to log, retry, or drop on your own.

## Hard Requirements

These are the non-negotiable contracts a plugin must satisfy to be loaded and dispatched to. Verify each one before calling your plugin complete.

### 1. Package layout

Minimum viable layout:

```
my-cao-plugin/
├── pyproject.toml          # Build config + entry-point declaration
├── my_cao_plugin/
│   ├── __init__.py         # Can be empty
│   └── plugin.py           # Contains the CaoPlugin subclass
├── tests/                  # Optional but strongly recommended
│   └── test_plugin.py
├── env.template            # Optional; only if the plugin reads env vars
└── README.md               # Optional; install + config instructions for users
```

See `examples/plugins/cao-discord/` in this repo for a complete reference implementation.

### 2. Plugin class contract

- Must subclass `CaoPlugin` from `cli_agent_orchestrator.plugins`.
- Must be zero-arg constructible — the registry instantiates plugins with `cls()`. Do NOT define `__init__` with required parameters.
- May override `async def setup(self) -> None` — called once at `cao-server` startup after instantiation.
- May override `async def teardown(self) -> None` — called once at `cao-server` shutdown.
- No other methods are required. Hooks are opt-in via the `@hook` decorator.

A raising `setup()` disables that plugin for the lifetime of the server process (warning logged, other plugins continue to load). A raising `teardown()` is logged and does not stop other plugins from tearing down.

### 3. Hook method contract

A hook method must:

- Be `async def` — sync hooks are not supported in v1.
- Be decorated with `@hook("<event_type>")` using the exact event-type string from `references/hook-events.md`.
- Accept exactly one positional argument: the typed event dataclass matching that event type.
- Return `None`.
- Be a regular method on the plugin class (the registry discovers hooks via `inspect.getmembers` on the instance).

Multiple hook methods on the same plugin may subscribe to the same event type — each is dispatched independently. Execution order across hooks is not guaranteed.

Exceptions raised inside a hook are caught by the registry and logged as warnings. They do not affect CAO's primary operation and they do not stop other hooks for the same event from running.

### 4. Entry-point registration

Declare the plugin class under the `cao.plugins` entry-point group in `pyproject.toml`:

```toml
[project.entry-points."cao.plugins"]
my_plugin = "my_cao_plugin.plugin:MyPlugin"
```

- The key (`my_plugin`) is the plugin name used in CAO's startup log (`Loaded CAO plugin: my_plugin`). It has no other runtime effect.
- The value must resolve to a class that is a subclass of `CaoPlugin`. Entry points whose target is not a `CaoPlugin` subclass are skipped with a warning.
- A single package may declare multiple entry points under `cao.plugins` if it ships multiple plugin classes.

No CAO-side configuration is required to enable a plugin — installation plus entry-point declaration is sufficient.

### 5. Build system

- Use `hatchling` as the build backend to match CAO's toolchain.
- Target Python `>=3.10`.
- Declare `cli-agent-orchestrator` as a runtime dependency so `CaoPlugin`, `hook`, and the event dataclasses are importable.
- Declare any external libraries (e.g. `httpx`, `aiohttp`, `python-dotenv`) your plugin uses.

Minimal `pyproject.toml`:

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-cao-plugin"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "cli-agent-orchestrator",
    # ... your plugin's deps
]

[project.entry-points."cao.plugins"]
my_plugin = "my_cao_plugin.plugin:MyPlugin"
```

### 6. Configuration

CAO does not inject configuration into plugins in v1. Options:

- **Environment variables** — read inside `setup()` with `os.environ.get(...)`. Raise `RuntimeError` with a clear message if a required var is missing so the startup log points the user at the misconfiguration.
- **`.env` files** — use `python-dotenv` (`load_dotenv(find_dotenv(usecwd=True))`) inside `setup()`. Process-level env vars override `.env` values, which is the expected precedence.
- **Config files** — load any path you like inside `setup()`; you own the format.

Ship an `env.template` alongside the plugin if it reads env vars, documenting every variable, whether it's required, and its default.

### 7. Lifecycle guarantees

- `setup()` is awaited exactly once, after the plugin class is instantiated at server startup.
- `teardown()` is awaited exactly once at server shutdown, only for plugins whose `setup()` succeeded.
- There is no hot reload — changes to an installed plugin