Engineering Reference · zeus.go

Zeus — How It Works

Zeus is declared as the master orchestration engine. In practice it is a smart LLM client with four real responsibilities: provider routing, context compression, conversation history, and observability. This page covers the full runtime flow and the gap between what Zeus does today and what the Dark Forge spec expects it to do.

What Zeus Is

Responsibilities today vs. the spec

Zeus owns the things that matter for every request: it picks the right provider, compresses history before cloud calls, stores turns, and tracks cost. What it does not yet own is command dispatch, streaming events to the TUI, or the agentic loop — those are split across DFGAdapter and loopdriver. Issue #62 tracks collapsing this fragmentation so Zeus becomes the true single control plane.

Responsibility	Where today	Target
Provider routing	Zeus → Hermes	Zeus → Hermes (no change)
Context compression	Zeus	Zeus (no change)
Conversation history	Zeus	Zeus (no change)
Command dispatch	DFGAdapter / CommandRegistry	Zeus
Event streaming to TUI	DFGAdapter / EventBus	Zeus
Agentic loop	loopdriver (separate package)	Zeus
Capacity gating	StateMachine (disconnected)	Zeus

Request Lifecycle

Generate and Stream flow

Every free-text prompt follows this path through Zeus. Slash commands take a different path through DFGAdapter's command registry (see DFGAdapter).

sequenceDiagram actor User participant TUI as Shell TUI participant DFG as DFGAdapter participant Zeus as Zeus participant Hermes as Hermes participant Comp as Compressor participant Prov as Provider User->>TUI: types prompt TUI->>DFG: Submit(prompt) DFG->>Zeus: Stream(ctx, prompt) Zeus->>Zeus: append prompt to history Zeus->>Hermes: Route(CapCodeGeneration, prompt) Hermes-->>Zeus: selected provider alt provider is cloud Zeus->>Comp: Compress(history, keep_last=4) Comp-->>Zeus: summary + recent turns end Zeus->>Zeus: modeSystemPrompt() + buildDynamicContext() Zeus->>Prov: Stream(ctx, messages, onToken) Prov-->>TUI: token stream Prov-->>Zeus: stream closed Zeus->>Zeus: append response to history Zeus->>Zeus: update telemetry Zeus->>Zeus: maybeCheckpoint()

Generate() is the same flow without streaming — it collects the full response in memory and returns it as a string. Both paths share identical routing, compression, and history logic.

Dynamic Context

What Zeus injects into every request

Two functions build the system prompt on every call. There is no caching — the context is rebuilt fresh for each request to reflect the current environment.

modeSystemPrompt() — loads the active mode profile (default: olympus). Mode profiles are embedded markdown files that set Zeus's persona and operating constraints. Switching modes (e.g. /mode security) swaps the base profile.

buildDynamicContext() — appends live state to every request:

context:
  active_provider: ollama          # which provider was selected
  routing_mode: local-first        # local-first / balanced / cloud-first
  working_directory: /src/myapp
  git_branch: feature/auth-rewrite
  turn_count: 14                   # turns this session
  slash_commands: [/fix, /review, /security, /govern, ...]

This is how Zeus knows it's running in a specific project context. The slash command list is currently hardcoded in buildDynamicContext() rather than derived from the live CommandRegistry — a known gap that will be fixed when DFGAdapter is absorbed into Zeus.

Auto-Checkpoint

maybeCheckpoint — context threshold guard

After every response, Zeus calls maybeCheckpoint(). When estimated token usage exceeds 80% of the active provider's context window, Zeus saves a text snapshot and surfaces a notice in the TUI. This fires at most once per session (checkpointFired flag).

The checkpoint is a text snapshot only — it is not a structured resume point. The Phase 0 Recovery spec requires a structured JSON checkpoint with phase state; that is not yet implemented.

Telemetry

What Zeus tracks (Argus)

Zeus accumulates counters throughout the session. These are displayed in the TUI status bar and via slash commands like /stats and /context.

Field	Meaning
`tokensUsed`	Estimated total tokens sent to providers this session
`localRuns`	Count of requests routed to Ollama
`cloudRuns`	Count of requests routed to cloud providers
`tokensSaved`	Estimated tokens saved by compression
`totalCost`	Estimated USD cost for pay-per-token calls

Auth state flags (apiKeyWarning, oauthBroken, oauthExpired, noCloudAuth) are set at construction time and used to generate actionable status messages in AuthText().

Dark Forge Gap

What the spec expects Zeus to own that isn't implemented

Missing capability	Where it lives in spec	Current state
Submit / Cancel / Events interface	Zeus should own the full async dispatch contract	Owned by DFGAdapter (see DFGAdapter page)
Intent classification	Zeus should classify each input: chat / command / agentic before routing	No intent layer — prompts go straight to providers, slash commands detected by prefix only
Agentic loop ownership	Zeus should drive the 8-phase DFG loop	Delegated to loopdriver via zeusLLMInvoker bridge
Capacity gate consultation	Zeus should check StateMachine tier before each provider call	StateMachine exists but is never called (see StateMachine page)
Structured governance panels	Phase prompts should be evaluated by structured validators (Aegis, Athena)	Governance is implemented as plain LLM prompt strings

See loopdriver for the full phase-by-phase gap analysis between the Dark Forge embedded specs and the Go implementation.