Orchestration & Autonomous Loop

The AgentRuntime class (src/core/agent-runtime.ts) is the autonomous execution engine. It wraps every run in a structured lifecycle, sends context to the model, processes tool calls in a loop, and persists all events to the session store.

Run modes

Each task is dispatched in one of four modes, selected by the caller:

Mode	Description	Tool preset	Time box
plan	One-shot structured plan generation; no tool calls, no edits	none	none
agent	Interactive turn loop; write/execute tools gated by approval	agent-default	none
full	Interactive loop with full tool access; no approval gates	exec-full	none
exec	Autonomous edit-run-fix harness; runs checks, iterates on failures	exec-full	30 min

Agent loop

For agent and full modes:

for turn in 1..MAX_AGENT_TURNS (12):
  1. Send messages[] + tools[] to provider (streaming or batch)
  2. Append assistant_message event
  3. If stop_reason == "end_turn" → done
  4. For each tool_call in response:
       a. Evaluate permission (preset + rules)
       b. Execute tool (validate input → run → validate output)
       c. Append tool_call and tool_result events
       d. Add result to messages as role=tool
  5. Loop

Exec harness loop

For exec mode — the autonomous fix loop:

for attempt in 1..MAX_EXEC_HARNESS_ATTEMPTS (6):
  1. Run the agent loop (up to 12 turns)
  2. If a check command is present in the result:
       a. Execute the check command via shell.exec
       b. If exit code == 0 → success, stop
       c. Append failure as user message: "Check failed: <stderr>"
       d. Continue to next attempt
  3. If no check command → stop after first agent loop pass

The check command is resolved from the project directory: check.sh is used on Unix, check.ps1 on Windows. If neither file exists, the harness skips the check loop and runs a single agent pass. This closes the write → run → read error → fix cycle without human intervention.

System prompt composition

Each run assembles a system prompt from:

1. Bootstrap context — OS, Node version, current date, project path, git branch
2. Mode instruction — mode-specific rules (plan / agent / exec)
3. Hierarchical instructions — merged from UMBRA.md / AGENTS.md / CLAUDE.md etc.
4. Skills — loaded from ~/.umbra/skills/ and project-local skills/
5. Memory — long-term memory text (if useMemories: true)
6. Similar memories — vector-retrieved past context
7. Repo map — AST-generated project outline
8. Session summary — compacted history of the current session

Events

Every agent action is recorded as a typed event and stored in SQLite:

Event type	When
user_message	Task prompt received
assistant_delta	Streaming text chunk
assistant_message	Full assistant turn
reasoning_delta	Extended reasoning token chunk
tool_call	Tool invoked by the model
tool_result	Tool execution completed
permission_requested	Approval dialog shown
command	Check command emitted by model
status	Run status change
error	Unhandled error in the loop

Events are the source of truth for session replay, compaction, and memory generation.

Extended thinking

Pass thinkBudget in the run request to enable extended reasoning:

• Anthropic models: translates to budget_tokens (number) or a named tier
• OpenAI o-series: translates to reasoning_effort (low / medium / high)
• null disables thinking entirely