supercode_harness/
model_change.rs

1//! P4c (COMPOSABLE-HARNESS-DESIGN.md §5.2 "P4" core NEW-significant item,
2//! §1.10/§3.1 `core.model_switch.allow_switch`, D9 row): a persisted,
3//! TYPED record of a mid-session model switch — pi's `model_change`
4//! precedent (design §1.10: "persisted change records … pi's `model_change`
5//! is the cleanest precedent"). Deliberately flat/typed (not a formatted
6//! string), mirroring [`crate::usage_log::UsageRecord`]'s exact rationale:
7//! a translatable, lossless session-data channel (§1.13), not a lossy
8//! notice — so it survives a save/load round trip byte-for-byte in the
9//! fields that matter, and a future reader (a translator emitting this same
10//! session under another harness's format, a `doctor`/`inspect stats`
11//! command) can consume it without re-parsing prose.
12
13use serde::{Deserialize, Serialize};
14
15/// One mid-session model switch, as `Agent::switch_model` records it when
16/// `Config::model_switch_allow_switch` is on (see that field's doc comment
17/// for the exact gate — with the knob off, `switch_model` never creates one
18/// of these at all, matching `Agent::set_model`'s pre-existing,
19/// record-free mechanics byte-for-byte).
20#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
21pub struct ModelChangeRecord {
22    /// 0-based index of the model round-trip THIS switch takes effect
23    /// before (i.e. `Agent::turn_index` at the moment of the switch) — the
24    /// same per-turn addressing [`crate::usage_log::UsageRecord::turn`]
25    /// uses, so the two logs can be correlated.
26    pub turn: usize,
27    /// The model id in effect immediately before this switch.
28    pub from_model: String,
29    /// The model id in effect immediately after this switch.
30    pub to_model: String,
31    /// Whether `reduce::rehydrate::filter_reasoning_artifacts` ran over the
32    /// live history as part of this switch (dep 8) — always `true` when
33    /// this record exists at all (a record is only ever created under
34    /// `allow_switch = true`, which is the same gate that runs the filter),
35    /// but recorded explicitly rather than implied, so a reader of the
36    /// persisted log alone (without also knowing the config that produced
37    /// it) can see the safety guarantee held for this specific switch.
38    #[serde(default)]
39    pub reasoning_filtered: bool,
40    /// Count of `ChatMessage`s the reasoning-artifact filter actually
41    /// touched (stripped a metadata key from, or removed a `content_parts`
42    /// reasoning block from) during this switch. `0` is a legitimate,
43    /// common value (nothing to filter yet), not an error signal.
44    #[serde(default)]
45    pub reasoning_artifacts_filtered: usize,
46    /// Unix-ms wall-clock time the switch happened.
47    #[serde(default)]
48    pub timestamp_ms: i64,
49    /// BP-13: why this change happened, when it was NOT user-initiated —
50    /// the provider failure that made `Agent::run_loop` walk to the next
51    /// entry of `Config::model_fallback`. `None` for a deliberate switch
52    /// (`/model`), which needs no reason beyond the user having asked.
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub reason: Option<String>,
55}
56
57impl ModelChangeRecord {
58    /// Build a record — the constructor `Agent::switch_model` calls.
59    pub fn new(
60        turn: usize,
61        from_model: impl Into<String>,
62        to_model: impl Into<String>,
63        reasoning_filtered: bool,
64        reasoning_artifacts_filtered: usize,
65        timestamp_ms: i64,
66    ) -> ModelChangeRecord {
67        ModelChangeRecord {
68            turn,
69            from_model: from_model.into(),
70            to_model: to_model.into(),
71            reasoning_filtered,
72            reasoning_artifacts_filtered,
73            timestamp_ms,
74            reason: None,
75        }
76    }
77
78    /// BP-13: attach the non-user cause of this change (a fallback hop's
79    /// provider failure). A record with no reason describes a switch the
80    /// user asked for.
81    pub fn with_reason(mut self, reason: Option<String>) -> ModelChangeRecord {
82        self.reason = reason;
83        self
84    }
85
86    /// BP-13: whether this change was performed BY the loop rather than
87    /// asked for by the user.
88    pub fn automatic(&self) -> bool {
89        self.reason.is_some()
90    }
91}
92
93/// Serialize `records` as JSONL (one [`ModelChangeRecord`] per line) — the
94/// same shape [`crate::usage_log::to_jsonl`] and every other append-log in
95/// this crate uses. Never fails on an empty slice (produces an empty
96/// string).
97pub fn to_jsonl(records: &[ModelChangeRecord]) -> crate::Result<String> {
98    let mut out = String::new();
99    for r in records {
100        out.push_str(&serde_json::to_string(r).map_err(crate::Error::Decode)?);
101        out.push('\n');
102    }
103    Ok(out)
104}
105
106/// Parse a JSONL model-change log back into records — the exact inverse of
107/// [`to_jsonl`]. Blank lines are skipped; a malformed line is a hard error
108/// (like [`crate::usage_log::from_jsonl`] — this is accounting/provenance
109/// data, corruption should be visible, not silently dropped).
110pub fn from_jsonl(text: &str) -> crate::Result<Vec<ModelChangeRecord>> {
111    let mut out = Vec::new();
112    for line in text.lines() {
113        let line = line.trim();
114        if line.is_empty() {
115            continue;
116        }
117        out.push(serde_json::from_str(line).map_err(crate::Error::Decode)?);
118    }
119    Ok(out)
120}
supercode_harness/model_change.rs

supercode_harness/
model_change.rs
