Runtime Model

Holon treats agent execution as a runtime system. A single model turn is important, but it's not the whole picture. The runtime tracks durable identity, active work, supervised tasks, wake conditions, and final delivery as separate concerns — each with its own lifecycle.

Core Concepts

Agents

An agent is an addressable runtime actor with:

Identity — A unique agent_id used for addressing messages and inspecting state
Lifecycle — Created, active, sleeping, and eventually terminated
Workspace — A project root where the agent reads and mutates files
Guidance — Loaded from AGENTS.md (project and agent-level)
Local state — Agent-specific memory, pending follow-ups, and work item focus

Agent profiles:

Public (self-owned): Standalone identity, self-managed lifecycle. Used for long-running, addressable agents.
Private (child): Parent-supervised via a task handle. Used for delegated subtasks and parallel work.

Work Items

A work item is a durable objective record that outlives individual model turns. It contains:

Objective — The short goal statement (e.g. "Fix build warnings in src/")
Plan — Durable multi-step plan in prose
Plan status — draft, ready, or needs_input
Todo list — Discrete progress checklist items
Blocked by — Specific blocker description when progress stalls

Work items let Holon resume work across turns, inspect progress, or hand off incomplete work to another agent. They are not chat history — they're a project management primitive built into the runtime.

Work item lifecycle:

[Created] -> [Draft plan] -> [Ready] -> [In progress] -> [Completed]
                ^                            |
                +--- [Needs input] <-- [Blocked]

When a work item finishes, it records an operator-facing completion report. This report captures the final conclusions, key deliverables, and verification evidence. Completion reports become durable records indexed into memory, allowing users and agents to instantly recall "what did we decide and deliver on that objective?" without re-reading lengthy conversation transcripts. For exact tool invocation protocols and scheduler settlement contracts, see the maintainer-facing Work items spec.

Tasks

A task is a supervised execution handle. Tasks include:

Command tasks — Shell commands, builds, tests, scripts
Child agent tasks — Delegated agents invoked via InvokeAgent

Task lifecycle is independent of the agent's user-facing answer. You can:

Inspect status (TaskStatus)
Read bounded output (TaskOutput)
Send continuation input (TaskInput)
Stop explicitly (TaskStop)

Queues and Wakeups

Holon's scheduling primitives manage when an agent acts and when it rests:

Enqueue — Schedule a follow-up message for this agent. Priorities: interject, next, normal, background.
Sleep — Runtime idle posture when no immediate work remains.
Wake — External trigger or queued message reactivates the agent.

These state transitions are visible — integrations don't need to infer hidden background behavior.

External Triggers

External triggers let an agent wait for events from outside the runtime:

Agent waits ──► External ingress provisioned ──► Event arrives ──► Agent wakes

Holon provisions a default external ingress capability for each agent. The agent uses this capability to receive wake hints and contentful external events without creating or cancelling triggers on every wait cycle.

Delivery modes:

Mode	Behavior
`wake_hint`	Wakes the agent so it can inspect external state (e.g., check a CI run). The hint payload is not enqueued as a message.
`enqueue_message`	Wakes the agent and delivers the event payload as a message in the agent's queue.

Choose wake_hint when the external system already has a query API (GitHub API, CI status endpoints). Choose enqueue_message when the callback payload itself contains the actionable information.

External ingress capabilities are agent-scoped. The same agent ingress can be reused across PRs, CI runs, issues, and WorkItems; WorkItems record their waiting state separately through blocked_by, plan_status, and todo state.

Delivery

Holon separates internal execution traces from user-facing delivery:

Briefs — Condensed context summaries for model consumption
Final answer — The useful result shown to the operator
Task output — Command stdout/stderr, available through task inspection
Transcripts — Full turn history for debugging

Briefs and task results are linked back to the runtime turns that produced them. This lets Holon preserve continuity across wakeups and task-result continuations without treating the raw transcript as the only context source. See Context Continuity for the user-facing model of prompt layout, projection, and compaction.

Workspaces

Every agent has exactly one active workspace. Workspaces define:

Instruction root — Where AGENTS.md and policy files are resolved
Execution root — Default working directory for commands
ApplyPatch target — Where file mutations land

Workspaces can be attached, detached, or isolated for safe experimentation.

The Operating Loop

Each agent turn follows this pattern:

Ingress arrives with origin, trust, and priority metadata.
Anchor — Non-trivial work gets a work item with a stable objective.
Load context — Agent reads only what's needed for the current decision.
Mutate — Changes happen through explicit workspace tools (ApplyPatch, ExecCommand).
Verify — Run real project checks (cargo test, cargo check) when available.
Deliver — Concise user-facing result, then sleep or enqueue follow-up.