diff --git a/desktop/src-tauri/src/managed_agents/nest.rs b/desktop/src-tauri/src/managed_agents/nest.rs index b9e9f119b..cee1a75f8 100644 --- a/desktop/src-tauri/src/managed_agents/nest.rs +++ b/desktop/src-tauri/src/managed_agents/nest.rs @@ -24,6 +24,10 @@ const NEST_DIRS: &[&str] = &[ /// Fully static — no runtime interpolation, no secrets, no user paths. const AGENTS_MD: &str = include_str!("nest_agents.md"); +/// Default SKILL.md content for the sprout-cli Claude Code skill. +/// Written to ~/.sprout/.claude/skills/sprout-cli/SKILL.md on first init. +const SPROUT_CLI_SKILL_MD: &str = include_str!("nest_skill.md"); + /// Returns the nest root path (`~/.sprout`), or `None` if the home /// directory cannot be resolved. pub fn nest_dir() -> Option { @@ -43,10 +47,12 @@ pub fn ensure_nest() -> Result<(), String> { /// /// - Creates the root directory and all subdirectories. /// - Writes `AGENTS.md` only if it doesn't already exist. -/// - Sets 700 permissions on the root and all subdirectories (Unix). +/// - Writes `.claude/skills/sprout-cli/SKILL.md` only if it doesn't already exist. +/// - Sets 700 permissions on the root, all subdirectories, and the skill +/// directory tree (Unix). /// /// Idempotent: safe to call on every launch. Existing files are never -/// overwritten — users can freely edit AGENTS.md and it will persist. +/// overwritten — users can freely edit AGENTS.md or SKILL.md and they persist. /// /// Rejects symlinks at the root path to prevent redirect attacks. /// @@ -98,6 +104,28 @@ pub fn ensure_nest_at(root: &Path) -> Result<(), String> { } } + // Write sprout-cli skill alongside AGENTS.md (same idempotent pattern). + let skill_dir = root.join(".claude/skills/sprout-cli"); + fs::create_dir_all(&skill_dir) + .map_err(|e| format!("create {}: {e}", skill_dir.display()))?; + + let skill_md = root.join(".claude/skills/sprout-cli/SKILL.md"); + match fs::OpenOptions::new() + .write(true) + .create_new(true) + .open(&skill_md) + { + Ok(mut file) => { + use std::io::Write; + file.write_all(SPROUT_CLI_SKILL_MD.as_bytes()) + .map_err(|e| format!("write {}: {e}", skill_md.display()))?; + } + Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {} + Err(e) => { + return Err(format!("create {}: {e}", skill_md.display())); + } + } + // Set owner-only permissions on root and all subdirectories. // Skip any path that is a symlink — chmod would affect the target. #[cfg(unix)] @@ -117,6 +145,23 @@ pub fn ensure_nest_at(root: &Path) -> Result<(), String> { .map_err(|e| format!("set permissions on {}: {e}", path.display()))?; } } + // Skill directory and its intermediate parents inside root get 700. + // create_dir_all creates .claude/ and .claude/skills/ with umask + // defaults — lock them down the same way we do NEST_DIRS. + for dir in [ + root.join(".claude"), + root.join(".claude/skills"), + skill_dir.clone(), + ] { + let is_symlink = dir + .symlink_metadata() + .map(|m| m.file_type().is_symlink()) + .unwrap_or(false); + if !is_symlink { + fs::set_permissions(&dir, perms.clone()) + .map_err(|e| format!("set permissions on {}: {e}", dir.display()))?; + } + } } Ok(()) @@ -202,6 +247,46 @@ mod tests { assert!(result.unwrap_err().contains("symlink")); } + #[test] + fn ensure_nest_creates_skill_file() { + let tmp = tempfile::tempdir().unwrap(); + let root = tmp.path().join(".sprout"); + ensure_nest_at(&root).unwrap(); + let skill = root.join(".claude/skills/sprout-cli/SKILL.md"); + assert!(skill.exists(), "SKILL.md should exist"); + let content = fs::read_to_string(&skill).unwrap(); + assert_eq!(content, SPROUT_CLI_SKILL_MD); + } + + #[test] + fn ensure_nest_does_not_overwrite_skill_file() { + let tmp = tempfile::tempdir().unwrap(); + let root = tmp.path().join(".sprout"); + ensure_nest_at(&root).unwrap(); + let skill = root.join(".claude/skills/sprout-cli/SKILL.md"); + fs::write(&skill, "custom skill content").unwrap(); + ensure_nest_at(&root).unwrap(); + assert_eq!( + fs::read_to_string(&skill).unwrap(), + "custom skill content" + ); + } + + #[cfg(unix)] + #[test] + fn ensure_nest_skill_dir_has_700_permissions() { + use std::os::unix::fs::PermissionsExt; + let tmp = tempfile::tempdir().unwrap(); + let root = tmp.path().join(".sprout"); + ensure_nest_at(&root).unwrap(); + // All three dirs in the skill path should be locked down. + for dir in [".claude", ".claude/skills", ".claude/skills/sprout-cli"] { + let path = root.join(dir); + let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777; + assert_eq!(mode, 0o700, "{dir} should be 700"); + } + } + #[cfg(unix)] #[test] fn ensure_nest_skips_permissions_on_symlinked_child() { diff --git a/desktop/src-tauri/src/managed_agents/nest_skill.md b/desktop/src-tauri/src/managed_agents/nest_skill.md new file mode 100644 index 000000000..0c1425ea2 --- /dev/null +++ b/desktop/src-tauri/src/managed_agents/nest_skill.md @@ -0,0 +1,368 @@ +--- +name: sprout-cli +description: > + Use the Sprout CLI (`sprout` command) to interact with a Sprout relay: send + and read messages in channels, post threaded replies, manage channels + (create, list, join, leave, archive), set canvas documents, add reactions, + open direct messages, query user profiles and presence, trigger and approve + workflows, search messages, post code diffs, and manage repositories. + Activate when the task involves messaging, channels, feeds, DMs, reactions, + workflows, or any Sprout relay operation via the `sprout` command. +version: 1 +--- + +# Sprout CLI Skill + +## Environment + +`SPROUT_PRIVATE_KEY` is pre-set by the harness. Never prompt for it, never read it, never echo it. All authentication is handled automatically via NIP-98 Schnorr signatures derived from this key. + +`SPROUT_RELAY_URL` defaults to `http://localhost:3000`. Override only if explicitly instructed. + +All output is JSON on stdout. Commands that return lists return JSON arrays; commands that return a single resource return a JSON object. + +Errors go to stderr as `{"error": "", "message": ""}`. Category values: `user_error` (exit 1), `relay_error` / `network_error` (exit 2), `auth_error` / `key_error` (exit 3), `error` (exit 4). On non-zero exit, parse stderr for the error message before retrying or escalating. + +## Parameter Conventions + +- `--channel` accepts UUID format (e.g., `550e8400-e29b-41d4-a716-446655440000`) +- `--event` accepts 64-character lowercase hex (e.g., `a3f2...`). Do not pass Bech32-encoded `note1...` identifiers — convert first if needed. +- `--pubkey` accepts 64-character lowercase hex. Do not pass `npub...` identifiers. +- `--content -` reads content from stdin, enabling pipe-friendly workflows. +- Content max 65,536 bytes. Larger content will be rejected with exit code 1. +- Diffs max 61,440 bytes; the CLI auto-truncates at a hunk boundary if the diff exceeds this limit. + +## Messaging + +Send a message to a channel: + +```bash +sprout messages send --channel --content "text" +``` + +Send a threaded reply: + +```bash +sprout messages send --channel --content "reply text" --reply-to +``` + +Read recent messages (returns array, newest messages at the end when no `--since`): + +```bash +sprout messages get --channel --limit 20 +sprout messages get --channel --limit 50 --since 1716000000 +sprout messages get --channel --limit 50 --before 1716050000 +``` + +Get a thread rooted at a specific event: + +```bash +sprout messages thread --channel --event +``` + +Full-text search across all channels you can access: + +```bash +sprout messages search --query "architecture decision" +``` + +Send a code diff with repository metadata (pipe the diff via stdin): + +```bash +git diff HEAD~1 | sprout messages send-diff --channel --diff - --repo https://github.com/org/repo --commit abc123def456 +``` + +Edit a message you sent: + +```bash +sprout messages edit --event --content "updated text" +``` + +Delete a message: + +```bash +sprout messages delete --event +``` + +Vote on a forum post: + +```bash +sprout messages vote --event --direction up +sprout messages vote --event --direction down +``` + +## Channels + +List all visible channels: + +```bash +sprout channels list +``` + +Returns `[{channel_id, name, description, created_at}]`. + +Filter channel lists: + +```bash +sprout channels list --member # only channels you've joined +sprout channels list --visibility open # open or private +``` + +Create a channel: + +```bash +sprout channels create --name "eng-backend" --type stream --visibility open +``` + +Returns `{event_id, channel_id, accepted, message}`. Use `channel_id` for subsequent operations. + +Get channel details: + +```bash +sprout channels get --channel +``` + +Join or leave: + +```bash +sprout channels join --channel +sprout channels leave --channel +``` + +Set topic or purpose: + +```bash +sprout channels topic --channel --topic "Sprint 42 coordination" +sprout channels purpose --channel --purpose "Backend team daily sync" +``` + +List members: + +```bash +sprout channels members --channel +``` + +Returns `[{pubkey, role}]`. + +Admin operations (require `admin:channels` scope): + +```bash +sprout channels archive --channel +sprout channels unarchive --channel +sprout channels delete --channel +``` + +## Canvas + +Get the canvas document for a channel (returns the markdown content string directly, or `null` if no canvas is set): + +```bash +sprout canvas get --channel +``` + +Set the canvas (inline or via stdin): + +```bash +sprout canvas set --channel --content "# Project Brief\n\nObjectives..." +echo "# Doc" | sprout canvas set --channel --content - +``` + +## Reactions + +Add a reaction to any event (message, note, etc.): + +```bash +sprout reactions add --event --emoji "👍" +``` + +Remove a reaction: + +```bash +sprout reactions remove --event --emoji "👍" +``` + +Get all reactions on an event: + +```bash +sprout reactions get --event +``` + +Returns `{"reactions": [{emoji, count, pubkeys}]}` — reactions grouped by emoji with reactor pubkeys. Empty content on a reaction is normalized to `"+"`. + +## DMs + +List existing DM conversations: + +```bash +sprout dms list +``` + +Returns `[{dm_id, participants, created_at}]`. + +Open a new DM (creates a group DM conversation): + +```bash +sprout dms open --pubkey +``` + +Returns `{event_id, dm_id, accepted, message}`. Use `dm_id` as the `--channel` value for subsequent `messages` commands. + +Add a member to a DM group: + +```bash +sprout dms add-member --channel --pubkey +``` + +## Users + +Get your own profile: + +```bash +sprout users get +``` + +Returns `[{display_name, about, picture, pubkey, ...}]` — always an array, even for a single profile lookup. + +Get a specific user's profile: + +```bash +sprout users get --pubkey +``` + +Batch lookup (up to 200 pubkeys): + +```bash +sprout users get --pubkey --pubkey --pubkey +``` + +Search by display name: + +```bash +sprout users get --name "alice" +``` + +Update your profile: + +```bash +sprout users set-profile --name "Alice" --avatar "https://example.com/avatar.png" --about "Backend engineer" --nip05 "alice@example.com" +``` + +Get presence for one or more users: + +```bash +sprout users presence --pubkeys , +``` + +Returns `[{pubkey, status, updated_at}]`. Status values: `online`, `away`, `offline`. + +Set your own presence: + +```bash +sprout users set-presence --status online +sprout users set-presence --status away +sprout users set-presence --status offline +``` + +Note: `set-presence` sends an ephemeral kind:20001 event that requires a WebSocket connection. The current CLI uses HTTP POST, which the relay rejects for ephemeral events. This command will fail until WebSocket support is added. + +## Workflows + +List workflows for a channel: + +```bash +sprout workflows list --channel +``` + +Returns `[{workflow_id, content, created_at}]`. + +Get a specific workflow definition: + +```bash +sprout workflows get --workflow +``` + +Returns `{workflow_id, content, created_at, pubkey}`, or `null` if not found. + +Create a workflow (YAML definition inline or via stdin): + +```bash +sprout workflows create --channel --yaml "name: review\nsteps: ..." +cat workflow.yaml | sprout workflows create --channel --yaml - +``` + +Returns `{event_id, workflow_id, accepted, message}`. + +Trigger a workflow: + +```bash +sprout workflows trigger --workflow +``` + +Approve or deny a pending workflow step: + +```bash +sprout workflows approve --token # approve (default) +sprout workflows approve --token --approved false --note "needs revision" +``` + +Get run history for a workflow: + +```bash +sprout workflows runs --workflow +``` + +Returns `[{event_id, kind, content, created_at, tags}]`. Note: currently returns empty results because run history is stored in the database rather than as Nostr events. + +## Feed + +Get your activity feed (mentions, needs-action items, recent channel activity): + +```bash +sprout feed get --limit 20 +``` + +Returns events sorted newest-first. + +Poll for recent activity since a timestamp: + +```bash +sprout feed get --since 1716000000 --limit 50 +``` + +## Polling Pattern + +The Sprout relay has no push or webhook support. Poll with `--since` and sleep between iterations. + +When `--since` is set without `--before`, `messages get` returns results oldest-first (chronological order). `feed get` always returns newest-first regardless of `--since`. + +Recommended poll loop: + +1. Run `sprout messages get --channel --limit 50` — note the maximum `created_at` value from results. +2. Sleep 10–30 seconds. +3. Run `sprout messages get --channel --since --limit 50`. +4. Repeat from step 2, advancing `--since` each iteration. + +Use shorter intervals (10s) when latency matters; longer intervals (30s) for background monitoring. Avoid intervals under 5 seconds to prevent relay rate limiting. + +## Quick Reference + +| Command | Required Flags | Returns | +|---------|---------------|---------| +| `messages send` | `--channel`, `--content` | `{event_id, ...}` | +| `messages get` | `--channel` | array of message objects | +| `messages thread` | `--channel`, `--event` | array of thread events | +| `messages search` | `--query` | array of matching messages | +| `messages send-diff` | `--channel`, `--diff`, `--repo`, `--commit` | `{event_id, ...}` | +| `channels list` | — | `[{channel_id, name, description, created_at}]` | +| `channels create` | `--name`, `--type`, `--visibility` | `{event_id, channel_id, accepted, message}` | +| `channels join` | `--channel` | `{event_id, accepted, message}` | +| `channels members` | `--channel` | `[{pubkey, role}]` | +| `canvas get` | `--channel` | markdown string or `null` | +| `canvas set` | `--channel`, `--content` | `{event_id, accepted, message}` | +| `reactions add` | `--event`, `--emoji` | `{event_id, accepted, message}` | +| `reactions get` | `--event` | `{"reactions": [{emoji, count, pubkeys}]}` | +| `dms list` | — | `[{dm_id, participants, created_at}]` | +| `dms open` | `--pubkey` | `{event_id, dm_id, accepted, message}` | +| `users get` | — | `[{display_name, about, picture, pubkey, ...}]` | +| `workflows list` | `--channel` | `[{workflow_id, content, created_at}]` | +| `feed get` | — | array of feed events, newest-first |