From 5175d3663e7f8a581f4dd3c51fc62a2b7be81c38 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 16 Nov 2026 10:50:13 +0100 Subject: [PATCH] swarm: set the fresh-session threshold per agent --- docs/2-handbook/swarm/swarmctl-cli.md | 6 +- docs/4-implementation/swarm/inference.md | 19 ++++-- .../turn-loop/claude-invocation.md | 3 +- hive-agent/src/events.rs | 17 ++++++ hive-agent/src/swarm_inference.rs | 7 ++- hive-agent/src/turn.rs | 15 ++++- swarm-controller-api/src/inference.rs | 10 +++- swarm-controller/src/inference.rs | 58 ++++++++++++++++++- swarm-wire/src/agent_inference.rs | 13 ++++- swarmctl/src/inference.rs | 27 ++++++--- swarmctl/src/main.rs | 11 ++-- 11 files changed, 154 insertions(+), 32 deletions(-) diff --git a/docs/2-handbook/swarm/swarmctl-cli.md b/docs/2-handbook/swarm/swarmctl-cli.md index aaf71a210..1cb5a922b 100644 --- a/docs/2-handbook/swarm/swarmctl-cli.md +++ b/docs/2-handbook/swarm/swarmctl-cli.md @@ -83,7 +83,7 @@ Manage agents across the swarm * `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale * `set-state` — Declare the state a hive converges an agent to: `up`, `offline`, `paused` or `destroyed` * `watch` — Follow an agent's terminal rows live: the newest retained rows, then each new one, one line per row, until Ctrl-C or the stream ends -* `inference` — Show the model, effort, subagent models, subagent cap and soft context limit the swarm sets for an agent, or change the model, effort and subagent models +* `inference` — Show the model, effort, subagent models, subagent cap and the two context limits the swarm sets for an agent, or change the model, effort and subagent models * `permissions` — Show or change the permissions the swarm grants an agent * `agents-md` — Show an agent's AGENTS.md, or edit it with a diff @@ -192,9 +192,9 @@ The swarm-level counterpart of `hivectl agent watch`, read from the swarm-contro ## `swarmctl agent inference` -Show the model, effort, subagent models, subagent cap and soft context limit the swarm sets for an agent, or change the model, effort and subagent models. +Show the model, effort, subagent models, subagent cap and the two context limits the swarm sets for an agent, or change the model, effort and subagent models. -`get` prints the subagent cap (`max_subagents`) and the soft context limit (`soft_context_percent`); `set` has no flag for them and keeps stored ones. Only swarm-ui sets them. +`get` prints the subagent cap (`max_subagents`), the soft context limit (`soft_context_percent`) and the fresh-session threshold (`fresh_session_percent`); `set` has no flag for them and keeps stored ones. Only swarm-ui sets them. A field the swarm sets wins over the agent's own value (its agent.nix or a `hyperhive-model`/`hyperhive-effort` file) from its next turn on; the agent reads its settings every ten seconds. A field the swarm doesn't set, or clears, leaves the agent on its own value. diff --git a/docs/4-implementation/swarm/inference.md b/docs/4-implementation/swarm/inference.md index d915a7202..c658cf819 100644 --- a/docs/4-implementation/swarm/inference.md +++ b/docs/4-implementation/swarm/inference.md @@ -29,10 +29,17 @@ swarmctl agent inference clear iris dialog; `set` has no flag for it either. It's the percent of the model's context window at which the agent compacts at the end of a turn, in place of the harness's own 75%: 20 on a 1M window compacts once the context passes - 200k. A turn can still run past it, and it changes nothing else (the idle - autoreset, the context shown in the UI). It's a whole number from 5 to 100; + 200k. A turn can still run past it, and it changes nothing else (the + context shown in the UI). It's a whole number from 5 to 100; unset keeps the harness's own watermark ([`claude-invocation.md`](../turn-loop/claude-invocation.md)). +- You set the fresh-session threshold, `fresh_session_percent`, with it: the + percent of the context window above which a turn that finds the prompt cache + cold starts a fresh session instead of resuming, in place of the harness's + own 50%. It's a whole number from 5 to 100, and not above the soft limit when + both are set, since the agent compacts at the soft limit and the context would + never reach a higher threshold; the controller refuses a pair that crosses. + `set` has no flag for it either, and the dialog edits both on one slider. - `get` shows each field, naming the unset ones (or says the swarm sets nothing for the agent), and then the model and effort the agent reports running on, each with where it comes from. @@ -54,6 +61,7 @@ effort: (not set; the agent's own) subagent_models: (not set; the agent's own) max_subagents: (not set; no cap) soft_context_percent: (not set; the harness's own watermark) +fresh_session_percent: (not set; the harness's own half) running model: opus (swarm) running effort: medium (local_file) ``` @@ -103,7 +111,8 @@ which swarm-controller alone writes: "effort": "high", "subagent_models": ["haiku", "sonnet"], "max_subagents": 3, - "soft_context_percent": 20 + "soft_context_percent": 20, + "fresh_session_percent": 10 } ``` @@ -130,7 +139,9 @@ in-memory model or effort without writing `hyperhive-model` or The same loop hands `soft_context_percent` to the Bus (`set_soft_context_percent`), which the compaction policy reads when it decides -at turn end; a key with no limit, or no key, clears it on the next read. +at turn end, and `fresh_session_percent` (`set_fresh_session_percent`), which +the pre-turn auto-reset reads; a key with no limit, or no key, clears it on the +next read. The subagent daemon (`hive-subagent-mcp`'s `swarm_models`) reads `subagent_models` and `max_subagents` with the same direct get, under the diff --git a/docs/4-implementation/turn-loop/claude-invocation.md b/docs/4-implementation/turn-loop/claude-invocation.md index 9778420a7..a797ea978 100644 --- a/docs/4-implementation/turn-loop/claude-invocation.md +++ b/docs/4-implementation/turn-loop/claude-invocation.md @@ -188,7 +188,8 @@ still applies. - **Auto session-reset** — a third path (`turn::maybe_auto_reset`, pre-turn) that fires when both conditions hold: context is ≥ a watermark (`HIVE_AUTO_RESET_WATERMARK_TOKENS`, default **50% of the reported - window**, none until the API reports one) AND the time since the last turn + window**, none until the API reports one; the swarm replaces the 50% per + agent with its `fresh_session_percent`, [`inference.md`](../swarm/inference.md)) AND the time since the last turn exceeds the assumed prompt-cache TTL (`HIVE_CACHE_TTL_SECS`, default `3600`; `0` turns the check off, so an idle session is always resumed, and the harness logs a warning at start when it's off). Claude's prompt cache goes cold after a while; once it's cold, diff --git a/hive-agent/src/events.rs b/hive-agent/src/events.rs index dab9ed838..c8da627c2 100644 --- a/hive-agent/src/events.rs +++ b/hive-agent/src/events.rs @@ -218,6 +218,11 @@ pub struct Bus { /// compaction policy compacts at it instead of the harness's own /// watermark. `None` until the swarm sets one. soft_context_percent: Arc>>, + /// The swarm's fresh-session threshold, as a percent of the context window + /// (`fresh_session_percent` of the agent's `agent-inference` key): above it, a + /// turn that finds the prompt cache cold starts a fresh session. `None` + /// until the swarm sets one, which keeps the harness's own half. + fresh_session_percent: Arc>>, /// Resolved model id from the most recent turn's `assistant` events /// (the API-echoed `message.model`, e.g. `claude-opus-4-8`), as /// opposed to the requested `--model` name which may be a short @@ -261,6 +266,7 @@ impl Bus { last_turn_ended_unix: Arc::new(AtomicI64::new(0)), api_context_window: Arc::new(Mutex::new(None)), soft_context_percent: Arc::new(Mutex::new(None)), + fresh_session_percent: Arc::new(Mutex::new(None)), last_resolved_model: Arc::new(Mutex::new(None)), } } @@ -530,6 +536,17 @@ impl Bus { *self.soft_context_percent.lock().unwrap() } + /// Set (or clear, with `None`) the swarm's fresh-session threshold. + pub fn set_fresh_session_percent(&self, percent: Option) { + *self.fresh_session_percent.lock().unwrap() = percent; + } + + /// The swarm's fresh-session threshold, as a percent of the window. + #[must_use] + pub fn fresh_session_percent(&self) -> Option { + *self.fresh_session_percent.lock().unwrap() + } + /// Walk a stream-json value for `tool_use` blocks and bump the /// per-turn counter for each one we find. Called by the stdout /// pump on every parsed line. Cheap when the line isn't an diff --git a/hive-agent/src/swarm_inference.rs b/hive-agent/src/swarm_inference.rs index 4b07ae51d..fc9dfc4ac 100644 --- a/hive-agent/src/swarm_inference.rs +++ b/hive-agent/src/swarm_inference.rs @@ -21,7 +21,8 @@ //! start, the agent runs on its local values. //! //! `subagent_models` and `max_subagents` are not read here. `soft_context_percent` -//! is handed to the Bus, which the compaction policy reads at turn end. +//! is handed to the Bus, which the compaction policy reads at turn end, and so is +//! `fresh_session_percent`, which the pre-turn auto-reset reads. use std::time::Duration; @@ -147,6 +148,9 @@ pub async fn run(bus: Bus) { target .bus .set_soft_context_percent(read.soft_context_percent); + target + .bus + .set_fresh_session_percent(read.fresh_session_percent); } tokio::time::sleep(POLL_INTERVAL).await; } @@ -234,6 +238,7 @@ mod tests { subagent_models: None, max_subagents: None, soft_context_percent: None, + fresh_session_percent: None, } } diff --git a/hive-agent/src/turn.rs b/hive-agent/src/turn.rs index fb5c6452c..87c85408e 100644 --- a/hive-agent/src/turn.rs +++ b/hive-agent/src/turn.rs @@ -264,12 +264,16 @@ pub fn stall_sleep_secs() -> u64 { /// Resolve the auto-reset watermark. Priority order: /// 1. `HIVE_AUTO_RESET_WATERMARK_TOKENS` env var (explicit override). -/// 2. 50% of the window the API last reported, or `0` before one has been. +/// 2. The swarm's `fresh_session_percent` of the window the API last reported, +/// or 50% when the swarm sets none; `0` before a window has been reported. /// /// `0` disables auto-reset entirely. fn auto_reset_watermark_tokens(bus: &Bus) -> u64 { - env_u64("HIVE_AUTO_RESET_WATERMARK_TOKENS") - .unwrap_or_else(|| bus.api_context_window().map_or(0, |window| window / 2)) + env_u64("HIVE_AUTO_RESET_WATERMARK_TOKENS").unwrap_or_else(|| { + let percent = u64::from(bus.fresh_session_percent().unwrap_or(50)); + bus.api_context_window() + .map_or(0, |window| window * percent / 100) + }) } /// Resolve the assumed cache TTL: `HIVE_CACHE_TTL_SECS` if set (`0` disables @@ -958,6 +962,11 @@ mod tests { assert_eq!(auto_reset_watermark_tokens(&bus), 0); bus.set_api_context_window(1_000_000); assert_eq!(auto_reset_watermark_tokens(&bus), 500_000); + // The swarm sets the threshold: a percent of the same window. + bus.set_fresh_session_percent(Some(20)); + assert_eq!(auto_reset_watermark_tokens(&bus), 200_000); + bus.set_fresh_session_percent(None); + assert_eq!(auto_reset_watermark_tokens(&bus), 500_000); } /// A turn that reports no window never triggers the proactive compaction, diff --git a/swarm-controller-api/src/inference.rs b/swarm-controller-api/src/inference.rs index 3c0f6ada8..d1ec2502a 100644 --- a/swarm-controller-api/src/inference.rs +++ b/swarm-controller-api/src/inference.rs @@ -42,6 +42,13 @@ pub struct InferenceSettings { /// Absent keeps the harness's own watermark. #[serde(default, skip_serializing_if = "Option::is_none")] pub soft_context_percent: Option, + /// The percent of the model's context window above which a turn that finds + /// the prompt cache cold starts a fresh session instead of resuming, in the + /// same range as `soft_context_percent` and not above it when both are set + /// (the agent compacts at the soft limit, so the context would never reach a + /// higher threshold). Absent keeps the harness's own half. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fresh_session_percent: Option, } /// What `GET` answers for one agent. @@ -87,8 +94,9 @@ mod tests { subagent_models: Some(vec!["haiku".to_owned()]), max_subagents: Some(3), soft_context_percent: Some(20), + fresh_session_percent: Some(10), }, - r#"{"model":"opus","effort":"xhigh","subagent_models":["haiku"],"max_subagents":3,"soft_context_percent":20}"#, + r#"{"model":"opus","effort":"xhigh","subagent_models":["haiku"],"max_subagents":3,"soft_context_percent":20,"fresh_session_percent":10}"#, ), ] { assert_eq!(serde_json::to_string(&value).unwrap(), wire); diff --git a/swarm-controller/src/inference.rs b/swarm-controller/src/inference.rs index 749536b0a..df4d1d0ae 100644 --- a/swarm-controller/src/inference.rs +++ b/swarm-controller/src/inference.rs @@ -49,6 +49,7 @@ fn settings_view(v: AgentInference) -> InferenceSettings { subagent_models: v.subagent_models, max_subagents: v.max_subagents, soft_context_percent: v.soft_context_percent, + fresh_session_percent: v.fresh_session_percent, } } @@ -100,12 +101,27 @@ pub(crate) fn into_stored(settings: InferenceSettings) -> Result soft + { + return Err(format!( + "fresh_session_percent is {percent}, above soft_context_percent {soft}; the agent compacts at the soft limit, so a fresh start above it would never happen" + )); + } + } Ok(AgentInference { model: settings.model, effort: settings.effort, subagent_models: settings.subagent_models, max_subagents: settings.max_subagents, soft_context_percent: settings.soft_context_percent, + fresh_session_percent: settings.fresh_session_percent, }) } @@ -261,8 +277,8 @@ pub(crate) async fn get_agent_inference( ones whole", body = InferenceSettings), (status = 400, description = "not an identifier, not declared on any hive, or a \ model name is empty, has whitespace, starts with `-`, or is listed \ - twice, or `max_subagents` is above 32, or `soft_context_percent` is outside \ - its range (problem+json)", + twice, or `max_subagents` is above 32, or `soft_context_percent` or `fresh_session_percent` is outside \ + its range, or the fresh-session percent is above the soft limit (problem+json)", body = String), (status = 422, description = "an unknown field, or an effort that is not one of \ the five levels"), @@ -406,6 +422,7 @@ mod tests { subagent_models: Some(vec!["haiku".to_owned()]), max_subagents: None, soft_context_percent: None, + fresh_session_percent: None, } ); assert_eq!( @@ -590,6 +607,43 @@ mod tests { } } + #[test] + fn fresh_session_percent_outside_its_range_is_refused() { + for percent in [ + 0, + MIN_SOFT_CONTEXT_PERCENT - 1, + MAX_SOFT_CONTEXT_PERCENT + 1, + ] { + let json = format!(r#"{{"fresh_session_percent":{percent}}}"#); + assert!(into_stored(settings(&json).unwrap()).is_err(), "{json}"); + } + assert!(settings(r#"{"fresh_session_percent":-1}"#).is_err()); + } + + #[test] + fn fresh_session_percent_in_range_is_stored() { + for percent in [MIN_SOFT_CONTEXT_PERCENT, 50, MAX_SOFT_CONTEXT_PERCENT] { + let json = format!(r#"{{"fresh_session_percent":{percent}}}"#); + let stored = into_stored(settings(&json).unwrap()).unwrap(); + assert_eq!(stored.fresh_session_percent, Some(percent)); + } + } + + /// The agent compacts at the soft limit, so a fresh-session threshold above + /// it could never be reached. + #[test] + fn fresh_session_percent_above_the_soft_limit_is_refused() { + let above = r#"{"soft_context_percent":40,"fresh_session_percent":41}"#; + assert!(into_stored(settings(above).unwrap()).is_err()); + for ok in [ + r#"{"soft_context_percent":40,"fresh_session_percent":40}"#, + r#"{"soft_context_percent":40,"fresh_session_percent":10}"#, + r#"{"fresh_session_percent":90}"#, + ] { + assert!(into_stored(settings(ok).unwrap()).is_ok(), "{ok}"); + } + } + #[test] fn max_subagents_in_range_is_stored() { for max in [0, 1, 3, MAX_SUBAGENTS] { diff --git a/swarm-wire/src/agent_inference.rs b/swarm-wire/src/agent_inference.rs index 4d28f8147..190c77883 100644 --- a/swarm-wire/src/agent_inference.rs +++ b/swarm-wire/src/agent_inference.rs @@ -54,6 +54,11 @@ pub struct AgentInference { /// in place of the harness's own watermark. `None` keeps the harness's. #[serde(default, skip_serializing_if = "Option::is_none")] pub soft_context_percent: Option, + /// The percent of the model's context window above which a turn that finds + /// the prompt cache cold starts a fresh session instead of resuming. `None` + /// keeps the harness's own half. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fresh_session_percent: Option, } /// A claude `--effort` level, ascending. @@ -147,11 +152,12 @@ mod tests { subagent_models: Some(vec!["haiku".to_owned(), "sonnet".to_owned()]), max_subagents: Some(3), soft_context_percent: Some(20), + fresh_session_percent: Some(10), }; let encoded = serde_json::to_string(&value).unwrap(); assert_eq!( encoded, - r#"{"model":"opus","effort":"xhigh","subagent_models":["haiku","sonnet"],"max_subagents":3,"soft_context_percent":20}"# + r#"{"model":"opus","effort":"xhigh","subagent_models":["haiku","sonnet"],"max_subagents":3,"soft_context_percent":20,"fresh_session_percent":10}"# ); assert_eq!( serde_json::from_str::(&encoded).unwrap(), @@ -176,8 +182,8 @@ mod tests { ); } - /// A value written before `max_subagents` or `soft_context_percent` - /// existed decodes with neither set. + /// A value written before `max_subagents`, `soft_context_percent` or + /// `fresh_session_percent` existed decodes with none set. #[test] fn a_value_without_the_caps_has_neither_set() { let decoded: AgentInference = @@ -185,6 +191,7 @@ mod tests { .unwrap(); assert_eq!(decoded.max_subagents, None); assert_eq!(decoded.soft_context_percent, None); + assert_eq!(decoded.fresh_session_percent, None); assert_eq!(decoded.model.as_deref(), Some("opus")); } diff --git a/swarmctl/src/inference.rs b/swarmctl/src/inference.rs index 53d9410e9..8fecd577a 100644 --- a/swarmctl/src/inference.rs +++ b/swarmctl/src/inference.rs @@ -37,6 +37,7 @@ impl SetFlags { subagent_models: self.subagent_models.or(current.subagent_models), max_subagents: current.max_subagents, soft_context_percent: current.soft_context_percent, + fresh_session_percent: current.fresh_session_percent, }) } } @@ -131,7 +132,7 @@ fn render_configured(s: Option<&InferenceSettings>) -> String { fn render(s: &InferenceSettings) -> String { const UNSET: &str = "(not set; the agent's own)"; format!( - "model: {}\neffort: {}\nsubagent_models: {}\nmax_subagents: {}\nsoft_context_percent: {}\n", + "model: {}\neffort: {}\nsubagent_models: {}\nmax_subagents: {}\nsoft_context_percent: {}\nfresh_session_percent: {}\n", s.model.as_deref().unwrap_or(UNSET), s.effort.map_or(UNSET, Effort::as_str), s.subagent_models @@ -142,6 +143,10 @@ fn render(s: &InferenceSettings) -> String { s.soft_context_percent.map_or_else( || "(not set; the harness's own watermark)".to_owned(), |n| format!("{n}%") + ), + s.fresh_session_percent.map_or_else( + || "(not set; the harness's own half)".to_owned(), + |n| format!("{n}%") ) ) } @@ -203,12 +208,14 @@ mod tests { assert_eq!(merged.effort, Some(Effort::High)); } - /// `set` has no flag for the cap or the soft limit, and stored ones - /// survive it. + /// `set` has no flag for the cap or the two context limits, and stored + /// ones survive it. #[test] - fn set_keeps_the_stored_cap_and_soft_limit() { - let current: InferenceSettings = - serde_json::from_str(r#"{"max_subagents":3,"soft_context_percent":20}"#).unwrap(); + fn set_keeps_the_stored_cap_and_context_limits() { + let current: InferenceSettings = serde_json::from_str( + r#"{"max_subagents":3,"soft_context_percent":20,"fresh_session_percent":10}"#, + ) + .unwrap(); let merged = SetFlags { model: Some("opus".to_owned()), ..flags() @@ -217,6 +224,7 @@ mod tests { .unwrap(); assert_eq!(merged.max_subagents, Some(3)); assert_eq!(merged.soft_context_percent, Some(20)); + assert_eq!(merged.fresh_session_percent, Some(10)); } /// An effort the controller would answer 422 for fails before the request. @@ -267,16 +275,17 @@ mod tests { serde_json::from_str(r#"{"configured":{},"effective":null}"#).unwrap(); assert_eq!( render_configured(empty.configured.as_ref()).lines().count(), - 5 + 6 ); } #[test] fn an_empty_value_renders_every_field_as_unset() { let row = render(&serde_json::from_str("{}").unwrap()); - assert_eq!(row.lines().count(), 5); + assert_eq!(row.lines().count(), 6); assert!( - row.ends_with("soft_context_percent: (not set; the harness's own watermark)\n"), + row.contains("soft_context_percent: (not set; the harness's own watermark)\n") + && row.ends_with("fresh_session_percent: (not set; the harness's own half)\n"), "{row}" ); assert!(row.contains("max_subagents: (not set; no cap)\n"), "{row}"); diff --git a/swarmctl/src/main.rs b/swarmctl/src/main.rs index dfe9d738b..721a9ff15 100644 --- a/swarmctl/src/main.rs +++ b/swarmctl/src/main.rs @@ -386,13 +386,14 @@ enum AgentVerb { /// show what it last did. Fails when the swarm has never heard from the /// agent. Watch(AgentWatchArgs), - /// Show the model, effort, subagent models, subagent cap and soft context - /// limit the swarm sets for an agent, or change the model, effort and + /// Show the model, effort, subagent models, subagent cap and the two context + /// limits the swarm sets for an agent, or change the model, effort and /// subagent models. /// - /// `get` prints the subagent cap (`max_subagents`) and the soft context - /// limit (`soft_context_percent`); `set` has no flag for them and keeps - /// stored ones. Only swarm-ui sets them. + /// `get` prints the subagent cap (`max_subagents`), the soft context limit + /// (`soft_context_percent`) and the fresh-session threshold + /// (`fresh_session_percent`); `set` has no flag for them and keeps stored + /// ones. Only swarm-ui sets them. /// /// A field the swarm sets wins over the agent's own value (its agent.nix /// or a `hyperhive-model`/`hyperhive-effort` file) from its next turn on;