98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# PRD 0026: Agent Provider Templates
|
|
|
|
- **Status:** Active
|
|
- **Author:** codex
|
|
- **Created:** 2026-05-28
|
|
|
|
## Summary
|
|
|
|
Support Claude and Codex agent providers while keeping agent files provider-agnostic and bottle files responsible for boundaries.
|
|
|
|
## Problem
|
|
|
|
Today bot-bottle is hard-wired around Claude Code assumptions. When Claude runs out or is otherwise unavailable, the operator cannot spin up an equivalent Codex-backed bottle from the dashboard or `start` path. Agent files should remain purpose/guidance documents, while bottle files define security boundaries and provider/runtime choices.
|
|
|
|
## Goals / Success Criteria
|
|
|
|
- A Codex agent can be started from the dashboard and via `./cli.py start` alongside a Claude agent.
|
|
- The manifest can express the agent provider/template and, where needed, a custom agent Dockerfile.
|
|
- Claude-specific default egress/auth behavior is no longer implicit; provider-specific auth is expressed through explicit bottle egress routes and roles.
|
|
- The launcher preserves required infrastructure behavior for sidecars, egress, pipelock, supervisor MCP, CA handling, git, and shell basics.
|
|
- Unit tests cover manifest parsing, provider validation, provider-specific auth role behavior, and launch/prepare plan differences.
|
|
|
|
## Non-goals
|
|
|
|
- Do not implement support for providers beyond Claude and Codex.
|
|
- Do not move security boundaries into agent files.
|
|
- Do not allow custom Dockerfiles to remove or bypass required bot-bottle infrastructure.
|
|
- Do not add new runtime dependencies unless the existing Docker/Codex tooling cannot satisfy the minimum cut.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- Add a bottle-level provider/template configuration for Claude and Codex.
|
|
- Add a Codex template that can launch a Codex agent from the dashboard and `start`.
|
|
- Support a custom agent Dockerfile path for the agent environment.
|
|
- Make Claude-specific egress/auth defaults explicit in bottle manifests instead of auto-provided.
|
|
- Add a Codex-specific auth role and provider-aware role validation.
|
|
- Keep existing Claude behavior available through a Claude provider/template.
|
|
- Gate Claude-specific crash-state/transcript handling behind a Claude-only flag or provider branch.
|
|
|
|
### Out of scope
|
|
|
|
- Implementing providers beyond Claude and Codex.
|
|
- Redesigning the agent file format beyond keeping it provider/bottle agnostic.
|
|
- Reworking the whole state/transcript subsystem in this PRD; provider-specific state handling should be isolated now and refactored in a follow-up.
|
|
|
|
## Proposed Design
|
|
|
|
### New services / components
|
|
|
|
- New `AgentProvider` model for provider/template behavior.
|
|
- Bottle manifests use a nested `agent_provider` shape:
|
|
|
|
```yaml
|
|
agent_provider:
|
|
template: codex # or claude
|
|
dockerfile: ./Dockerfile.codex # optional
|
|
```
|
|
|
|
- Provider templates do not implicitly add egress routes. Operators
|
|
should put provider-specific `agent_provider` and egress/auth routes
|
|
in home-owned base bottles such as `claude` or `codex`, then use
|
|
`extends` for task-specific bottles.
|
|
- Provider-specific launch configuration for Claude and Codex, including command argv, auth placeholder behavior, and default image/Dockerfile selection.
|
|
- Provider-aware egress role validation, including a new Codex auth role.
|
|
|
|
### Existing code touched
|
|
|
|
- `bot_bottle/manifest.py` for provider schema and role validation.
|
|
- Docker and smolmachines prepare/launch/provision paths for provider-specific image, command, auth, and state behavior.
|
|
- Dashboard/start display paths so the selected provider is visible and usable.
|
|
- README and PRD docs for provider/template configuration.
|
|
- Unit tests around manifest parsing, backend plans, launch argv, egress roles, and dashboard/start behavior.
|
|
|
|
### Data model changes
|
|
|
|
- Manifest schema gains bottle-level provider/template configuration.
|
|
- No persistent state migration is expected.
|
|
- Existing Claude-specific crash-state/transcript dumping in the state folder should be guarded so it only runs for Claude agents. A broader state/transcript abstraction is a follow-up.
|
|
|
|
### External dependencies
|
|
|
|
- Avoid new runtime dependencies where possible.
|
|
- Use existing Docker image build flows and whatever Codex install is already available in the chosen agent image/template.
|
|
|
|
## Open questions
|
|
|
|
- `codex_auth` is retained as a placeholder marker for follow-up Codex
|
|
credential-injection work. The Codex template should not inject an
|
|
`OPENAI_API_KEY` placeholder; Codex bottles use device/ChatGPT login
|
|
state instead.
|
|
- Existing state-folder transcript capture is Claude-specific and should remain gated to Claude until the follow-up state/transcript refactor.
|
|
|
|
## References
|
|
|
|
- Issue #90: Support for different agents
|