codex/prs/bolinfest/study/PR-1497-study.md

DOs

• Align Enum And Match Order: Keep match arms in the same logical order as variants in the enum; place new, less-used variants near the end.

// enum (place less-frequent variants later)
pub enum Op {
    ConfigureSession { /* ... */ },
    // ...
    EraseConversationHistory,
}

// match (mirror the enum’s structure)
match sub.op {
    Op::ConfigureSession { .. } => { /* ... */ }
    // ...
    Op::EraseConversationHistory => {
        if let Some(sess) = sess.as_ref() {
            sess.erase_conversation_history();
        }
    }
}

• Keep Comments Tight: Prefer brief comments that state intent; link out if needed.

// Fully reset server-side context, too.
state.previous_response_id = None;

• Group Test Imports Clearly: Put all use items for tests together at the top of mod tests.

#[cfg(test)]
mod tests {
    use super::*;
    use crate::models::{ContentItem, ResponseItem};

    #[test]
    fn clear_removes_all_items() { /* ... */ }
}

• Centralize Model Calls In Core: Expose a single core helper that respects the configured provider (Responses or Chat Completions), and call it from the TUI.

// core
pub async fn summarize_messages(
    cfg: &Config,
    model: &str,
    messages: Vec<Message>
) -> anyhow::Result<String> {
    let base = cfg.model_provider.base_url.trim_end_matches('/');
    let path = if cfg.model_provider.prefers_responses() { "/responses" } else { "/chat/completions" };
    let url = format!("{}{}", base, path);
    // ... perform request using shared Client and schema ...
    Ok(summary)
}

// tui
let summary = codex_core::client::summarize_messages(&self.config, &self.config.model, messages).await?;

• Prefer Non-Blocking Async: Use tokio::spawn for async I/O; avoid blocking the runtime.

let tx = app_event_tx.clone();
tokio::spawn(async move {
    let result = generate_compact_summary(&transcript, &model, &config).await;
    let evt = AppEvent::CompactComplete(result.map_err(|e| format!("{e}")));
    tx.send(evt);
});

• Consider A Dedicated Op For Compaction: Push compaction into core so TUI stays thin and purely event-driven.

// protocol
pub enum Op {
    ConfigureSession { /* ... */ },
    // ...
    CompactConversationHistory { transcript: Vec<Message> },
}

// tui
self.submit_op(Op::CompactConversationHistory { transcript });

// core
Op::CompactConversationHistory { transcript } => {
    let summary = summarize_messages(&cfg, &cfg.model, transcript).await?;
    sess.erase_conversation_history();
    // ... send summary back via existing event/stream path ...
}

• Clear Frontend And Backend State: When compacting, wipe UI history and backend identifiers.

self.conversation_history.clear_agent_history();
self.transcript.clear();
self.submit_op(Op::EraseConversationHistory); // clears transcript + previous_response_id

---

DON’Ts

• Don’t Mismatch Enum/Match Placement: Avoid placing the match arm for a variant far from where the variant appears in the enum.

// Don’t do this: variant is last, but arm appears first.
match sub.op {
    Op::EraseConversationHistory => { /* ... */ }, // misplaced
    Op::ConfigureSession { .. } => { /* ... */ },
}

• Don’t Write Paragraph-Long Comments: Avoid long narrative comments in code bodies.

// Don’t: multi-line essay about API behavior...
// Do: a one-liner plus a link if necessary.

• Don’t Duplicate HTTP Logic In TUI: TUI shouldn’t hardcode endpoints or JSON shapes; don’t assume Chat Completions is always available.

// Don’t: hardcoded path and bespoke JSON in TUI.
let url = format!("{}/chat/completions", base);
let body: serde_json::Value = client.post(url).json(&payload).send().await?.json().await?;

• Don’t Block The Runtime For Async Work: Avoid spawn_blocking + rt.block_on for network calls.

// Don’t
tokio::task::spawn_blocking(move || {
    tokio::runtime::Handle::current().block_on(async { /* network */ });
});

• Don’t Only Clear Local UI State: Erasing history must also drop server-side identifiers so past context can’t leak back in.

// Don’t: only clear UI entries.
// Do: also clear session’s server-side handle/id.

• Don’t Scatter Test-Local Imports: Avoid importing types inside test functions when they’re used across the module.

// Don’t
#[test]
fn t() {
    use crate::models::ContentItem; // scattered import
    // ...
}