mirror of
https://github.com/block/buzz.git
synced 2026-11-15 22:02:04 +00:00
feat: add portable multi-relay buzz-swarm runner
Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
This commit is contained in:
1
.github/workflows/_ci-rust.yml
vendored
1
.github/workflows/_ci-rust.yml
vendored
@@ -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
2
.gitignore
vendored
@@ -61,6 +61,8 @@ doc/
|
||||
/repos/
|
||||
|
||||
# Local identity files
|
||||
*.nsec
|
||||
/buzz-swarm.yaml
|
||||
identity.key
|
||||
**/identity.key
|
||||
|
||||
|
||||
@@ -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
18
Cargo.lock
generated
@@ -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"
|
||||
|
||||
@@ -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",
|
||||
|
||||
2
Justfile
2
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)
|
||||
|
||||
@@ -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
|
||||
|
||||
26
crates/buzz-swarm/Cargo.toml
Normal file
26
crates/buzz-swarm/Cargo.toml
Normal 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
135
crates/buzz-swarm/README.md
Normal 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.
|
||||
29
crates/buzz-swarm/buzz-swarm.example.yaml
Normal file
29
crates/buzz-swarm/buzz-swarm.example.yaml
Normal 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.
|
||||
94
crates/buzz-swarm/src/cli.rs
Normal file
94
crates/buzz-swarm/src/cli.rs
Normal 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())
|
||||
}
|
||||
}
|
||||
}
|
||||
344
crates/buzz-swarm/src/config.rs
Normal file
344
crates/buzz-swarm/src/config.rs
Normal 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;
|
||||
168
crates/buzz-swarm/src/config/tests.rs
Normal file
168
crates/buzz-swarm/src/config/tests.rs
Normal 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")
|
||||
);
|
||||
}
|
||||
45
crates/buzz-swarm/src/env.rs
Normal file
45
crates/buzz-swarm/src/env.rs
Normal 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(),
|
||||
}
|
||||
}
|
||||
}
|
||||
114
crates/buzz-swarm/src/identity.rs
Normal file
114
crates/buzz-swarm/src/identity.rs
Normal 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(())
|
||||
}
|
||||
27
crates/buzz-swarm/src/main.rs
Normal file
27
crates/buzz-swarm/src/main.rs
Normal 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
|
||||
}
|
||||
250
crates/buzz-swarm/src/plan.rs
Normal file
250
crates/buzz-swarm/src/plan.rs
Normal 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;
|
||||
198
crates/buzz-swarm/src/plan/tests.rs
Normal file
198
crates/buzz-swarm/src/plan/tests.rs
Normal 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");
|
||||
}
|
||||
}
|
||||
289
crates/buzz-swarm/src/supervisor.rs
Normal file
289
crates/buzz-swarm/src/supervisor.rs
Normal 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;
|
||||
344
crates/buzz-swarm/src/supervisor/tests.rs
Normal file
344
crates/buzz-swarm/src/supervisor/tests.rs
Normal 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;
|
||||
}
|
||||
}
|
||||
238
crates/buzz-swarm/tests/cli.rs
Normal file
238
crates/buzz-swarm/tests/cli.rs
Normal 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());
|
||||
}
|
||||
114
crates/buzz-swarm/tests/shutdown.rs
Normal file
114
crates/buzz-swarm/tests/shutdown.rs
Normal 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");
|
||||
}
|
||||
Reference in New Issue
Block a user