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:

[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:

[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 require restarting cao-server.
• Event dispatch only happens after the underlying CAO operation succeeds (e.g. post_create_terminal fires after the terminal is persisted, not before).
• There are no pre_* hooks today — you cannot veto or mutate an operation from a plugin.