feat: add portable multi-relay buzz-swarm runner

Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
This commit is contained in:
Tyler Longwell
2026-09-23 12:16:17 -04:00
parent fa00e61f0e
commit ce6763cc3a
22 changed files with 2444 additions and 0 deletions

View File

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

2
.gitignore vendored
View File

@@ -61,6 +61,8 @@ doc/
/repos/
# Local identity files
*.nsec
/buzz-swarm.yaml
identity.key
**/identity.key

View File

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

18
Cargo.lock generated
View File

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

View File

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

View File

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

View File

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

View File

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

135
crates/buzz-swarm/README.md Normal file
View File

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

View File

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

View File

@@ -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<String>,
#[command(subcommand)]
command: Option<Command>,
}
#[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<bool> {
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())
}
}
}

View File

@@ -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<Owner>,
/// 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<Value>,
}
/// 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(<redacted>)")
}
}
/// Keep source errors actionable without echoing secret values.
impl<'de> Deserialize<'de> for SecretRef {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
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<E: serde::de::Error>(self, value: &str) -> Result<Self::Value, E> {
Ok(SecretRef::Literal(value.to_owned()))
}
fn visit_map<M: serde::de::MapAccess<'de>>(self, mut map: M) -> Result<Self::Value, M::Error> {
let mut source: Option<SecretRef> = None;
while let Some(key) = map.next_key::<String>()? {
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<Secret> {
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<String>);
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(<redacted>)")
}
}
/// 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<String>,
pub nsec: Option<SecretRef>,
/// Pre-signed NIP-OA tag for this identity; avoids sending the owner key
/// to the machine running the swarm.
pub auth_tag: Option<SecretRef>,
pub enabled: Option<bool>,
pub relays: Option<Vec<String>>,
pub workdir: Option<PathBuf>,
pub harness: Option<String>,
pub restart: Option<Restart>,
pub max_restarts: Option<u32>,
/// Extra environment for the harness and everything below it. Keys the
/// swarm owns are rejected.
#[serde(default)]
pub env: BTreeMap<String, SecretRef>,
}
/// 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<Self> {
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<Self> {
serde_yaml::from_str(text).context("parsing swarm file")
}
pub fn owner(&self, env: &Env) -> Option<Owner> {
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<Vec<Spec>> {
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<Vec<Spec>> {
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;

View File

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

View File

@@ -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<String, Option<String>>,
}
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<Item = &str> {
self.vars.keys().map(String::as_str)
}
}
impl<K: Into<String>, V: Into<String>> FromIterator<(K, V)> for Env {
fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
Self {
vars: iter
.into_iter()
.map(|(k, v)| (k.into(), Some(v.into())))
.collect(),
}
}
}

View File

@@ -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<GeneratedKey>,
}
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<Self> {
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(())
}

View File

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

View File

@@ -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<String>,
pub workdir: PathBuf,
pub env: BTreeMap<String, String>,
pub env_remove: Vec<String>,
pub restart: Restart,
pub max_restarts: u32,
}
pub struct Plan {
pub owner_pubkey: String,
pub agents: Vec<AgentPlan>,
pub generated_keys: Vec<GeneratedKey>,
}
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<Self> {
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<PathBuf> {
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<String> {
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;

View File

@@ -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<Plan> {
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::<BTreeSet<_>>()
.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(<redacted>)"
);
}
#[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");
}
}

View File

@@ -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<Summary> {
// 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<u8>,
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<Child> {
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<u8>,
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<Pid>);
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<u8>, 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;

View File

@@ -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<u8>) -> (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::<i32>() {
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::<i32>() {
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;
}
}

View File

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

View File

@@ -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<Pid> {
fs::read_to_string(&self.pid_file)
.ok()?
.trim()
.parse::<i32>()
.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");
}