Architecture · Zorai

System boundary

The daemon owns state; UIs are clients. Sessions, goal runs, workspace tasks, threads, approvals, memory, transcripts, and telemetry do not belong to any browser window or terminal tab.

Operator
  +-- Electron / React UI
  +-- TUI
  +-- CLI
  +-- MCP clients
  +-- Chat gateways


           Zorai daemon

       state + execution + memory

Runtime components

Daemon

Owns PTY sessions, workspace state, agent threads, workspace tasks, execution queue entries, goal runs, approvals, persistence, telemetry, memory.

Clients

Electron, TUI, CLI, MCP, gateways — alternate operator surfaces over the same daemon-owned runtime.

Session manager

PTY lifecycle, terminal I/O, history, transcript indexing, mission events, snapshot metadata.

Agent runtime

Threaded conversations, tool execution, background execution, goal planning, memory maintenance, health supervision, learning loops.

Thread, workspace task, and goal relationships

Zorai separates conversational turns from durable execution:

Threads: persisted conversations and tool messages
Workspace tasks: board-owned cards with status, priority, assignee, reviewer, and a target thread or goal
Goal runs: durable autonomy layer that plans, dispatches, monitors, replans, reflects
Execution queue entries: lower-level daemon work records used by goals, subagents, and managed commands

Rule: workspace tasks are the operator-facing tasks. Goal runners and agents may create execution queue entries underneath them.

Execution hot path

User or external client sends message into daemon thread
Daemon persists message immediately
Runtime builds prompt from system, SOUL/MEMORY/USER, skills, operator model, context, recall
Agent executes bounded loop of model and tool calls
Tool results persisted back into thread
Assistant result stored and broadcast to clients
Background learning, provenance, health updated around the turn

Self-orchestrating layers

Layer 3: Learning
  traces · patterns · heuristics · effectiveness
Layer 2: Meta-cognition
  self-assessment · replanning · escalation · resources
Layer 1: Liveness & monitoring
  checkpoints · health · stuck detection · recovery
Layer 0: Execution
  agent loop · dispatcher · tools · goal planner

Layer 0 — Execution

LLM streaming, tool calls, child execution dispatch, goal-step progression, direct runtime work.

Layer 1 — Liveness

Checkpointing, health monitoring, stuck detection, recovery. Makes long-running work durable.

Layer 2 — Meta-cognition

Self-assessment, dynamic replanning, escalation, resource management.

Layer 3 — Learning

Execution traces, pattern mining, heuristics, tool-effectiveness tracking.

Agent subsystems

Subsystem	Purpose	Why it matters
Goal planner	Plans, replans, reflections, goal-step lifecycle	Turns objectives into durable structured work
Tool executor	Routes tool calls to subsystems	Makes tool use a persisted runtime path
Checkpointing	Saves pre/post-step state and context	Enables recovery and honest long-lived state
Health monitor	Assesses degradation, stuck behavior, crashes	Prevents silent failure in autonomous work
Escalation	Moves from self-correction to operator to external notice	Lets autonomy fail safely
Learning traces	Captures tool and execution patterns	Supports future optimization

Daemon ownership advantage

Long-running work survives UI disconnects
Multiple clients attach to same execution state
Memory, workspace tasks, and queue state stay coherent across surfaces
Approvals, audit trails, run history stay central
Plugins and gateways extend the same runtime

Without this ownership, Zorai would collapse into a fancy prompt shell. The daemon makes it an operating environment.

Next steps

For implementation, read Workspaces, Goal Runners, Memory, Security, and Plugins. These explain how the execution substrate surfaces to operators and extension authors.