Agent Harness Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Harness Architecture provides a unified interface for Rebase to communicate with diverse coding agents including Claude, Cursor, Devin, and others. It manages session lifecycles, translates provider-specific protocols into internal events, and coordinates complex multi-agent workflows through orchestration and subagent delegation.
Sources: README.md:9-12, src/features/orchestration/model/orchestrationPlan.ts:182-192
Core Components
The architecture relies on several distinct systems to manage agent identity, memory, and task execution.
Pilots and Sessions
Pilots are persistent agents that operate across multiple projects. They maintain long-term memory and can execute scheduled habits. A session represents an active conversation with a specific agent harness within a project context.
Sources: src/features/pilots/model/pilotFiles.ts:251-260, README.md:28-31
Harness Adapters
The system uses adapters to normalize interactions with different CLIs. These adapters translate raw provider updates into standardized Rebase events, such as tool calls, thoughts, and messages.
Sources: src/integrations/harness/providers/devin/devinSubagents.test.ts:10-20, CONTRIBUTING.md:28-35
Skill Management
The create-skill feature allows authoring portable SKILL.md files. These files provide instructions and domain knowledge that any supported harness can load, ensuring consistent agent behavior across different tools.
Sources: src/features/skills/model/createSkill.ts:7-15
Orchestration and Delegation
Rebase supports complex task breakdowns through an orchestration layer. This allows a "Lead" agent to plan work and delegate specific assignments to "Worker" agents.
Orchestration Workflow
The orchestration process involves three primary stages: planning, validation, and execution.
The diagram shows the lifecycle of an orchestration proposal from initial request to worker deployment.
Sources: src/features/orchestration/model/orchestrationPlan.ts:182-205, src/features/orchestration/model/orchestrationPlan.ts:220-235
Subagent Execution
Agents can spawn subagents to handle background tasks. The harness architecture captures these nested tool calls and reasoning steps, presenting them as distinct activity rows within the main transcript.
| Component | Description |
|---|---|
run_subagent | Initiates a background agent with a specific task and profile. |
agent_thought_chunk | Captures reasoning steps from a subagent. |
tool_call | Represents a specific action (read, search, execute) performed by a subagent. |
subagent_context | Maintains the relationship between parent and child agents via parentAgentId. |
Sources: src/integrations/harness/providers/devin/devinSubagents.test.ts:25-70, src/features/sessions/model/transcriptActivity.ts:635-650
Memory and Context Management
The harness maintains agent "Soul" and "Memory" files to preserve identity and knowledge across turns.
Context Budgeting
The system enforces a memory budget to prevent context window overflow. Only the most recent or relevant portions of MEMORY.md are loaded into a conversation turn.
- Maximum Lines: 200 lines
- Maximum Size: 24 KB
- Persistence: Stored in the app's data folder as
SOUL.mdandMEMORY.md.
Sources: src/features/pilots/model/pilotFiles.ts:28-40, src/features/pilots/model/pilotFiles.ts:145-165
Data Flow for Conversation Turns
When a user sends a message, the harness assembles a context block containing the agent's identity, rules, and memory before forwarding it to the provider.
The sequence diagram illustrates how Rebase injects system instructions and memory into the user's message before invoking the agent CLI.
Sources: src/features/pilots/model/pilotFiles.ts:226-240, src/features/pilots/model/pilotFiles.ts:251-300
Implementation Details
Transcript Activity Logic
The system groups raw blocks into "Activity Phases" for cleaner UI rendering. It uses heuristic analysis to determine if a sequence of calls represents "Research", "Editing", or "Running" tasks.
// Example of how work is summarized based on tool kinds
function activityPhaseTitle(phase: ActivityPhase, live: boolean): string {
// Logic derives a headline like "Edited 2 files" or "Ran 3 commands"
// from the collection of tool call blocks in the phase.
}
Sources: src/features/sessions/model/transcriptActivity.ts:460-500, src/features/sessions/model/transcriptActivity.ts:520-550
Security and Validation
The harness architecture enforces strict path validation to prevent agents from accessing files outside the authorized project scope or performing unauthorized Git operations.
- Path Normalization: Paths are converted to project-relative formats.
- Scope Checks: Assignments are validated against the current
cwd(Current Working Directory). - Acyclic Verification: Orchestration graphs are checked for dependency cycles before approval.
Sources: src/features/orchestration/model/orchestrationPlan.ts:65-90, src/features/orchestration/model/orchestrationPlan.ts:165-180
The Agent Harness Architecture serves as the backbone of the Rebase multi-agent ecosystem, enabling structured interaction, persistent memory, and complex task delegation across diverse coding tools.