Skip to content

Commit 0a0b3a6

Browse files
author
Dawn
committed
docs(testing): patch sharp edges found in cold-reader walkthrough
- Step 3: add port-collision callout (Sprout Desktop on :3000/:8080) and flag that overriding relay ports requires $SPROUT_RELAY_URL on the CLI. - Step 3: warn cold readers to `unset SPROUT_AUTH_TAG` if their shell has it set from another relay's config. - ACP recipe: add `channels add-member $AGENT_PUBKEY` BEFORE starting sprout-acp. Without this the agent boots to 'discovered 0 channel(s)' / 'no channel subscriptions resolved — agent will sit idle' and never picks up mentions. Verified end-to-end with goose against a local relay. - ACP recipe: capture sender SK first so the reader can switch back to it to send the @mention. Note that the agent log is quiet during turns; use `sprout messages get` to confirm the reply. - Troubleshooting: new row for the 'discovered 0 channels / sit idle' case.
1 parent 359fe6c commit 0a0b3a6

1 file changed

Lines changed: 51 additions & 10 deletions

File tree

‎TESTING.md‎

Lines changed: 51 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,19 @@ The relay starts in dev mode (`SPROUT_REQUIRE_AUTH_TOKEN=false`). The startup
6868
log emits a WARN about this — that's expected for local testing. See the env
6969
vars table at the bottom if you need to lock it down.
7070

71+
> **Already running Sprout Desktop (or another relay) on `:3000` / `:8080`?**
72+
> Override the relay's three ports and point the CLI at the new main port:
73+
> ```bash
74+
> export SPROUT_BIND_ADDR=0.0.0.0:3030 SPROUT_HEALTH_PORT=8088 SPROUT_METRICS_PORT=9202
75+
> export RELAY_URL=ws://localhost:3030 # for the relay (NIP-42 advertisement)
76+
> export SPROUT_RELAY_URL=http://localhost:3030 # for the CLI in steps 4+
77+
> ```
78+
79+
> **Heads up:** if your shell already has `SPROUT_AUTH_TAG` set (e.g. from a
80+
> staging relay config), `unset SPROUT_AUTH_TAG` before testing. The local
81+
> dev relay tolerates it, but a stale tag will trip you up the moment you
82+
> point the CLI at a membership-gated relay.
83+
7184
### 4. Smoke test the CLI against the relay
7285
7386
End-to-end: generate an identity, create a channel, post a message, read it
@@ -132,36 +145,63 @@ agent over stdio, and the agent replies through MCP tools.
132145
> integration. Keep it in mind if you're poking at the ACP code, but new
133146
> tests should not depend on it.
134147
135-
Minimum recipe — assumes the relay from step 3 is running:
148+
Minimum recipe — assumes the relay from step 3 is running and the channel
149+
`$CHANNEL` from step 4 still exists. The agent identity must be **different**
150+
from the sender identity (`SPROUT_ACP_RESPOND_TO=anyone` still skips events
151+
the agent signed itself).
136152
137153
```bash
138154
cargo build --release -p sprout-acp -p sprout-mcp
139155
export PATH="$PWD/target/release:$PATH"
140156
157+
# 1. Save your sender identity from step 4 — you'll need it to @mention the agent
158+
SENDER_SK="$SPROUT_PRIVATE_KEY"
159+
160+
# 2. Mint a fresh agent identity and capture its pubkey
141161
AGENT_GEN=$(sprout-admin generate-key)
142-
export SPROUT_PRIVATE_KEY=$(echo "$AGENT_GEN" | awk '/Secret key:/ {print $3}')
143-
export SPROUT_RELAY_URL=ws://localhost:3000
144-
export SPROUT_ACP_RESPOND_TO=anyone # default is owner-only; opens the gate for testing
145-
export GOOSE_MODE=auto # must be 'auto' or goose hangs on prompts
162+
AGENT_SK=$(echo "$AGENT_GEN" | awk '/Secret key:/ {print $3}')
163+
AGENT_PUBKEY=$(echo "$AGENT_GEN" | awk '/Public key:/ {print $3}')
164+
165+
# 3. Add the agent as a member of $CHANNEL — still using the sender identity.
166+
# Skip this and the agent boots to "discovered 0 channel(s) → agent will
167+
# sit idle" and silently ignores every mention.
168+
sprout channels add-member --channel "$CHANNEL" --pubkey "$AGENT_PUBKEY" --role member
146169
147-
sprout-acp # foreground; logs to stdout
170+
# 4. Switch to the agent identity and start it
171+
export SPROUT_PRIVATE_KEY="$AGENT_SK"
172+
export SPROUT_RELAY_URL=ws://localhost:3000 # or :3030 if you overrode ports in step 3
173+
export SPROUT_ACP_RESPOND_TO=anyone # default is owner-only; opens the gate for testing
174+
export GOOSE_MODE=auto # must be 'auto' or goose hangs on prompts
175+
176+
sprout-acp # foreground; logs to stdout (run in a separate terminal)
148177
```
149178
179+
If you started the agent before adding it to the channel, just run the
180+
`add-member` afterwards — it picks up the membership notification live and
181+
subscribes without restart (`membership notification: subscribing to new channel …`).
182+
150183
The justfile also ships `just goose key="$AGENT_NSEC"` (foreground) and
151184
`just goose-bg key="$AGENT_NSEC"` (background screen session) which set the
152185
same env. See `crates/sprout-acp/README.md` for parallel agents, heartbeats,
153186
respond-to gates, and forum subscriptions.
154187
155-
To send the agent a task, @mention its pubkey from another identity:
188+
Send the agent a task — switch your shell back to the **sender** identity
189+
from step 4 and @mention the agent:
156190
157191
```bash
192+
export SPROUT_PRIVATE_KEY=$SENDER_SK # the key from step 4
158193
sprout messages send --channel "$CHANNEL" \
159-
--content "Hey agent, say hello." \
194+
--content "Hey agent, reply PONG only." \
160195
--mention "$AGENT_PUBKEY"
196+
197+
# Wait 10–90s, then read the channel — the agent's reply is a kind:9 from
198+
# AGENT_PUBKEY. The current ACP build is quiet on stdout during a turn, so
199+
# `sprout messages get` is how you confirm it ran.
200+
sprout messages get --channel "$CHANNEL" --limit 5 | jq '.[] | {pubkey, content}'
161201
```
162202
163-
Agent turns typically take 10–90s. Replies appear as kind:9 threaded events;
164-
`sprout messages thread --channel <id> --event <event_id>` fetches them.
203+
Replies are kind:9 in the same channel; `sprout messages thread --channel <id>
204+
--event <event_id>` fetches the reply chain for a specific mention.
165205
166206
---
167207
@@ -204,5 +244,6 @@ CLI-side, only two matter for testing:
204244
| `auth-required: verification failed` on a closed relay | NIP-OA attestation needed | Set `SPROUT_AUTH_TAG` to the owner-issued JSON, or relax `SPROUT_REQUIRE_RELAY_MEMBERSHIP` |
205245
| `channels list` empty after `channels create` | The CLI doesn't echo the channel UUID; use the filter shown in step 4 | Or `POST /query` with `{"kinds":[39002]}` |
206246
| ACP agent ignores all events | `SPROUT_ACP_RESPOND_TO=owner-only` (default) with no owner configured | Set `SPROUT_ACP_RESPOND_TO=anyone` for testing |
247+
| ACP logs `discovered 0 channel(s)` / `no channel subscriptions resolved` | Agent identity isn't a member of any channel | `sprout channels add-member --channel "$CHANNEL" --pubkey "$AGENT_PUBKEY" --role member` from another identity |
207248
| `GOOSE_MODE` warning, agent hangs | Not set | `export GOOSE_MODE=auto` |
208249
| Tests pass locally but CI fails | Forgot to run `just ci` | `just ci` runs the gate (fmt, clippy, unit tests, desktop/web builds) |

0 commit comments

Comments
 (0)