[Phase 4] Agent Adapter Protocol Definition

[frankbria]

Summary

Define the AgentAdapter protocol — the interface that any coding agent (Claude Code, Codex, Aider, built-in) must implement to be used as a CodeFrame execution engine.

Parent issue: #408

Motivation

CodeFrame currently has two tightly-coupled engines (ReactAgent and legacy Agent) that both implement their own execution patterns. To support frontier coding agents as execution engines, we need a clean abstraction that captures what CodeFrame needs from any agent without caring about implementation details.

Scope

New module: core/agent_adapter.py

1. AgentAdapter protocol (Python Protocol class):

from typing import Protocol, Iterator

class AgentAdapter(Protocol):
    """Interface for any coding agent that CodeFrame can orchestrate."""
    
    def execute(
        self,
        task_prompt: str,
        workspace_path: Path,
        context: AgentContext,
        timeout_ms: int = 3_600_000,
    ) -> AgentResult:
        """Execute a coding task and return the result."""
        ...
    
    def stream_events(self) -> Iterator[AgentEvent]:
        """Yield progress events during execution (optional)."""
        ...
    
    @property
    def name(self) -> str:
        """Human-readable engine name."""
        ...
    
    @property
    def requires_api_key(self) -> dict[str, str]:
        """Map of required env vars to descriptions.
        e.g. {"ANTHROPIC_API_KEY": "Anthropic API key for Claude"}
        """
        ...

2. AgentContext dataclass — what CodeFrame provides to every engine:

@dataclass
class AgentContext:
    task_id: str
    task_title: str
    task_description: str
    prd_content: str | None          # Full PRD text
    tech_stack: str | None           # Natural language tech stack
    project_preferences: str | None  # AGENTS.md/CLAUDE.md content
    relevant_files: list[str]        # Paths to relevant files
    file_contents: dict[str, str]    # Pre-loaded file contents
    blocker_history: list[str]       # Previous blocker resolutions
    dependency_context: str | None   # What dependent tasks produced
    verification_gates: list[str]    # Gates to pass (ruff, pytest, etc.)
    attempt: int                     # Retry attempt number (0 = first)
    previous_errors: list[str]       # Errors from previous attempts

3. AgentResult dataclass — what every engine returns:

@dataclass
class AgentResult:
    status: AgentResultStatus  # COMPLETED, FAILED, BLOCKED, TIMEOUT
    files_modified: list[str]
    files_created: list[str]
    summary: str               # Human-readable summary of changes
    error: str | None          # Error message if failed
    blocker_question: str | None  # Question if blocked
    token_usage: TokenUsage | None
    duration_ms: int

4. AgentEvent for streaming:

@dataclass  
class AgentEvent:
    type: str           # "progress", "file_changed", "command_run", "error"
    message: str
    timestamp: datetime
    metadata: dict      # Engine-specific data

Design Decisions

• Protocol, not ABC: Use Python Protocol for structural subtyping. Adapters don't need to inherit from a base class — they just need to implement the interface.
• Context is rich: CodeFrame assembles all context; the adapter doesn't need to load files or read PRDs.
• Result is simple: CodeFrame just needs to know what changed and whether it worked.
• Streaming is optional: Not all engines support progress events (e.g., Aider).

Acceptance Criteria

• AgentAdapter Protocol defined with execute(), stream_events(), name, requires_api_key
• AgentContext captures all context CodeFrame currently assembles
• AgentResult captures outcome, modified files, errors, blockers
• AgentEvent supports progress streaming
• Existing ReactAgent can be wrapped to satisfy the protocol (design validation)
• Unit tests for dataclass construction and protocol compliance

Dependencies

• None — this is a foundational definition

[traycerai]

Plan

Observations

The codebase has a well-established pattern: @dataclass for internal/headless data structures (see file:codeframe/core/agent.py, file:codeframe/core/context.py, file:codeframe/core/events.py) and Pydantic BaseModel for API-facing models (see file:codeframe/core/models.py). The LLM adapter layer uses ABC (see file:codeframe/adapters/llm/base.py), but the issue explicitly calls for a Protocol here. A TokenUsage Pydantic model already exists in file:codeframe/core/models.py (lines 878–923). AgentStatus is defined as a str, Enum in file:codeframe/core/agent.py.

Approach

Create a single new module file:codeframe/core/agent_adapter.py containing all four constructs — AgentResultStatus enum, AgentContext dataclass, AgentResult dataclass, AgentEvent dataclass, and the AgentAdapter Protocol — consistent with the headless/dataclass convention used throughout codeframe/core/. The TokenUsage reference will point at the existing model in file:codeframe/core/models.py to avoid duplication.

---

Implementation Steps

1. Create file:codeframe/core/agent_adapter.py

This is the only new file needed.

1a. Imports

Import from the standard library: dataclasses (dataclass, field), datetime, enum (Enum), pathlib (Path), typing (Protocol, Iterator, runtime_checkable). Import TokenUsage from codeframe.core.models.

1b. Define AgentResultStatus enum

Follow the str, Enum convention established by AgentStatus in file:codeframe/core/agent.py:

Member	Value
COMPLETED	"completed"
FAILED	"failed"
BLOCKED	"blocked"
TIMEOUT	"timeout"

1c. Define AgentContext dataclass

Decorate with @dataclass. Use field(default_factory=list) for all list fields and None defaults for optional fields, matching the pattern in TaskContext (file:codeframe/core/context.py). Fields:

• task_id: str
• task_title: str
• task_description: str
• prd_content: str | None = None
• tech_stack: str | None = None
• project_preferences: str | None = None
• relevant_files: list[str] — field(default_factory=list)
• file_contents: dict[str, str] — field(default_factory=dict)
• blocker_history: list[str] — field(default_factory=list)
• dependency_context: str | None = None
• verification_gates: list[str] — field(default_factory=list)
• attempt: int = 0
• previous_errors: list[str] — field(default_factory=list)

1d. Define AgentResult dataclass

Decorate with @dataclass. Fields:

• status: AgentResultStatus
• files_modified: list[str] — field(default_factory=list)
• files_created: list[str] — field(default_factory=list)
• summary: str
• error: str | None = None
• blocker_question: str | None = None
• token_usage: TokenUsage | None = None — reference to the existing TokenUsage from codeframe.core.models
• duration_ms: int = 0

1e. Define AgentEvent dataclass

Decorate with @dataclass. Fields:

• type: str — one of "progress", "file_changed", "command_run", "error"
• message: str
• timestamp: datetime — use field(default_factory=lambda: datetime.now(timezone.utc))
• metadata: dict — field(default_factory=dict)

1f. Define AgentAdapter Protocol

Decorate with @runtime_checkable and @Protocol. This allows isinstance() checks at runtime, which is useful for CodeFrame's internal validation. Define these members:

execute(self, task_prompt, workspace_path, context, timeout_ms) -> AgentResult
stream_events(self) -> Iterator[AgentEvent]
name (property) -> str
requires_api_key (property) -> dict[str, str]

All method bodies use ... (ellipsis), matching Protocol convention.

---

2. Export from file:codeframe/core/__init__.py

Add AgentAdapter, AgentContext, AgentResult, AgentEvent, AgentResultStatus to the imports and __all__ list, following the same pattern as Task, TaskStatus, and AgentMaturity already exported there.

---

3. Verify ReactAgent satisfies the protocol (design validation — no new code)

Check that ReactAgent in file:codeframe/core/react_agent.py can be wrapped (not modified) to satisfy AgentAdapter. The wrapper would need to:

• Accept a ReactAgent instance
• Implement execute() by calling react_agent.run(task_id) and mapping the returned AgentStatus to AgentResultStatus
• Implement stream_events() using the existing on_event callback mechanism
• Expose name and requires_api_key as simple properties

This validation confirms the protocol is implementable; the actual wrapper is out of scope for this ticket.

---

graph TD
    A[AgentAdapter Protocol] -->|execute returns| B[AgentResult]
    A -->|stream_events yields| C[AgentEvent]
    B -->|status field| D[AgentResultStatus]
    B -->|token_usage field| E[TokenUsage\ncodeframe.core.models]
    A -->|receives| F[AgentContext]
    G[ReactAgent\ncodeframe.core.react_agent] -.->|satisfies via wrapper| A
    H[Future: ClaudeCodeAdapter\nCodexAdapter\nAiderAdapter] -.->|satisfies| A

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established pattern: `@dataclass` for internal/headless data structures (see `file:codeframe/core/agent.py`, `file:codeframe/core/context.py`, `file:codeframe/core/events.py`) and Pydantic `BaseModel` for API-facing models (see `file:codeframe/core/models.py`). The LLM adapter layer uses `ABC` (see `file:codeframe/adapters/llm/base.py`), but the issue explicitly calls for a `Protocol` here. A `TokenUsage` Pydantic model already exists in `file:codeframe/core/models.py` (lines 878–923). `AgentStatus` is defined as a `str, Enum` in `file:codeframe/core/agent.py`.

## Approach

Create a single new module `file:codeframe/core/agent_adapter.py` containing all four constructs — `AgentResultStatus` enum, `AgentContext` dataclass, `AgentResult` dataclass, `AgentEvent` dataclass, and the `AgentAdapter` Protocol — consistent with the headless/dataclass convention used throughout `codeframe/core/`. The `TokenUsage` reference will point at the existing model in `file:codeframe/core/models.py` to avoid duplication.

---

## Implementation Steps

### 1. Create `file:codeframe/core/agent_adapter.py`

This is the only new file needed.

#### 1a. Imports

Import from the standard library: `dataclasses` (`dataclass`, `field`), `datetime`, `enum` (`Enum`), `pathlib` (`Path`), `typing` (`Protocol`, `Iterator`, `runtime_checkable`). Import `TokenUsage` from `codeframe.core.models`.

#### 1b. Define `AgentResultStatus` enum

Follow the `str, Enum` convention established by `AgentStatus` in `file:codeframe/core/agent.py`:

| Member | Value |
|---|---|
| `COMPLETED` | `"completed"` |
| `FAILED` | `"failed"` |
| `BLOCKED` | `"blocked"` |
| `TIMEOUT` | `"timeout"` |

#### 1c. Define `AgentContext` dataclass

Decorate with `@dataclass`. Use `field(default_factory=list)` for all list fields and `None` defaults for optional fields, matching the pattern in `TaskContext` (`file:codeframe/core/context.py`). Fields:

- `task_id: str`
- `task_title: str`
- `task_description: str`
- `prd_content: str | None = None`
- `tech_stack: str | None = None`
- `project_preferences: str | None = None`
- `relevant_files: list[str]` — `field(default_factory=list)`
- `file_contents: dict[str, str]` — `field(default_factory=dict)`
- `blocker_history: list[str]` — `field(default_factory=list)`
- `dependency_context: str | None = None`
- `verification_gates: list[str]` — `field(default_factory=list)`
- `attempt: int = 0`
- `previous_errors: list[str]` — `field(default_factory=list)`

#### 1d. Define `AgentResult` dataclass

Decorate with `@dataclass`. Fields:

- `status: AgentResultStatus`
- `files_modified: list[str]` — `field(default_factory=list)`
- `files_created: list[str]` — `field(default_factory=list)`
- `summary: str`
- `error: str | None = None`
- `blocker_question: str | None = None`
- `token_usage: TokenUsage | None = None` — reference to the existing `TokenUsage` from `codeframe.core.models`
- `duration_ms: int = 0`

#### 1e. Define `AgentEvent` dataclass

Decorate with `@dataclass`. Fields:

- `type: str` — one of `"progress"`, `"file_changed"`, `"command_run"`, `"error"`
- `message: str`
- `timestamp: datetime` — use `field(default_factory=lambda: datetime.now(timezone.utc))`
- `metadata: dict` — `field(default_factory=dict)`

#### 1f. Define `AgentAdapter` Protocol

Decorate with `@runtime_checkable` and `@Protocol`. This allows `isinstance()` checks at runtime, which is useful for CodeFrame's internal validation. Define these members:

```
execute(self, task_prompt, workspace_path, context, timeout_ms) -> AgentResult
stream_events(self) -> Iterator[AgentEvent]
name (property) -> str
requires_api_key (property) -> dict[str, str]
```

All method bodies use `...` (ellipsis), matching Protocol convention.

---

### 2. Export from `file:codeframe/core/__init__.py`

Add `AgentAdapter`, `AgentContext`, `AgentResult`, `AgentEvent`, `AgentResultStatus` to the imports and `__all__` list, following the same pattern as `Task`, `TaskStatus`, and `AgentMaturity` already exported there.

---

### 3. Verify `ReactAgent` satisfies the protocol (design validation — no new code)

Check that `ReactAgent` in `file:codeframe/core/react_agent.py` can be wrapped (not modified) to satisfy `AgentAdapter`. The wrapper would need to:
- Accept a `ReactAgent` instance
- Implement `execute()` by calling `react_agent.run(task_id)` and mapping the returned `AgentStatus` to `AgentResultStatus`
- Implement `stream_events()` using the existing `on_event` callback mechanism
- Expose `name` and `requires_api_key` as simple properties

This validation confirms the protocol is implementable; the actual wrapper is out of scope for this ticket.

---

```mermaid
graph TD
    A[AgentAdapter Protocol] -->|execute returns| B[AgentResult]
    A -->|stream_events yields| C[AgentEvent]
    B -->|status field| D[AgentResultStatus]
    B -->|token_usage field| E[TokenUsage\ncodeframe.core.models]
    A -->|receives| F[AgentContext]
    G[ReactAgent\ncodeframe.core.react_agent] -.->|satisfies via wrapper| A
    H[Future: ClaudeCodeAdapter\nCodexAdapter\nAiderAdapter] -.->|satisfies| A
```

---

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

#11 - feat: Convert worker agents to async/await pattern (cf-48) [merged]
#125 - Implement WorkerAgent execute_task method [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [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!