unreallabsai / unreal-agent

# Unreal Agent
An async-first agent harness from Unreal Labs.
- harness/ — the library.
- cmd/ — executables that use the library.
 - cmd/unreal-agent-runner - cloud agent runner.
 - cmd/unreal-agent-tui - cozy TUI.
- benchmarks/ — benchmark runners.
## Glossary
- **Input**: an event with a caller-supplied globally unique ID that remains
 stable across redeliveries.
- **Inbox**: session-scoped, in-memory deduplication of external, control, and
 crash inputs.
- **Session**: append-only persisted history that can be forked.
- **LLM turn**: the coordinator-managed sequence around one logical LLM request.
- **Tool**: a capability described by a schema and bound to a translator.
- **Tool call**: a model-produced request to use a tool.
- **Tool translator**: validates a tool call and translates it into one or more
 operations. It runs synchronously on the coordinator's event loop and must not
 perform I/O or suspend the loop.
- **Tool call status**: the translation outcome: a validation error or references
 to submitted operations. Operation execution state is tracked separately;
 the translator formats these into a model-facing result.
- **Operation**: a serializable description of work produced by a tool translator
 for asynchronous execution. Implementations are encouraged to use the available
 primitives.
## Components
| Component | Responsibility |
| --- | --- |
| Session inbox | Volatile, session-scoped input idempotency. |
| Coordinator | Persist accepted inputs, run LLM turns, resolve tool translators through the registry, and dispatch committed operations. |
| Session store | Persist canonical session history and operation state; support recovery and forks; atomically record tool-call status with operations. |
| Context builder | Statefully assemble model input in memory. Return the model input together with a record of anything omitted, truncated, or compacted. Perform no I/O and accept no persistence dependencies. |
| LLM Adapter | Send prepared model input to a provider and return a normalized completed response. Own authentication, cancellation, and provider errors. |
| Tool registry | Own the fixed Bash, ViewImage, and skill-use definitions and their translators; expose the host-selected set. |
| Tool translator | Validate a tool call and produce its status and operations. Format a recorded call status and prepared operation output into model results. Perform no I/O. |
| Operation manager | Actor runtime for durable operations. The local implementation is swappable. |
## Extending the harness
Harness components are composable, and alternative implementations of their interfaces are encouraged.
We intend to preserve these invariants:
- Session-store items are serializable, and the storage format is versioned.
- We'll do our best to maintain backwards compatibility for sessions.
 An unsupported session version will always cause an explicit error on resume.
- Operations are versioned and always serializable.
For example, a proxy operations m