Building an app

 ┌──────────────── your app ────────────────┐
 │ thread list │ chat view      │ settings  │
 │  badges     │ text, tools,   │ model,    │
 │             │ permissions    │ effort    │
 └──────┬──────┴───────▲────────┴─────┬─────┘
        │              │              │
   StatusChanged    Events        configure()
        │              │              │
        └──────► Session ◄────────────┘
                    │
                agent process

let runtime = Runtime::new();
runtime.prewarm();                      // start scanning while the window opens

let report = runtime.discover().await;
for agent in &report.agents {
    ui.agent_row(&agent.name);   // login state comes from probe, not discovery
}
for missing in &report.missing {
    ui.install_row(&missing.name, &missing.install_hint);
}
let agent = report.require(&chosen_id)?.clone();

let details = runtime.probe(&agent).await?;
if let AuthStatus::Unauthenticated { login } = &details.auth {
    for method in login {
        match method {
            LoginMethod::Terminal { command, description, .. } => ui.login_button(command, description),
            LoginMethod::EnvVar { name } => ui.env_hint(name),
            _ => {}
        }
    }
    return Ok(());
}

let mut options = SessionOptions::in_dir(&thread.repo_dir);
if let Some(token) = &thread.resume_token {
    options = options.resume(token.clone());                    // continue an old conversation
}
if thread.unattended {
    options = options.permission_mode(PermissionMode::AutoApprove);
}
if let Some(model) = &thread.model {
    options = options.configure("model", model.as_str());
}

let (session, events) = match runtime.open(&agent, options).await {
    Ok(pair) => pair,
    Err(AgentError::ResumeFailed(_)) => {
        // the token went stale: start fresh, keep your transcript
        runtime.open(&agent, SessionOptions::in_dir(&thread.repo_dir)).await?
    }
    Err(AgentError::AuthRequired { login }) => return ui.show_login(login),
    Err(e) => return Err(e.into()),
};
thread.save_info(session.info());   // resume token, capabilities, options

let thread_id = thread.id;
let ui = ui.clone();
tokio::spawn(async move {
    while let Some(event) = events.next().await {
        let event = match event {
            Ok(e) => e,
            Err(err) => { ui.thread_failed(thread_id, err); break }
        };
        store.append(thread_id, &event);
        render(&ui, thread_id, event);
    }
    ui.thread_closed(thread_id);       // the stream ended: close() or the agent died
});

fn render(ui: &Ui, thread: ThreadId, event: Event) {
    let nested = event.turn_info.as_ref().is_some_and(|t| t.parent_tool_id.is_some());
    match event.kind {
        // content
        EventKind::TextDelta { message_id, text } if !nested => ui.append(thread, message_id, text),
        EventKind::ReasoningDelta { text, .. } if !nested => ui.append_thinking(thread, text),
        EventKind::MessageEnded { message_id } => ui.finish_message(thread, message_id),

        // tools: ToolUpdated is a full snapshot, replace by id
        EventKind::ToolUpdated(tool) => ui.upsert_tool(thread, event.turn_info, tool),
        EventKind::ToolOutputDelta { tool_id, text } => ui.append_tool_output(thread, tool_id, text),
        EventKind::PlanUpdated { entries } => ui.set_plan(thread, entries),   // replaces, not appends

        // requests: step 6
        EventKind::RequestOpened(request) => ui.open_request(thread, request),
        EventKind::RequestClosed { request_id } => ui.close_request(thread, request_id),

        // session state
        EventKind::StatusChanged(status) => ui.set_badge(thread, status),
        EventKind::SessionUpdated(info) => { store.save_info(thread, &info); ui.rebuild_settings(thread, &info) }
        EventKind::ContextUsage { used_tokens, window_tokens, .. } => ui.set_gauge(thread, used_tokens, window_tokens),

        // turn boundaries
        EventKind::TurnStarted { .. } => ui.start_turn(thread),
        EventKind::TurnEnded { stop, background } => ui.end_turn(thread, stop, background),

        EventKind::Diagnostic(d) => tracing::warn!(?d),
        _ => {}
    }
}

fn open_request(ui: &Ui, session: Session, request: Request) {
    match request {
        Request::Permission(r) => {
            // r.tool is the ToolUpdate awaiting approval (title, input, diffs)
            ui.permission_dialog(r.tool, r.detail, r.options, move |choice| {
                let session = session.clone();
                async move { session.answer(r.id.clone(), Answer::Permission(choice)).await }
            });
        }
        Request::Question(r) => {
            // one answer per question, in order; choices or free text per q.allows_free_text
            ui.question_form(r.questions, move |answers: Vec<QuestionAnswer>| {
                let session = session.clone();
                async move { session.answer(r.id.clone(), Answer::Question(answers)).await }
            });
        }
    }
}

async fn send(session: &Session, text: String, files: Vec<PathBuf>) -> Result<(), AgentError> {
    let mut input = Input::text(text);
    for f in files { input = input.attach(f); }
    match session.prompt(input).await?.kind {
        DeliveryKind::Started { .. } | DeliveryKind::Steered { .. } => {}
        DeliveryKind::Queued { position } => ui.show_queued(position),
    }
    Ok(())
}

// stop button
session.cancel(false).await?;    // true also drops queued prompts

fn rebuild_settings(ui: &Ui, session: &Session, info: &SessionInfo) {
    ui.clear_settings();
    for option in &info.details.config_options {
        let session = session.clone();
        let id = option.id.clone();
        match &option.kind {
            ConfigKind::Select { choices } => ui.dropdown(&option.name, choices, &option.current, move |v| {
                let s = session.clone(); let id = id.clone();
                async move { s.configure(id, v).await }
            }),
            ConfigKind::Boolean => ui.toggle(&option.name, &option.current, move |b| {
                let s = session.clone(); let id = id.clone();
                async move { s.configure(id, b).await }
            }),
            _ => {}
        }
    }
}

let caps = &info.details.capabilities;
ui.show_fork(caps.supports(Capability::Fork));
ui.show_rollback(caps.supports(Capability::Rollback), caps.supports(Capability::RollbackFiles));
ui.show_compact(caps.supports(Capability::Compact));

// tomorrow, after restart
let info = store.load_info(thread_id);
let token = info.resume_token.clone().ok_or("this agent cannot resume")?;
let (session, events) = runtime
    .open(&info.agent, SessionOptions::in_dir(&repo).resume(token))
    .await?;

let title = runtime
    .generate(&agent, SessionOptions::in_dir(&repo), format!("five-word title for: {first_prompt}"))
    .await?;
store.set_title(thread_id, title);

for entry in runtime.plan_usage_all().await {              // one call, every installed agent
    match entry.usage {
        Ok(usage) => ui.quota_card(&entry.agent.name, usage),   // plan name, 5-hour and weekly windows
        Err(_) => {}                                            // no subscription or no PlanUsage capability
    }
}

let options = SessionOptions::in_dir(&repo)
    .permission_mode(PermissionMode::AutoApprove)   // allow every tool request
    .configure("mode", "accept-edits");             // if the agent has such a mode

let runtime = Runtime::with_mock(Script::default().turn(vec![
    Step::Emit(text("m1", "hi")),
    Step::Emit(permission("p1")),
    Step::AwaitAnswer,
    Step::End(completed()),
]));
let agent = runtime.discover().await.require("mock")?.clone();
// steps 3 to 7 run unchanged