Watch
0
0
Fork
You've already forked hyperhive
0

swarm: set the fresh-session threshold per agent

This commit is contained in:
iris 2026-11-16 10:50:13 +01:00
commit 5175d3663e
11 changed files with 154 additions and 32 deletions

View file

@ -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.

View file

@ -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

View file

@ -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,

View file

@ -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<Mutex<Option<u8>>>,
/// 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<Mutex<Option<u8>>>,
/// 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<u8>) {
*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<u8> {
*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

View file

@ -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,
}
}

View file

@ -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,

View file

@ -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<u8>,
/// 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<u8>,
}
/// 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);

View file

@ -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<AgentInference,
"soft_context_percent is {percent}; it is from {MIN_SOFT_CONTEXT_PERCENT} to {MAX_SOFT_CONTEXT_PERCENT}, or left out for the harness's own watermark"
));
}
if let Some(percent) = settings.fresh_session_percent {
if !(MIN_SOFT_CONTEXT_PERCENT..=MAX_SOFT_CONTEXT_PERCENT).contains(&percent) {
return Err(format!(
"fresh_session_percent is {percent}; it is from {MIN_SOFT_CONTEXT_PERCENT} to {MAX_SOFT_CONTEXT_PERCENT}, or left out for the harness's own half"
));
}
if let Some(soft) = settings.soft_context_percent
&& percent > 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] {

View file

@ -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<u8>,
/// 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<u8>,
}
/// 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::<AgentInference>(&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"));
}

View file

@ -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}");

View file

@ -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;