From ce6763cc3af1d5d8f726b354adf584351dde2bf6 Mon Sep 17 00:00:00 2001 From: Tyler Longwell Date: Wed, 23 Sep 2026 12:16:17 -0400 Subject: [PATCH] feat: add portable multi-relay buzz-swarm runner Signed-off-by: Tyler Longwell --- .github/workflows/_ci-rust.yml | 1 + .gitignore | 2 + AGENTS.md | 1 + Cargo.lock | 18 ++ Cargo.toml | 1 + Justfile | 2 + README.md | 4 + crates/buzz-swarm/Cargo.toml | 26 ++ crates/buzz-swarm/README.md | 135 +++++++++ crates/buzz-swarm/buzz-swarm.example.yaml | 29 ++ crates/buzz-swarm/src/cli.rs | 94 ++++++ crates/buzz-swarm/src/config.rs | 344 ++++++++++++++++++++++ crates/buzz-swarm/src/config/tests.rs | 168 +++++++++++ crates/buzz-swarm/src/env.rs | 45 +++ crates/buzz-swarm/src/identity.rs | 114 +++++++ crates/buzz-swarm/src/main.rs | 27 ++ crates/buzz-swarm/src/plan.rs | 250 ++++++++++++++++ crates/buzz-swarm/src/plan/tests.rs | 198 +++++++++++++ crates/buzz-swarm/src/supervisor.rs | 289 ++++++++++++++++++ crates/buzz-swarm/src/supervisor/tests.rs | 344 ++++++++++++++++++++++ crates/buzz-swarm/tests/cli.rs | 238 +++++++++++++++ crates/buzz-swarm/tests/shutdown.rs | 114 +++++++ 22 files changed, 2444 insertions(+) create mode 100644 crates/buzz-swarm/Cargo.toml create mode 100644 crates/buzz-swarm/README.md create mode 100644 crates/buzz-swarm/buzz-swarm.example.yaml create mode 100644 crates/buzz-swarm/src/cli.rs create mode 100644 crates/buzz-swarm/src/config.rs create mode 100644 crates/buzz-swarm/src/config/tests.rs create mode 100644 crates/buzz-swarm/src/env.rs create mode 100644 crates/buzz-swarm/src/identity.rs create mode 100644 crates/buzz-swarm/src/main.rs create mode 100644 crates/buzz-swarm/src/plan.rs create mode 100644 crates/buzz-swarm/src/plan/tests.rs create mode 100644 crates/buzz-swarm/src/supervisor.rs create mode 100644 crates/buzz-swarm/src/supervisor/tests.rs create mode 100644 crates/buzz-swarm/tests/cli.rs create mode 100644 crates/buzz-swarm/tests/shutdown.rs diff --git a/.github/workflows/_ci-rust.yml b/.github/workflows/_ci-rust.yml index f49cc96eb2..8fd11d69c4 100644 --- a/.github/workflows/_ci-rust.yml +++ b/.github/workflows/_ci-rust.yml @@ -100,6 +100,7 @@ jobs: cross "$CARGO_CMD" --release --target "$TARGET" \ -p buzz-relay \ -p buzz-acp \ + -p buzz-swarm \ -p buzz-agent \ -p buzz-dev-mcp \ -p git-credential-nostr \ diff --git a/.gitignore b/.gitignore index f26e74136c..131010c639 100644 --- a/.gitignore +++ b/.gitignore @@ -61,6 +61,8 @@ doc/ /repos/ # Local identity files +*.nsec +/buzz-swarm.yaml identity.key **/identity.key diff --git a/AGENTS.md b/AGENTS.md index 58309c0865..86236e5104 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,7 @@ crates/ buzz-cli # Agent-first CLI buzz-sdk # Typed Nostr event builders buzz-admin # Operator CLI for relay administration + buzz-swarm # Runs agent identities across relays from one YAML file buzz-ws-client # Shared NIP-42 WebSocket client (connect, auth, publish) buzz-test-client # Integration test client and E2E test suite sprig # All-in-one harness bundling ACP, agent, and dev MCP diff --git a/Cargo.lock b/Cargo.lock index 421642e526..986469167d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1438,6 +1438,24 @@ dependencies = [ "uuid", ] +[[package]] +name = "buzz-swarm" +version = "0.1.0" +dependencies = [ + "anyhow", + "buzz-core", + "buzz-sdk", + "clap", + "nostr 0.44.7", + "rustix 1.1.4", + "serde", + "serde_yaml", + "tempfile", + "tokio", + "url", + "zeroize", +] + [[package]] name = "buzz-test-client" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 3e47708e37..e4a3e054d5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,6 +20,7 @@ members = [ "crates/buzz-workflow", "crates/buzz-media", "crates/buzz-cli", + "crates/buzz-swarm", "crates/buzz-pairing-cli", "crates/buzz-sdk", "crates/buzz-persona", diff --git a/Justfile b/Justfile index ecaf6e15f5..aebe8f057a 100644 --- a/Justfile +++ b/Justfile @@ -385,6 +385,7 @@ test-unit: # buzz-acp owns the relay-to-agent trust boundary. Run its tests here so # forged relay events cannot regain a path into agent routing unnoticed. cargo nextest run -p buzz-acp + cargo nextest run -p buzz-swarm # buzz-db migrator/lint tests: pure SQL-parsing unit tests (no infra). # They guard the embedded-migrator invariant (the complete checked-in # additive migration set; legacy cutover/backfill remains an operator @@ -473,6 +474,7 @@ test-unit: cargo nextest run -p buzz-acp --lib else ./scripts/run-tests.sh unit + cargo test -p buzz-swarm fi # Run integration tests only (starts services if needed) diff --git a/README.md b/README.md index 56439f00bc..06c5304d85 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,10 @@ Want a single-node / VPS relay instead of the local-dev stack? Use the productio For agents, set `BUZZ_PRIVATE_KEY` and use [`buzz-cli`](crates/buzz-cli) — JSON in, JSON out, designed for LLM tool calls. +To run a team of agents on your laptop, a VM, or in a container, use +[`buzz-swarm`](crates/buzz-swarm). One YAML file connects each agent to your +chosen relays using its own identity and your NIP-OA owner attestation. + --- ## Windows prerequisites diff --git a/crates/buzz-swarm/Cargo.toml b/crates/buzz-swarm/Cargo.toml new file mode 100644 index 0000000000..4ce2c6bc50 --- /dev/null +++ b/crates/buzz-swarm/Cargo.toml @@ -0,0 +1,26 @@ +[package] +name = "buzz-swarm" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +license.workspace = true +repository.workspace = true +description = "Start and supervise a swarm of Buzz agents from one YAML file" + +[[bin]] +name = "buzz-swarm" +path = "src/main.rs" + +[target.'cfg(unix)'.dependencies] +buzz-sdk = { workspace = true } +buzz-core = { workspace = true } +nostr = { workspace = true } +anyhow = { workspace = true } +serde = { workspace = true } +serde_yaml = { workspace = true } +tokio = { workspace = true } +zeroize = { workspace = true } +clap = { version = "4", features = ["derive"] } +rustix = { version = "1", features = ["process"] } +tempfile = "3" +url = { workspace = true } diff --git a/crates/buzz-swarm/README.md b/crates/buzz-swarm/README.md new file mode 100644 index 0000000000..48308dbfd2 --- /dev/null +++ b/crates/buzz-swarm/README.md @@ -0,0 +1,135 @@ +# buzz-swarm + +Run Buzz agents from a laptop, Kubernetes pod, EC2 instance, or another +Linux/macOS host. Swarm resolves each agent's key, signs its NIP-OA owner +attestation using the existing SDK, then starts one `buzz-acp` process per +agent/relay pair. Every connection for an agent uses **the same key and auth +tag**. There is no fixed relay-count limit. + +The existing harness handles relay connections, conversations, agent sessions, +and tools. Swarm adds only configuration, identity setup, and process +supervision. It runs where you launch it; your deployment platform provisions +the host, logs, and persistent storage. + +## Start + +Install `buzz-swarm` and the existing agent runtime: + +```sh +cargo install --path crates/buzz-swarm --locked +cargo install --path crates/sprig --locked +# Create Sprig's standard personality links in the directory on PATH: +cd "${CARGO_HOME:-$HOME/.cargo}/bin" +ln -s sprig buzz-acp +ln -s sprig buzz-agent +ln -s sprig buzz-dev-mcp +``` + +Separately installed `buzz-acp`, `buzz-agent`, and `buzz-dev-mcp` binaries also +work. Create `buzz-swarm.yaml`: + +```yaml +owner: + nsec: { env: BUZZ_OWNER_NSEC } +defaults: + relays: [wss://team.example.com, wss://project.example.com] +agents: + - name: helper + - name: reviewer + nsec: { file: keys/reviewer.nsec } # optional existing identity +``` + +Supply the owner's private key through the referenced environment variable or +file. The runtime also needs its usual model/provider configuration and +credentials, inherited from the environment or provided under `env` in YAML. + +```sh +buzz-swarm --config /etc/buzz/swarm.yaml validate +buzz-swarm --config /etc/buzz/swarm.yaml +buzz-swarm --config /etc/buzz/swarm.yaml --only helper +``` + +Missing agent keys are generated once and saved as `keys/.nsec` beside +the config, with mode `0600`. Subsequent runs reuse them. Mount that directory +on persistent storage in ephemeral containers, or supply keys from your secret +manager. `validate` checks swarm wiring, identities, and the harness executable; +it writes no keys and starts nothing. Generated preview identities are temporary. +The runtime validates its own model and ACP settings when started. + +The owner must have access to every target relay, and each relay must support +NIP-OA. Profiles, channel membership, conversation history, and memory remain +local to each community. Set a profile and invite agents to the relevant +channels on each relay. The harness defaults to responding only to its owner. + +## Configuration + +See [buzz-swarm.example.yaml](buzz-swarm.example.yaml). Agent fields replace +`defaults`; `env` merges by variable name. Unknown fields are rejected. + +| Fields | Purpose | +|---|---| +| `owner.nsec`, `owner.conditions` | Owner key and optional NIP-OA conditions | +| `name`, `nsec`, `auth_tag`, `enabled` | Per-agent identity and selection | +| `relays` | Non-empty relay list, shared or per agent | +| `workdir` | Working directory, defaulting to the config directory | +| `harness` | Executable path or name on PATH, default `buzz-acp` | +| `restart`, `max_restarts` | `on-failure` (default), `always`, or `never`; default budget 10 | +| `env` | Existing ACP/agent options and credentials | + +Keys and environment values accept literals, `{env: VARIABLE}`, or `{file: +PATH}`. Prefer references for secrets; file contents are trimmed. Swarm file +paths resolve relative to its directory, with `~` expansion. Paths embedded +inside runtime environment values retain the runtime's own semantics, usually +relative to `workdir`. + +Configure the runtime directly using its existing environment contract: + +```yaml +defaults: + relays: [wss://team.example.com] + env: + BUZZ_AGENT_PROVIDER: anthropic + BUZZ_AGENT_MODEL: your-model-id + ANTHROPIC_API_KEY: {env: ANTHROPIC_API_KEY} + BUZZ_ACP_SYSTEM_PROMPT: You are a helpful engineering teammate. + BUZZ_ACP_RESPOND_TO: owner-only +``` + +Swarm defaults `BUZZ_ACP_AGENT_COMMAND` to `buzz-agent` and +`BUZZ_ACP_MCP_COMMAND` to `buzz-dev-mcp`. Override these under `env` for another +ACP runtime; an empty MCP command disables it. See `buzz-acp --help` and +[buzz-agent](../buzz-agent/README.md) for runtime options. Ambient `BUZZ_ACP_*` +settings are cleared; use YAML `env` to configure them explicitly. Model/provider +environment variables are inherited. Swarm owns relay and identity variables; +YAML `env` cannot override them. Owner and sibling agent key source variables +are removed before launching each harness. Processes sharing an OS user still +share that user's filesystem access. + +An existing agent key and pre-signed `auth_tag` can be supplied without `owner`, +so a remote execution host need not hold the owner's key. Swarm verifies each +tag against its agent key, owner, and time conditions. All agents in a swarm +must have the same owner. Duplicate identity/relay pairs are rejected. Separate +deployments must also avoid running the same pair twice. + +## Lifecycle and verification + +Swarm stays in the foreground. Harness stdout/stderr go directly to the caller; +use the runtime or deployment platform for logging. Failures retry with 1–60 +second backoff; the restart budget resets after 60 seconds of uptime. Clean +exits stay ended under the default policy. Final failures produce exit code 1. + +Ctrl-C or SIGTERM stops harness process groups with 15 seconds of grace +(`start --grace SECONDS`). A second signal forces shutdown. Remaining group +members are killed before their leader is reaped, including on natural exit. +Custom runtimes must manage subprocesses they move into other process groups; +container/service containment is the backstop. Workdirs are ordinary directories, +not sandboxes. + +```sh +cargo test -p buzz-swarm +cargo clippy -p buzz-swarm --all-targets -- -D warnings +``` + +Tests launch real fixture processes to check identity/tag reuse, key persistence, +config-relative invocation, failure before launch, and process cleanup. They do +not contact hosted relays or model providers. diff --git a/crates/buzz-swarm/buzz-swarm.example.yaml b/crates/buzz-swarm/buzz-swarm.example.yaml new file mode 100644 index 0000000000..66a1970f20 --- /dev/null +++ b/crates/buzz-swarm/buzz-swarm.example.yaml @@ -0,0 +1,29 @@ +# Run from any directory: buzz-swarm --config /path/to/buzz-swarm.yaml +owner: + nsec: {env: BUZZ_OWNER_NSEC} + conditions: "" # Optional NIP-OA conditions. + +defaults: + relays: + - wss://team.example.com + - wss://project.example.com + # Runtime configuration uses the existing ACP/agent environment contract. + env: + BUZZ_AGENT_PROVIDER: anthropic + BUZZ_AGENT_MODEL: your-model-id + ANTHROPIC_API_KEY: {env: ANTHROPIC_API_KEY} + BUZZ_ACP_RESPOND_TO: owner-only + +agents: + - name: helper + # Omit nsec to generate and reuse keys/helper.nsec beside this file. + env: + BUZZ_ACP_SYSTEM_PROMPT: You are a helpful engineering teammate. + + - name: reviewer + nsec: {file: keys/reviewer.nsec} # Optional existing identity. + env: + BUZZ_ACP_SYSTEM_PROMPT: Review changes for correctness and maintainability. + + # An agent can replace the shared relay list or supply a pre-signed auth_tag. + # With pre-signed tags for every agent, omit owner on the execution host. diff --git a/crates/buzz-swarm/src/cli.rs b/crates/buzz-swarm/src/cli.rs new file mode 100644 index 0000000000..69f55546be --- /dev/null +++ b/crates/buzz-swarm/src/cli.rs @@ -0,0 +1,94 @@ +use std::path::PathBuf; +use std::process::ExitCode; +use std::time::Duration; + +use anyhow::Result; +use clap::{Parser, Subcommand}; + +use crate::config::{expand_tilde, SwarmFile, DEFAULT_CONFIG_FILE}; +use crate::env::Env; +use crate::plan::Plan; +use crate::supervisor::{self, Options}; + +#[derive(Parser)] +#[command(version, about = "Run Buzz agent identities on any number of relays")] +struct Cli { + /// YAML swarm file. Paths inside it are relative to its directory. + #[arg(short, long, default_value = DEFAULT_CONFIG_FILE, global = true)] + config: PathBuf, + /// Run only these agent names. + #[arg(long, value_delimiter = ',', global = true)] + only: Vec, + #[command(subcommand)] + command: Option, +} + +#[derive(Subcommand)] +enum Command { + /// Start and supervise the swarm (default). + Start { + /// Grace period in seconds before forcibly stopping harness groups. + #[arg(long, default_value_t = 15)] + grace: u64, + }, + /// Check swarm wiring and identities; write no keys and start no processes. + /// Runtime-specific settings are validated by the runtime when it starts. + Validate, +} + +#[tokio::main] +pub async fn main() -> ExitCode { + match run(Cli::parse()).await { + Ok(failed) if !failed => ExitCode::SUCCESS, + Ok(_) => ExitCode::FAILURE, + Err(error) => { + eprintln!("buzz-swarm: {error:#}"); + ExitCode::FAILURE + } + } +} + +async fn run(cli: Cli) -> Result { + let env = Env::from_process(); + let file = SwarmFile::load(&expand_tilde(&cli.config, &env))?; + let plan = Plan::build(&file, &cli.only, &env)?; + match cli.command.unwrap_or(Command::Start { grace: 15 }) { + Command::Validate => { + println!("owner {}", plan.owner_pubkey); + for agent in &plan.agents { + println!( + "{} · relay {} · identity {} · {} · workdir {}", + agent.name, + agent.relay_url, + agent.pubkey, + agent.program.display(), + agent.workdir.display() + ); + } + for key in &plan.generated_keys { + println!( + "{}: created on start (preview identity is temporary)", + key.path.display() + ); + } + Ok(false) + } + Command::Start { grace } => { + // Validate the whole file before creating keys or starting anything. + for key in &plan.generated_keys { + key.persist()?; + } + let summary = supervisor::run( + plan, + Options { + grace: Duration::from_secs(grace), + }, + ) + .await?; + for (name, outcome) in &summary.outcomes { + eprintln!("{name}: {outcome:?}"); + } + Ok(summary.failed()) + } + } +} diff --git a/crates/buzz-swarm/src/config.rs b/crates/buzz-swarm/src/config.rs new file mode 100644 index 0000000000..aff46660d5 --- /dev/null +++ b/crates/buzz-swarm/src/config.rs @@ -0,0 +1,344 @@ +//! The swarm file: one YAML document holding the owner identity, the defaults +//! every agent inherits, and the per-agent overrides. +//! +//! Defaults and agent entries share a single schema (`Spec`). They are merged +//! as YAML mappings before typing, so a new knob is added in exactly one place +//! and can never be forgotten in a hand-written merge function. + +use std::collections::BTreeMap; +use std::fmt; +use std::path::{Path, PathBuf}; + +use anyhow::{bail, ensure, Context, Result}; +use serde::Deserialize; +use serde_yaml::{Mapping, Value}; +use zeroize::Zeroizing; + +use crate::env::Env; + +pub const DEFAULT_CONFIG_FILE: &str = "buzz-swarm.yaml"; + +/// Top-level document. +#[derive(Deserialize)] +#[serde(deny_unknown_fields, rename_all = "snake_case")] +pub struct SwarmFile { + pub owner: Option, + /// Paths in the file are relative to its directory, independent of cwd. + #[serde(skip)] + pub directory: PathBuf, + /// Settings every agent inherits. Merged under each agent entry. + #[serde(default)] + pub defaults: Mapping, + /// One entry per agent identity. Each becomes one supervised `buzz-acp`. + pub agents: Vec, +} + +/// The human whose community membership the agents borrow. +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "snake_case")] +pub struct Owner { + pub nsec: SecretRef, + /// NIP-OA delegation conditions, e.g. `kind=1&created_at<1913957000`. + /// Empty (the default) delegates until the owner retires the agent key. + #[serde(default)] + pub conditions: String, +} + +/// Where a value comes from — an agent key, or an entry under `env:`. Literals +/// are supported for convenience; `env:` and `file:` keep the secret out of the +/// config file entirely. +#[derive(Clone)] +pub enum SecretRef { + Literal(String), + Env(String), + File(PathBuf), +} + +impl fmt::Debug for SecretRef { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("SecretRef()") + } +} + +/// Keep source errors actionable without echoing secret values. +impl<'de> Deserialize<'de> for SecretRef { + fn deserialize>(deserializer: D) -> Result { + deserializer.deserialize_any(SecretRefVisitor) + } +} + +struct SecretRefVisitor; + +impl<'de> serde::de::Visitor<'de> for SecretRefVisitor { + type Value = SecretRef; + + fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("a value, `{env: VAR}`, or `{file: PATH}`") + } + + fn visit_str(self, value: &str) -> Result { + Ok(SecretRef::Literal(value.to_owned())) + } + + fn visit_map>(self, mut map: M) -> Result { + let mut source: Option = None; + while let Some(key) = map.next_key::()? { + let next = match key.as_str() { + "env" => SecretRef::Env(map.next_value()?), + "file" => SecretRef::File(map.next_value()?), + other => { + return Err(serde::de::Error::custom(format!( + "unknown source `{other}` — expected `env` or `file`" + ))) + } + }; + if source.replace(next).is_some() { + return Err(serde::de::Error::custom( + "set either `env:` or `file:`, not both", + )); + } + } + source.ok_or_else(|| { + serde::de::Error::custom("expected a value, `{env: VAR}`, or `{file: PATH}`") + }) + } +} + +impl SecretRef { + /// Resolve without logging values. Literal and environment values are exact; + /// files trim surrounding whitespace for secret-manager mounted credentials. + pub fn resolve(&self, env: &Env) -> Result { + let value = match self { + Self::Literal(value) => Zeroizing::new(value.clone()), + Self::Env(var) => { + let value = env + .get(var) + .with_context(|| format!("environment variable `{var}` is not set"))?; + Zeroizing::new(value.to_owned()) + } + Self::File(path) => { + let path = expand_tilde(path, env); + let contents = Zeroizing::new( + std::fs::read_to_string(&path) + .with_context(|| format!("reading secret file {}", path.display()))?, + ); + Zeroizing::new(contents.trim().to_owned()) + } + }; + Ok(Secret(value)) + } + + fn resolve_path(&mut self, directory: &Path, env: &Env) { + if let Self::File(path) = self { + *path = directory.join(expand_tilde(path, env)); + } + } + + pub fn env_key(&self) -> Option<&str> { + match self { + Self::Env(key) => Some(key), + _ => None, + } + } +} + +/// Secret material that never reaches a log line by accident. +#[derive(Clone)] +pub struct Secret(Zeroizing); + +impl Secret { + pub fn expose(&self) -> &str { + &self.0 + } +} + +impl fmt::Debug for Secret { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("Secret()") + } +} + +/// Swarm settings. Runtime-specific options use the existing `BUZZ_*` +/// environment contract through `env`, rather than a second configuration API. +#[derive(Debug, Default, Clone, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "snake_case")] +pub struct Spec { + // Identity — agent entries only. + pub name: Option, + pub nsec: Option, + /// Pre-signed NIP-OA tag for this identity; avoids sending the owner key + /// to the machine running the swarm. + pub auth_tag: Option, + pub enabled: Option, + + pub relays: Option>, + pub workdir: Option, + pub harness: Option, + pub restart: Option, + pub max_restarts: Option, + + /// Extra environment for the harness and everything below it. Keys the + /// swarm owns are rejected. + #[serde(default)] + pub env: BTreeMap, +} + +/// What to do when a harness process exits. +/// +/// `on-failure` is the default because a Buzz agent is built to end itself — +/// it says goodbye and exits 0 after `exit_after_inactivity`, or when its owner +/// tells it to stop. Restarting a clean exit would fight that lifecycle. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum Restart { + Never, + #[default] + OnFailure, + Always, +} + +impl SwarmFile { + pub fn load(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .with_context(|| format!("reading swarm file {}", path.display()))?; + let mut file = Self::parse(&text)?; + file.directory = std::path::absolute(path)? + .parent() + .context("swarm file has no parent directory")? + .to_path_buf(); + Ok(file) + } + + pub fn parse(text: &str) -> Result { + serde_yaml::from_str(text).context("parsing swarm file") + } + + pub fn owner(&self, env: &Env) -> Option { + self.owner.as_ref().map(|owner| { + let mut nsec = owner.nsec.clone(); + nsec.resolve_path(&self.directory, env); + Owner { + nsec, + conditions: owner.conditions.clone(), + } + }) + } + + pub fn resolved_specs(&self, env: &Env) -> Result> { + let mut specs = self.specs()?; + for spec in &mut specs { + for source in spec + .nsec + .iter_mut() + .chain(spec.auth_tag.iter_mut()) + .chain(spec.env.values_mut()) + { + source.resolve_path(&self.directory, env); + } + if let Some(path) = &mut spec.workdir { + *path = self.directory.join(expand_tilde(path, env)); + } + if spec.workdir.is_none() && !self.directory.as_os_str().is_empty() { + spec.workdir = Some(self.directory.clone()); + } + if let Some(command) = &mut spec.harness { + if command.contains('/') || command.starts_with('~') { + *command = self + .directory + .join(expand_tilde(Path::new(command), env)) + .to_string_lossy() + .into_owned(); + } + } + } + Ok(specs) + } + + /// Type-check `defaults:` on its own, then produce one fully merged `Spec` + /// per agent entry (agent keys win; `env:` maps merge key-wise). + pub fn specs(&self) -> Result> { + let defaults: Spec = serde_yaml::from_value(Value::Mapping(self.defaults.clone())) + .context("parsing `defaults:`")?; + for (field, present) in [ + ("name", defaults.name.is_some()), + ("nsec", defaults.nsec.is_some()), + ("auth_tag", defaults.auth_tag.is_some()), + ("enabled", defaults.enabled.is_some()), + ] { + if present { + bail!("`defaults:` must not set `{field}` — it belongs to an agent entry"); + } + } + + let mut specs = Vec::with_capacity(self.agents.len()); + for (index, entry) in self.agents.iter().enumerate() { + let Value::Mapping(entry) = entry else { + bail!("agents[{index}]: each entry must be a mapping with a `name`"); + }; + let label = entry + .get(Value::from("name")) + .and_then(Value::as_str) + .map(|name| format!("agents[{index}] (`{name}`)")) + .unwrap_or_else(|| format!("agents[{index}]")); + let merged = merge_mappings(&self.defaults, entry); + let spec: Spec = serde_yaml::from_value(Value::Mapping(merged)) + .with_context(|| format!("parsing {label}"))?; + specs.push(spec); + } + Ok(specs) + } +} + +impl fmt::Debug for SwarmFile { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("SwarmFile") + .field("agents", &self.agents.len()) + .finish_non_exhaustive() + } +} + +/// Only `env` merges key-wise. A secret source is replaced as a whole. +fn merge_mappings(base: &Mapping, over: &Mapping) -> Mapping { + let mut merged = base.clone(); + for (key, value) in over { + match (merged.get(key), value) { + (Some(Value::Mapping(base_map)), Value::Mapping(over_map)) + if key.as_str() == Some("env") => + { + let mut nested = base_map.clone(); + nested.extend(over_map.clone()); + merged.insert(key.clone(), Value::Mapping(nested)); + } + _ => { + merged.insert(key.clone(), value.clone()); + } + } + } + merged +} + +/// Names also determine the default key filenames. +pub fn validate_name(name: &str) -> Result<()> { + ensure!( + !name.is_empty() + && name.len() <= 64 + && name + .bytes() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, b'-' | b'_')), + "agent name must be 1–64 ASCII letters, digits, hyphens, or underscores" + ); + Ok(()) +} + +pub fn expand_tilde(path: &Path, env: &Env) -> PathBuf { + let Ok(rest) = path.strip_prefix("~") else { + return path.to_path_buf(); + }; + match env.get("HOME") { + Some(home) if !home.is_empty() => Path::new(home).join(rest), + _ => path.to_path_buf(), + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/buzz-swarm/src/config/tests.rs b/crates/buzz-swarm/src/config/tests.rs new file mode 100644 index 0000000000..9e19daae3b --- /dev/null +++ b/crates/buzz-swarm/src/config/tests.rs @@ -0,0 +1,168 @@ +use super::*; + +fn spec_of(yaml: &str) -> Spec { + SwarmFile::parse(yaml) + .expect("parse") + .specs() + .expect("specs") + .remove(0) +} + +#[test] +fn agent_overrides_defaults_and_environment_values_merge_by_key() { + let spec = spec_of( + r#" +defaults: + relays: [wss://shared.example] + harness: buzz-acp + restart: never + env: + SHARED: retained + CREDENTIAL: {env: SHARED_CREDENTIAL} +agents: + - name: helper + relays: [wss://agent.example] + restart: on-failure + env: + CREDENTIAL: {file: keys/credential} + BUZZ_ACP_MCP_COMMAND: '' +"#, + ); + assert_eq!(spec.relays, Some(vec!["wss://agent.example".to_owned()])); + assert_eq!(spec.harness.as_deref(), Some("buzz-acp")); + assert_eq!(spec.restart, Some(Restart::OnFailure)); + assert!( + matches!(spec.env.get("CREDENTIAL"), Some(SecretRef::File(path)) if path == Path::new("keys/credential")) + ); + let env = Env::default(); + assert_eq!( + spec.env["SHARED"].resolve(&env).unwrap().expose(), + "retained" + ); + assert_eq!( + spec.env["BUZZ_ACP_MCP_COMMAND"] + .resolve(&env) + .unwrap() + .expose(), + "" + ); +} + +#[test] +fn rejects_unknown_fields_and_shared_identity() { + for (yaml, message) in [ + ("agents: [{name: helper, typo: true}]", "typo"), + ("agents: [{name: helper, provider: anything}]", "provider"), + ( + "defaults: {name: helper}\nagents: []", + "`defaults:` must not set `name`", + ), + ( + "defaults: {nsec: {env: KEY}}\nagents: []", + "`defaults:` must not set `nsec`", + ), + ( + "defaults: {auth_tag: anything}\nagents: []", + "`defaults:` must not set `auth_tag`", + ), + ( + "defaults: {enabled: true}\nagents: []", + "`defaults:` must not set `enabled`", + ), + ] { + let error = format!("{:#}", SwarmFile::parse(yaml).unwrap().specs().unwrap_err()); + assert!(error.contains(message), "{error}"); + } + assert!(SwarmFile::parse("agent: []").is_err()); +} + +#[test] +fn secret_sources_preserve_values_and_do_not_expose_them_in_debug() { + let env = Env::from_iter([("VALUE", " exact value ")]); + for yaml in ["' exact value '", "{env: VALUE}"] { + let source: SecretRef = serde_yaml::from_str(yaml).unwrap(); + let value = source.resolve(&env).unwrap(); + assert_eq!(value.expose(), " exact value "); + assert!(!format!("{source:?} {value:?}").contains("exact value")); + } + let missing: SecretRef = serde_yaml::from_str("{env: MISSING}").unwrap(); + assert!(format!("{:#}", missing.resolve(&env).unwrap_err()).contains("MISSING")); + + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("key"); + std::fs::write(&path, " credential\n").unwrap(); + assert_eq!( + SecretRef::File(path).resolve(&env).unwrap().expose(), + "credential" + ); +} + +#[test] +fn secret_sources_reject_ambiguous_or_unknown_forms() { + for yaml in ["{env: A, file: key}", "{}", "{fiel: key}"] { + assert!(serde_yaml::from_str::(yaml).is_err(), "{yaml}"); + } +} + +#[test] +fn paths_resolve_from_the_config_directory() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("swarm.yaml"); + std::fs::write( + &path, + r#" +owner: {nsec: {file: owner.nsec}} +defaults: + harness: ./bin/harness + env: + CREDENTIAL: {file: secret} +agents: + - name: helper + nsec: {file: keys/helper.nsec} + auth_tag: {file: auth.json} + - name: other + workdir: checkout + harness: buzz-acp +"#, + ) + .unwrap(); + let file = SwarmFile::load(&path).unwrap(); + let env = Env::default(); + assert!( + matches!(file.owner(&env).unwrap().nsec, SecretRef::File(path) if path == directory.path().join("owner.nsec")) + ); + let specs = file.resolved_specs(&env).unwrap(); + assert_eq!(specs[0].workdir.as_deref(), Some(directory.path())); + assert_eq!( + Path::new(specs[0].harness.as_deref().unwrap()), + directory.path().join("bin/harness") + ); + for (source, relative) in [ + (specs[0].nsec.as_ref().unwrap(), "keys/helper.nsec"), + (specs[0].auth_tag.as_ref().unwrap(), "auth.json"), + (&specs[0].env["CREDENTIAL"], "secret"), + ] { + assert!( + matches!(source, SecretRef::File(path) if path == &directory.path().join(relative)) + ); + } + assert_eq!(specs[1].workdir, Some(directory.path().join("checkout"))); + assert_eq!(specs[1].harness.as_deref(), Some("buzz-acp")); +} + +#[test] +fn tilde_expands_only_at_the_root() { + let env = Env::from_iter([("HOME", "/home/operator")]); + assert_eq!( + expand_tilde(Path::new("~/keys/a"), &env), + PathBuf::from("/home/operator/keys/a") + ); + assert_eq!( + expand_tilde(Path::new("/etc/~/a"), &env), + PathBuf::from("/etc/~/a") + ); + assert_eq!( + expand_tilde(Path::new("~/a"), &Env::default()), + PathBuf::from("~/a") + ); +} diff --git a/crates/buzz-swarm/src/env.rs b/crates/buzz-swarm/src/env.rs new file mode 100644 index 0000000000..fd7d045204 --- /dev/null +++ b/crates/buzz-swarm/src/env.rs @@ -0,0 +1,45 @@ +//! A snapshot of the process environment. +//! +//! Every environment read goes through this type so that secret resolution +//! and `PATH` lookup are pure functions of an explicit input and can +//! be exercised in tests without mutating global process state. + +use std::collections::BTreeMap; + +#[derive(Clone, Default)] +pub struct Env { + vars: BTreeMap>, +} + +impl Env { + /// Preserve variable names even when values are not UTF-8, so identity and + /// ACP settings can always be removed from inherited child environments. + pub fn from_process() -> Self { + Self { + vars: std::env::vars_os() + .filter_map(|(key, value)| { + Some((key.into_string().ok()?, value.into_string().ok())) + }) + .collect(), + } + } + + pub fn get(&self, key: &str) -> Option<&str> { + self.vars.get(key).and_then(Option::as_deref) + } + + pub fn keys(&self) -> impl Iterator { + self.vars.keys().map(String::as_str) + } +} + +impl, V: Into> FromIterator<(K, V)> for Env { + fn from_iter>(iter: I) -> Self { + Self { + vars: iter + .into_iter() + .map(|(k, v)| (k.into(), Some(v.into()))) + .collect(), + } + } +} diff --git a/crates/buzz-swarm/src/identity.rs b/crates/buzz-swarm/src/identity.rs new file mode 100644 index 0000000000..7c4b657c5e --- /dev/null +++ b/crates/buzz-swarm/src/identity.rs @@ -0,0 +1,114 @@ +//! Resolve one stable identity, then reuse it on every configured relay. + +use std::io::Write; +use std::path::{Path, PathBuf}; + +use anyhow::{Context, Result}; +use nostr::{Keys, ToBech32}; + +use crate::config::{Secret, SecretRef, Spec}; +use crate::env::Env; + +pub struct Identity { + pub secret: Secret, + pub pubkey: String, + pub owner: String, + pub auth_tag: String, + pub generated: Option, +} + +pub struct GeneratedKey { + pub path: PathBuf, + keys: Keys, +} + +impl GeneratedKey { + pub fn persist(&self) -> Result<()> { + write_secret(&self.path, &self.keys) + } +} + +pub fn key_path(directory: &Path, name: &str) -> PathBuf { + directory + .join("keys") + .join(format!("{}.nsec", name.to_ascii_lowercase())) +} + +impl Identity { + pub fn resolve( + name: &str, + spec: &Spec, + directory: &Path, + owner: Option<&Keys>, + conditions: &str, + env: &Env, + ) -> Result { + let path = key_path(directory, name); + let (keys, generated_path) = match &spec.nsec { + Some(source) => ( + Keys::parse(source.resolve(env)?.expose().trim()) + .context("invalid agent `nsec`")?, + None, + ), + None if path.try_exists()? => ( + Keys::parse(SecretRef::File(path.clone()).resolve(env)?.expose()) + .with_context(|| format!("invalid agent key in {}", path.display()))?, + None, + ), + None => (Keys::generate(), Some(path)), + }; + let auth_tag = match &spec.auth_tag { + Some(source) => source + .resolve(env) + .context("resolving `auth_tag`")? + .expose() + .to_owned(), + None => buzz_sdk::nip_oa::compute_auth_tag( + owner.context("set `owner.nsec` or provide this agent's `nsec` and `auth_tag`")?, + &keys.public_key(), + conditions, + ) + .context("signing agent delegation")?, + }; + let delegated_owner = buzz_sdk::nip_oa::verify_auth_tag_for_auth_event( + &auth_tag, + &keys.public_key(), + nostr::Timestamp::now().as_secs(), + ) + .context("`auth_tag` does not authorize this agent key")?; + Ok(Self { + secret: SecretRef::Literal(keys.secret_key().to_bech32()?).resolve(env)?, + pubkey: keys.public_key().to_hex(), + owner: delegated_owner.to_hex(), + auth_tag, + generated: generated_path.map(|path| GeneratedKey { path, keys }), + }) + } +} + +/// Create the key file with 0600 from the start — never world-readable for the +/// window between `create` and `chmod` — and refuse to clobber an existing key. +pub fn write_secret(path: &Path, keys: &Keys) -> Result<()> { + if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) { + std::fs::create_dir_all(parent) + .with_context(|| format!("creating {}", parent.display()))?; + } + let parent = path + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + let mut handle = tempfile::NamedTempFile::new_in(parent)?; + let nsec = keys + .secret_key() + .to_bech32() + .context("encoding the new secret key")?; + writeln!(handle, "{nsec}").with_context(|| format!("writing {}", path.display()))?; + handle.as_file().sync_all()?; + handle.persist_noclobber(path).with_context(|| { + format!( + "creating {} — refusing to overwrite an existing key", + path.display() + ) + })?; + Ok(()) +} diff --git a/crates/buzz-swarm/src/main.rs b/crates/buzz-swarm/src/main.rs new file mode 100644 index 0000000000..65b176374b --- /dev/null +++ b/crates/buzz-swarm/src/main.rs @@ -0,0 +1,27 @@ +//! Run Buzz agents on any configured relays from a Unix host. + +#![deny(unsafe_code)] + +#[cfg(unix)] +mod cli; +#[cfg(unix)] +mod config; +#[cfg(unix)] +mod env; +#[cfg(unix)] +mod identity; +#[cfg(unix)] +mod plan; +#[cfg(unix)] +mod supervisor; + +#[cfg(unix)] +fn main() -> std::process::ExitCode { + cli::main() +} + +#[cfg(not(unix))] +fn main() -> std::process::ExitCode { + eprintln!("buzz-swarm requires Unix process groups; run it on Linux or macOS"); + std::process::ExitCode::FAILURE +} diff --git a/crates/buzz-swarm/src/plan.rs b/crates/buzz-swarm/src/plan.rs new file mode 100644 index 0000000000..82bc5db8fc --- /dev/null +++ b/crates/buzz-swarm/src/plan.rs @@ -0,0 +1,250 @@ +//! Bind each identity once, then launch the existing harness on every relay. + +use std::collections::{BTreeMap, BTreeSet}; +use std::path::PathBuf; + +use anyhow::{bail, ensure, Context, Result}; +use buzz_core::relay::normalize_relay_url; +use nostr::Keys; + +use crate::config::{validate_name, Restart, SwarmFile}; +use crate::env::Env; +use crate::identity::{GeneratedKey, Identity}; + +// Identity and desktop handoffs must never override the swarm's delegation. +const RESERVED: &[&str] = &[ + "BUZZ_RELAY_URL", + "BUZZ_PRIVATE_KEY", + "NOSTR_PRIVATE_KEY", + "BUZZ_AUTH_TAG", + "BUZZ_OWNER_NSEC", + "BUZZ_API_TOKEN", + "BUZZ_ACP_PRIVATE_KEY", + "BUZZ_ACP_API_TOKEN", + "BUZZ_ACP_AGENT_OWNER", + "BUZZ_ACP_SETUP_PAYLOAD", + "BUZZ_MANAGED_AGENT", + "BUZZ_MANAGED_AGENT_START_NONCE", +]; + +#[derive(Clone)] +pub struct AgentPlan { + pub name: String, + pub pubkey: String, + pub relay_url: String, + pub program: PathBuf, + pub args: Vec, + pub workdir: PathBuf, + pub env: BTreeMap, + pub env_remove: Vec, + pub restart: Restart, + pub max_restarts: u32, +} + +pub struct Plan { + pub owner_pubkey: String, + pub agents: Vec, + pub generated_keys: Vec, +} + +impl Plan { + /// Validate swarm wiring and identities without persisting or launching. + /// ACP and model configuration belongs to the runtime and is validated there. + pub fn build(file: &SwarmFile, only: &[String], env: &Env) -> Result { + let owner = file.owner(env); + let owner_keys = owner + .as_ref() + .map(|owner| { + Keys::parse(owner.nsec.resolve(env)?.expose().trim()) + .context("invalid owner private key") + }) + .transpose()?; + let mut owner_pubkey = owner_keys.as_ref().map(|keys| keys.public_key().to_hex()); + let specs = file.resolved_specs(env)?; + // Include disabled and unselected agents: their source variables still + // exist in the parent's environment and must not reach another agent. + let private_sources: BTreeSet<_> = owner + .iter() + .map(|owner| &owner.nsec) + .chain(specs.iter().filter_map(|spec| spec.nsec.as_ref())) + .filter_map(|source| source.env_key()) + .map(str::to_owned) + .collect(); + let env_remove: Vec<_> = env + .keys() + .filter(|key| key.starts_with("BUZZ_ACP_") || RESERVED.contains(key)) + .map(str::to_owned) + .chain(private_sources.iter().cloned()) + .collect(); + let mut agents = Vec::new(); + let mut generated_keys = Vec::new(); + let mut seen_names = BTreeSet::new(); + let mut seen_connections = BTreeSet::new(); + let mut selected = BTreeSet::new(); + + for spec in &specs { + let name = spec.name.as_deref().context("each agent needs a name")?; + validate_name(name)?; + ensure!( + seen_names.insert(name.to_ascii_lowercase()), + "duplicate agent name `{name}`" + ); + if !spec.enabled.unwrap_or(true) + || (!only.is_empty() && !only.iter().any(|n| n == name)) + { + continue; + } + let identity = Identity::resolve( + name, + spec, + &file.directory, + owner_keys.as_ref(), + owner.as_ref().map_or("", |owner| owner.conditions.as_str()), + env, + ) + .with_context(|| format!("agent `{name}`"))?; + match &owner_pubkey { + Some(owner) => ensure!( + *owner == identity.owner, + "agent `{name}` has a different owner" + ), + None => owner_pubkey = Some(identity.owner.clone()), + } + let program = executable(spec.harness.as_deref().unwrap_or("buzz-acp"), env)?; + let workdir = spec + .workdir + .clone() + .unwrap_or_else(|| file.directory.clone()); + ensure!( + workdir.is_dir(), + "agent `{name}`: workdir {} is not a directory", + workdir.display() + ); + let mut child_env = BTreeMap::from([ + ("BUZZ_ACP_AGENT_COMMAND".into(), "buzz-agent".into()), + ("BUZZ_ACP_MCP_COMMAND".into(), "buzz-dev-mcp".into()), + ("BUZZ_ACP_DISPLAY_NAME".into(), name.to_owned()), + ]); + for (key, source) in &spec.env { + ensure!( + !key.is_empty() + && !key.starts_with(|c: char| c.is_ascii_digit()) + && key.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'_'), + "invalid environment variable name `{key}`" + ); + ensure!( + !RESERVED.contains(&key.as_str()) + && !private_sources.contains(key) + && !source + .env_key() + .is_some_and(|source| private_sources.contains(source)), + "`env` may not override identity source `{key}`" + ); + child_env.insert( + key.clone(), + source + .resolve(env) + .with_context(|| format!("agent `{name}`: env.{key}"))? + .expose() + .to_owned(), + ); + } + child_env.insert( + "BUZZ_PRIVATE_KEY".into(), + identity.secret.expose().to_owned(), + ); + child_env.insert( + "NOSTR_PRIVATE_KEY".into(), + identity.secret.expose().to_owned(), + ); + child_env.insert("BUZZ_AUTH_TAG".into(), identity.auth_tag); + let relays = spec + .relays + .as_ref() + .filter(|relays| !relays.is_empty()) + .with_context(|| format!("agent `{name}` needs a non-empty `relays` list"))?; + for relay in relays { + let relay = relay_url(relay)?; + ensure!( + seen_connections + .insert((identity.pubkey.clone(), normalize_relay_url(&relay)?)), + "duplicate identity on relay {relay}" + ); + let mut connection_env = child_env.clone(); + connection_env.insert("BUZZ_RELAY_URL".into(), relay.clone()); + agents.push(AgentPlan { + name: format!("{name}@{relay}"), + pubkey: identity.pubkey.clone(), + relay_url: relay, + program: program.clone(), + args: Vec::new(), + workdir: workdir.clone(), + env: connection_env, + env_remove: env_remove.clone(), + restart: spec.restart.unwrap_or_default(), + max_restarts: spec.max_restarts.unwrap_or(10), + }); + } + selected.insert(name); + if let Some(key) = identity.generated { + generated_keys.push(key); + } + } + for name in only { + ensure!( + selected.contains(&name.as_str()), + "--only names an unknown or disabled agent `{name}`" + ); + } + ensure!(!agents.is_empty(), "no enabled agents selected"); + Ok(Self { + owner_pubkey: owner_pubkey.context("no agent owner")?, + agents, + generated_keys, + }) + } +} + +// Resolve only the executable Swarm launches. The harness owns its subprocess +// configuration, including PATH lookup for alternative ACP agents and MCPs. +fn executable(name: &str, env: &Env) -> Result { + use std::os::unix::fs::PermissionsExt; + let candidates = if name.contains('/') { + vec![PathBuf::from(name)] + } else { + std::env::split_paths(env.get("PATH").unwrap_or_default()) + .map(|directory| directory.join(name)) + .collect() + }; + candidates.into_iter().find(|path| std::fs::metadata(path) + .is_ok_and(|metadata| metadata.is_file() && metadata.permissions().mode() & 0o111 != 0)) + .map(std::path::absolute).transpose()? + .with_context(|| format!("cannot find executable `{name}`; install buzz-acp or Sprig's personality symlinks on PATH")) +} + +/// Normalize equivalent relay addresses before checking duplicate identities. +pub fn relay_url(community: &str) -> Result { + let community = community.trim(); + ensure!(!community.is_empty(), "`relays` is empty"); + let url = if let Some(rest) = community.strip_prefix("https://") { + format!("wss://{rest}") + } else if let Some(rest) = community.strip_prefix("http://") { + format!("ws://{rest}") + } else if community.starts_with("wss://") || community.starts_with("ws://") { + community.to_owned() + } else if let Some((scheme, _)) = community.split_once("://") { + bail!("`relays: {community}` uses unsupported scheme `{scheme}`"); + } else { + format!("wss://{community}") + }; + let parsed = url::Url::parse(&url).context("invalid relay URL")?; + normalize_relay_url(parsed.as_str())?; + Ok(if parsed.path() == "/" && parsed.query().is_none() { + parsed.as_str().trim_end_matches('/').to_owned() + } else { + parsed.to_string() + }) +} + +#[cfg(test)] +mod tests; diff --git a/crates/buzz-swarm/src/plan/tests.rs b/crates/buzz-swarm/src/plan/tests.rs new file mode 100644 index 0000000000..6f243653f0 --- /dev/null +++ b/crates/buzz-swarm/src/plan/tests.rs @@ -0,0 +1,198 @@ +use super::*; +use crate::config::SecretRef; + +struct Fixture { + root: tempfile::TempDir, + owner: Keys, +} + +impl Fixture { + fn new() -> Self { + Self { + root: tempfile::tempdir().expect("directory"), + owner: Keys::generate(), + } + } + + fn plan(&self, settings: &str, agents: &str, parent: &Env) -> Result { + let mut file = SwarmFile::parse(&format!( + "owner:\n nsec: {{env: OWNER}}\ndefaults:\n harness: /usr/bin/true\n relays: [https://relay.example]\n{settings}\nagents:\n{agents}" + ))?; + file.directory = self.root.path().to_owned(); + let mut values: Vec<_> = parent + .keys() + .map(|key| (key.to_owned(), parent.get(key).unwrap().to_owned())) + .collect(); + values.push(("OWNER".into(), self.owner.secret_key().to_secret_hex())); + Plan::build(&file, &[], &Env::from_iter(values)) + } +} + +#[test] +fn runtime_configuration_passes_through_without_a_second_provider_contract() { + let fixture = Fixture::new(); + let plan = fixture.plan( + " env:\n BUZZ_ACP_AGENT_COMMAND: custom-agent\n BUZZ_ACP_MCP_COMMAND: ''\n BUZZ_AGENT_PROVIDER: future-provider\n BUZZ_ACP_SYSTEM_PROMPT: ' preserve spaces '\n API_CREDENTIAL: {env: CREDENTIAL}", + " - name: helper", &Env::from_iter([("CREDENTIAL", "test-value")]), + ).expect("plan"); + let env = &plan.agents[0].env; + assert_eq!(env["BUZZ_ACP_AGENT_COMMAND"], "custom-agent"); + assert_eq!(env["BUZZ_ACP_MCP_COMMAND"], ""); + assert_eq!(env["BUZZ_AGENT_PROVIDER"], "future-provider"); + assert_eq!(env["BUZZ_ACP_SYSTEM_PROMPT"], " preserve spaces "); + assert_eq!(env["API_CREDENTIAL"], "test-value"); + assert!( + fixture + .plan("", " - name: helper", &Env::default()) + .is_ok(), + "runtime, not swarm, validates provider configuration" + ); +} + +#[test] +fn inherited_identity_and_acp_policy_are_removed_but_provider_env_is_inherited() { + let fixture = Fixture::new(); + let plan = fixture + .plan( + "", + " - name: helper\n - name: sibling\n enabled: false\n nsec: {env: SIBLING}", + &Env::from_iter([ + ("SIBLING", "other-key"), + ("BUZZ_ACP_RESPOND_TO", "anyone"), + ("BUZZ_API_TOKEN", "stale-token"), + ("BUZZ_AGENT_PROVIDER", "anthropic"), + ]), + ) + .expect("plan"); + let agent = &plan.agents[0]; + for key in ["OWNER", "SIBLING", "BUZZ_ACP_RESPOND_TO", "BUZZ_API_TOKEN"] { + assert!( + agent.env_remove.iter().any(|removed| removed == key), + "{key}" + ); + } + assert!(!agent + .env_remove + .iter() + .any(|key| key == "BUZZ_AGENT_PROVIDER")); + assert_eq!( + agent.env["BUZZ_PRIVATE_KEY"], + agent.env["NOSTR_PRIVATE_KEY"] + ); + assert_eq!(agent.env["BUZZ_ACP_AGENT_COMMAND"], "buzz-agent"); + let agent_keys = Keys::parse(&agent.env["BUZZ_PRIVATE_KEY"]).expect("agent key"); + assert_ne!(fixture.owner.public_key(), agent_keys.public_key()); + assert_eq!( + buzz_sdk::nip_oa::verify_auth_tag(&agent.env["BUZZ_AUTH_TAG"], &agent_keys.public_key()) + .expect("tag"), + fixture.owner.public_key() + ); +} + +#[test] +fn env_cannot_override_identity_sources_or_use_invalid_names() { + let fixture = Fixture::new(); + for key in RESERVED.iter().copied().chain(["OWNER", "BAD=KEY", "1BAD"]) { + let error = fixture + .plan( + &format!(" env:\n '{key}': forbidden"), + " - name: helper", + &Env::default(), + ) + .err() + .expect("invalid env rejected"); + assert!(format!("{error:#}").contains(key), "{key}"); + } +} + +#[test] +fn one_identity_is_reused_on_every_relay() { + let fixture = Fixture::new(); + let plan = fixture + .plan( + "", + " - name: helper\n relays: [one.example, two.example, three.example]", + &Env::default(), + ) + .expect("plan"); + assert_eq!(plan.generated_keys.len(), 1); + assert_eq!(plan.agents.len(), 3); + for connection in &plan.agents { + assert_eq!( + connection.env["BUZZ_AUTH_TAG"], + plan.agents[0].env["BUZZ_AUTH_TAG"] + ); + assert_eq!(connection.pubkey, plan.agents[0].pubkey); + } + assert_eq!( + plan.agents + .iter() + .map(|agent| &agent.relay_url) + .collect::>() + .len(), + 3 + ); +} + +#[test] +fn duplicate_connections_and_names_are_rejected() { + let fixture = Fixture::new(); + for agents in [ + " - name: helper\n relays: [https://relay.example, wss://relay.example/]", + " - name: helper\n - name: HELPER", + " - name: helper\n relays: [ws://localhost:3000, ws://127.0.0.1:3000]", + ] { + assert!(fixture.plan("", agents, &Env::default()).is_err()); + } +} + +#[test] +fn file_credentials_resolve_relative_to_the_config_directory() { + let fixture = Fixture::new(); + std::fs::write(fixture.root.path().join("credential"), "test-value\n").expect("credential"); + let plan = fixture + .plan( + " env:\n API_CREDENTIAL: {file: credential}", + " - name: helper", + &Env::default(), + ) + .expect("plan"); + assert_eq!(plan.agents[0].env["API_CREDENTIAL"], "test-value"); + assert_eq!(plan.agents[0].workdir, fixture.root.path()); + assert_eq!( + format!("{:?}", SecretRef::Literal("hidden".into())), + "SecretRef()" + ); +} + +#[test] +fn relay_urls_normalize_without_losing_paths() { + for (input, want) in [ + ("https://buzz.example.com", "wss://buzz.example.com"), + ("https://buzz.example.com/", "wss://buzz.example.com"), + ("http://localhost:3000", "ws://localhost:3000"), + ("buzz.example.com", "wss://buzz.example.com"), + ("wss://buzz.example.com", "wss://buzz.example.com"), + ("ws://localhost:3000/", "ws://localhost:3000"), + ( + "https://buzz.example.com/team/", + "wss://buzz.example.com/team/", + ), + ( + "https://buzz.example.com/?community=one", + "wss://buzz.example.com/?community=one", + ), + ] { + assert_eq!(relay_url(input).expect(input), want); + } + for bad in [ + "", + " ", + "ftp://buzz.example.com", + "https://", + "wss://user:pass@relay.example", + "wss://relay.example/#part", + ] { + assert!(relay_url(bad).is_err(), "{bad} should be rejected"); + } +} diff --git a/crates/buzz-swarm/src/supervisor.rs b/crates/buzz-swarm/src/supervisor.rs new file mode 100644 index 0000000000..70ba9d631b --- /dev/null +++ b/crates/buzz-swarm/src/supervisor.rs @@ -0,0 +1,289 @@ +//! Run one harness per connection and stop its process group before reaping it. + +use std::io; +use std::process::Stdio; +use std::time::{Duration, Instant}; + +use anyhow::{Context, Result}; +use rustix::process::{kill_process_group, waitid, Pid, Signal, WaitId, WaitIdOptions}; +use tokio::process::{Child, Command}; +use tokio::sync::watch; +use tokio::task::JoinSet; +use tokio::time::sleep; + +use crate::config::Restart; +use crate::plan::{AgentPlan, Plan}; + +const HEALTHY_UPTIME: Duration = Duration::from_secs(60); +const BACKOFF_CAP: Duration = Duration::from_secs(60); +const RUN: u8 = 0; +const DRAIN: u8 = 1; +const KILL: u8 = 2; + +/// Final result for one agent/relay connection. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Outcome { + Completed, + Stopped, + GaveUp { status: String }, + SpawnFailed { error: String }, +} + +/// Outcomes after all connections have ended. +#[derive(Debug)] +pub struct Summary { + pub outcomes: Vec<(String, Outcome)>, +} + +impl Summary { + /// Clean exits and requested shutdowns are successful. + pub fn failed(&self) -> bool { + self.outcomes.iter().any(|(_, outcome)| { + matches!( + outcome, + Outcome::GaveUp { .. } | Outcome::SpawnFailed { .. } + ) + }) + } +} + +/// Process shutdown settings shared by all connections. +#[derive(Debug, Clone, Copy)] +pub struct Options { + /// Time allowed after SIGTERM before SIGKILL. + pub grace: Duration, +} + +/// First signal requests a graceful stop; a second forces every group to exit. +pub async fn run(plan: Plan, options: Options) -> Result { + // Install handlers before spawning anything. + let mut interrupt = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())?; + let mut terminate = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())?; + let (tx, rx) = watch::channel(RUN); + let mut tasks = JoinSet::new(); + for agent in plan.agents { + tasks.spawn(supervise(agent, rx.clone(), options)); + } + let mut outcomes = Vec::with_capacity(tasks.len()); + while !tasks.is_empty() { + tokio::select! { + task = tasks.join_next() => { + if let Some(task) = task { + outcomes.push(task.context("agent supervisor task failed")?); + } + } + _ = interrupt.recv() => { tx.send_modify(|state| *state = (*state + 1).min(KILL)); } + _ = terminate.recv() => { tx.send_modify(|state| *state = (*state + 1).min(KILL)); } + } + } + Ok(Summary { outcomes }) +} + +async fn supervise( + plan: AgentPlan, + mut shutdown: watch::Receiver, + options: Options, +) -> (String, Outcome) { + let mut strikes = 0; + loop { + if *shutdown.borrow() != RUN { + return (plan.name, Outcome::Stopped); + } + let started = Instant::now(); + let mut child = match spawn(&plan) { + Ok(child) => child, + Err(error) => { + return ( + plan.name, + Outcome::SpawnFailed { + error: error.to_string(), + }, + ); + } + }; + let Some(pid) = child + .id() + .and_then(|pid| i32::try_from(pid).ok()) + .and_then(Pid::from_raw) + else { + return ( + plan.name, + Outcome::SpawnFailed { + error: "spawned child has no PID".into(), + }, + ); + }; + let mut group = ProcessGroup(Some(pid)); + let mut interrupted = false; + let exited = tokio::select! { + status = exited(pid) => status, + _ = wait_for(&mut shutdown, DRAIN) => { + interrupted = true; + terminate(pid, &mut shutdown, options.grace).await + } + }; + // A waitable leader reserves the PID until cleanup, so it cannot be + // recycled into an unrelated group between exit and kill. + let cleanup = group.kill(); + let status = match exited.and(cleanup) { + Ok(()) => child.wait().await, + Err(error) => Err(error), + }; + let status = match status { + Ok(_) if interrupted || *shutdown.borrow() != RUN => { + return (plan.name, Outcome::Stopped); + } + Ok(status) => status, + Err(error) => { + return ( + plan.name, + Outcome::GaveUp { + status: error.to_string(), + }, + ); + } + }; + if started.elapsed() >= HEALTHY_UPTIME { + strikes = 0; + } + match decide(plan.restart, status.success(), strikes, plan.max_restarts) { + Next::Stop => { + let outcome = if status.success() { + Outcome::Completed + } else { + Outcome::GaveUp { + status: status.to_string(), + } + }; + return (plan.name, outcome); + } + Next::Restart(delay) => { + strikes += 1; + tokio::select! { + _ = sleep(delay) => {} + _ = wait_for(&mut shutdown, DRAIN) => return (plan.name, Outcome::Stopped), + } + } + } + } +} + +fn spawn(plan: &AgentPlan) -> io::Result { + let mut command = Command::new(&plan.program); + command + .args(&plan.args) + .current_dir(&plan.workdir) + .stdin(Stdio::null()) + .stdout(Stdio::inherit()) + .stderr(Stdio::inherit()) + .kill_on_drop(true) + .process_group(0); + for key in &plan.env_remove { + command.env_remove(key); + } + command.envs(&plan.env).spawn() +} + +/// Observe exit without reaping; ProcessGroup owns the cleanup boundary. +async fn exited(pid: Pid) -> io::Result<()> { + let mut signal = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::child())?; + loop { + match waitid( + WaitId::Pid(pid), + WaitIdOptions::EXITED | WaitIdOptions::NOHANG | WaitIdOptions::NOWAIT, + ) { + Ok(Some(_)) => return Ok(()), + Ok(None) => { + signal.recv().await; + } + Err(rustix::io::Errno::INTR) => continue, + Err(error) => return Err(error.into()), + } + } +} + +async fn terminate( + pid: Pid, + shutdown: &mut watch::Receiver, + grace: Duration, +) -> io::Result<()> { + signal_group(pid, Signal::TERM)?; + tokio::select! { + status = exited(pid) => status, + _ = sleep(grace) => Ok(()), + _ = wait_for(shutdown, KILL) => Ok(()), + } +} + +struct ProcessGroup(Option); + +impl ProcessGroup { + fn kill(&mut self) -> io::Result<()> { + if let Some(pid) = self.0 { + signal_group(pid, Signal::KILL)?; + self.0 = None; + } + Ok(()) + } +} + +impl Drop for ProcessGroup { + fn drop(&mut self) { + // Task cancellation and unwinding must also kill the group, before + // dropping the Child lets Tokio reap its leader. + let _ = self.kill(); + } +} + +fn signal_group(pid: Pid, signal: Signal) -> io::Result<()> { + match kill_process_group(pid, signal) { + Ok(()) | Err(rustix::io::Errno::SRCH) => Ok(()), + // Darwin reports EPERM for a group containing only its zombie leader. + #[cfg(target_os = "macos")] + Err(rustix::io::Errno::PERM) + if waitid( + WaitId::Pid(pid), + WaitIdOptions::EXITED | WaitIdOptions::NOHANG | WaitIdOptions::NOWAIT, + ) + .is_ok_and(|status| status.is_some()) => + { + Ok(()) + } + Err(error) => Err(error.into()), + } +} + +async fn wait_for(rx: &mut watch::Receiver, level: u8) { + loop { + if *rx.borrow() >= level { + return; + } + if rx.changed().await.is_err() { + std::future::pending::<()>().await; + } + } +} + +#[derive(Debug, PartialEq, Eq)] +enum Next { + Restart(Duration), + Stop, +} + +fn decide(policy: Restart, success: bool, strikes: u32, max_restarts: u32) -> Next { + match policy { + Restart::Never => Next::Stop, + Restart::OnFailure if success => Next::Stop, + _ if strikes >= max_restarts => Next::Stop, + _ => Next::Restart(backoff(strikes)), + } +} + +fn backoff(strikes: u32) -> Duration { + BACKOFF_CAP.min(Duration::from_secs( + 1u64.checked_shl(strikes).unwrap_or(u64::MAX), + )) +} + +#[cfg(test)] +mod tests; diff --git a/crates/buzz-swarm/src/supervisor/tests.rs b/crates/buzz-swarm/src/supervisor/tests.rs new file mode 100644 index 0000000000..346d34b1a4 --- /dev/null +++ b/crates/buzz-swarm/src/supervisor/tests.rs @@ -0,0 +1,344 @@ +use super::*; +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::atomic::{AtomicU32, Ordering}; + +static COUNTER: AtomicU32 = AtomicU32::new(0); + +fn temp_path(tag: &str) -> PathBuf { + let n = COUNTER.fetch_add(1, Ordering::Relaxed); + std::env::temp_dir().join(format!("buzz-swarm-{tag}-{}-{n}", std::process::id())) +} + +fn shell_plan(name: &str, script: &str, restart: Restart, max_restarts: u32) -> AgentPlan { + AgentPlan { + name: name.to_owned(), + pubkey: "ab".repeat(32), + relay_url: "wss://buzz.example.com".to_owned(), + program: PathBuf::from("/bin/sh"), + args: vec!["-c".to_owned(), script.to_owned()], + workdir: std::env::temp_dir(), + env: BTreeMap::new(), + env_remove: Vec::new(), + restart, + max_restarts, + } +} + +async fn run_one(plan: AgentPlan, shutdown: watch::Receiver) -> (String, Outcome) { + supervise( + plan, + shutdown, + Options { + grace: Duration::from_secs(2), + }, + ) + .await +} + +#[test] +fn restart_policy_covers_every_combination() { + // (policy, success, strikes, max) -> restart? + let cases = [ + (Restart::Never, true, 0, 10, false), + (Restart::Never, false, 0, 10, false), + (Restart::OnFailure, true, 0, 10, false), + (Restart::OnFailure, false, 0, 10, true), + (Restart::OnFailure, false, 9, 10, true), + (Restart::OnFailure, false, 10, 10, false), + (Restart::OnFailure, false, 0, 0, false), + (Restart::Always, true, 0, 10, true), + (Restart::Always, false, 0, 10, true), + (Restart::Always, true, 10, 10, false), + ]; + for (policy, success, strikes, max, wants_restart) in cases { + let decision = decide(policy, success, strikes, max); + assert_eq!( + matches!(decision, Next::Restart(_)), + wants_restart, + "{policy:?} success={success} strikes={strikes} max={max}" + ); + } +} + +#[test] +fn backoff_grows_and_is_capped() { + assert_eq!(backoff(0), Duration::from_secs(1)); + assert_eq!(backoff(1), Duration::from_secs(2)); + assert_eq!(backoff(5), Duration::from_secs(32)); + assert_eq!(backoff(6), BACKOFF_CAP); + // No overflow panic for an absurd strike count. + assert_eq!(backoff(4_000), BACKOFF_CAP); +} + +#[tokio::test] +async fn a_clean_exit_is_not_restarted() { + let marker = temp_path("clean"); + let script = format!("echo run >> {}; exit 0", marker.display()); + let (_tx, rx) = watch::channel(RUN); + let (name, outcome) = run_one(shell_plan("clean", &script, Restart::OnFailure, 5), rx).await; + + assert_eq!(name, "clean"); + assert_eq!(outcome, Outcome::Completed); + let runs = std::fs::read_to_string(&marker).expect("marker"); + assert_eq!(runs.lines().count(), 1, "a clean exit must not be retried"); + let _ = std::fs::remove_file(&marker); +} + +#[tokio::test] +async fn failures_are_retried_up_to_the_budget_then_reported() { + let marker = temp_path("fail"); + let script = format!("echo run >> {}; exit 3", marker.display()); + let (_tx, rx) = watch::channel(RUN); + let (_, outcome) = run_one(shell_plan("fail", &script, Restart::OnFailure, 1), rx).await; + + assert_eq!( + outcome, + Outcome::GaveUp { + status: "exit status: 3".to_owned() + } + ); + let runs = std::fs::read_to_string(&marker).expect("marker"); + assert_eq!( + runs.lines().count(), + 2, + "expected the original run plus one restart" + ); + let _ = std::fs::remove_file(&marker); +} + +#[tokio::test] +async fn shutdown_reaps_the_whole_process_group() { + let pidfile = temp_path("group"); + // The shell backgrounds a grandchild in the same process group and waits. + let script = format!("sleep 30 & echo $! > {}; wait", pidfile.display()); + let (tx, rx) = watch::channel(RUN); + let supervised = tokio::spawn(run_one( + shell_plan("group", &script, Restart::Always, 5), + rx, + )); + + let grandchild = tokio::time::timeout(Duration::from_secs(5), async { + loop { + if let Ok(text) = std::fs::read_to_string(&pidfile) { + if let Ok(pid) = text.trim().parse::() { + break pid; + } + } + sleep(Duration::from_millis(20)).await; + } + }) + .await + .expect("grandchild did not start"); + assert!(is_alive(grandchild), "grandchild should be running"); + + tx.send(DRAIN).expect("signal shutdown"); + let (_, outcome) = tokio::time::timeout(Duration::from_secs(10), supervised) + .await + .expect("supervisor did not stop within the grace period") + .expect("task"); + assert_eq!( + outcome, + Outcome::Stopped, + "restart: always must not survive shutdown" + ); + + let deadline = Instant::now() + Duration::from_secs(5); + while is_alive(grandchild) && Instant::now() < deadline { + sleep(Duration::from_millis(20)).await; + } + assert!(!is_alive(grandchild), "grandchild was orphaned by shutdown"); + let _ = std::fs::remove_file(&pidfile); +} + +#[tokio::test] +async fn a_leader_exit_cleans_up_its_descendants() { + let scratch = tempfile::tempdir().expect("tempdir"); + let pidfile = scratch.path().join("child.pid"); + let script = format!("sleep 30 & echo $! > '{}'; exit 0", pidfile.display()); + let (_tx, rx) = watch::channel(RUN); + let (_, outcome) = tokio::time::timeout( + Duration::from_secs(5), + run_one(shell_plan("orphan", &script, Restart::Never, 0), rx), + ) + .await + .expect("supervisor hung after leader exited"); + assert_eq!(outcome, Outcome::Completed); + let pid = std::fs::read_to_string(pidfile) + .expect("pidfile") + .trim() + .parse() + .expect("pid"); + let deadline = Instant::now() + Duration::from_secs(3); + while is_alive(pid) && Instant::now() < deadline { + sleep(Duration::from_millis(20)).await; + } + assert!(!is_alive(pid), "surviving descendant"); +} + +#[tokio::test] +async fn shutdown_kills_a_descendant_that_ignores_sigterm_after_its_leader_exits() { + let scratch = tempfile::tempdir().expect("tempdir"); + let pidfile = scratch.path().join("child.pid"); + let script = format!( + "trap 'exit 0' TERM; (trap '' TERM; exec sleep 30) & echo $! > '{}'; wait", + pidfile.display() + ); + let (tx, rx) = watch::channel(RUN); + let task = tokio::spawn(run_one( + shell_plan("stubborn", &script, Restart::Never, 0), + rx, + )); + let pid = tokio::time::timeout(Duration::from_secs(5), async { + loop { + if let Ok(value) = std::fs::read_to_string(&pidfile) { + if let Ok(pid) = value.trim().parse::() { + break pid; + } + } + sleep(Duration::from_millis(20)).await; + } + }) + .await + .expect("child did not start"); + tx.send(DRAIN).expect("signal"); + let (_, outcome) = tokio::time::timeout(Duration::from_secs(5), task) + .await + .expect("hung") + .expect("task"); + assert_eq!(outcome, Outcome::Stopped); + let deadline = Instant::now() + Duration::from_secs(3); + while is_alive(pid) && Instant::now() < deadline { + sleep(Duration::from_millis(20)).await; + } + assert!(!is_alive(pid), "SIGTERM-ignoring descendant survived"); +} + +#[tokio::test] +async fn a_missing_binary_fails_the_agent_without_retrying() { + let mut plan = shell_plan("ghost", "exit 0", Restart::Always, 5); + plan.program = PathBuf::from("/nonexistent/buzz-acp"); + let (_tx, rx) = watch::channel(RUN); + let (_, outcome) = run_one(plan, rx).await; + assert!(matches!(outcome, Outcome::SpawnFailed { .. })); +} + +#[tokio::test] +async fn agents_are_not_started_when_shutdown_arrives_first() { + let (tx, rx) = watch::channel(RUN); + tx.send(DRAIN).expect("shutdown"); + let marker = temp_path("never"); + let script = format!("echo run >> {}", marker.display()); + let (_, outcome) = run_one(shell_plan("never", &script, Restart::Always, 5), rx).await; + assert_eq!(outcome, Outcome::Stopped); + assert!(!marker.exists(), "no process should have been spawned"); +} + +fn is_alive(pid: i32) -> bool { + Pid::from_raw(pid).is_some_and(|pid| rustix::process::test_kill_process(pid).is_ok()) +} + +#[test] +fn summary_fails_only_on_real_failures() { + let ok = Summary { + outcomes: vec![ + ("a".into(), Outcome::Completed), + ("b".into(), Outcome::Stopped), + ], + }; + assert!(!ok.failed()); + let bad = Summary { + outcomes: vec![( + "a".into(), + Outcome::GaveUp { + status: "with code 1".into(), + }, + )], + }; + assert!(bad.failed()); + let worse = Summary { + outcomes: vec![( + "a".into(), + Outcome::SpawnFailed { + error: "missing binary".into(), + }, + )], + }; + assert!(worse.failed()); +} + +async fn child_pid(path: &std::path::Path) -> i32 { + tokio::time::timeout(Duration::from_secs(5), async { + loop { + if let Ok(contents) = std::fs::read_to_string(path) { + if let Ok(pid) = contents.trim().parse() { + return pid; + } + } + sleep(Duration::from_millis(20)).await; + } + }) + .await + .expect("child did not start") +} + +async fn assert_stopped(pid: i32) { + tokio::time::timeout(Duration::from_secs(3), async { + while is_alive(pid) { + sleep(Duration::from_millis(20)).await; + } + }) + .await + .expect("descendant survived cleanup"); +} + +#[tokio::test] +async fn cancellation_kills_the_owned_process_group() { + let scratch = tempfile::tempdir().expect("tempdir"); + let pidfile = scratch.path().join("child.pid"); + let script = format!("sleep 30 & echo $! > '{}'; wait", pidfile.display()); + let (_tx, rx) = watch::channel(RUN); + let task = tokio::spawn(run_one( + shell_plan("cancelled", &script, Restart::Never, 0), + rx, + )); + let pid = child_pid(&pidfile).await; + task.abort(); + assert!(task.await.expect_err("cancelled task").is_cancelled()); + assert_stopped(pid).await; +} + +#[tokio::test] +async fn grace_expiry_and_second_signal_force_a_stubborn_group_to_exit() { + for force in [false, true] { + let scratch = tempfile::tempdir().expect("tempdir"); + let pidfile = scratch.path().join("child.pid"); + let script = format!( + "trap '' TERM; sleep 30 & echo $! > '{}'; wait", + pidfile.display() + ); + let (tx, rx) = watch::channel(RUN); + let task = tokio::spawn(supervise( + shell_plan("stubborn", &script, Restart::Always, 5), + rx, + Options { + grace: if force { + Duration::from_secs(30) + } else { + Duration::from_millis(50) + }, + }, + )); + let pid = child_pid(&pidfile).await; + tx.send(DRAIN).expect("request graceful stop"); + if force { + tx.send(KILL).expect("force stop"); + } + let (_, outcome) = tokio::time::timeout(Duration::from_secs(2), task) + .await + .expect("group did not stop") + .expect("supervisor task"); + assert_eq!(outcome, Outcome::Stopped); + assert_stopped(pid).await; + } +} diff --git a/crates/buzz-swarm/tests/cli.rs b/crates/buzz-swarm/tests/cli.rs new file mode 100644 index 0000000000..adcf2a7cb5 --- /dev/null +++ b/crates/buzz-swarm/tests/cli.rs @@ -0,0 +1,238 @@ +#![cfg(unix)] + +use std::fs; +use std::os::unix::ffi::OsStringExt; +use std::os::unix::fs::PermissionsExt; +use std::process::{Command, Output}; + +use nostr::{Keys, ToBech32}; +use tempfile::TempDir; + +/// Exercise the shipped CLI and real child processes without contacting a +/// community or model provider. The harness records only test identities. +struct Fixture { + root: TempDir, + owner: Keys, +} + +impl Fixture { + fn new() -> Self { + let root = tempfile::tempdir().expect("tempdir"); + let script = root.path().join("harness"); + fs::write(&script, r#"#!/bin/sh +set -eu +test -z "${OWNER_SOURCE+x}" +test -z "${OTHER_AGENT_SOURCE+x}" +test -z "${BUZZ_ACP_HEARTBEAT_PROMPT+x}" +test "$BUZZ_ACP_SYSTEM_PROMPT_FILE" = "persona.txt" +test -f "$BUZZ_ACP_SYSTEM_PROMPT_FILE" +test -z "$BUZZ_ACP_MCP_COMMAND" +printf '%s\n%s\n%s\n' "$BUZZ_PRIVATE_KEY" "$BUZZ_AUTH_TAG" "$BUZZ_RELAY_URL" > "launch-${BUZZ_RELAY_URL##*/}" +"#).expect("harness"); + fs::set_permissions(script, fs::Permissions::from_mode(0o755)).expect("chmod"); + fs::write(root.path().join("persona.txt"), "Test agent").expect("persona"); + Self { + root, + owner: Keys::generate(), + } + } + + fn write_config(&self, agents: &str) { + fs::write( + self.root.path().join("swarm.yaml"), + format!( + r#" +owner: + nsec: {{env: OWNER_SOURCE}} +defaults: + relays: [https://one.example, wss://two.example] + harness: ./harness + env: + BUZZ_ACP_AGENT_COMMAND: /usr/bin/true + BUZZ_ACP_MCP_COMMAND: "" + BUZZ_ACP_SYSTEM_PROMPT_FILE: persona.txt +agents: +{agents} +"# + ), + ) + .expect("config"); + } + + fn command(&self) -> Command { + let mut command = Command::new(env!("CARGO_BIN_EXE_buzz-swarm")); + command + .current_dir(std::env::temp_dir()) + .env_clear() + .env("PATH", "/usr/bin:/bin") + .env( + "OWNER_SOURCE", + self.owner.secret_key().to_bech32().expect("nsec"), + ) + .env("OTHER_AGENT_SOURCE", "must-not-reach-the-child") + .env( + "BUZZ_ACP_HEARTBEAT_PROMPT", + std::ffi::OsString::from_vec(vec![0xff]), + ) + // A non-UTF-8 ambient variable must not panic environment capture. + .env("NON_UTF8", std::ffi::OsString::from_vec(vec![0xff])) + .arg("--config") + .arg(self.root.path().join("swarm.yaml")); + command + } + + fn run(&self, args: &[&str]) -> Output { + let output = self.command().args(args).output().expect("run swarm"); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + output + } +} + +#[test] +fn starts_from_another_directory_and_reuses_one_identity_across_relays_and_restarts() { + let fixture = Fixture::new(); + fixture.write_config(" - name: helper\n - name: disabled\n enabled: false\n nsec: {env: OTHER_AGENT_SOURCE}"); + let preview = fixture.run(&["validate"]); + assert!(String::from_utf8_lossy(&preview.stdout).contains("created on start")); + assert!( + !fixture.root.path().join("keys").exists(), + "validation wrote keys" + ); + assert!( + !fixture.root.path().join("launch-one.example").exists(), + "validation launched a harness" + ); + + fixture.run(&[]); + let key_file = fixture.root.path().join("keys/helper.nsec"); + let persisted = fs::read_to_string(&key_file).expect("persisted key"); + assert_eq!( + fs::metadata(&key_file) + .expect("metadata") + .permissions() + .mode() + & 0o777, + 0o600 + ); + let keys = Keys::parse(persisted.trim()).expect("agent key"); + let first = + fs::read_to_string(fixture.root.path().join("launch-one.example")).expect("first launch"); + let second = + fs::read_to_string(fixture.root.path().join("launch-two.example")).expect("second launch"); + let first: Vec<_> = first.lines().collect(); + let second: Vec<_> = second.lines().collect(); + assert!( + first[0] == persisted.trim() && first[0] == second[0], + "identities differ" + ); + assert_eq!(first[1], second[1], "relays received different auth tags"); + assert_ne!(first[2], second[2]); + assert_eq!( + buzz_sdk::nip_oa::verify_auth_tag(first[1], &keys.public_key()).expect("tag"), + fixture.owner.public_key() + ); + + fixture.run(&[]); + assert!( + fs::read_to_string(key_file).expect("key after restart") == persisted, + "identity changed on restart" + ); +} + +#[test] +fn accepts_a_presigned_tag_without_the_owner_key() { + let fixture = Fixture::new(); + let agent = Keys::generate(); + let tag = + buzz_sdk::nip_oa::compute_auth_tag(&fixture.owner, &agent.public_key(), "").expect("tag"); + fixture.write_config( + " - name: helper\n nsec: {file: supplied.nsec}\n auth_tag: {file: auth.json}", + ); + fs::write( + fixture.root.path().join("supplied.nsec"), + agent.secret_key().to_bech32().expect("nsec"), + ) + .expect("key"); + fs::write(fixture.root.path().join("auth.json"), tag).expect("tag file"); + let path = fixture.root.path().join("swarm.yaml"); + let config = fs::read_to_string(&path) + .expect("config") + .replace("owner:\n nsec: {env: OWNER_SOURCE}\n", ""); + fs::write(path, config).expect("without owner"); + let output = fixture + .command() + .env_remove("OWNER_SOURCE") + .env_remove("OTHER_AGENT_SOURCE") + .output() + .expect("run"); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(!fixture.root.path().join("keys").exists()); +} + +#[test] +fn invalid_launches_start_nothing_and_persist_no_keys() { + for agents in [ + " - name: helper\n relays: [https://one.example, wss://one.example/]", + " - name: helper\n - name: other\n harness: /missing/harness", + " - name: ../outside", + " - name: helper\n relays: []", + ] { + let fixture = Fixture::new(); + fixture.write_config(agents); + let output = fixture.command().output().expect("run"); + assert!(!output.status.success(), "invalid configuration succeeded"); + assert!(!fixture.root.path().join("keys").exists()); + assert!(!fixture.root.path().join("launch-one.example").exists()); + } +} + +#[test] +fn unknown_selection_and_mismatched_delegation_fail_closed() { + let fixture = Fixture::new(); + fixture.write_config(" - name: helper"); + let output = fixture + .command() + .args(["--only", "helper,typo", "validate"]) + .output() + .expect("run"); + assert!(!output.status.success()); + assert!(String::from_utf8_lossy(&output.stderr).contains("typo")); + + let agent = Keys::generate(); + let stranger = Keys::generate(); + let tag = buzz_sdk::nip_oa::compute_auth_tag(&fixture.owner, &stranger.public_key(), "") + .expect("tag"); + fixture.write_config( + " - name: helper\n nsec: {file: supplied.nsec}\n auth_tag: {file: auth.json}", + ); + fs::write( + fixture.root.path().join("supplied.nsec"), + agent.secret_key().to_bech32().expect("nsec"), + ) + .expect("key"); + fs::write(fixture.root.path().join("auth.json"), tag).expect("tag file"); + assert!(!fixture.command().output().expect("run").status.success()); + assert!(!fixture.root.path().join("launch-one.example").exists()); +} + +#[test] +fn an_expired_delegation_fails_before_launch() { + let fixture = Fixture::new(); + fixture.write_config(" - name: helper"); + let path = fixture.root.path().join("swarm.yaml"); + let config = fs::read_to_string(&path) + .expect("read") + .replace("owner:\n", "owner:\n conditions: created_at<1\n"); + fs::write(path, config).expect("write"); + assert!(!fixture.command().output().expect("run").status.success()); + assert!(!fixture.root.path().join("keys").exists()); + assert!(!fixture.root.path().join("launch-one.example").exists()); +} diff --git a/crates/buzz-swarm/tests/shutdown.rs b/crates/buzz-swarm/tests/shutdown.rs new file mode 100644 index 0000000000..524ef87d0f --- /dev/null +++ b/crates/buzz-swarm/tests/shutdown.rs @@ -0,0 +1,114 @@ +#![cfg(unix)] + +use std::fs; +use std::os::unix::fs::PermissionsExt; +use std::path::PathBuf; +use std::process::{Child, Command, Stdio}; +use std::thread::sleep; +use std::time::{Duration, Instant}; + +use nostr::{Keys, ToBech32}; +use rustix::process::{kill_process, kill_process_group, test_kill_process, Pid, Signal}; + +// Always clean up the real processes, including when an assertion fails. +struct Running { + swarm: Child, + pid_file: PathBuf, +} + +impl Running { + fn harness_pid(&self) -> Option { + fs::read_to_string(&self.pid_file) + .ok()? + .trim() + .parse::() + .ok() + .and_then(Pid::from_raw) + } +} + +impl Drop for Running { + fn drop(&mut self) { + if let Some(pid) = self.harness_pid() { + let _ = kill_process_group(pid, Signal::KILL); + } + let _ = self.swarm.kill(); + let _ = self.swarm.wait(); + } +} + +#[test] +fn blocked_stdout_does_not_prevent_shutdown_or_orphan_the_harness() { + let directory = tempfile::tempdir().expect("temporary directory"); + let harness = directory.path().join("harness"); + fs::write( + &harness, + "#!/bin/sh\ntrap '' TERM\necho $$ > harness.pid\nwhile :; do printf '%08000d\\n' 0; done\n", + ) + .expect("fixture harness"); + fs::set_permissions(&harness, fs::Permissions::from_mode(0o700)).expect("executable"); + let config = directory.path().join("swarm.yaml"); + fs::write( + &config, + "owner:\n nsec: {env: TEST_OWNER}\ndefaults:\n relays: [wss://relay.example.com]\n harness: ./harness\nagents:\n - name: noisy\n", + ) + .expect("swarm config"); + let swarm = Command::new(env!("CARGO_BIN_EXE_buzz-swarm")) + .env_clear() + .env("PATH", "/usr/bin:/bin") + .env( + "TEST_OWNER", + Keys::generate() + .secret_key() + .to_bech32() + .expect("owner key"), + ) + .args([ + "--config", + config.to_str().expect("config path"), + "start", + "--grace", + "1", + ]) + // Keep stdout open but never read it. The fixture quickly fills the + // pipe and blocks; Swarm still has to supervise and kill it on time. + .stdout(Stdio::piped()) + .stderr(Stdio::null()) + .spawn() + .expect("start swarm"); + let mut running = Running { + swarm, + pid_file: directory.path().join("harness.pid"), + }; + let startup_deadline = Instant::now() + Duration::from_secs(5); + let harness_pid = loop { + if let Some(pid) = running.harness_pid() { + break pid; + } + assert!(Instant::now() < startup_deadline, "harness did not start"); + assert!(running.swarm.try_wait().expect("poll startup").is_none()); + sleep(Duration::from_millis(10)); + }; + // The PID is written before output begins. Let even a slow fixture fill + // the OS pipe; the original log multiplexer hung during writer drain. + sleep(Duration::from_millis(300)); + let swarm_pid = Pid::from_raw(i32::try_from(running.swarm.id()).expect("swarm PID")) + .expect("nonzero swarm PID"); + kill_process(swarm_pid, Signal::TERM).expect("request shutdown"); + let deadline = Instant::now() + Duration::from_secs(5); + let status = loop { + if let Some(status) = running.swarm.try_wait().expect("poll shutdown") { + break status; + } + assert!(Instant::now() < deadline, "Swarm hung with blocked stdout"); + sleep(Duration::from_millis(10)); + }; + assert!(status.success(), "shutdown failed: {status}"); + assert_eq!( + test_kill_process(harness_pid), + Err(rustix::io::Errno::SRCH), + "Swarm exited but its harness survived" + ); + // The harness is reaped. Do not signal its former PID during cleanup. + fs::remove_file(&running.pid_file).expect("remove PID record"); +}