[Phase 4] Engine Registry and Runtime Selection

[frankbria]

Summary

Create an engine registry that maps engine names to AgentAdapter implementations and wire it into the runtime's execute_agent() function, replacing the current hardcoded if engine == "react" / elif engine == "plan" branching.

Parent issue: #408

Scope

New module: core/engine_registry.py

1. EngineRegistry class:

class EngineRegistry:
    _engines: dict[str, type[AgentAdapter]] = {}
    
    @classmethod
    def register(cls, name: str, adapter_class: type[AgentAdapter]):
        cls._engines[name] = adapter_class
    
    @classmethod
    def get(cls, name: str) -> AgentAdapter:
        if name not in cls._engines:
            raise ValueError(f"Unknown engine '{name}'. Available: {cls.available()}")
        return cls._engines[name]()
    
    @classmethod
    def available(cls) -> list[str]:
        return sorted(cls._engines.keys())
    
    @classmethod
    def check_requirements(cls, name: str) -> dict[str, bool]:
        """Check if engine's requirements are met (API keys, binaries)."""
        ...

2. Built-in registrations:

   • "built-in" → BuiltInReactAdapter (wraps existing ReactAgent)
   • "plan" → BuiltInPlanAdapter (wraps existing Agent)
   • "claude-code" → ClaudeCodeAdapter (from [Phase 4] Claude Code Engine Adapter #411)
   • "codex" → CodexAdapter (from [Phase 4] Codex/OpenAI Engine Adapter (App-Server Protocol) #412)
   • "aider" → AiderAdapter (from [Phase 4] Aider Engine Adapter #413)

3. BuiltInReactAdapter — wraps existing ReactAgent to satisfy AgentAdapter protocol:

   • Takes AgentContext, builds the 3-layer system prompt internally
   • Returns AgentResult from AgentStatus
   • This keeps ReactAgent working exactly as before

Changes to core/runtime.py

4. Refactor execute_agent():
   • Replace if engine == "react" branching with registry lookup
   • Use ContextPackager to build AgentContext
   • Call adapter.execute()
   • Map AgentResult back to AgentState for runtime state management
   • Keep verification gate logic outside the adapter (CodeFrame owns gates)

Changes to cli/app.py

5. Update --engine flag:
   • Accept any registered engine name
   • cf work start <id> --execute --engine claude-code
   • Add cf engines list command showing available engines and their requirements
   • Add cf engines check <name> to validate requirements (API keys, binaries)

Changes to AGENTS.md / CODEFRAME.md support

6. Default engine configurable per-workspace:

   engine: claude-code  # or: built-in, codex, aider, plan

Acceptance Criteria

• EngineRegistry maps engine names to adapter classes
• BuiltInReactAdapter wraps ReactAgent (no behavior change)
• execute_agent() uses registry instead of hardcoded branching
• --engine flag accepts any registered engine
• cf engines list shows available engines with requirement status
• Default engine configurable via workspace config
• Existing --engine react and --engine plan still work (mapped to built-in adapters)
• All existing tests pass (backward compatible)

Dependencies

• Depends on [Phase 4] Agent Adapter Protocol Definition #409 (AgentAdapter protocol)
• Depends on [Phase 4] Task Context Packager for External Agents #410 (context packager)
• Should have at least one external adapter ([Phase 4] Claude Code Engine Adapter #411, [Phase 4] Codex/OpenAI Engine Adapter (App-Server Protocol) #412, or [Phase 4] Aider Engine Adapter #413) to validate

[traycerai]

Plan

Observations

The codebase has a well-structured codeframe/core/runtime.py with execute_agent() that hardcodes if engine == "react" / else branching. ReactAgent.run() returns AgentStatus, while Agent.run() returns AgentState. The existing codeframe/adapters/ package already hosts LLM adapters, making it a natural home for engine adapters. The CLI uses typer throughout; sub-apps are registered at the bottom of file:codeframe/cli/app.py. Config is YAML-based via file:codeframe/core/config.py's EnvironmentConfig dataclass.

Approach

Introduce a new codeframe/core/engine_registry.py module, add built-in adapters for the two existing engines, wire the registry into execute_agent(), extend EnvironmentConfig with an engine field, and add a cf engines CLI sub-app — all with zero behavior change to existing react/plan paths.

---

Implementation Steps

1. Create codeframe/core/engine_registry.py

Create a new module at file:codeframe/core/engine_registry.py containing:

• AgentAdapter protocol — a typing.Protocol with a single method execute(workspace, run, **kwargs) -> AgentState. This is the contract all adapters must satisfy. It should accept the same keyword arguments that execute_agent() currently passes (dry_run, debug, verbose, fix_coordinator, event_publisher).

• EngineRegistry class — a pure class-level registry (no instances):

  • _engines: dict[str, type[AgentAdapter]] = {} as a class variable
  • register(cls, name: str, adapter_class: type[AgentAdapter]) -> None — adds an entry
  • get(cls, name: str) -> AgentAdapter — instantiates and returns the adapter; raises ValueError with the list of available engines if name is unknown
  • available(cls) -> list[str] — returns sorted(_engines.keys())
  • check_requirements(cls, name: str) -> dict[str, bool] — for each registered adapter, call an optional requirements() classmethod if present (e.g. checking os.getenv("ANTHROPIC_API_KEY")); return a dict of requirement-name → bool

• BuiltInReactAdapter — wraps ReactAgent:

  • In execute(), construct ReactAgent with the exact same arguments currently used in execute_agent()'s if engine == "react" branch
  • Call react_agent.run(run.task_id) to get AgentStatus
  • Wrap the result into AgentState(status=react_status) and return it (mirroring the existing wrapping logic)
  • Add a requirements() classmethod returning {"ANTHROPIC_API_KEY": bool(os.getenv("ANTHROPIC_API_KEY"))}

• BuiltInPlanAdapter — wraps Agent:

  • In execute(), replicate the full else branch of execute_agent() including the supervisor BLOCKED-retry logic and tactical failure recovery
  • Return the AgentState from agent.run(run.task_id) (and retries)
  • Add the same requirements() classmethod

• Module-level registrations at the bottom of the file:

  EngineRegistry.register("react", BuiltInReactAdapter)
  EngineRegistry.register("built-in", BuiltInReactAdapter)   # alias per spec
  EngineRegistry.register("plan", BuiltInPlanAdapter)
  

  External adapters (claude-code, codex, aider) should register themselves from their own modules when those modules are imported — do not register them here to avoid hard dependencies.

---

2. Refactor execute_agent() in file:codeframe/core/runtime.py

• Import EngineRegistry from codeframe.core.engine_registry at the top of execute_agent() (keep it a local import to preserve the existing lazy-import pattern)
• Replace the valid_engines tuple check and the if engine == "react" / else branching with:
  1. Call EngineRegistry.get(engine) — this raises a descriptive ValueError if unknown, replacing the current manual check
  2. Call adapter.execute(workspace, run, dry_run=dry_run, debug=debug, verbose=verbose, fix_coordinator=fix_coordinator, event_publisher=event_publisher) to get AgentState
• Keep everything outside the adapter unchanged: the RunLogger, on_agent_event callback, output_logger, the final status-to-run mapping (complete_run / block_run / fail_run), and the _event_type_to_category helper
• The ANTHROPIC_API_KEY validation can remain in execute_agent() as a guard before the registry lookup for built-in adapters, or be delegated to EngineRegistry.check_requirements() — the simplest approach is to keep it as-is so no existing behavior changes

---

3. Extend EnvironmentConfig in file:codeframe/core/config.py

• Add an engine: str = "react" field to the EnvironmentConfig dataclass (alongside package_manager, test_framework, etc.)
• Update validate() to call EngineRegistry.available() and check that self.engine is in the list, appending an error message if not
• No changes needed to from_dict / to_dict since dataclasses.asdict handles it automatically

---

4. Read workspace engine default in work_start in file:codeframe/cli/app.py

In the work_start command:

• After resolving the workspace, call load_environment_config(workspace.repo_path) to get the EnvironmentConfig
• If the config exists and specifies an engine, use it as the default for the --engine option — only when the user has not explicitly passed --engine on the CLI
• The simplest approach: read the config default, and pass it as the default= value to the typer.Option — but since typer.Option defaults are static, instead check after option parsing: if the user did not override (i.e., engine == "react" and workspace config has a different value), replace engine with env_config.engine

---

5. Create codeframe/cli/engines_commands.py

Create a new file file:codeframe/cli/engines_commands.py following the same structure as file:codeframe/cli/agents_commands.py:

• engines_app = typer.Typer(name="engines", help="Engine management commands", no_args_is_help=True)

• list command — @engines_app.command("list"):

  • Call EngineRegistry.available() to get engine names
  • For each, call EngineRegistry.check_requirements(name) to get requirement status
  • Render a rich.table.Table with columns: Engine, Description, Requirements Status
  • Mark built-in engines (react, plan, built-in) as always available; others show their requirement checks

• check command — @engines_app.command("check"):

  • Accept a name: str argument
  • Call EngineRegistry.check_requirements(name)
  • Print each requirement and whether it's satisfied
  • Exit with code 1 if any requirement is missing

---

6. Register engines_app in file:codeframe/cli/app.py

At the bottom of file:codeframe/cli/app.py (alongside the other app.add_typer(...) calls):

• Import engines_app from codeframe.cli.engines_commands
• Add app.add_typer(engines_app, name="engines")

---

Data Flow After Refactor

sequenceDiagram
    participant CLI as cli/app.py work_start
    participant RT as core/runtime.py execute_agent()
    participant REG as core/engine_registry.py EngineRegistry
    participant ADP as BuiltInReactAdapter / BuiltInPlanAdapter
    participant AGT as ReactAgent / Agent

    CLI->>RT: execute_agent(workspace, run, engine="react")
    RT->>REG: EngineRegistry.get("react")
    REG-->>RT: BuiltInReactAdapter instance
    RT->>ADP: adapter.execute(workspace, run, **kwargs)
    ADP->>AGT: ReactAgent(...).run(task_id)
    AGT-->>ADP: AgentStatus.COMPLETED
    ADP-->>RT: AgentState(status=COMPLETED)
    RT->>RT: complete_run / block_run / fail_run
    RT-->>CLI: AgentState

Loading

---

File Summary

File	Action
codeframe/core/engine_registry.py	Create — AgentAdapter protocol, EngineRegistry, BuiltInReactAdapter, BuiltInPlanAdapter
codeframe/core/runtime.py	Modify — replace hardcoded branching in execute_agent() with registry lookup
codeframe/core/config.py	Modify — add engine: str = "react" field to EnvironmentConfig and validate it
codeframe/cli/engines_commands.py	Create — engines_app with list and check commands
codeframe/cli/app.py	Modify — import and register engines_app; read workspace engine default in work_start

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-structured `codeframe/core/runtime.py` with `execute_agent()` that hardcodes `if engine == "react" / else` branching. `ReactAgent.run()` returns `AgentStatus`, while `Agent.run()` returns `AgentState`. The existing `codeframe/adapters/` package already hosts LLM adapters, making it a natural home for engine adapters. The CLI uses `typer` throughout; sub-apps are registered at the bottom of `file:codeframe/cli/app.py`. Config is YAML-based via `file:codeframe/core/config.py`'s `EnvironmentConfig` dataclass.

## Approach

Introduce a new `codeframe/core/engine_registry.py` module, add built-in adapters for the two existing engines, wire the registry into `execute_agent()`, extend `EnvironmentConfig` with an `engine` field, and add a `cf engines` CLI sub-app — all with zero behavior change to existing `react`/`plan` paths.

---

## Implementation Steps

### 1. Create `codeframe/core/engine_registry.py`

Create a new module at `file:codeframe/core/engine_registry.py` containing:

- **`AgentAdapter` protocol** — a `typing.Protocol` with a single method `execute(workspace, run, **kwargs) -> AgentState`. This is the contract all adapters must satisfy. It should accept the same keyword arguments that `execute_agent()` currently passes (`dry_run`, `debug`, `verbose`, `fix_coordinator`, `event_publisher`).

- **`EngineRegistry` class** — a pure class-level registry (no instances):
  - `_engines: dict[str, type[AgentAdapter]] = {}` as a class variable
  - `register(cls, name: str, adapter_class: type[AgentAdapter]) -> None` — adds an entry
  - `get(cls, name: str) -> AgentAdapter` — instantiates and returns the adapter; raises `ValueError` with the list of available engines if name is unknown
  - `available(cls) -> list[str]` — returns `sorted(_engines.keys())`
  - `check_requirements(cls, name: str) -> dict[str, bool]` — for each registered adapter, call an optional `requirements()` classmethod if present (e.g. checking `os.getenv("ANTHROPIC_API_KEY")`); return a dict of requirement-name → bool

- **`BuiltInReactAdapter`** — wraps `ReactAgent`:
  - In `execute()`, construct `ReactAgent` with the exact same arguments currently used in `execute_agent()`'s `if engine == "react"` branch
  - Call `react_agent.run(run.task_id)` to get `AgentStatus`
  - Wrap the result into `AgentState(status=react_status)` and return it (mirroring the existing wrapping logic)
  - Add a `requirements()` classmethod returning `{"ANTHROPIC_API_KEY": bool(os.getenv("ANTHROPIC_API_KEY"))}`

- **`BuiltInPlanAdapter`** — wraps `Agent`:
  - In `execute()`, replicate the full `else` branch of `execute_agent()` including the supervisor BLOCKED-retry logic and tactical failure recovery
  - Return the `AgentState` from `agent.run(run.task_id)` (and retries)
  - Add the same `requirements()` classmethod

- **Module-level registrations** at the bottom of the file:
  ```
  EngineRegistry.register("react", BuiltInReactAdapter)
  EngineRegistry.register("built-in", BuiltInReactAdapter)   # alias per spec
  EngineRegistry.register("plan", BuiltInPlanAdapter)
  ```
  External adapters (`claude-code`, `codex`, `aider`) should register themselves from their own modules when those modules are imported — do not register them here to avoid hard dependencies.

---

### 2. Refactor `execute_agent()` in `file:codeframe/core/runtime.py`

- Import `EngineRegistry` from `codeframe.core.engine_registry` at the top of `execute_agent()` (keep it a local import to preserve the existing lazy-import pattern)
- Replace the `valid_engines` tuple check and the `if engine == "react" / else` branching with:
  1. Call `EngineRegistry.get(engine)` — this raises a descriptive `ValueError` if unknown, replacing the current manual check
  2. Call `adapter.execute(workspace, run, dry_run=dry_run, debug=debug, verbose=verbose, fix_coordinator=fix_coordinator, event_publisher=event_publisher)` to get `AgentState`
- Keep everything outside the adapter unchanged: the `RunLogger`, `on_agent_event` callback, `output_logger`, the final status-to-run mapping (`complete_run` / `block_run` / `fail_run`), and the `_event_type_to_category` helper
- The `ANTHROPIC_API_KEY` validation can remain in `execute_agent()` as a guard before the registry lookup for built-in adapters, or be delegated to `EngineRegistry.check_requirements()` — the simplest approach is to keep it as-is so no existing behavior changes

---

### 3. Extend `EnvironmentConfig` in `file:codeframe/core/config.py`

- Add an `engine: str = "react"` field to the `EnvironmentConfig` dataclass (alongside `package_manager`, `test_framework`, etc.)
- Update `validate()` to call `EngineRegistry.available()` and check that `self.engine` is in the list, appending an error message if not
- No changes needed to `from_dict` / `to_dict` since `dataclasses.asdict` handles it automatically

---

### 4. Read workspace engine default in `work_start` in `file:codeframe/cli/app.py`

In the `work_start` command:

- After resolving the workspace, call `load_environment_config(workspace.repo_path)` to get the `EnvironmentConfig`
- If the config exists and specifies an `engine`, use it as the default for the `--engine` option — only when the user has not explicitly passed `--engine` on the CLI
- The simplest approach: read the config default, and pass it as the `default=` value to the `typer.Option` — but since `typer.Option` defaults are static, instead check after option parsing: if the user did not override (i.e., `engine == "react"` and workspace config has a different value), replace `engine` with `env_config.engine`

---

### 5. Create `codeframe/cli/engines_commands.py`

Create a new file `file:codeframe/cli/engines_commands.py` following the same structure as `file:codeframe/cli/agents_commands.py`:

- `engines_app = typer.Typer(name="engines", help="Engine management commands", no_args_is_help=True)`

- **`list` command** — `@engines_app.command("list")`:
  - Call `EngineRegistry.available()` to get engine names
  - For each, call `EngineRegistry.check_requirements(name)` to get requirement status
  - Render a `rich.table.Table` with columns: Engine, Description, Requirements Status
  - Mark built-in engines (`react`, `plan`, `built-in`) as always available; others show their requirement checks

- **`check` command** — `@engines_app.command("check")`:
  - Accept a `name: str` argument
  - Call `EngineRegistry.check_requirements(name)`
  - Print each requirement and whether it's satisfied
  - Exit with code 1 if any requirement is missing

---

### 6. Register `engines_app` in `file:codeframe/cli/app.py`

At the bottom of `file:codeframe/cli/app.py` (alongside the other `app.add_typer(...)` calls):

- Import `engines_app` from `codeframe.cli.engines_commands`
- Add `app.add_typer(engines_app, name="engines")`

---

### Data Flow After Refactor

```mermaid
sequenceDiagram
    participant CLI as cli/app.py work_start
    participant RT as core/runtime.py execute_agent()
    participant REG as core/engine_registry.py EngineRegistry
    participant ADP as BuiltInReactAdapter / BuiltInPlanAdapter
    participant AGT as ReactAgent / Agent

    CLI->>RT: execute_agent(workspace, run, engine="react")
    RT->>REG: EngineRegistry.get("react")
    REG-->>RT: BuiltInReactAdapter instance
    RT->>ADP: adapter.execute(workspace, run, **kwargs)
    ADP->>AGT: ReactAgent(...).run(task_id)
    AGT-->>ADP: AgentStatus.COMPLETED
    ADP-->>RT: AgentState(status=COMPLETED)
    RT->>RT: complete_run / block_run / fail_run
    RT-->>CLI: AgentState
```

---

### File Summary

| File | Action |
|---|---|
| `codeframe/core/engine_registry.py` | **Create** — `AgentAdapter` protocol, `EngineRegistry`, `BuiltInReactAdapter`, `BuiltInPlanAdapter` |
| `codeframe/core/runtime.py` | **Modify** — replace hardcoded branching in `execute_agent()` with registry lookup |
| `codeframe/core/config.py` | **Modify** — add `engine: str = "react"` field to `EnvironmentConfig` and validate it |
| `codeframe/cli/engines_commands.py` | **Create** — `engines_app` with `list` and `check` commands |
| `codeframe/cli/app.py` | **Modify** — import and register `engines_app`; read workspace engine default in `work_start` |

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#367 - feat: extend ReactAgent interface to support full runtime parameters (#362) [merged]
#369 - test: add CLI integration tests for ReactAgent runtime parameters [merged]
#387 - [Phase 2.5-F] Wire engine parameter through v2 API routes (#354) [merged]
#388 - [Phase 2.5-F] Switch default engine to react and update documentation (#355) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!