From a6d14640711ae5f62c36ff475c6666b0cfc0f29b Mon Sep 17 00:00:00 2001 From: damocles Date: Sat, 16 May 2026 14:16:25 +0200 Subject: [PATCH] refactor: per-agent state paths (/agents/{label}/state), centralize in paths.rs --- hive-ag3nt/prompts/agent.md | 4 ++-- hive-ag3nt/prompts/manager.md | 2 +- hive-ag3nt/src/bin/hive-ag3nt.rs | 2 +- hive-ag3nt/src/bin/hive-m1nd.rs | 2 +- hive-ag3nt/src/events.rs | 35 ++++++++++++---------------- hive-ag3nt/src/lib.rs | 1 + hive-ag3nt/src/login.rs | 16 ++++++++----- hive-ag3nt/src/paths.rs | 39 ++++++++++++++++++++++++++++++++ hive-ag3nt/src/turn.rs | 16 ++++++------- hive-c0re/src/lifecycle.rs | 25 ++++++++------------ 10 files changed, 86 insertions(+), 56 deletions(-) create mode 100644 hive-ag3nt/src/paths.rs diff --git a/hive-ag3nt/prompts/agent.md b/hive-ag3nt/prompts/agent.md index 01c6f18..46a1edd 100644 --- a/hive-ag3nt/prompts/agent.md +++ b/hive-ag3nt/prompts/agent.md @@ -11,10 +11,10 @@ Need new packages, env vars, or other NixOS config for yourself? You can't edit Durable knowledge: write to `/agents/{label}/state/notes.md` (free-form) or any other path under `/agents/{label}/state/`. That directory is bind-mounted from the host and persists across container destroy/recreate — claude's `--continue` session only carries short-term context, but `/agents/{label}/state/` is forever. Read it back at the start of relevant turns to remember things across resets. -Claude session (OAuth credentials) lives at `/agents/{label}/claude/` and persists across restarts. +Claude session (OAuth credentials) lives at `/root/.claude/` and persists across restarts. **Shared space**: `/shared` is accessible to all agents (read/write). Only put things here you're willing to lose — other agents may delete them. Use for explicit cross-agent communication or shared artifacts when appropriate. -Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/state/` and `send` a short pointer ("dropped the cluster audit in /state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The manager + operator can read your `/state/` from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's `/state/` directly — go through the manager if a payload needs to reach another sub-agent. +Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/agents/{label}/state/` and `send` a short pointer ("dropped the cluster audit in /state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The manager + operator can read your state from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's `/state/` directly — go through the manager if a payload needs to reach another sub-agent. When your inbox has a message, handle it and stop. Don't narrate intent — act. diff --git a/hive-ag3nt/prompts/manager.md b/hive-ag3nt/prompts/manager.md index 8a4d945..fed3154 100644 --- a/hive-ag3nt/prompts/manager.md +++ b/hive-ag3nt/prompts/manager.md @@ -32,7 +32,7 @@ in { environment.systemPackages = [ matrixPkg ]; hyperhive.extraMcpServers.matrix = { command = "${matrixPkg}/bin/mcp-matrix"; - args = [ "--config" "/state/matrix.toml" ]; + args = [ "--config" "/agents//state/matrix.toml" ]; # replace with the agent's label allowedTools = [ "send_message" "join_room" ]; }; } diff --git a/hive-ag3nt/src/bin/hive-ag3nt.rs b/hive-ag3nt/src/bin/hive-ag3nt.rs index 8d6741b..fa9e1fe 100644 --- a/hive-ag3nt/src/bin/hive-ag3nt.rs +++ b/hive-ag3nt/src/bin/hive-ag3nt.rs @@ -65,7 +65,7 @@ async fn main() -> Result<()> { .and_then(|s| s.parse::().ok()) .unwrap_or(DEFAULT_WEB_PORT); let label = std::env::var("HIVE_LABEL").unwrap_or_else(|_| "hive-ag3nt".into()); - let claude_dir = PathBuf::from(login::DEFAULT_CLAUDE_DIR); + let claude_dir = login::default_dir(); let initial = LoginState::from_dir(&claude_dir); tracing::info!(state = ?initial, claude_dir = %claude_dir.display(), "harness boot"); let login_state = Arc::new(Mutex::new(initial)); diff --git a/hive-ag3nt/src/bin/hive-m1nd.rs b/hive-ag3nt/src/bin/hive-m1nd.rs index b56e9b4..aa70079 100644 --- a/hive-ag3nt/src/bin/hive-m1nd.rs +++ b/hive-ag3nt/src/bin/hive-m1nd.rs @@ -55,7 +55,7 @@ async fn main() -> Result<()> { .and_then(|s| s.parse::().ok()) .unwrap_or(DEFAULT_WEB_PORT); let label = std::env::var("HIVE_LABEL").unwrap_or_else(|_| "hm1nd".into()); - let claude_dir = PathBuf::from(login::DEFAULT_CLAUDE_DIR); + let claude_dir = login::default_dir(); let initial = LoginState::from_dir(&claude_dir); tracing::info!(state = ?initial, claude_dir = %claude_dir.display(), "hm1nd boot"); let login_state = Arc::new(Mutex::new(initial)); diff --git a/hive-ag3nt/src/events.rs b/hive-ag3nt/src/events.rs index a5c89d2..c8b0b08 100644 --- a/hive-ag3nt/src/events.rs +++ b/hive-ag3nt/src/events.rs @@ -20,21 +20,18 @@ const CHANNEL_CAPACITY: usize = 256; /// Max `LiveEvent`s the `Bus` returns from `history()` and keeps in /// sqlite. Older rows are vacuumed on a periodic sweep. const HISTORY_CAPACITY: usize = 2000; -/// Default sqlite db path. Lives under `/state/` so it survives -/// destroy/recreate but goes away on purge. Overridable via the -/// `HYPERHIVE_EVENTS_DB` env var (used in tests and one-shot tools). -const DEFAULT_EVENTS_DB: &str = "/state/hyperhive-events.sqlite"; +/// Path to the persisted event db. Overridable via `HYPERHIVE_EVENTS_DB` +/// for dev / tests; otherwise derived from the agent's state dir. +fn events_db_path() -> PathBuf { + std::env::var_os("HYPERHIVE_EVENTS_DB") + .map_or_else(|| crate::paths::state_dir().join("hyperhive-events.sqlite"), PathBuf::from) +} -/// Persisted model name file. Same lifecycle as the events db — -/// survives destroy/recreate, gone on purge. Empty / missing file -/// falls back to `DEFAULT_MODEL`. -const DEFAULT_MODEL_FILE: &str = "/state/hyperhive-model"; - -/// Path to the persisted model file. Overridable via -/// `HYPERHIVE_MODEL_FILE` for dev / tests. +/// Path to the persisted model file. Overridable via `HYPERHIVE_MODEL_FILE` +/// for dev / tests; otherwise derived from the agent's state dir. fn model_file_path() -> PathBuf { std::env::var_os("HYPERHIVE_MODEL_FILE") - .map_or_else(|| PathBuf::from(DEFAULT_MODEL_FILE), PathBuf::from) + .map_or_else(|| crate::paths::state_dir().join("hyperhive-model"), PathBuf::from) } fn load_model() -> Option { @@ -183,7 +180,7 @@ pub struct Bus { tx: Arc>, /// Persistent event log. `None` only if opening the sqlite db failed /// at construction — we keep going so the harness doesn't die on a - /// missing `/state/` mount in dev / test scenarios. + /// missing state dir mount in dev / test scenarios. store: Option>, /// Current turn-loop state + since-when (unix seconds). state: Arc>, @@ -200,13 +197,11 @@ pub struct Bus { } impl Bus { - /// Open the default events db (`/state/hyperhive-events.sqlite`, or - /// `HYPERHIVE_EVENTS_DB`). On failure, fall back to a no-store bus — - /// the harness still works, just without persistent history. + /// Open the events db (path from `events_db_path()`). On failure, fall back + /// to a no-store bus — the harness still works, just without persistent history. #[must_use] pub fn new() -> Self { - let path = std::env::var_os("HYPERHIVE_EVENTS_DB") - .map_or_else(|| PathBuf::from(DEFAULT_EVENTS_DB), PathBuf::from); + let path = events_db_path(); let store = match EventStore::open(&path) { Ok(s) => Some(Arc::new(s)), Err(e) => { @@ -247,8 +242,8 @@ impl Bus { } /// Switch the model for future turns. The current turn (if any) - /// keeps the model it was already running. Persisted to - /// `/state/hyperhive-model` so the override survives harness + /// keeps the model it was already running. Persisted to the agent's + /// state dir (`hyperhive-model`) so the override survives harness /// restart and container rebuild (gone on `--purge`, matching /// every other piece of agent state). pub fn set_model(&self, name: impl Into) { diff --git a/hive-ag3nt/src/lib.rs b/hive-ag3nt/src/lib.rs index d29f393..22ced06 100644 --- a/hive-ag3nt/src/lib.rs +++ b/hive-ag3nt/src/lib.rs @@ -6,6 +6,7 @@ pub mod events; pub mod login; pub mod login_session; pub mod mcp; +pub mod paths; pub mod plugins; pub mod turn; pub mod web_ui; diff --git a/hive-ag3nt/src/login.rs b/hive-ag3nt/src/login.rs index 208045b..68578db 100644 --- a/hive-ag3nt/src/login.rs +++ b/hive-ag3nt/src/login.rs @@ -1,6 +1,6 @@ //! Login-state probe for the bind-mounted `~/.claude/` dir. The dir is -//! provided by hive-c0re (Phase 8 step 1) and persists across container -//! destroy/recreate so OAuth tokens survive. +//! provided by hive-c0re and persists across container destroy/recreate so +//! OAuth tokens survive. //! //! "Has session" today means "the dir contains at least one regular file." //! That's a heuristic: a fresh bind-mount starts empty, and `claude auth login` @@ -8,11 +8,15 @@ //! specific credentials filename, or run a no-op `claude` call) once the //! exact layout is locked in. -use std::path::Path; +use std::path::{Path, PathBuf}; -/// Mount point of the per-agent Claude credentials dir inside the container. -/// Matches `hive_c0re::lifecycle::CONTAINER_CLAUDE_MOUNT`. -pub const DEFAULT_CLAUDE_DIR: &str = "/root/.claude"; +/// Returns the Claude credentials directory for this agent, derived from +/// `HIVE_LABEL`. Manager ("hm1nd") uses `/root/.claude`; sub-agents use +/// `/agents/{label}/claude`. Overridable via `HYPERHIVE_CLAUDE_DIR`. +#[must_use] +pub fn default_dir() -> PathBuf { + crate::paths::claude_dir() +} /// Returns `true` if `dir` exists and contains any regular file. Used at /// startup to decide whether to enter the turn loop (logged in) or stay in diff --git a/hive-ag3nt/src/paths.rs b/hive-ag3nt/src/paths.rs new file mode 100644 index 0000000..0774f75 --- /dev/null +++ b/hive-ag3nt/src/paths.rs @@ -0,0 +1,39 @@ +//! Per-agent path resolution for state and credential directories. +//! +//! Manager ("hm1nd") keeps `/state`; sub-agents use `/agents/{label}/state`. +//! Claude credentials are always at `/root/.claude` for all agents. +//! +//! Both paths can be overridden via env vars (`HYPERHIVE_STATE_DIR`, +//! `HYPERHIVE_CLAUDE_DIR`) for dev / test scenarios. + +use std::path::PathBuf; + +/// Container label of the manager. Sub-agents get `/agents/{label}/state`; +/// the manager keeps `/state`. Must match `hive-c0re::lifecycle::MANAGER_NAME`. +pub const MANAGER_NAME: &str = "hm1nd"; + +/// Durable state directory for the current agent. Reads `HYPERHIVE_STATE_DIR` +/// first; falls back to `/agents/{label}/state` for sub-agents or `/state` for +/// the manager / any unrecognised label. +#[must_use] +pub fn state_dir() -> PathBuf { + if let Some(p) = std::env::var_os("HYPERHIVE_STATE_DIR") { + return PathBuf::from(p); + } + let label = std::env::var("HIVE_LABEL").unwrap_or_default(); + if label == MANAGER_NAME || label.is_empty() { + PathBuf::from("/state") + } else { + PathBuf::from(format!("/agents/{label}/state")) + } +} + +/// Claude credentials directory for the current agent. Always `/root/.claude` +/// because the `claude` CLI reads `$HOME/.claude` (uid 0 → `/root`), and +/// hive-c0re binds the per-agent credentials dir there for every container. +/// Overridable via `HYPERHIVE_CLAUDE_DIR` for dev / test scenarios. +#[must_use] +pub fn claude_dir() -> PathBuf { + std::env::var_os("HYPERHIVE_CLAUDE_DIR") + .map_or_else(|| PathBuf::from("/root/.claude"), PathBuf::from) +} diff --git a/hive-ag3nt/src/turn.rs b/hive-ag3nt/src/turn.rs index 89a614c..651f2a7 100644 --- a/hive-ag3nt/src/turn.rs +++ b/hive-ag3nt/src/turn.rs @@ -230,15 +230,13 @@ async fn run_claude(prompt: &str, files: &TurnFiles, bus: &Bus) -> Result )); } let mut cmd = Command::new("claude"); - // Spawn inside /state so any path claude resolves relatively (Read - // foo.md, Bash ls, Write notes.md) lands in the agent's durable - // dir instead of wherever the harness systemd unit started. /state - // is bind-mounted RW from the host so survives destroy/recreate. - // Fall back silently if the dir is missing (dev / test setups - // running without the bind mount) — Command picks up the parent's - // cwd in that case. - if std::path::Path::new("/state").is_dir() { - cmd.current_dir("/state"); + // Spawn inside the agent's state dir so relative paths in tool calls + // (Read foo.md, Bash ls, Write notes.md) land in the durable dir + // instead of wherever the harness systemd unit started. Falls back + // silently if the dir is missing (dev / test without the bind mount). + let state_dir = crate::paths::state_dir(); + if state_dir.is_dir() { + cmd.current_dir(&state_dir); } cmd.arg("--print") .arg("--verbose") diff --git a/hive-c0re/src/lifecycle.rs b/hive-c0re/src/lifecycle.rs index e5ee15b..760d4b4 100644 --- a/hive-c0re/src/lifecycle.rs +++ b/hive-c0re/src/lifecycle.rs @@ -743,25 +743,18 @@ fn set_nspawn_flags( let path = format!("/etc/nixos-containers/{container}.conf"); let original = std::fs::read_to_string(&path).with_context(|| format!("read {path}"))?; - // Compute mount points: for sub-agents, bind /agents// with state+claude inside. - // For manager, use the old structure with /root/.claude and /state. - let agent_mount_base = if container == MANAGER_NAME { - None // Manager has no agent-specific mount + // Compute the in-container state mount point. Sub-agents get + // /agents//state; the manager keeps the legacy /state path. + // Claude credentials always land at /root/.claude for all agents so + // the `claude` CLI (which reads $HOME/.claude) finds them without any + // HOME override. + let notes_mount = if container == MANAGER_NAME { + CONTAINER_NOTES_MOUNT.to_owned() } else { - // Strip the "h-" prefix from container name to get agent name let agent_name = container.strip_prefix(AGENT_PREFIX).unwrap_or(container); - Some(format!("/agents/{agent_name}")) - }; - - // For sub-agents: bind /agents// containing state and claude - // For manager: use old /state and /root/.claude mounts - let (notes_mount, claude_mount) = if let Some(ref mount_base) = agent_mount_base { - // Sub-agent: state at /agents//state, claude at /agents//claude - (format!("{mount_base}/state"), format!("{mount_base}/claude")) - } else { - // Manager: keep current structure - (CONTAINER_NOTES_MOUNT.to_owned(), CONTAINER_CLAUDE_MOUNT.to_owned()) + format!("/agents/{agent_name}/state") }; + let claude_mount = CONTAINER_CLAUDE_MOUNT; let mut binds = format!( "--bind={runtime}:{CONTAINER_RUNTIME_MOUNT} --bind={claude}:{claude_mount} --bind={notes}:{notes_mount} --bind={shared}:{CONTAINER_SHARED_MOUNT}",