car_registry/

declarative.rs

//! Declarative agents — in-daemon agents that need no external process.
//!
//! A [`DeclarativeAgentSpec`](crate::declarative::DeclarativeAgentSpec) is pure data: an identity (system prompt), a
//! tool **allowlist** (names of tools the daemon already exposes), an optional
//! deny list, a standing goal, an optional deterministic completion goal, and
//! scenarios (test cases). The daemon runs it with a generic model→tool loop — there is no command to spawn, so a
//! non-developer never installs Node/Python/anything.
//!
//! This is a **parallel registry** to [`crate::supervisor`], deliberately NOT
//! an extension of `supervisor::AgentSpec`: that type's whole security model is
//! the absolute-executable-path validation in `Supervisor::upsert` (the
//! 2026-05 audit's control). A declarative agent has no command, so it must
//! never travel through that path. `agents.list` read-merges declarative
//! entries (tagged `kind:"declarative"`) for the unified host view.

use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};

/// A test case for a declarative agent: run it on `input`, the output must
/// contain `expect` (a stable substring — not an exact match, so the contract
/// tolerates benign model variation).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Scenario {
    pub input: String,
    pub expect: String,
}

/// Deterministic completion contract for a declarative agent invocation.
/// The daemon runs `check` in the same scratch worktree after each agent pass
/// and re-drives until it exits 0 or `max_iterations` is exhausted.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DeclarativeGoal {
    pub check: String,
    #[serde(default = "default_goal_iterations")]
    pub max_iterations: u32,
}

fn default_goal_iterations() -> u32 {
    8
}

/// Who owns the agent's conversation context across a multi-turn run.
///
/// The daemon already bounds the assistant and coder loops to the model's
/// context window; a declarative agent had no such bound and no way to ask for
/// one. This is that switch, per agent, named for who does the work rather than
/// for a mechanism the spec author cannot see.
///
/// Deserialization is deliberately TOLERANT (see the hand-written impl below):
/// an unrecognized value warns and falls back to [`ContextPolicy::Car`] rather
/// than failing the parse. A strict impl would be a foot-gun here — the
/// authoring guide teaches hand-editing `declagents.json`, and `DeclRegistry`
/// treats an unparseable file as an empty registry that the next `upsert`
/// writes back, so one mistyped policy would delete every agent on the box.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ContextPolicy {
    /// CAR manages it: before each model call the running history is compacted
    /// to fit the model's context window, exactly as the assistant and coder
    /// loops do (oldest middle turns dropped on a turn boundary, the system
    /// prompt and the original task pinned, a `[history compacted:` notice left
    /// behind). The default, so an agent that never thinks about context still
    /// gets a bounded one.
    #[default]
    Car,
    /// The agent author manages it. CAR never compacts this agent's history —
    /// the spec owns whatever summarizing, truncation or externalization it
    /// wants. Choose it deliberately: nothing else bounds the transcript.
    #[serde(rename = "self")]
    SelfManaged,
}

impl ContextPolicy {
    /// Whether CAR compacts this agent's history.
    ///
    /// Exhaustive on purpose (repo rule): a `matches!` here would make every
    /// future variant silently self-managed — i.e. would turn "we added a
    /// policy" into "we switched compaction off for it", which is the failure
    /// mode with no symptom until a run overflows.
    pub fn is_car_managed(self) -> bool {
        match self {
            ContextPolicy::Car => true,
            ContextPolicy::SelfManaged => false,
        }
    }

    /// The on-disk / on-the-wire spelling.
    pub fn as_str(self) -> &'static str {
        match self {
            ContextPolicy::Car => "car",
            ContextPolicy::SelfManaged => "self",
        }
    }
}

impl<'de> Deserialize<'de> for ContextPolicy {
    /// Accepts `"car"` and `"self"`; ANYTHING else warns and yields `Car`.
    ///
    /// The strict derive returned `unknown variant`, and one bad character in a
    /// hand-edited `declagents.json` then travelled the whole swallow chain —
    /// [`DeclRegistry::read_all`] maps a parse error to an empty registry, and
    /// the next `upsert` persists that emptiness — so a typo in an optional
    /// field could unregister every agent the user had. A field whose only two
    /// values both mean "keep running" must never be able to do that. The
    /// fallback is the managed default, which is also the safe one: the worst
    /// outcome of guessing wrong is a bounded history for an author who wanted
    /// to bound it themselves, and the warning says so.
    ///
    /// The spec id is not reachable from here (serde hands this impl only the
    /// field's own value), so the warning names the value; the surrounding
    /// spec is one `declagents.json` grep away.
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        // Through `serde_json::Value` rather than `String` so a non-string
        // (`"context": 5`, `null`, an object) takes the same tolerant path
        // instead of the parse error this impl exists to prevent.
        let raw = serde_json::Value::deserialize(deserializer)?;
        match raw.as_str() {
            Some("car") => Ok(ContextPolicy::Car),
            Some("self") => Ok(ContextPolicy::SelfManaged),
            _ => {
                tracing::warn!(
                    value = %raw,
                    "declarative agent spec has an unrecognized `context` policy {raw}; \
                     expected \"car\" or \"self\" — using \"car\" (CAR manages the \
                     history). Fix the value in declagents.json to silence this."
                );
                Ok(ContextPolicy::Car)
            }
        }
    }
}

/// A declarative, in-daemon agent.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DeclarativeAgentSpec {
    /// Filename-safe id (derived from the project slug).
    pub id: String,
    pub name: String,
    /// System prompt — who the agent is and how it behaves.
    pub identity: String,
    /// Allowlist of tool names the agent may call. The daemon exposes ONLY
    /// these to the model; anything else is invisible. Empty = no tools
    /// (a pure-reasoning agent).
    #[serde(default)]
    pub tools: Vec<String>,
    /// Extra hard denials layered under the allowlist (belt and suspenders).
    #[serde(default)]
    pub denied_tools: Vec<String>,
    /// The agent's persistent objective, prepended to every run.
    #[serde(default)]
    pub standing_goal: String,
    /// Optional deterministic completion contract. This is not shown to the
    /// model as a tool; it is the runtime-owned verifier for each invocation.
    #[serde(default)]
    pub goal: Option<DeclarativeGoal>,
    /// Acceptance scenarios — the contract the coder→agent loop drives to green.
    #[serde(default)]
    pub scenarios: Vec<Scenario>,
    /// Lifecycle toggle. A disabled agent stays registered but won't run.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Who manages the conversation context of a run: CAR (compaction keyed to
    /// the model's context window, the default) or the agent itself.
    ///
    /// `#[serde(default)]` is load-bearing: every spec already written to
    /// `declagents.json` predates this field and must keep loading, with the
    /// same managed behavior a new one gets.
    #[serde(default)]
    pub context: ContextPolicy,
}

fn default_true() -> bool {
    true
}

impl DeclarativeAgentSpec {
    /// Structural problems that make a spec unusable. Empty = valid.
    pub fn validate(&self) -> Vec<String> {
        let mut issues = Vec::new();
        if !is_filename_safe(&self.id) {
            issues.push(format!(
                "invalid agent id (alphanumeric + -_.): {:?}",
                self.id
            ));
        }
        if self.name.trim().is_empty() {
            issues.push("agent name is empty".into());
        }
        if self.identity.trim().is_empty() {
            issues.push("agent identity (system prompt) is empty".into());
        }
        if let Some(goal) = &self.goal {
            if goal.check.trim().is_empty() {
                issues.push("agent goal.check is empty".into());
            }
            if goal.max_iterations == 0 || goal.max_iterations > 50 {
                issues.push("agent goal.max_iterations must be between 1 and 50".into());
            }
        }
        // Scenarios are the contract the coder→agent loop drives to green; an
        // agent with none was never validated against any example. The builder
        // always writes at least one, so a zero-scenario spec is a hand-edit or
        // a malformed write — reject it at upsert rather than register an
        // unverifiable agent.
        if self.scenarios.is_empty() {
            issues.push("agent must have at least one acceptance scenario".into());
        }
        issues
    }
}

fn is_filename_safe(id: &str) -> bool {
    !id.is_empty()
        && id != "."
        && id != ".."
        && id
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')
}

/// File-backed registry of declarative agents at `declagents.json` under the
/// CAR state root (`CAR_DECLAGENTS_PATH` overrides for tests/embedders).
/// Atomic write-through — the on-disk JSON is authoritative across restarts,
/// mirroring the supervisor manifest's hygiene.
pub struct DeclRegistry {
    path: PathBuf,
}

impl DeclRegistry {
    /// `declagents.json` under the CAR state root — `$CAR_HOME` when set,
    /// otherwise `~/.car`. `CAR_DECLAGENTS_PATH` is the narrower override and
    /// still wins over both: it names the file outright, so a caller that set
    /// it means that exact path regardless of where the rest of the state
    /// lives.
    pub fn user_default() -> Result<Self, String> {
        if let Some(p) = std::env::var_os("CAR_DECLAGENTS_PATH") {
            return Ok(Self {
                path: PathBuf::from(p),
            });
        }
        let root = car_home::root()
            .ok_or("cannot resolve home directory (CAR_HOME/HOME/USERPROFILE unset)")?;
        Ok(Self {
            path: root.join("declagents.json"),
        })
    }

    pub fn at(path: impl Into<PathBuf>) -> Self {
        Self { path: path.into() }
    }

    /// Exact file this registry reads and writes.
    ///
    /// Location is registry metadata, not part of [`DeclarativeAgentSpec`], so
    /// exposing it cannot leak into persisted `declagents.json` records.
    pub fn path(&self) -> &Path {
        &self.path
    }

    fn read_all(&self) -> Vec<DeclarativeAgentSpec> {
        std::fs::read_to_string(&self.path)
            .ok()
            .and_then(|s| serde_json::from_str(&s).ok())
            .unwrap_or_default()
    }

    fn write_all(&self, specs: &[DeclarativeAgentSpec]) -> Result<(), String> {
        if let Some(parent) = self.path.parent() {
            std::fs::create_dir_all(parent)
                .map_err(|e| format!("create {}: {e}", parent.display()))?;
        }
        let json = serde_json::to_string_pretty(specs).map_err(|e| e.to_string())?;
        // Atomic: write a sibling temp then rename over the target.
        let tmp = self.path.with_extension("json.tmp");
        std::fs::write(&tmp, json).map_err(|e| format!("write {}: {e}", tmp.display()))?;
        std::fs::rename(&tmp, &self.path)
            .map_err(|e| format!("rename into {}: {e}", self.path.display()))
    }

    /// Insert or replace by id. Validates the spec first.
    pub fn upsert(&self, spec: DeclarativeAgentSpec) -> Result<(), String> {
        let issues = spec.validate();
        if !issues.is_empty() {
            return Err(format!("invalid declarative agent: {}", issues.join("; ")));
        }
        let mut all = self.read_all();
        if let Some(existing) = all.iter_mut().find(|s| s.id == spec.id) {
            *existing = spec;
        } else {
            all.push(spec);
        }
        self.write_all(&all)
    }

    pub fn list(&self) -> Vec<DeclarativeAgentSpec> {
        self.read_all()
    }

    pub fn get(&self, id: &str) -> Option<DeclarativeAgentSpec> {
        self.read_all().into_iter().find(|s| s.id == id)
    }

    pub fn remove(&self, id: &str) -> Result<bool, String> {
        let mut all = self.read_all();
        let before = all.len();
        all.retain(|s| s.id != id);
        let removed = all.len() != before;
        if removed {
            self.write_all(&all)?;
        }
        Ok(removed)
    }

    pub fn set_enabled(&self, id: &str, on: bool) -> Result<(), String> {
        let mut all = self.read_all();
        let spec = all
            .iter_mut()
            .find(|s| s.id == id)
            .ok_or_else(|| format!("no declarative agent '{id}'"))?;
        spec.enabled = on;
        self.write_all(&all)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn spec(id: &str) -> DeclarativeAgentSpec {
        DeclarativeAgentSpec {
            id: id.into(),
            name: "Test".into(),
            identity: "You are a test agent.".into(),
            tools: vec!["read_file".into()],
            denied_tools: vec![],
            standing_goal: "be helpful".into(),
            goal: None,
            scenarios: vec![Scenario {
                input: "hi".into(),
                expect: "ok".into(),
            }],
            enabled: true,
            context: ContextPolicy::default(),
        }
    }

    fn temp_registry() -> (tempfile::TempDir, DeclRegistry) {
        let dir = tempfile::tempdir().unwrap();
        let reg = DeclRegistry::at(dir.path().join("declagents.json"));
        (dir, reg)
    }

    #[test]
    fn upsert_rejects_spec_with_no_scenarios() {
        let (_d, reg) = temp_registry();
        let mut s = spec("no-scenarios");
        s.scenarios.clear();
        let err = reg
            .upsert(s)
            .expect_err("zero-scenario spec must be rejected");
        assert!(
            err.contains("at least one acceptance scenario"),
            "got: {err}"
        );
    }

    #[test]
    fn upsert_rejects_invalid_goal_contract() {
        let (_d, reg) = temp_registry();
        let mut s = spec("bad-goal");
        s.goal = Some(DeclarativeGoal {
            check: " ".into(),
            max_iterations: 0,
        });
        let err = reg.upsert(s).expect_err("invalid goal must be rejected");
        assert!(err.contains("goal.check"), "{err}");
        assert!(err.contains("goal.max_iterations"), "{err}");
    }

    #[test]
    fn upsert_list_get_remove_round_trip() {
        let (_d, reg) = temp_registry();
        reg.upsert(spec("email-bot")).unwrap();
        reg.upsert(spec("note-taker")).unwrap();
        assert_eq!(reg.list().len(), 2);
        assert_eq!(reg.get("email-bot").unwrap().name, "Test");
        // Upsert replaces, doesn't duplicate.
        let mut updated = spec("email-bot");
        updated.name = "Renamed".into();
        reg.upsert(updated).unwrap();
        assert_eq!(reg.list().len(), 2);
        assert_eq!(reg.get("email-bot").unwrap().name, "Renamed");
        assert!(reg.remove("email-bot").unwrap());
        assert!(!reg.remove("email-bot").unwrap());
        assert_eq!(reg.list().len(), 1);
    }

    #[test]
    fn set_enabled_toggles() {
        let (_d, reg) = temp_registry();
        reg.upsert(spec("a")).unwrap();
        reg.set_enabled("a", false).unwrap();
        assert!(!reg.get("a").unwrap().enabled);
        reg.set_enabled("a", true).unwrap();
        assert!(reg.get("a").unwrap().enabled);
        assert!(reg.set_enabled("missing", true).is_err());
    }

    #[test]
    fn invalid_spec_is_rejected() {
        let (_d, reg) = temp_registry();
        let mut bad = spec("../escape");
        assert!(reg.upsert(bad.clone()).is_err());
        bad.id = "ok".into();
        bad.identity = "  ".into();
        assert!(reg.upsert(bad).is_err());
    }

    #[test]
    fn get_preserves_existing_registry_bytes_and_path_is_derived() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("declagents.json");
        let fixture = r#"[
  {
    "id": "existing-agent",
    "name": "Existing",
    "identity": "You preserve old state.",
    "tools": [],
    "standing_goal": "remain compatible",
    "scenarios": [{"input": "ping", "expect": "pong"}],
    "enabled": true
  }
]
"#;
        std::fs::write(&path, fixture).unwrap();
        let reg = DeclRegistry::at(&path);

        assert_eq!(reg.path(), path.as_path());
        assert_eq!(reg.get("existing-agent").unwrap().name, "Existing");
        assert_eq!(
            std::fs::read(&path).unwrap(),
            fixture.as_bytes(),
            "a metadata read must not write registry_path into persisted user state"
        );
    }

    #[test]
    fn persists_across_handles() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("declagents.json");
        DeclRegistry::at(&path).upsert(spec("persist")).unwrap();
        // A fresh handle reads the same on-disk state.
        assert!(DeclRegistry::at(&path).get("persist").is_some());
    }

    #[test]
    fn context_policy_round_trips_through_the_spec() {
        // The wire/disk spelling is the spec author's spelling: `car` / `self`.
        let mut s = spec("ctx");
        assert_eq!(s.context, ContextPolicy::Car, "default is CAR-managed");
        let json = serde_json::to_value(&s).unwrap();
        assert_eq!(json["context"], "car");
        assert_eq!(
            serde_json::from_value::<DeclarativeAgentSpec>(json).unwrap(),
            s
        );

        s.context = ContextPolicy::SelfManaged;
        let json = serde_json::to_value(&s).unwrap();
        assert_eq!(json["context"], "self");
        assert_eq!(
            serde_json::from_value::<DeclarativeAgentSpec>(json).unwrap(),
            s
        );
    }

    #[test]
    fn a_spec_written_before_the_context_field_still_loads_as_car_managed() {
        // Every agent already on disk predates the field. It must load — with
        // the managed default, not a parse error and not an unmanaged run.
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("declagents.json");
        std::fs::write(
            &path,
            r#"[
  {
    "id": "legacy-agent",
    "name": "Legacy",
    "identity": "You predate the context field.",
    "tools": [],
    "standing_goal": "remain compatible",
    "scenarios": [{"input": "ping", "expect": "pong"}],
    "enabled": true
  }
]
"#,
        )
        .unwrap();

        let loaded = DeclRegistry::at(&path).get("legacy-agent").unwrap();
        assert_eq!(loaded.context, ContextPolicy::Car);
        assert!(loaded.context.is_car_managed());
    }

    #[test]
    fn a_mistyped_context_value_warns_and_defaults_instead_of_failing_the_parse() {
        // The blast radius of strictness here is the whole registry, not one
        // field: `read_all` maps a parse error to an empty Vec and the next
        // `upsert` writes that back. So a typo in a hand-edited spec — which
        // the authoring guide invites — must degrade to the managed default
        // (with a warning), never to "every agent deleted".
        let spec = serde_json::from_value::<DeclarativeAgentSpec>(serde_json::json!({
            "id": "typo",
            "name": "Typo",
            "identity": "x",
            "scenarios": [{"input": "a", "expect": "b"}],
            "context": "mine",
        }))
        .expect("a mistyped context policy must still load");
        assert_eq!(spec.context, ContextPolicy::Car);

        // Non-strings take the same path (`"context": 5` is the same class of
        // hand-edit), and so does a wrong case.
        for bad in [
            serde_json::json!(5),
            serde_json::json!(null),
            serde_json::json!({"who": "me"}),
            serde_json::json!("Self"),
        ] {
            let spec = serde_json::from_value::<DeclarativeAgentSpec>(serde_json::json!({
                "id": "typo",
                "name": "Typo",
                "identity": "x",
                "scenarios": [{"input": "a", "expect": "b"}],
                "context": bad,
            }))
            .expect("a malformed context policy must still load");
            assert_eq!(spec.context, ContextPolicy::Car);
        }
    }

    #[test]
    fn a_mistyped_context_value_cannot_empty_the_registry() {
        // The chain the test above exists to break, end to end: a file holding
        // two agents, one of them hand-edited wrong, must still list two — and
        // an upsert on top of it must not persist an empty registry.
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("declagents.json");
        std::fs::write(
            &path,
            r#"[
  {
    "id": "good-agent",
    "name": "Good",
    "identity": "You are fine.",
    "scenarios": [{"input": "ping", "expect": "pong"}],
    "enabled": true,
    "context": "self"
  },
  {
    "id": "typo-agent",
    "name": "Typo",
    "identity": "You were hand-edited.",
    "scenarios": [{"input": "ping", "expect": "pong"}],
    "enabled": true,
    "context": "mine"
  }
]
"#,
        )
        .unwrap();

        let reg = DeclRegistry::at(&path);
        assert_eq!(reg.list().len(), 2, "a typo must not empty the registry");
        assert_eq!(
            reg.get("typo-agent").unwrap().context,
            ContextPolicy::Car,
            "the mistyped policy falls back to the managed default"
        );
        assert_eq!(
            reg.get("good-agent").unwrap().context,
            ContextPolicy::SelfManaged,
            "a valid neighbour is unaffected"
        );

        reg.upsert(spec("third")).unwrap();
        assert_eq!(
            DeclRegistry::at(&path).list().len(),
            3,
            "upsert after a tolerated typo must not have written an empty registry"
        );
    }
}