[Phase 4] Unify ReactAgent context assembly with TaskContextPackager

[frankbria]

Summary

ReactAgent._build_system_prompt() and TaskContextPackager both assemble context from the same sources (TaskContext, PRD, preferences, tech stack, files) but via independent code paths. This creates a maintenance risk where changes to context assembly need to be made in two places.

Parent issue: #408

Current State

Two parallel context assembly paths exist:

1. External engines (Claude Code, OpenCode): TaskContextPackager.build() → prompt string → adapter
   Used in runtime.py line 687-688

2. Internal ReactAgent: ReactAgent._build_system_prompt() → 3-layer system prompt
   Directly calls ContextLoader.load() and formats its own prompt

Both pull from the same ContextLoader + TaskContext but format independently.

Proposed Change

Refactor ReactAgent._build_system_prompt() to:

1. Use TaskContextPackager.build_agent_context() for context assembly
2. Keep ReactAgent's 3-layer formatting as a ReactAgent-specific renderer on top
3. Remove direct ContextLoader usage from ReactAgent

Acceptance Criteria

• ReactAgent uses TaskContextPackager internally for context loading
• ReactAgent's 3-layer prompt format is preserved (no behavior change)
• ContextLoader import can be removed from react_agent.py
• Integration test confirms same effective prompt content

Risk Assessment

Medium risk — ReactAgent's prompt is complex (3-layer, adaptive complexity hints, token budget management). The refactor must not change the effective prompt content or break the agent's reasoning.

Dependencies

• [Phase 4] Task Context Packager for External Agents #410 (TaskContextPackager enhancement) — must be merged first

[traycerai]

Plan

Observations

ReactAgent.run() (line 183–184 of file:codeframe/core/react_agent.py) directly instantiates ContextLoader and calls .load(), then passes the resulting TaskContext to _build_system_prompt(). TaskContextPackager (in file:codeframe/core/context_packager.py) already wraps ContextLoader and owns the load call, but currently only exposes build() which produces a flat prompt string — not the raw TaskContext that ReactAgent needs for adaptive budget calculation and 3-layer prompt rendering. The PackagedContext dataclass already carries both prompt: str and context: TaskContext, which is the key bridge.

Approach

Add a build_agent_context() method to TaskContextPackager that returns only the loaded TaskContext (no gate/instruction sections), then update ReactAgent.run() to call it instead of instantiating ContextLoader directly. _build_system_prompt() stays untouched — it continues to receive and render TaskContext in its 3-layer format. This is the minimal, lowest-risk path: one new method, two changed lines in run(), one removed import.

---

Implementation Steps

1. Add build_agent_context() to TaskContextPackager

In file:codeframe/core/context_packager.py, add a new public method build_agent_context(task_id: str) -> TaskContext to the TaskContextPackager class.

• It should call self._loader.load(task_id) and return the resulting TaskContext directly — no gate section, no instructions section.
• This gives ReactAgent a single, packager-owned entry point for context loading without altering the existing build() method used by external engines.

def build_agent_context(self, task_id: str) -> TaskContext:
    """Load and return TaskContext for internal agent use (no gate/instruction sections)."""
    return self._loader.load(task_id)

2. Update ReactAgent.run() to use TaskContextPackager

In file:codeframe/core/react_agent.py, inside the run() method (around lines 183–184):

• Replace the direct ContextLoader(self.workspace) instantiation and .load(task_id) call with:
  • Import TaskContextPackager from codeframe.core.context_packager (add to the top-level imports).
  • Instantiate TaskContextPackager(self.workspace) and call .build_agent_context(task_id) to obtain the TaskContext.
• The rest of run() — adaptive budget calculation, _build_system_prompt(context), the ReAct loop — remains completely unchanged.

3. Remove the ContextLoader import from react_agent.py

In file:codeframe/core/react_agent.py, line 23:

from codeframe.core.context import ContextLoader, TaskContext

• Remove ContextLoader from this import. TaskContext must be kept because it is used as a type annotation in _build_system_prompt(context: TaskContext) and elsewhere.
• The line becomes:

  from codeframe.core.context import TaskContext

---

Summary of Changes

File	Change
file:codeframe/core/context_packager.py	Add build_agent_context(task_id) -> TaskContext method
file:codeframe/core/react_agent.py	Import TaskContextPackager; replace ContextLoader(self.workspace).load(task_id) with TaskContextPackager(self.workspace).build_agent_context(task_id) in run(); remove ContextLoader from import

Data Flow (Before vs After)

sequenceDiagram
    participant R as ReactAgent.run()
    participant TCP as TaskContextPackager
    participant CL as ContextLoader
    participant BSP as _build_system_prompt()

    Note over R,BSP: BEFORE
    R->>CL: ContextLoader(workspace).load(task_id)
    CL-->>R: TaskContext
    R->>BSP: _build_system_prompt(context)
    BSP-->>R: 3-layer prompt string

    Note over R,BSP: AFTER
    R->>TCP: TaskContextPackager(workspace).build_agent_context(task_id)
    TCP->>CL: self._loader.load(task_id)
    CL-->>TCP: TaskContext
    TCP-->>R: TaskContext
    R->>BSP: _build_system_prompt(context)
    BSP-->>R: 3-layer prompt string

Loading

No behavior changes to the prompt content or the ReAct loop — only the ownership of context loading moves from ReactAgent to TaskContextPackager.

Import In IDE

🤖 Prompt for AI Agents

## Observations

`ReactAgent.run()` (line 183–184 of `file:codeframe/core/react_agent.py`) directly instantiates `ContextLoader` and calls `.load()`, then passes the resulting `TaskContext` to `_build_system_prompt()`. `TaskContextPackager` (in `file:codeframe/core/context_packager.py`) already wraps `ContextLoader` and owns the `load` call, but currently only exposes `build()` which produces a flat prompt string — not the raw `TaskContext` that `ReactAgent` needs for adaptive budget calculation and 3-layer prompt rendering. The `PackagedContext` dataclass already carries both `prompt: str` and `context: TaskContext`, which is the key bridge.

## Approach

Add a `build_agent_context()` method to `TaskContextPackager` that returns only the loaded `TaskContext` (no gate/instruction sections), then update `ReactAgent.run()` to call it instead of instantiating `ContextLoader` directly. `_build_system_prompt()` stays untouched — it continues to receive and render `TaskContext` in its 3-layer format. This is the minimal, lowest-risk path: one new method, two changed lines in `run()`, one removed import.

---

## Implementation Steps

### 1. Add `build_agent_context()` to `TaskContextPackager`

In `file:codeframe/core/context_packager.py`, add a new public method `build_agent_context(task_id: str) -> TaskContext` to the `TaskContextPackager` class.

- It should call `self._loader.load(task_id)` and return the resulting `TaskContext` directly — no gate section, no instructions section.
- This gives `ReactAgent` a single, packager-owned entry point for context loading without altering the existing `build()` method used by external engines.

```
def build_agent_context(self, task_id: str) -> TaskContext:
    """Load and return TaskContext for internal agent use (no gate/instruction sections)."""
    return self._loader.load(task_id)
```

### 2. Update `ReactAgent.run()` to use `TaskContextPackager`

In `file:codeframe/core/react_agent.py`, inside the `run()` method (around lines 183–184):

- Replace the direct `ContextLoader(self.workspace)` instantiation and `.load(task_id)` call with:
  - Import `TaskContextPackager` from `codeframe.core.context_packager` (add to the top-level imports).
  - Instantiate `TaskContextPackager(self.workspace)` and call `.build_agent_context(task_id)` to obtain the `TaskContext`.
- The rest of `run()` — adaptive budget calculation, `_build_system_prompt(context)`, the ReAct loop — remains completely unchanged.

### 3. Remove the `ContextLoader` import from `react_agent.py`

In `file:codeframe/core/react_agent.py`, line 23:

```python
from codeframe.core.context import ContextLoader, TaskContext
```

- Remove `ContextLoader` from this import. `TaskContext` must be kept because it is used as a type annotation in `_build_system_prompt(context: TaskContext)` and elsewhere.
- The line becomes:
  ```python
  from codeframe.core.context import TaskContext
  ```

---

## Summary of Changes

| File | Change |
|---|---|
| `file:codeframe/core/context_packager.py` | Add `build_agent_context(task_id) -> TaskContext` method |
| `file:codeframe/core/react_agent.py` | Import `TaskContextPackager`; replace `ContextLoader(self.workspace).load(task_id)` with `TaskContextPackager(self.workspace).build_agent_context(task_id)` in `run()`; remove `ContextLoader` from import |

## Data Flow (Before vs After)

```mermaid
sequenceDiagram
    participant R as ReactAgent.run()
    participant TCP as TaskContextPackager
    participant CL as ContextLoader
    participant BSP as _build_system_prompt()

    Note over R,BSP: BEFORE
    R->>CL: ContextLoader(workspace).load(task_id)
    CL-->>R: TaskContext
    R->>BSP: _build_system_prompt(context)
    BSP-->>R: 3-layer prompt string

    Note over R,BSP: AFTER
    R->>TCP: TaskContextPackager(workspace).build_agent_context(task_id)
    TCP->>CL: self._loader.load(task_id)
    CL-->>TCP: TaskContext
    TCP-->>R: TaskContext
    R->>BSP: _build_system_prompt(context)
    BSP-->>R: 3-layer prompt string
```

No behavior changes to the prompt content or the ReAct loop — only the ownership of context loading moves from `ReactAgent` to `TaskContextPackager`.

---

Execution Information

Branch: main
Commit: c37498f

---

💡 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

#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#361 - feat: ReactAgent core loop with system prompt builder [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [merged]
#370 - feat: token budget tracking and message compaction for ReactAgent (#352) [merged]
#379 - fix: include pre-loaded file contents in ReactAgent system prompt [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!