One orchestrator package runs as three processes: the API, the worker and the terminal gateway. The worker talks to agents only through the runtime contract. Agents deliver their work to GitHub, and the worker observes it there.
Components
The parts
- API
- Serves the dashboard and the MCP server. People read tickets and send requests through it.
- Worker
- Runs the reconciliation loop for each active ticket.
- Terminal gateway
- Relays the live terminal of a run to the dashboard. It changes no state of the run.
- Database
- Holds the state of every ticket, the event log and the stored secrets. It encrypts the secrets.
- Runtimes
- Start, watch and stop a run. They can also interrupt a run and resume it. Runtimes describes each one.
Factorial owns the state
The state of every ticket lives in the database. GitHub shows a copy of it. Factorial writes labels and assignees back to the issue, so that people can see where the ticket is. Tickets and gates lists the labels.
A person can still edit a ticket. Factorial reads that edit as input. It does not obey it as a command. A request from the dashboard or from an MCP client works the same way: Factorial records the request and answers it on its next pass.
Each ticket keeps its process version
When Factorial admits a ticket, it stamps the ticket with the current version of the process. The version includes the agents that the process names. The ticket keeps that version until it is done.
A change to the config makes a new version. It never changes a ticket that is already in flight. The allowlists that an operator sets, and the place where the work runs, stay live. An operator can still restrict a ticket in flight.
The event log
Every change is an event. The event log is append-only: Factorial adds events and never edits or deletes one. These parts of the dashboard come from the log:
- the activity of each ticket
- the audit trail
- the cost of each ticket
Factorial records the tokens and the cost of every run. The cost of a ticket is the sum over its runs.