//! Pure helpers factored out of the harness serve loop //! (`serve_main` in `main.rs`). //! Only functions with no wire-type dependency live here; //! request/response-flavored helpers (`requeue_inflight`, `ack_turn`, etc.) //! stay in the binary because they touch the request enum variants directly. use crate::events::Bus; use crate::turn::{TurnError, TurnOutcome}; /// Assemble the per-turn wake prompt string. The role/tools/etc. live in the /// system prompt; this is just the wake signal body. `redelivered` prepends a "may already be handled" banner; `interrupted` /// prepends a "previous turn was /cancel'd" banner instead (the two are /// mutually exclusive in practice — a redelivered message means the harness /// itself restarted, which also clears the in-memory interrupted flag — so /// `redelivered` takes priority if both were somehow set). #[must_use] pub fn format_wake_prompt(from: &str, body: &str, redelivered: bool, interrupted: bool) -> String { let banner = if redelivered { hive_sh4re::inbox::REDELIVERY_HINT } else if interrupted { hive_sh4re::inbox::INTERRUPTED_HINT } else { "" }; format!("{banner}Incoming message from `{from}`:\n---\n{body}\n---") } /// What one finished turn leaves for the OTEL turn metrics /// (`otel_turn_metrics::record`). #[derive(Debug, Clone)] pub struct TurnStatRow { pub duration_ms: i64, pub model: String, pub wake_from: String, /// Prompt tokens billed at the full rate, summed over the turn's inferences. pub input_tokens: u64, /// Per-tool breakdown as JSON: `{"Read":12,"Bash":3,...}`; `None` when no /// tool was called. pub tool_call_breakdown_json: Option, /// Post-turn loose-ends snapshot; `None` when the request failed. pub open_threads_count: Option, pub open_reminders_count: Option, /// `"ok" | "compacted" | "failed" | ...`, see [`build_row`]. pub result_kind: &'static str, } /// Field-named args for [`build_row`]; `outcome` and `bus` borrow for the /// duration of the call. `tool_calls` is passed in (rather than pulled from /// `bus` internally) because the caller needs the same map to check for a /// `get_loose_ends` call before it's consumed — `Bus::take_tool_calls` resets /// the counter, so there's only one chance to read it per turn. pub struct TurnRowArgs<'a> { pub duration_ms: i64, pub model: String, pub wake_from: String, pub outcome: &'a TurnOutcome, pub bus: &'a Bus, pub tool_calls: std::collections::HashMap, pub open_threads_count: Option, pub open_reminders_count: Option, } /// Assemble a `TurnStatRow` from the harness's per-turn state. Lives here /// (rather than inline in the serve loop) so it stays wire-type-free /// and unit-testable; the binary just feeds it the post-turn counts. #[must_use] pub fn build_row(args: TurnRowArgs<'_>) -> TurnStatRow { let TurnRowArgs { duration_ms, model, wake_from, outcome, bus, tool_calls, open_threads_count, open_reminders_count, } = args; // Prefer the API-resolved model id (e.g. `claude-opus-4-8`) captured // from this turn's assistant events over the requested `--model` // name/alias, so the model-mix rollup labels the concrete version that // ran. Falls back to the requested name on a degenerate turn that // produced no assistant event. let model = bus.last_resolved_model().unwrap_or(model); let cost = bus.last_cost_usage().unwrap_or_default(); let tool_call_breakdown_json = if tool_calls.is_empty() { None } else { serde_json::to_string(&tool_calls).ok() }; let result_kind = match outcome { Ok(false) => "ok", Ok(true) => "compacted", Err(TurnError::PromptTooLong) => "prompt_too_long", Err(TurnError::RateLimited) => "rate_limited", Err(TurnError::AuthFailed) => "auth_failed", Err(TurnError::SessionNotFound) => "session_not_found", Err(TurnError::ApiStall | TurnError::AgentStall(_)) => "api_stall", Err(TurnError::Failed(_)) => "failed", }; TurnStatRow { duration_ms, model, wake_from, input_tokens: cost.input_tokens, tool_call_breakdown_json, open_threads_count, open_reminders_count, result_kind, } } #[cfg(test)] mod wake_prompt_tests { use super::format_wake_prompt; /// The prompt is the sender and body only: no `[msg #N]` tag and no /// "N more pending, call recv" nudge, since the tools they pointed at /// are gone. #[test] fn the_wake_prompt_carries_the_sender_and_body_only() { let p = format_wake_prompt("todo", "you have todos", false, false); assert_eq!(p, "Incoming message from `todo`:\n---\nyou have todos\n---"); assert!(!p.contains("[msg #") && !p.contains("recv")); } #[test] fn a_banner_leads_the_prompt_and_redelivery_wins_over_interruption() { let redelivered = format_wake_prompt("a", "b", true, true); assert!(redelivered.starts_with(hive_sh4re::inbox::REDELIVERY_HINT)); let interrupted = format_wake_prompt("a", "b", false, true); assert!(interrupted.starts_with(hive_sh4re::inbox::INTERRUPTED_HINT)); let plain = format_wake_prompt("a", "b", false, false); assert!(plain.starts_with("Incoming message from `a`:")); } } #[cfg(test)] mod build_row_tests { use super::{TurnRowArgs, build_row}; use crate::events::Bus; use crate::turn::TurnError; fn row_for( outcome: &crate::turn::TurnOutcome, tool_calls: &[(&str, u64)], ) -> super::TurnStatRow { build_row(TurnRowArgs { duration_ms: 2_000, model: "opus".to_owned(), wake_from: "todo".to_owned(), outcome, bus: &Bus::new(), tool_calls: tool_calls .iter() .map(|(k, v)| ((*k).to_owned(), *v)) .collect(), open_threads_count: Some(2), open_reminders_count: None, }) } #[test] fn the_outcome_names_the_result_kind() { let _dir = crate::paths::harness_dir_guard(); for (outcome, kind) in [ (Ok(false), "ok"), (Ok(true), "compacted"), (Err(TurnError::PromptTooLong), "prompt_too_long"), (Err(TurnError::RateLimited), "rate_limited"), (Err(TurnError::AuthFailed), "auth_failed"), (Err(TurnError::SessionNotFound), "session_not_found"), (Err(TurnError::ApiStall), "api_stall"), (Err(TurnError::AgentStall("quiet".into())), "api_stall"), (Err(TurnError::Failed(anyhow::anyhow!("boom"))), "failed"), ] { assert_eq!(row_for(&outcome, &[]).result_kind, kind); } } #[test] fn the_row_carries_the_turns_identity_counts_and_tool_breakdown() { let _dir = crate::paths::harness_dir_guard(); let row = row_for(&Ok(false), &[("Bash", 3)]); assert_eq!(row.duration_ms, 2_000); assert_eq!( (row.model.as_str(), row.wake_from.as_str()), ("opus", "todo") ); assert_eq!( (row.open_threads_count, row.open_reminders_count), (Some(2), None) ); assert_eq!( row.tool_call_breakdown_json.as_deref(), Some(r#"{"Bash":3}"#) ); assert_eq!(row_for(&Ok(false), &[]).tool_call_breakdown_json, None); } /// The model the API resolved wins over the requested alias. #[test] fn the_resolved_model_replaces_the_requested_one() { let _dir = crate::paths::harness_dir_guard(); let bus = Bus::new(); bus.set_resolved_model(Some("claude-opus-4-8".to_owned())); let row = build_row(TurnRowArgs { duration_ms: 0, model: "opus".to_owned(), wake_from: "todo".to_owned(), outcome: &Ok(false), bus: &bus, tool_calls: std::collections::HashMap::new(), open_threads_count: None, open_reminders_count: None, }); assert_eq!(row.model, "claude-opus-4-8"); } }