Agent Conversation Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Conversation Interface provides a visual timeline and interaction layer for Opificia's AI software factory. It displays the progression of an agent's work from a ticket's inception to the final pull request, allowing users to review plans and track tool usage.
This system transforms a sequence of discrete events into a structured, human-readable conversation. It groups technical actions into logical stages such as "Plan," "Implement," and "Result."
Sources: apps/web/src/run/conversation.tsx:556-588, apps/web/src/timeline.ts:25-30
Timeline Architecture
The timeline logic resides in a pure module that processes raw event data into a hierarchy of stages and items. This separation ensures the logic remains testable without requiring a DOM environment.
Data Structures
The interface uses specific types to represent the lifecycle of an agent run:
| Type | Description |
|---|---|
Stage | A group of events sharing a common phase (e.g., Plan, Implement). Includes status, duration, and outcome. |
Item | An entry within a stage, which can be a single event, a group of tool calls, or a refused network action. |
RunEventDto | The raw event data received from the server, containing type and payload. |
Sources: apps/web/src/timeline.ts:8-23, apps/web/src/timeline.test.ts:13-25
Event Processing Flow
The system processes events chronologically to build the UI structure.
The buildTimeline function identifies stage.started events to open new stages. Consecutive agent.tool events are collapsed into a single "tools" item to reduce visual clutter, while "pinned" events like approvals or failures remain always visible.
Sources: apps/web/src/timeline.ts:25-50, apps/web/src/timeline.test.ts:40-52
Stage Management
Stages represent the primary phases of the agent's work. The interface handles dynamic stage transitions, including re-planning if a user requests changes.
Lifecycle of a Stage
- Started: Triggered by a
stage.startedevent. - Running: Active state while the run is
activeand no ending event has occurred. - Outcome: Concluded by events like
plan.proposed,implementation.finished,run.failed, orrun.cancelled.
Sources: apps/web/src/timeline.ts:52-75, apps/web/src/timeline.test.ts:84-96
Timeline Stages
| Stage Name | Start Event | End/Outcome Event |
|---|---|---|
| Plan | stage.started(plan) | plan.proposed |
| Implement | stage.started(implement) | implementation.finished |
| Result | End of Implement stage | pr.opened or run.failed |
Sources: apps/web/src/timeline.ts:52-70, apps/web/src/timeline.test.ts:40-48
Interaction and Display Components
The web application uses React components to render the processed timeline.
Tool Group Folding
To keep the interface clean, hundreds of individual tool calls (like reading files or running commands) are grouped. The UI displays a summary sentence, such as "Read 4 files and ran 2 commands."
Human and Agent Interaction
The interface distinguishes between human feedback and agent responses:
- Plan Cards: Render the agent's proposed implementation plan using Markdown.
- Human Messages: Display reviewer feedback, such as requested changes.
- Refused Actions: Highlight blocked network requests in amber to alert the operator.
Sources: apps/web/src/run/conversation.tsx:162-184, apps/web/src/run/conversation.tsx:287-308, apps/web/src/run/conversation.tsx:216-224
Implementation Constraints
The interface follows strict rules for formatting and behavior:
- Relative Paths: The UI strips absolute prefixes like
/work/repo/to show paths relative to the repository. - Duration Display: Stages display durations in formats like "6m 12s" or "1h 3m".
- Sign-off Policy: The interface reminds users that only humans can sign off on changes; agents never add
Signed-off-bylines.
Sources: apps/web/src/timeline.ts:167-172, apps/web/src/timeline.ts:160-165, AGENTS.md:38-40, plugins/harness-claude/src/prompts.ts:47-53
The Agent Conversation Interface serves as the central hub for monitoring and controlling the automated software development loop. By distilling complex logs into a structured timeline, it enables efficient human review and maintains the project's commitment to human-led decision making.