bot-bottle/docs/prds/0053-user-provider-plugins.md

# PRD 0053: User-defined agent provider plugins

- **Status:** Draft
- **Author:** claude
- **Created:** 2026-06-04

## Summary

The `get_provider()` registry in `bot_bottle/agent_provider.py` is a closed list —
only `"claude"` and `"codex"` are valid templates, validated at manifest-load time and
again at launch. Users who want to run a different agent (Gemini, Aider, a custom
local model wrapper) cannot add a provider without forking the package.

This PRD opens the registry to user-defined plugins. A plugin placed at
`~/.bot-bottle/contrib/<name>/agent_provider.py` is discovered and loaded at launch
time. The manifest accepts any non-empty template string that names a built-in or
resolves to a user plugin at that path. No changes to the built-in providers or the
internal `bot_bottle/contrib/` layout.

The preceding commit on this PR moves `codex_auth.py` from `bot_bottle/` into
`bot_bottle/contrib/codex/` — a clean-up that fits naturally here since this PR
also clarifies that `contrib/` is the per-provider home.

## Problem

Users building unconventional setups hit a hard wall: the template validation in
`manifest_agent.AgentProvider.from_dict` rejects any string not in `PROVIDER_TEMPLATES`.
There is no escape hatch short of editing bot-bottle's source.

PRD 0050 moved provider logic into `contrib/` specifically so a third provider would
be "cheap to add" — but "cheap" today still means a pull request against the bot-bottle
repo, not a drop-in file in the user's home directory. The filesystem layout is already
the right shape; the discovery step is missing.

## Goals / Success Criteria

1. A user places `~/.bot-bottle/contrib/<name>/agent_provider.py` — a file that exports
   a class inheriting `AgentProvider` — sets `agent_provider.template: <name>` in a
   bottle's frontmatter, and launches a bottle using that provider with no changes to
   the bot-bottle source.
2. The manifest validator accepts any non-empty template string. Unknown templates that
   resolve to no user plugin still raise a clear error, but at launch (via `get_provider`)
   rather than at manifest-load time.
3. Built-in provider knobs (`auth_token` → claude only; `forward_host_credentials` →
   codex only) are guarded to built-in template names. Bottles using a user provider
   may set neither knob.
4. `get_provider(template)` checks `~/.bot-bottle/contrib/<template>/agent_provider.py`
   before the built-ins, so a user can shadow a built-in for local testing.
5. A clear `ValueError` is raised if the user plugin file exists but contains no
   `AgentProvider` subclass.

## Non-goals

- Packaging or distributing user plugins as installable Python packages.
- A plugin registry, index, or discovery beyond the filesystem path convention.
- Adding a third built-in provider.
- Changing the `AgentProvider` ABC contract — user plugins implement the same abstract
  methods as `ClaudeAgentProvider` and `CodexAgentProvider`.
- Validating that user plugin images, Dockerfiles, or commands exist before launch
  (same policy as built-ins).
- Sandboxing user plugin code — plugins run with full Python interpreter access.

## Scope

### In scope

- `get_provider(template: str) -> AgentProvider` gains a `_load_user_plugin(template)`
  step that checks `~/.bot-bottle/contrib/<template>/agent_provider.py` first, then
  falls through to the built-in look-ups.
- `_load_user_plugin` uses `importlib.util.spec_from_file_location` to load the module
  and returns the first `AgentProvider` subclass found in its `__dict__`. Raises
  `ValueError` if the file exists but exports no subclass.
- `manifest_agent.AgentProvider.from_dict`: the `template not in PROVIDER_TEMPLATES`
  check is removed; the two built-in-specific knob guards (`auth_token` → claude,
  `forward_host_credentials` → codex) are tightened to `template in PROVIDER_TEMPLATES`
  so they are skipped for user-defined names.
- `PROVIDER_TEMPLATES` remains in `agent_provider.py` as the set of built-in names for
  use by tests and any enumeration callers.
- Unit tests for the discovery path:
  - Plugin found and loaded → correct `AgentProvider` instance returned.
  - Plugin file exists but exports no subclass → `ValueError`.
  - Unknown template with no user plugin → `ValueError` from `get_provider`.
  - Built-in template name still works normally even when no user plugin exists.
- One paragraph added to `README.md` under a new "Custom providers" section describing
  the `~/.bot-bottle/contrib/<name>/agent_provider.py` convention and pointing at the
  existing contrib providers as reference implementations.

### Out of scope

- Hot-reloading plugins during a running session.
- Plugin versioning or dependency declaration.
- Changes to smolmachines or Docker backend provisioning paths.

## Proposed design

### Discovery in `get_provider`

```python
import importlib.util

def get_provider(template: str) -> AgentProvider:
    user_plugin = _load_user_plugin(template)
    if user_plugin is not None:
        return user_plugin
    if template == PROVIDER_CLAUDE:
        from .contrib.claude.agent_provider import ClaudeAgentProvider
        return ClaudeAgentProvider()
    if template == PROVIDER_CODEX:
        from .contrib.codex.agent_provider import CodexAgentProvider
        return CodexAgentProvider()
    raise ValueError(f"unknown agent provider template: {template!r}")


def _load_user_plugin(template: str) -> AgentProvider | None:
    plugin_path = (
        Path.home() / ".bot-bottle" / "contrib" / template / "agent_provider.py"
    )
    if not plugin_path.exists():
        return None
    spec = importlib.util.spec_from_file_location(
        f"_user_contrib_{template}.agent_provider", plugin_path
    )
    if spec is None or spec.loader is None:
        raise ValueError(f"user plugin at {plugin_path} could not be loaded")
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)  # type: ignore[union-attr]
    for obj in vars(mod).values():
        if (
            isinstance(obj, type)
            and issubclass(obj, AgentProvider)
            and obj is not AgentProvider
        ):
            return obj()
    raise ValueError(
        f"user plugin at {plugin_path} defines no AgentProvider subclass"
    )
```

### Manifest validation change

In `manifest_agent.AgentProvider.from_dict`, remove the hard rejection:

```python
# Before
if template not in PROVIDER_TEMPLATES:
    raise ManifestError(
        f"bottle '{bottle_name}' agent_provider.template {template!r} "
        f"is not one of {', '.join(sorted(PROVIDER_TEMPLATES))}"
    )

# After — removed entirely; get_provider() raises at launch for unknown names
```

Guard the built-in knob checks with `template in PROVIDER_TEMPLATES`:

```python
if auth_token and template == "claude":   # unchanged
    ...
if auth_token and template not in PROVIDER_TEMPLATES:
    raise ManifestError(
        f"bottle '{bottle_name}' agent_provider.auth_token is only "
        f"supported for built-in templates ({', '.join(sorted(PROVIDER_TEMPLATES))})"
    )
if forward_host_credentials and template == "codex":  # unchanged
    ...
if forward_host_credentials and template not in PROVIDER_TEMPLATES:
    raise ManifestError(
        f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
        f"is only supported for built-in templates"
    )
```

## Open questions

1. **Shadow order.** This PRD puts user plugins before built-ins, allowing local
   overrides. If the preference is built-ins-first (to prevent accidental shadowing),
   swap the order and document accordingly.
2. **`BOT_BOTTLE_CONTRIB_DIR` env var.** Omitted for now — `~/.bot-bottle/contrib/`
   is consistent with the rest of the user config layout. Revisit if the need surfaces.

## References

- PRD 0050 — agent provider contrib (established `contrib/` as the per-provider home)
- PRD 0048 — SSH deploy key provisioning (the `contrib/` convention)
- `bot_bottle/agent_provider.py` — `get_provider`, `PROVIDER_TEMPLATES`, `AgentProvider` ABC
- `bot_bottle/manifest_agent.py` — template validation that this PRD relaxes