From 9721be7bc3d2cb82b9d4fc902d107c8dfe18ed24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?m=C3=BCde?= Date: Sun, 5 Jul 2026 22:39:45 +0200 Subject: [PATCH] docs(turn_stats): mark unread columns as forward-capture, not consumed --- hive-ag3nt/src/turn_stats.rs | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/hive-ag3nt/src/turn_stats.rs b/hive-ag3nt/src/turn_stats.rs index e314923e..31682712 100644 --- a/hive-ag3nt/src/turn_stats.rs +++ b/hive-ag3nt/src/turn_stats.rs @@ -1,8 +1,14 @@ //! Per-turn analytics sink. One sqlite row per claude turn captures: //! identity (`model`, `wake_from`, `result_kind`), timing (`started_at`, -//! `ended_at`, `duration_ms`), cost (token counts), behaviour (tool-call -//! count + per-tool breakdown), and post-turn snapshot metrics -//! (`open_threads_count`, `open_reminders_count`). +//! `ended_at`, `duration_ms`), cost (token counts), and behaviour (tool-call +//! count + per-tool breakdown). +//! +//! **Captured but not yet read** (written every turn, no reader today — +//! kept for a future chart / backfill, not consumed by `stats::snapshot` +//! or the host rollup): `tool_call_count` (the snapshot recomputes tool +//! totals from `tool_call_breakdown_json` instead), `open_threads_count` + +//! `open_reminders_count` (planned: a loose-ends-over-time trend), and +//! `note` (failure detail for `result_kind = "failed"`). //! //! Lives next to `hyperhive-events.sqlite` in the agent's state dir //! so the host-side state vacuum sweep can reach both. Schema is @@ -103,14 +109,19 @@ pub struct TurnStatRow { pub last_output_tokens: u64, pub last_cache_read_input_tokens: u64, pub last_cache_creation_input_tokens: u64, + /// Captured, not yet read — the snapshot recomputes tool totals from + /// `tool_call_breakdown_json` (see the module doc). pub tool_call_count: u64, /// Per-tool breakdown as JSON: `{"Read":12,"Bash":3,...}`. None /// when no tools were called (saves a sqlite write of `"{}"`). pub tool_call_breakdown_json: Option, + /// Post-turn loose-ends snapshot. Captured, not yet read — planned to + /// feed a loose-ends-over-time trend on the stats page. pub open_threads_count: Option, pub open_reminders_count: Option, /// `"ok" | "failed" | "prompt_too_long"`. pub result_kind: &'static str, + /// Failure detail for `result_kind = "failed"`. Captured, not yet read. pub note: Option, /// FK to `sessions.id` for the fresh claude session this turn belongs /// to. `None` on pre-capture rows (and when the stats db couldn't mint