CHAPTER 12 · CALL PATH

From Real main() to First Sampling Round

The actual entry point is xai-grok-pager-bin/src/main.rs. A single composite entry parses commands and interaction modes, then delegates to the TUI or Shell Agent host.

Learning Objective
Be able to articulate all four execution branches and trace the first conversation turn through connect_or_spawn, MvpAgent, spawn_session_on_thread, SessionActor, and SamplerActor.
Core Diagram · Annotated Call Graph
main()PagerArgs run_headlessagent headless run_stdio_agentACP stdio run_leader leader host xai_grok_pager::app::runInteractive TUI connect_or_spawnconnect or start leaderACP channels MvpAgentsession host SessionActorturn loop ChatStateActorhistory SamplerActorstreaming
run_headless

Agent Headless Mode

grok agent headless enters the headless host provided by the Shell.

run_stdio_agent

Stdio Agent

Sends and receives requests via ACP stdio, suitable for external client-driven scenarios.

run_leader

Leader Process

Hosts long-lived Agents and serves clients through connection channels.

app::run

Interactive TUI

The default interactive branch enters the pager app; TUI can establish connections via the leader.

Main Handoff Chain
connect_or_spawnEstablishes a leader connection or spawns a process on demand.
MvpAgentHandles ACP requests and manages session handles.
spawn_session_on_threadCreates an OS thread for the Session.
SessionActorAdvances the turn loop, coordinating state and tools.
SamplerActorCreates a streaming sampling task for the request.
Real Source Code Evidence
crates/codegen/xai-grok-pager-bin/src/main.rs
use xai_grok_shell::agent::app::{
  run_headless, run_leader, run_stdio_agent
};

let runtime = tokio::runtime::Builder
  ::new_multi_thread()
  .enable_all()
  .build()?;
crates/codegen/xai-grok-shell/src/session/acp_session_impl/spawn.rs
/// Spawn a session actor on a dedicated thread
/// with its own Tokio runtime and `LocalSet`.
pub(crate) async fn spawn_session_on_thread(...) {
  let rt = tokio::runtime::Builder
    ::new_current_thread()
    .enable_all().build()?;
  let local = tokio::task::LocalSet::new();
}
Source Snapshot Note: This page was verified against a locally synchronized copy. That copy has no .git metadata, so no specific commit version is claimed.
Classroom Exercise

Draw the boundaries of one interactive request

Label which nodes belong to xai-grok-pager-bin, xai-grok-pager, xai-grok-shell, and xai-grok-sampler. Explain why the TUI and Agent host are two separate crates.

Takeaway: The real entry point is xai-grok-pager-bin/src/main.rs. It dispatches execution modes — pager handles the UI, Shell owns the Agent and Session host, and Sampler owns model requests.