API Contracts & Runner SDK
Relevant source files
The following files were used as context for generating this wiki page:
The API Contracts and Runner SDK define the communication interface between the Opificia server, autonomous agents, and the frontend. These components enable the "working loop" where agents receive tickets, propose plans, and implement code changes within network-isolated sandboxes. The system follows an event-sourced architecture to track the lifecycle of a run from queuing to pull request creation.
The project maintains a strict separation of concerns through its package structure: @opificia/contracts contains shared types and event definitions, while the runner SDK provides the protocol for harness execution. The runner protocol is currently at version 0 and is considered unstable, requiring synchronized updates between the server and agent harnesses.
Sources: AGENTS.md:71-73, README.md:14-19, CHANGELOG.md:19-24
Run Lifecycle and Event Types
The Opificia system uses RunEventDto to represent state transitions and agent actions. Events are sequential and include timestamps to facilitate timeline rendering and audit logging.
Event Categories
The system categorizes events into lifecycle stages, agent actions, and human interventions.
| Event Type | Actor | Description |
|---|---|---|
run.queued | Server | Initiates a new run with repository and issue details. |
stage.started | Server | Marks the beginning of a specific stage (e.g., plan, implement). |
agent.tool | Agent | Records a tool call (Read, Bash, Edit, network) performed by the agent. |
agent.message | Agent | Captures descriptive text or updates from the agent. |
plan.proposed | Agent | Submits a Markdown-formatted implementation plan for review. |
plan.approved | Human | Records human authorization to proceed with a plan. |
implementation.finished | Agent | Signals the completion of coding tasks and provides a summary. |
checks.completed | Server | Reports the result of automated hygiene and security checks. |
pr.opened | Server | Provides the URL and details of the generated pull request. |
run.failed | System | Terminates the run due to an error, citing a specific reason. |
Sources: apps/web/fixtures/runs.ts:25-145, apps/web/src/run/conversation.tsx:288-345
Data Flow Diagram
The following diagram illustrates how a run transitions through stages and how events are generated by different components.
This diagram shows the sequential flow of a typical Opificia run from initialization to pull request closure.
Sources: apps/web/fixtures/runs.ts:25-150, CHANGELOG.md:19-24
Agent Harness Integration
Agents operate through a "harness" that implements the runner protocol. The harness receives a RunnerTask and interacts with the repository using predefined prompts and tools.
Task and Prompting Structure
The RunnerTask object contains the repository context, issue details, and history of previous revisions. Harnesses like harness-claude use this data to generate system and implementation prompts.
- Network Control: The SDK defines
NetworkLevel(none, registries, open) to restrict agent outbound access. - System Prompts: Appended rules prevent agents from modifying core policy files like
AGENTS.mdor CI workflows. - Plan/Implement Prompts: Structured blocks provide the agent with the issue body and any previous reviewer feedback.
Sources: plugins/harness-claude/src/prompts.ts:7-80, SOVEREIGNTY.md:28-36
Tool Execution Sequence
When an agent performs work, it utilizes tools mediated by the runner SDK. The server records these as agent.tool events.
The sequence shows how tool calls are proxied through the SDK to maintain isolation and auditability.
Sources: apps/web/fixtures/runs.ts:28-40, CHANGELOG.md:19-24
Security and Compliance Contracts
The contracts enforce project policies through automated checks and metadata requirements.
Hygiene and Signing Requirements
- DCO Sign-off: Every commit must include a
Signed-off-bytrailer. The SDK facilitates "Sign off by approval" where a maintainer's/signoffcomment triggers a server-side commit rewrite. - AI Disclosure: Commits generated or assisted by agents must include an
Assisted-by: <tool>/<model>trailer. - Check Findings: The
checks.completedevent includes afindingsarray. This array tracks violations such asprotected_path,secret,hidden_unicode, orsizelimits.
Sources: CONTRIBUTING.md:41-45, AGENTS.md:38-40, apps/web/src/run/conversation.tsx:64-72
Egress Policy Configuration
The server validates egress rules at startup to ensure the sandbox network environment is correctly configured.
The diagram shows the relationship between configuration validation and the runtime enforcement of network boundaries.
Sources: apps/web/fixtures/runs.ts:503-510, SOVEREIGNTY.md:40-45
Summary
The API Contracts and Runner SDK provide the necessary structure for Opificia's autonomous software factory. By standardizing event types (RunEventDto), task contexts (RunnerTask), and security findings, the project ensures that agents can be audited and controlled by humans. The transition from Phase 0 to Phase 1 relies on these contracts to stabilize the loop between the NestJS server, the network-isolated sandboxes, and the React-based frontend.
Sources: README.md:34-39, CHANGELOG.md:19-24