diff --git a/desktop/src-tauri/src/managed_agents/nest_skill.md b/desktop/src-tauri/src/managed_agents/nest_skill.md index 0c1425ea2f..30c21b3085 100644 --- a/desktop/src-tauri/src/managed_agents/nest_skill.md +++ b/desktop/src-tauri/src/managed_agents/nest_skill.md @@ -2,12 +2,12 @@ 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. + and read messages, manage channels, set canvas documents, add reactions, + open DMs, query user profiles, trigger workflows, search messages, post code + diffs, manage repositories, publish social notes, upload files, and manage + persistent agent memory. Activate when the task involves messaging, channels, + feeds, DMs, reactions, workflows, social notes, repos, uploads, agent memory, + or any Sprout relay operation via the `sprout` command. version: 1 --- @@ -19,9 +19,9 @@ version: 1 `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. +All output is JSON on stdout unless noted otherwise. Commands that return lists return JSON arrays; commands that return a single resource return a JSON object. Exceptions: `canvas get` returns a raw markdown string (not JSON); `mem get`/`mem hash` write raw values to stdout; `pack inspect` outputs human-readable text; `social` and `repos` commands return raw Nostr event JSON (includes `sig` and relay-specific fields — not the normalized format used by `messages`, `channels`, etc.). -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. +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), `conflict` (exit 5 — write conflict, relay rejected as superseded). On non-zero exit, parse stderr for the error message before retrying or escalating. ## Parameter Conventions @@ -46,24 +46,50 @@ Send a threaded reply: sprout messages send --channel --content "reply text" --reply-to ``` -Read recent messages (returns array, newest messages at the end when no `--since`): +Send a forum post (kind 45001) or forum comment (kind 45003): + +```bash +sprout messages send --channel --content "post title" --kind 45001 +sprout messages send --channel --content "comment" --kind 45003 --reply-to +``` + +`--kind` routing: omitted or `9` sends a stream message; `45001` sends a forum post; `45003` sends a forum comment (requires `--reply-to`). Other kinds are rejected. + +Attach files (uploads to Blossom, includes as imeta tags): + +```bash +sprout messages send --channel --content "see attached" --file /path/to/image.png +``` + +Explicitly mention users by pubkey (in addition to @name auto-resolution from message body): + +```bash +sprout messages send --channel --content "cc @alice" --mention +``` + +`--file` and `--mention` are repeatable. + +Read recent messages (default kinds: `[9, 40002, 40008, 45001, 45003]`): ```bash sprout messages get --channel --limit 20 sprout messages get --channel --limit 50 --since 1716000000 sprout messages get --channel --limit 50 --before 1716050000 +sprout messages get --channel --kinds "1,1984" # override default kinds ``` Get a thread rooted at a specific event: ```bash sprout messages thread --channel --event +sprout messages thread --channel --event --limit 100 --depth-limit 5 ``` Full-text search across all channels you can access: ```bash sprout messages search --query "architecture decision" +sprout messages search --query "deploy" --limit 50 ``` Send a code diff with repository metadata (pipe the diff via stdin): @@ -112,6 +138,7 @@ Create a channel: ```bash sprout channels create --name "eng-backend" --type stream --visibility open +sprout channels create --name "rfcs" --type forum --visibility open --description "Architecture RFCs" ``` Returns `{event_id, channel_id, accepted, message}`. Use `channel_id` for subsequent operations. @@ -122,6 +149,14 @@ Get channel details: sprout channels get --channel ``` +Returns `{channel_id, name, description, created_at, pubkey}`, or `null` if not found. + +Update channel metadata: + +```bash +sprout channels update --channel --name "new-name" --description "new description" +``` + Join or leave: ```bash @@ -142,7 +177,16 @@ List members: sprout channels members --channel ``` -Returns `[{pubkey, role}]`. +Returns `[{pubkey, role}]`. Roles: `owner`, `admin`, `member`, `guest`, `bot`. + +Manage members: + +```bash +sprout channels add-member --channel --pubkey --role member +sprout channels remove-member --channel --pubkey +``` + +`--role` is optional (defaults to `member`). Valid roles: `owner`, `admin`, `member`, `guest`, `bot`. Admin operations (require `admin:channels` scope): @@ -154,7 +198,7 @@ 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): +Get the canvas document for a channel (returns the markdown content string directly, or `null` if no canvas is set — this is NOT a JSON envelope): ```bash sprout canvas get --channel @@ -195,6 +239,7 @@ List existing DM conversations: ```bash sprout dms list +sprout dms list --limit 10 ``` Returns `[{dm_id, participants, created_at}]`. @@ -203,6 +248,7 @@ Open a new DM (creates a group DM conversation): ```bash sprout dms open --pubkey +sprout dms open --pubkey --pubkey # group DM (up to 8) ``` Returns `{event_id, dm_id, accepted, message}`. Use `dm_id` as the `--channel` value for subsequent `messages` commands. @@ -273,7 +319,7 @@ List workflows for a channel: sprout workflows list --channel ``` -Returns `[{workflow_id, content, created_at}]`. +Returns `[{workflow_id, content, created_at, pubkey}]`. Get a specific workflow definition: @@ -292,6 +338,18 @@ cat workflow.yaml | sprout workflows create --channel --yaml - Returns `{event_id, workflow_id, accepted, message}`. +Update a workflow (requires both `--channel` and `--workflow`): + +```bash +sprout workflows update --channel --workflow --yaml "name: updated\nsteps: ..." +``` + +Delete a workflow: + +```bash +sprout workflows delete --workflow +``` + Trigger a workflow: ```bash @@ -309,19 +367,20 @@ Get run history for a workflow: ```bash sprout workflows runs --workflow +sprout workflows runs --workflow --limit 10 ``` 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): +Get your activity feed (mentions of your pubkey): ```bash sprout feed get --limit 20 ``` -Returns events sorted newest-first. +Returns events sorted newest-first (descending `created_at`). This is the only list command that sorts newest-first; all others sort oldest-first. Poll for recent activity since a timestamp: @@ -329,6 +388,149 @@ Poll for recent activity since a timestamp: sprout feed get --since 1716000000 --limit 50 ``` +## Social + +Nostr social protocol commands (NIP-01, NIP-02, NIP-51/NIP-65). These commands return **raw Nostr event JSON** including `sig` and all relay fields — not the normalized format used by `messages`, `channels`, etc. + +Publish a text note (kind:1): + +```bash +sprout social publish --content "Hello world" +sprout social publish --content "reply text" --reply-to +``` + +Set your contact list (kind:3): + +```bash +sprout social set-contacts --contacts '[{"pubkey":"","relay_url":"","petname":"alice"}]' +``` + +Get a single event by ID: + +```bash +sprout social event --event +``` + +Get a user's recent notes: + +```bash +sprout social notes --pubkey --limit 20 +sprout social notes --pubkey --limit 20 --before 1716050000 +``` + +Get a user's contact list: + +```bash +sprout social contacts --pubkey +``` + +Publish a NIP-51/NIP-65 social list (supported kinds: 10000, 10001, 10002, 10003, 30000, 30003): + +```bash +sprout social set-list --kind 10002 --tags '[["r","wss://relay.example.com"]]' +``` + +Read a user's social lists by kind: + +```bash +sprout social list --pubkey --kind 10002 +sprout social list --pubkey --kind 30000 --d-tag "friends" +``` + +## Repos + +Git repository announcements (NIP-34 kind:30617). Returns raw Nostr event JSON. + +Create a repository announcement: + +```bash +sprout repos create --id "my-repo" --name "My Repo" --description "A project" --clone https://github.com/org/repo.git +``` + +`--clone`, `--web`, and `--nostr-relay` flags are optional; `--clone` is repeatable. + +Get a repository: + +```bash +sprout repos get --id "my-repo" +sprout repos get --id "my-repo" --owner +``` + +List repositories: + +```bash +sprout repos list +sprout repos list --owner --limit 10 +``` + +## Upload + +Upload a file to the relay's Blossom store: + +```bash +sprout upload file --file /path/to/image.png +``` + +Returns a pretty-printed (multi-line) JSON `BlobDescriptor`: `{url, sha256, size, type, uploaded}`. Optional fields: `dim`, `blurhash`, `thumb`, `duration`. + +## Mem (Agent Memory) + +Persistent agent memory (NIP-AE engrams). Progress messages go to stderr; data goes to stdout. Exit code 5 on write conflicts. + +List memory entries: + +```bash +sprout mem ls # tab-delimited: slug, created_at, event_id +sprout mem ls --json # JSON array: [{slug, event_id, created_at}] +``` + +Read a memory value (raw bytes to stdout, no trailing newline): + +```bash +sprout mem get +``` + +Get the SHA-256 hash of a value (use as `--base-hash` for safe patching): + +```bash +sprout mem hash +``` + +Set a memory value: + +```bash +sprout mem set "value" +echo "value" | sprout mem set - # read from stdin +sprout mem set - --allow-empty # allow empty stdin +``` + +Patch a memory value with a unified diff (safer than `set` for concurrent access): + +```bash +sprout mem hash # get base hash first +diff -u old.txt new.txt | sprout mem patch --base-hash +sprout mem patch --patch-file changes.patch --base-hash +sprout mem patch --no-base-hash # skip hash check (unsafe) +sprout mem patch --base-hash --dry-run # preview without writing +``` + +Delete (tombstone) a memory entry: + +```bash +sprout mem rm +``` + +The `core` slug cannot be deleted. + +## Pack (Local-Only) + +Persona pack operations. No relay connection or `--private-key` needed. + +```bash +sprout pack validate /path/to/pack # validate pack directory structure +sprout pack inspect /path/to/pack # show pack metadata (human-readable text, not JSON) +``` + ## Polling Pattern The Sprout relay has no push or webhook support. Poll with `--since` and sleep between iterations. @@ -346,23 +548,76 @@ Use shorter intervals (10s) when latency matters; longer intervals (30s) for bac ## Quick Reference +Most write commands return `{event_id, accepted, message}`. Exceptions noted below. + +**Read commands:** + | 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, ...}` | +| `messages get` | `--channel` | `[{id, pubkey, kind, content, created_at, tags}]` | +| `messages thread` | `--channel`, `--event` | `[{id, pubkey, kind, content, created_at, tags}]` | +| `messages search` | `--query` | `[{id, pubkey, kind, content, created_at, tags}]` | | `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 get` | `--channel` | `{channel_id, name, description, created_at, pubkey}` or `null` | | `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 | +| `users presence` | `--pubkeys` | `[{pubkey, status, updated_at}]` | +| `workflows list` | `--channel` | `[{workflow_id, content, created_at, pubkey}]` | +| `workflows get` | `--workflow` | `{workflow_id, content, created_at, pubkey}` or `null` | +| `workflows runs` | `--workflow` | `[{event_id, kind, content, created_at, tags}]` | +| `feed get` | — | event array, newest-first | + +**Write commands** (all return `{event_id, accepted, message}` unless noted): + +| Command | Required Flags | Notes | +|---------|---------------|-------| +| `messages send` | `--channel`, `--content` | | +| `messages send-diff` | `--channel`, `--diff`, `--repo`, `--commit` | | +| `messages edit` | `--event`, `--content` | | +| `messages delete` | `--event` | | +| `messages vote` | `--event`, `--direction` | | +| `channels create` | `--name`, `--type`, `--visibility` | adds `channel_id` | +| `channels update/join/leave/topic/purpose` | `--channel` (+ value flag) | | +| `channels add-member/remove-member` | `--channel`, `--pubkey` | | +| `channels archive/unarchive/delete` | `--channel` | | +| `canvas set` | `--channel`, `--content` | | +| `reactions add/remove` | `--event`, `--emoji` | | +| `dms open` | `--pubkey` | adds `dm_id` | +| `dms add-member` | `--channel`, `--pubkey` | | +| `users set-profile` | one of `--name`/`--avatar`/`--about`/`--nip05` | | +| `workflows create` | `--channel`, `--yaml` | adds `workflow_id` | +| `workflows update` | `--channel`, `--workflow`, `--yaml` | | +| `workflows delete/trigger` | `--workflow` | | +| `workflows approve` | `--token` | | +| `social publish` | `--content` | | +| `social set-contacts` | `--contacts` | | + +**Raw output commands** (return unprocessed Nostr event JSON including `sig`): + +| Command | Required Flags | +|---------|---------------| +| `social event` | `--event` | +| `social notes` | `--pubkey` | +| `social contacts` | `--pubkey` | +| `social set-list` | `--kind`, `--tags` | +| `social list` | `--pubkey`, `--kind` | +| `repos create` | `--id` | +| `repos get` | `--id` | +| `repos list` | — | + +**Other output formats:** + +| Command | Required Flags | Returns | +|---------|---------------|---------| +| `upload file` | `--file` | `{url, sha256, size, type, uploaded}` (pretty-printed) | +| `mem ls` | — | tab-delimited lines or `--json` array | +| `mem get` | `` | raw value (stdout, no newline) | +| `mem hash` | `` | SHA-256 hex string | +| `mem set` | ``, `` | stderr progress only | +| `mem patch` | ``, `--base-hash` or `--no-base-hash` | stderr progress only | +| `mem rm` | `` | stderr progress only | +| `pack validate` | `` | "Valid." or errors | +| `pack inspect` | `` | human-readable text |