feat(yopo): add yopo binary crate and simplify example

nikomatsakis · claude · nikomatsakis · commit f5a23f76cece · 2025-11-04T19:47:24.000-05:00
Create a new 'yopo' (You Only Prompt Once) binary crate that provides
a full-featured ACP client supporting both command strings and JSON
configurations. This crate can use sacp-tokio without circular dependency
issues.

Simplify the yolo_one_shot_client example to:
- Use clap for argument parsing
- Only support simple command strings (not JSON configs)
- Point users to the yopo crate for full features

This gives us both a useful utility (yopo) and a cleaner educational
example (yolo_one_shot_client).

Co-authored-by: Claude &lt;claude@anthropic.com&gt;
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -5,7 +5,7 @@ members = [
     "src/sacp",
     "src/sacp-tokio",
     "src/elizacp",
-    "src/sacp-test",
+    "src/sacp-test", "src/yopo",
 ]
 resolver = "2"
 
diff --git a/src/sacp/Cargo.toml b/src/sacp/Cargo.toml
@@ -21,6 +21,7 @@ tracing.workspace = true
 uuid.workspace = true
 
 [dev-dependencies]
+clap = { workspace = true, features = ["derive"] }
 expect-test.workspace = true
 shell-words = "1.1"
 tokio = { workspace = true, features = ["macros", "rt-multi-thread", "io-util", "time", "process"] }
diff --git a/src/sacp/examples/yolo_one_shot_client.rs b/src/sacp/examples/yolo_one_shot_client.rs
@@ -1,74 +1,54 @@
 //! YOLO one-shot client: A simple ACP client that runs a single prompt against an agent.
 //!
-//! This client:
-//! - Takes a prompt and agent configuration as arguments
-//! - Spawns the agent
-//! - Sends the prompt
-//! - Auto-approves all permission requests
-//! - Prints all session updates to stdout
-//! - Runs until the agent completes
+//! This is a simplified example showing basic ACP client usage. It only supports
+//! simple command strings (not JSON configs or environment variables).
 //!
-//! # Usage
+//! For a more full-featured client with JSON config support, see the `yopo` binary crate.
 //!
-//! With a command:
-//! ```bash
-//! cargo run --example yolo_one_shot_client -- "What is 2+2?" "python my_agent.py"
-//! ```
+//! # Usage
 //!
-//! With JSON config:
 //! ```bash
-//! cargo run --example yolo_one_shot_client -- "Hello!" '{"type":"stdio","name":"my-agent","command":"python","args":["agent.py"],"env":[]}'
+//! cargo run --example yolo_one_shot_client -- --command "python my_agent.py" "What is 2+2?"
 //! ```
 
+use clap::Parser;
 use sacp::JrConnection;
 use sacp::schema::{
-    ContentBlock, InitializeRequest, McpServer, NewSessionRequest, PromptRequest,
-    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse,
-    SessionNotification, TextContent, VERSION as PROTOCOL_VERSION,
+    ContentBlock, InitializeRequest, NewSessionRequest, PromptRequest, RequestPermissionOutcome,
+    RequestPermissionRequest, RequestPermissionResponse, SessionNotification, TextContent,
+    VERSION as PROTOCOL_VERSION,
 };
 use std::path::PathBuf;
 use tokio::process::Child;
 use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
 
-// NOTE: This code is inlined here to avoid a circular dependency between `sacp` and `sacp-tokio`.
-// If you're writing your own client, you can use `sacp_tokio::AcpAgent` and `JrConnectionExt::to_agent()`
-// to simplify this setup significantly.
-
-/// Parse agent configuration from either a command string or JSON.
-fn parse_agent_config(s: &str) -> Result<McpServer, Box<dyn std::error::Error>> {
-    let trimmed = s.trim();
+#[derive(Parser)]
+#[command(name = "yolo-one-shot-client")]
+#[command(about = "A simple ACP client for one-shot prompts", long_about = None)]
+struct Cli {
+    /// The command to run the agent (e.g., "python my_agent.py")
+    #[arg(short, long)]
+    command: String,
 
-    // If it starts with '{', try to parse as JSON
-    if trimmed.starts_with('{') {
-        let server: McpServer = serde_json::from_str(trimmed)?;
-        return Ok(server);
-    }
+    /// The prompt to send to the agent
+    prompt: String,
+}
 
-    // Otherwise, parse as a command string
-    let parts = shell_words::split(trimmed)?;
+/// Parse a command string into command and args
+fn parse_command_string(s: &str) -> Result<(PathBuf, Vec<String>), Box<dyn std::error::Error>> {
+    let parts = shell_words::split(s)?;
     if parts.is_empty() {
         return Err("Command string cannot be empty".into());
     }
-
     let command = PathBuf::from(&parts[0]);
     let args = parts[1..].to_vec();
-    let name = command
-        .file_name()
-        .and_then(|n| n.to_str())
-        .unwrap_or("agent")
-        .to_string();
-
-    Ok(McpServer::Stdio {
-        name,
-        command,
-        args,
-        env: vec![],
-    })
+    Ok((command, args))
 }
 
 /// Spawn a process for the agent and get stdio streams.
 fn spawn_agent_process(
-    server: &McpServer,
+    command: PathBuf,
+    args: Vec<String>,
 ) -> Result<
     (
         tokio::process::ChildStdin,
@@ -77,64 +57,31 @@ fn spawn_agent_process(
     ),
     Box<dyn std::error::Error>,
 > {
-    match server {
-        McpServer::Stdio {
-            command,
-            args,
-            env,
-            name: _,
-        } => {
-            let mut cmd = tokio::process::Command::new(command);
-            cmd.args(args);
-            for env_var in env {
-                cmd.env(&env_var.name, &env_var.value);
-            }
-            cmd.stdin(std::process::Stdio::piped())
-                .stdout(std::process::Stdio::piped());
+    let mut cmd = tokio::process::Command::new(&command);
+    cmd.args(&args);
+    cmd.stdin(std::process::Stdio::piped())
+        .stdout(std::process::Stdio::piped());
 
-            let mut child = cmd.spawn()?;
-            let child_stdin = child.stdin.take().ok_or("Failed to open stdin")?;
-            let child_stdout = child.stdout.take().ok_or("Failed to open stdout")?;
+    let mut child = cmd.spawn()?;
+    let child_stdin = child.stdin.take().ok_or("Failed to open stdin")?;
+    let child_stdout = child.stdout.take().ok_or("Failed to open stdout")?;
 
-            Ok((child_stdin, child_stdout, child))
-        }
-        McpServer::Http { .. } => Err("HTTP transport not yet supported".into()),
-        McpServer::Sse { .. } => Err("SSE transport not yet supported".into()),
-    }
+    Ok((child_stdin, child_stdout, child))
 }
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Parse command line arguments
-    let args: Vec<String> = std::env::args().collect();
-    if args.len() != 3 {
-        eprintln!("Usage: {} <prompt> <agent-config>", args[0]);
-        eprintln!();
-        eprintln!("  <prompt>       - The prompt to send to the agent");
-        eprintln!("  <agent-config> - Either a command string or JSON (starting with '{{')");
-        eprintln!();
-        eprintln!("Examples:");
-        eprintln!("  {} \"What is 2+2?\" \"python my_agent.py\"", args[0]);
-        eprintln!(
-            "  {} \"Hello!\" '{{\"type\":\"stdio\",\"name\":\"agent\",\"command\":\"python\",\"args\":[\"agent.py\"],\"env\":[]}}'",
-            args[0]
-        );
-        std::process::exit(1);
-    }
-
-    let prompt = &args[1];
-    let agent_config = &args[2];
+    let cli = Cli::parse();
 
-    // Parse the agent configuration
-    let server = parse_agent_config(agent_config)?;
+    // Parse the command string
+    let (command, args) = parse_command_string(&cli.command)?;
 
-    eprintln!("🚀 Spawning agent and connecting...");
+    eprintln!("🚀 Spawning agent: {} {:?}", command.display(), args);
 
     // Spawn the agent process
-    let (child_stdin, child_stdout, mut child) = spawn_agent_process(&server)?;
+    let (child_stdin, child_stdout, mut child) = spawn_agent_process(command, args)?;
 
     // Create a JrConnection with the agent's stdio streams
-    // NOTE: Using sacp_tokio::JrConnectionExt::to_agent() would simplify this setup
     let connection = JrConnection::new(child_stdin.compat_write(), child_stdout.compat());
 
     // Run the client
@@ -192,12 +139,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             eprintln!("✓ Session created: {}", session_id);
 
             // Send the prompt
-            eprintln!("💬 Sending prompt: \"{}\"", prompt);
+            eprintln!("💬 Sending prompt: \"{}\"", cli.prompt);
             let prompt_response = cx
                 .send_request(PromptRequest {
                     session_id: session_id.clone(),
                     prompt: vec![ContentBlock::Text(TextContent {
-                        text: prompt.to_string(),
+                        text: cli.prompt.clone(),
                         annotations: None,
                         meta: None,
                     })],
diff --git a/src/yopo/Cargo.toml b/src/yopo/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "yopo"
+version = "1.0.0-alpha"
+edition = "2024"
+description = "YOPO (You Only Prompt Once) - A simple ACP client for one-shot prompts"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/symposium-dev/symposium-acp"
+
+[dependencies]
+sacp = { version = "1.0.0-alpha", path = "../sacp" }
+sacp-tokio = { version = "1.0.0-alpha", path = "../sacp-tokio" }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
diff --git a/src/yopo/src/main.rs b/src/yopo/src/main.rs
@@ -0,0 +1,137 @@
+//! YOPO (You Only Prompt Once) - A simple ACP client for one-shot prompts
+//!
+//! This client:
+//! - Takes a prompt and agent configuration as arguments
+//! - Spawns the agent
+//! - Sends the prompt
+//! - Auto-approves all permission requests
+//! - Prints all session updates to stdout
+//! - Runs until the agent completes
+//!
+//! # Usage
+//!
+//! With a command:
+//! ```bash
+//! yopo "What is 2+2?" "python my_agent.py"
+//! ```
+//!
+//! With JSON config:
+//! ```bash
+//! yopo "Hello!" '{"type":"stdio","name":"my-agent","command":"python","args":["agent.py"],"env":[]}'
+//! ```
+
+use sacp::JrConnection;
+use sacp::schema::{
+    ContentBlock, InitializeRequest, NewSessionRequest, PromptRequest, RequestPermissionOutcome,
+    RequestPermissionRequest, RequestPermissionResponse, SessionNotification, TextContent,
+    VERSION as PROTOCOL_VERSION,
+};
+use sacp_tokio::{AcpAgent, JrConnectionExt};
+use std::path::PathBuf;
+use std::str::FromStr;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Parse command line arguments
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() != 3 {
+        eprintln!("Usage: {} <prompt> <agent-config>", args[0]);
+        eprintln!();
+        eprintln!("  <prompt>       - The prompt to send to the agent");
+        eprintln!("  <agent-config> - Either a command string or JSON (starting with '{{')");
+        eprintln!();
+        eprintln!("Examples:");
+        eprintln!("  {} \"What is 2+2?\" \"python my_agent.py\"", args[0]);
+        eprintln!(
+            "  {} \"Hello!\" '{{\"type\":\"stdio\",\"name\":\"agent\",\"command\":\"python\",\"args\":[\"agent.py\"],\"env\":[]}}'",
+            args[0]
+        );
+        std::process::exit(1);
+    }
+
+    let prompt = &args[1];
+    let agent_config = &args[2];
+
+    // Parse the agent configuration
+    let agent = AcpAgent::from_str(agent_config)?;
+
+    eprintln!("🚀 Spawning agent and connecting...");
+
+    // Run the client
+    JrConnection::to_agent(agent)?
+        .on_receive_notification(async move |notification: SessionNotification, _cx| {
+            // Print session updates to stdout (so 2>/dev/null shows only agent output)
+            println!("{:?}", notification.update);
+            Ok(())
+        })
+        .on_receive_request(async move |request: RequestPermissionRequest, request_cx| {
+            // YOPO: Auto-approve all permission requests by selecting the first option
+            eprintln!("✅ Auto-approving permission request: {:?}", request);
+            let option_id = request.options.first().map(|opt| opt.id.clone());
+            match option_id {
+                Some(id) => request_cx.respond(RequestPermissionResponse {
+                    outcome: RequestPermissionOutcome::Selected { option_id: id },
+                    meta: None,
+                }),
+                None => {
+                    eprintln!("⚠️ No options provided in permission request, cancelling");
+                    request_cx.respond(RequestPermissionResponse {
+                        outcome: RequestPermissionOutcome::Cancelled,
+                        meta: None,
+                    })
+                }
+            }
+        })
+        .with_client(|cx: sacp::JrConnectionCx| async move {
+            // Initialize the agent
+            eprintln!("🤝 Initializing agent...");
+            let init_response = cx
+                .send_request(InitializeRequest {
+                    protocol_version: PROTOCOL_VERSION,
+                    client_capabilities: Default::default(),
+                    client_info: Default::default(),
+                    meta: None,
+                })
+                .block_task()
+                .await?;
+
+            eprintln!("✓ Agent initialized: {:?}", init_response.agent_info);
+
+            // Create a new session
+            eprintln!("📝 Creating new session...");
+            let new_session_response = cx
+                .send_request(NewSessionRequest {
+                    mcp_servers: vec![],
+                    cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from("/")),
+                    meta: None,
+                })
+                .block_task()
+                .await?;
+
+            let session_id = new_session_response.session_id;
+            eprintln!("✓ Session created: {}", session_id);
+
+            // Send the prompt
+            eprintln!("💬 Sending prompt: \"{}\"", prompt);
+            let prompt_response = cx
+                .send_request(PromptRequest {
+                    session_id: session_id.clone(),
+                    prompt: vec![ContentBlock::Text(TextContent {
+                        text: prompt.to_string(),
+                        annotations: None,
+                        meta: None,
+                    })],
+                    meta: None,
+                })
+                .block_task()
+                .await?;
+
+            eprintln!("✅ Agent completed!");
+            eprintln!("Stop reason: {:?}", prompt_response.stop_reason);
+
+            Ok(())
+        })
+        .await?;
+
+    Ok(())
+}

Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@ members = [`
`5`	`5`	`"src/sacp",`
`6`	`6`	`"src/sacp-tokio",`
`7`	`7`	`"src/elizacp",`
`8`		`- "src/sacp-test",`
	`8`	`+ "src/sacp-test", "src/yopo",`
`9`	`9`	`]`
`10`	`10`	`resolver = "2"`
`11`	`11`