Event Store Service
Relevant source files
The following files were used as context for generating this wiki page:
The Event Store Service manages the lifecycle of automated software runs by recording, dispatching, and processing events. It acts as the central mechanism for tracking the progress of AI agents as they move through planning, implementation, and verification stages. The service ensures that every action—from tool calls to human approvals—is persisted and used to drive subsequent system effects.
Event Lifecycle and Dispatching
The system treats every significant action as an event that must be stored and potentially acted upon. The EventStore dispatches commands that trigger state changes or side effects within the factory.
Sequence of Operations
When a run progresses, the service records events with specific sequence numbers (seq) and timestamps (at). These events are used to reconstruct the run timeline in the web interface and to inform the EffectsService of required background tasks.
The diagram shows the standard flow of events through a successful software factory loop.
Sources: apps/web/fixtures/runs.ts:25-460, apps/server/src/worker/effects.service.ts:80-130
Core Event Types
The service handles a variety of event types defined in the system contracts. These events categorize agent actions, human interactions, and system outcomes.
| Event Type | Actor | Description |
|---|---|---|
run.queued | System | Initial state when a ticket is picked up for processing. |
stage.started | System | Marks the beginning of a specific stage (plan or implement). |
agent.tool | Agent | Records a specific tool execution (e.g., Read, Bash, Edit). |
agent.message | Agent | Natural language communication from the agent. |
plan.proposed | Agent | Submission of an implementation plan for human review. |
plan.approved | Human | Approval of the proposed plan by a reviewer. |
run.failed | System | Terminal state if an error or budget exhaustion occurs. |
pr.opened | System | Successful creation of a GitHub Pull Request. |
Sources: apps/web/fixtures/runs.ts:25-100, apps/web/src/run/conversation.tsx:280-350
Integration with Effects Service
The EventStore works closely with the EffectsService to perform side effects requested by run events. Because effects are delivered at least once, the service must verify the current run state before execution.
Side Effect Handling
When the EventStore dispatches specific commands, the EffectsService performs physical actions such as:
- Starting Sandboxes: Provisioning environments for agent work.
- Posting Comments: Updating GitHub issues with plans or failure reasons.
- Running Checks: Validating agent changes against protected paths and security rules.
- Publishing: Pushing code branches and opening pull requests.
This sequence illustrates how stored events trigger external integrations through the Effects Service.
Sources: apps/server/src/worker/effects.service.ts:38-75, apps/server/src/worker/effects.service.ts:140-230
Timeline Reconstruction
The web application uses the stored events to build a visual timeline for reviewers. It groups consecutive agent.tool events into "work groups" to keep the interface readable.
Processing Logic
- Grouping: Events are split into "Plan", "Implement", and "Result" stages based on
stage.startedand termination events. - Tool Folding: Consecutive tool calls are collapsed into a single UI row showing a summary (e.g., "Read 4 files and ran 2 commands").
- Outcome Identification: The final significant event of a stage (like
plan.proposed) is identified as the stage outcome. - Duration Calculation: Time differences between event timestamps determine the duration of each stage.
Sources: apps/web/src/timeline.test.ts:35-100, apps/web/src/run/conversation.tsx:400-480
Summary
The Event Store Service provides the foundational data layer for the Opificia software factory. By persisting every discrete step of an automated run, it enables human oversight through detailed timelines and ensures system reliability through a state-driven effects engine. This architecture allows the factory to maintain sovereignty by keeping all logs and traces within the operator's controlled environment.
Sources: AGENTS.md:12-25, apps/server/src/worker/effects.service.ts:15-35