feat: Markdown-based persona packs (crate + ACP + desktop) (#297)

Author: tlongwell-block

Cargo.lock

@@ -17,6 +17,7 @@ members = [
     "crates/sprout-media",
     "crates/sprout-cli",
     "crates/sprout-sdk",
+    "crates/sprout-persona",
 ]
 exclude = ["desktop/src-tauri"]
 resolver = "2"

Cargo.toml

@@ -15,6 +15,7 @@ path = "src/main.rs"
 # Internal
 sprout-core = { workspace = true }
 sprout-sdk = { workspace = true }
+sprout-persona = { path = "../sprout-persona" }
 
 # Nostr
 nostr = { workspace = true }

crates/sprout-acp/Cargo.toml

@@ -174,7 +174,11 @@ impl AcpClient {
     /// Spawn the agent binary as a subprocess and connect to its stdio pipes.
     ///
     /// After spawning, call [`initialize`](Self::initialize) before any other method.
-    pub async fn spawn(command: &str, args: &[String]) -> Result<Self, AcpError> {
+    pub async fn spawn(
+        command: &str,
+        args: &[String],
+        extra_env: &[(String, String)],
+    ) -> Result<Self, AcpError> {
         use std::process::Stdio;
 
         let mut cmd = tokio::process::Command::new(command);
@@ -187,6 +191,14 @@ impl AcpClient {
             // Callers MUST still call shutdown().await for guaranteed cleanup.
             .kill_on_drop(true);
 
+        // Per-persona env vars (e.g., GOOSE_PROVIDER, GOOSE_MODEL).
+        // Only injected if not already set in parent env (operator precedence).
+        for (key, value) in extra_env {
+            if std::env::var(key).is_err() {
+                cmd.env(key, value);
+            }
+        }
+
         // Spawn the agent in its own process group so SIGKILL doesn't propagate
         // to the harness's own process group on Unix.
         // tokio::process::Command::process_group is a stable tokio API (no extra imports needed).
@@ -1614,7 +1626,7 @@ mod tests {
     // ── Async integration tests with real subprocess ──────────────────────
 
     async fn spawn_script(script: &str) -> AcpClient {
-        AcpClient::spawn("bash", &["-c".into(), script.into()])
+        AcpClient::spawn("bash", &["-c".into(), script.into()], &[])
             .await
             .expect("failed to spawn test script")
     }

crates/sprout-acp/src/acp.rs

@@ -349,6 +349,15 @@ pub struct CliArgs {
     /// Owner pubkey is always implicitly included.
     #[arg(long, env = "SPROUT_ACP_RESPOND_TO_ALLOWLIST", value_delimiter = ',')]
     pub respond_to_allowlist: Option<Vec<String>>,
+
+    /// Path to a persona pack directory. Used with --persona-name to configure
+    /// the agent from a .persona.md pack instead of CLI flags.
+    #[arg(long, env = "SPROUT_ACP_PERSONA_PACK")]
+    pub persona_pack: Option<PathBuf>,
+
+    /// Name of the persona within the pack to use. Required when --persona-pack is set.
+    #[arg(long, env = "SPROUT_ACP_PERSONA_NAME")]
+    pub persona_name: Option<String>,
 }
 
 // ── Merged NIP-01 filter ──────────────────────────────────────────────────────
@@ -400,6 +409,9 @@ pub struct Config {
     pub respond_to: RespondTo,
     /// Validated allowlist of pubkey hex strings (used when respond_to == Allowlist).
     pub respond_to_allowlist: HashSet<String>,
+    /// Per-persona env vars to inject at agent spawn time (e.g., GOOSE_PROVIDER, GOOSE_MODEL).
+    /// Populated from persona pack resolution. Empty when no pack is configured.
+    pub persona_env_vars: Vec<(String, String)>,
 }
 
 /// Validate and deduplicate allowlist entries: each must be exactly 64 hex chars.
@@ -507,7 +519,7 @@ impl Config {
             .replace_range(.., &"0".repeat(args.private_key.len()));
         args.private_key.clear();
 
-        let system_prompt = if let Some(text) = args.system_prompt {
+        let mut system_prompt = if let Some(text) = args.system_prompt {
             Some(text)
         } else if let Some(ref path) = args.system_prompt_file {
             Some(std::fs::read_to_string(path)?)
@@ -642,6 +654,54 @@ impl Config {
             HashSet::new()
         };
 
+        // ── Persona pack resolution ──────────────────────────────────────────
+        //
+        // Precedence: CLI/env args > persona values > built-in defaults.
+        // Persona fills in what's missing. Explicit flags always win.
+        let (persona_system_prompt, persona_model, persona_env_vars) =
+            match (&args.persona_pack, &args.persona_name) {
+                (Some(pack_dir), Some(name)) => {
+                    let pack = sprout_persona::resolve::resolve_pack(pack_dir).map_err(|e| {
+                        ConfigError::ConfigFile(format!(
+                            "failed to resolve pack {}: {e}",
+                            pack_dir.display()
+                        ))
+                    })?;
+                    let persona = pack
+                        .personas
+                        .into_iter()
+                        .find(|p| p.name == *name)
+                        .ok_or_else(|| {
+                            ConfigError::ConfigFile(format!(
+                                "persona '{name}' not found in pack {}",
+                                pack_dir.display()
+                            ))
+                        })?;
+                    (
+                        Some(persona.system_prompt),
+                        persona.model,
+                        persona.goose_env_vars,
+                    )
+                }
+                (Some(_), None) => {
+                    return Err(ConfigError::ConfigFile(
+                        "--persona-pack requires --persona-name".into(),
+                    ));
+                }
+                (None, Some(_)) => {
+                    return Err(ConfigError::ConfigFile(
+                        "--persona-name requires --persona-pack".into(),
+                    ));
+                }
+                (None, None) => (None, None, vec![]),
+            };
+
+        // Apply persona defaults: CLI/env wins, persona fills gaps.
+        if system_prompt.is_none() {
+            system_prompt = persona_system_prompt;
+        }
+        let model = args.model.or(persona_model);
+
         // ── Multiple-event-handling validation ──────────────────────────────
         if matches!(
             args.multiple_event_handling,
@@ -682,10 +742,11 @@ impl Config {
             max_turns_per_session: args.max_turns_per_session,
             presence_enabled: !args.no_presence,
             typing_enabled: !args.no_typing,
-            model: args.model,
+            model,
             permission_mode: args.permission_mode,
             respond_to: args.respond_to,
             respond_to_allowlist,
+            persona_env_vars,
         };
 
         Ok(config)
@@ -1045,6 +1106,7 @@ mod tests {
             permission_mode: PermissionMode::BypassPermissions,
             respond_to: RespondTo::Anyone,
             respond_to_allowlist: HashSet::new(),
+            persona_env_vars: vec![],
         }
     }
 

crates/sprout-acp/src/config.rs

@@ -541,7 +541,12 @@ async fn tokio_main() -> Result<()> {
         // This matches the run_models pattern and prevents zombie leaks on
         // init timeout (the cancelled future would drop the AcpClient via
         // Drop which is best-effort only).
-        let spawn_result = AcpClient::spawn(&config.agent_command, &config.agent_args).await;
+        let spawn_result = AcpClient::spawn(
+            &config.agent_command,
+            &config.agent_args,
+            &config.persona_env_vars,
+        )
+        .await;
         match spawn_result {
             Ok(mut acp) => {
                 match tokio::time::timeout(Duration::from_secs(60), acp.initialize()).await {
@@ -912,9 +917,10 @@ async fn tokio_main() -> Result<()> {
                 tracing::info!(agent = idx, "slot refill: spawning background respawn");
                 let cmd = config.agent_command.clone();
                 let args = config.agent_args.clone();
+                let env = config.persona_env_vars.clone();
                 let guard = RespawnGuard::new(idx, respawn_tx.clone());
                 respawn_tasks.spawn(async move {
-                    let result = spawn_and_init(&cmd, &args).await;
+                    let result = spawn_and_init(&cmd, &args, &env).await;
                     guard.send(result);
                 });
             }
@@ -1837,12 +1843,13 @@ fn recover_panicked_agent(
     slot.respawn_in_flight = true;
     let cmd = config.agent_command.clone();
     let args = config.agent_args.clone();
+    let env = config.persona_env_vars.clone();
     let guard = RespawnGuard::new(i, respawn_tx.clone());
     respawn_tasks.spawn(async move {
         if !delay.is_zero() {
             tokio::time::sleep(delay).await;
         }
-        let result = spawn_and_init(&cmd, &args).await;
+        let result = spawn_and_init(&cmd, &args, &env).await;
         guard.send(result);
     });
 }
@@ -1983,6 +1990,7 @@ fn spawn_respawn_task(
     // Spawn the actual work (shutdown + sleep + spawn + init) off the main loop.
     let cmd = config.agent_command.clone();
     let args = config.agent_args.clone();
+    let env = config.persona_env_vars.clone();
     let guard = RespawnGuard::new(index, respawn_tx.clone());
     respawn_tasks.spawn(async move {
         // Shutdown old agent (reap child, prevent zombie).
@@ -1994,7 +2002,7 @@ fn spawn_respawn_task(
             tokio::time::sleep(delay).await;
         }
 
-        let result = spawn_and_init(&cmd, &args).await;
+        let result = spawn_and_init(&cmd, &args, &env).await;
         guard.send(result);
     });
 
@@ -2007,8 +2015,12 @@ fn spawn_respawn_task(
 ///
 /// Takes owned args so it can run in a background `tokio::spawn` task without
 /// borrowing `Config`. All respawn/refill paths use this.
-async fn spawn_and_init(command: &str, args: &[String]) -> Result<AcpClient> {
-    let mut acp = AcpClient::spawn(command, args)
+async fn spawn_and_init(
+    command: &str,
+    args: &[String],
+    extra_env: &[(String, String)],
+) -> Result<AcpClient> {
+    let mut acp = AcpClient::spawn(command, args, extra_env)
         .await
         .map_err(|e| anyhow::anyhow!("failed to spawn agent: {e}"))?;
 
@@ -2045,7 +2057,8 @@ async fn run_models(args: ModelsArgs) -> Result<()> {
         .to_string();
 
     // Spawn outside the timeout so we always own the child for cleanup.
-    let mut client = match AcpClient::spawn(&args.agent_command, &agent_args).await {
+    // `models` subcommand doesn't use persona packs — no extra env.
+    let mut client = match AcpClient::spawn(&args.agent_command, &agent_args, &[]).await {
         Ok(c) => c,
         Err(e) => {
             eprintln!("error: failed to spawn agent: {e}");

crates/sprout-acp/src/main.rs

@@ -42,3 +42,6 @@ base64 = "0.22"
 
 # SHA-256 — NIP-98 payload hash tag
 sha2 = "0.11"
+
+# Persona pack parsing, validation, and resolution
+sprout-persona = { path = "../sprout-persona" }

crates/sprout-cli/Cargo.toml

@@ -3,6 +3,7 @@ pub mod channels;
 pub mod dms;
 pub mod feed;
 pub mod messages;
+pub mod pack;
 pub mod reactions;
 pub mod social;
 pub mod users;