Skip to content

Commit 57af0b5

Browse files
willwashburnwillwashburn
committed
Move doctor repro docs into web
1 parent 514e175 commit 57af0b5

3 files changed

Lines changed: 185 additions & 140 deletions

File tree

‎docs/doctor-orchestration-repros.md‎

Lines changed: 0 additions & 140 deletions
This file was deleted.

‎web/content/docs/doctor-orchestration-repros.mdx‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Doctor orchestration repros
3+
description: Local repro steps for broker connection and orchestration diagnostics.
4+
---
5+
6+
Use these local repros when `agent-relay status`, `agent-relay who`, or
7+
messaging commands disagree about broker state. They intentionally create broken
8+
broker metadata so you can verify diagnostics without comparing command output
9+
by hand.
10+
11+
Credential values shown by your local commands should be treated as secrets.
12+
Do not paste unredacted workspace keys, broker API keys, or agent tokens into
13+
issues or shared logs.
14+
15+
## Stale Broker Connection
16+
17+
This repro simulates a connection file that points at an old broker URL while
18+
recording the PID of a newer broker process.
19+
20+
```bash
21+
TMP=$(mktemp -d "${TMPDIR:-/tmp}/relay-repro-stale-XXXXXX")
22+
cd "$TMP"
23+
24+
agent-relay up --no-dashboard --port 49200
25+
CONN1=$(cat .agent-relay/connection.json)
26+
PID1=$(node -e 'console.log(JSON.parse(process.argv[1]).pid)' "$CONN1")
27+
28+
kill -9 "$PID1"
29+
30+
agent-relay up --no-dashboard --port 49300
31+
CONN2=$(cat .agent-relay/connection.json)
32+
33+
node -e '
34+
const fs = require("node:fs");
35+
const oldConn = JSON.parse(process.argv[1]);
36+
const nextConn = JSON.parse(process.argv[2]);
37+
oldConn.pid = nextConn.pid;
38+
fs.writeFileSync(".agent-relay/connection.json", JSON.stringify(oldConn, null, 2));
39+
' "$CONN1" "$CONN2"
40+
41+
agent-relay status
42+
agent-relay status --wait-for=1
43+
agent-relay who --json
44+
```
45+
46+
Expected result:
47+
48+
```text
49+
Status: STARTING
50+
Broker process is running, but the API did not become ready before timeout.
51+
52+
[]
53+
```
54+
55+
The broker process exists, but the recorded API URL is stale. Diagnostic
56+
commands should report the mismatch instead of treating the workspace as a
57+
healthy broker session.
58+
59+
## Unresolved API Key Template
60+
61+
This repro checks that a literal unresolved environment template fails before a
62+
messaging command attempts a Relaycast read.
63+
64+
First confirm that the correctly resolved local broker context reaches
65+
Relaycast:
66+
67+
```bash
68+
agent-relay replies WorkerA --json
69+
```
70+
71+
Expected result when there is no conversation:
72+
73+
```text
74+
No DM conversation with WorkerA.
75+
```
76+
77+
Then run the same command with a literal unresolved template:
78+
79+
```bash
80+
RELAY_API_KEY='${RELAY_API_KEY}' agent-relay replies WorkerA --json
81+
```
82+
83+
Expected result:
84+
85+
```text
86+
Failed to initialize relaycast client: Workspace key required (rk_live_...)
87+
```
88+
89+
The command should reject the unresolved template as invalid credential input
90+
instead of treating it as a real workspace key.
91+
92+
## Half-Started Broker Metadata
93+
94+
This repro simulates a broker process that is still running after its local
95+
connection metadata has disappeared.
96+
97+
```bash
98+
TMP=$(mktemp -d "${TMPDIR:-/tmp}/relay-repro-half-started-XXXXXX")
99+
cd "$TMP"
100+
101+
env \
102+
-u RELAY_API_KEY \
103+
-u RELAY_AGENT_TOKEN \
104+
-u RELAY_WORKSPACES_JSON \
105+
-u RELAY_DEFAULT_WORKSPACE \
106+
-u RELAY_WORKSPACE_ID \
107+
-u RELAY_BASE_URL \
108+
-u RELAY_BROKER_URL \
109+
-u RELAY_BROKER_API_KEY \
110+
-u RELAY_AGENT_NAME \
111+
-u RELAY_AGENT_TYPE \
112+
-u RELAY_STRICT_AGENT_NAME \
113+
agent-relay up --no-dashboard --port 49600
114+
115+
CONN=$(cat .agent-relay/connection.json)
116+
PID=$(node -e 'console.log(JSON.parse(process.argv[1]).pid)' "$CONN")
117+
rm .agent-relay/connection.json
118+
119+
ps -p "$PID" -o pid=,comm=
120+
121+
env \
122+
-u RELAY_API_KEY \
123+
-u RELAY_AGENT_TOKEN \
124+
-u RELAY_WORKSPACES_JSON \
125+
-u RELAY_DEFAULT_WORKSPACE \
126+
-u RELAY_WORKSPACE_ID \
127+
-u RELAY_BASE_URL \
128+
-u RELAY_BROKER_URL \
129+
-u RELAY_BROKER_API_KEY \
130+
-u RELAY_AGENT_NAME \
131+
-u RELAY_AGENT_TYPE \
132+
-u RELAY_STRICT_AGENT_NAME \
133+
agent-relay status
134+
135+
env \
136+
-u RELAY_API_KEY \
137+
-u RELAY_AGENT_TOKEN \
138+
-u RELAY_WORKSPACES_JSON \
139+
-u RELAY_DEFAULT_WORKSPACE \
140+
-u RELAY_WORKSPACE_ID \
141+
-u RELAY_BASE_URL \
142+
-u RELAY_BROKER_URL \
143+
-u RELAY_BROKER_API_KEY \
144+
-u RELAY_AGENT_NAME \
145+
-u RELAY_AGENT_TYPE \
146+
-u RELAY_STRICT_AGENT_NAME \
147+
agent-relay history
148+
149+
env \
150+
-u RELAY_API_KEY \
151+
-u RELAY_AGENT_TOKEN \
152+
-u RELAY_WORKSPACES_JSON \
153+
-u RELAY_DEFAULT_WORKSPACE \
154+
-u RELAY_WORKSPACE_ID \
155+
-u RELAY_BASE_URL \
156+
-u RELAY_BROKER_URL \
157+
-u RELAY_BROKER_API_KEY \
158+
-u RELAY_AGENT_NAME \
159+
-u RELAY_AGENT_TYPE \
160+
-u RELAY_STRICT_AGENT_NAME \
161+
agent-relay replies WorkerA --json
162+
```
163+
164+
Expected result:
165+
166+
```text
167+
Status: STOPPED
168+
169+
Failed to initialize relaycast client: Failed to read broker connection metadata. Start the broker with `agent-relay up` or set RELAY_API_KEY.
170+
```
171+
172+
The process table can still contain the broker PID, but the workspace is missing
173+
the metadata needed for broker-backed messaging. Diagnostic commands should
174+
surface that missing metadata directly.
175+
176+
## Cleanup
177+
178+
Each repro creates a temporary project directory and may leave a broker process
179+
behind. Clean up with:
180+
181+
```bash
182+
agent-relay down --force --all
183+
```
184+

‎web/lib/docs-nav.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ const ALL_SLUGS = [
9595
'communicate-openai-agents',
9696
'communicate-swarms',
9797
'communicate-crewai',
98+
'doctor-orchestration-repros',
9899
'harness-runtime-config',
99100
'local-mode',
100101
'reference-openclaw',

0 commit comments

Comments
 (0)