docs: add a current Observer page built on scoped observer tokens - #44
docs: add a current Observer page built on scoped observer tokens#44willwashburn wants to merge 1 commit into
Conversation
Observer had no page in the current docs. The slug exists only in the
v7.1.1 archive and the legacy nav, so `/docs/observer` redirects into the
archive and the current sidebar never mentions the feature at all.
The archived page also documents the only method it knew:
https://agentrelay.com/observer?key=<workspace_key>
A workspace key is an administrative credential — it can send messages,
spawn agents, and change workspace settings — and a query string is not a
place to put one. Current releases ship `agent-relay observer`, which
mints a scoped, expiring, read-only `ot_live_` token and builds the link
from that.
- Adds `web/content/docs/observer.mdx` covering `agent-relay observer`,
the `--channels` / `--include-dms` / `--expires` narrowing, `observer
list` / `revoke`, the `get_observer_url` MCP tool, and a capability
table contrasting a workspace key with an observer token.
- Registers the slug under Interfaces in `docsNav`, so the page is
reachable and `/docs/observer` resolves to current docs instead of
redirecting to the archive.
- Leaves the archived v7.1.1 page in place but adds a note that the
pattern is unsafe on a current release, linking to the new page. The
link is absolute because `rewriteLegacyDocsLinks` rewrites bare
`/docs/` links back into `/docs/7.1.1/`, which would have pointed it at
itself.
Depends on the `agent-relay observer` command in AgentWorkforce/relay#1422.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1
📝 WalkthroughWalkthroughAdded Observer documentation for read-only workspace viewing, scoped observer tokens, security boundaries, deployment configuration, and usage. Added Observer to the Interfaces navigation. Updated versioned documentation with workspace-key warnings. ChangesObserver documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0f7db55a7f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <Card title="CLI reference" href="/docs/reference-cli"> | ||
| Every `agent-relay` command, including `observer`. |
There was a problem hiding this comment.
The linked reference-cli.mdx page describes itself as the complete command matrix but contains no observer command or any of the flags shown here. Readers following this card therefore cannot find the promised reference syntax; update the CLI reference alongside this page or remove the claim that it includes Observer.
Useful? React with 👍 / 👎.
| <Card title="Agent Relay MCP" href="/docs/agent-relay-mcp"> | ||
| Includes `get_observer_url` for orchestrating agents. |
There was a problem hiding this comment.
The linked agent-relay-mcp.mdx inventory does not mention get_observer_url, its inputs, or its output, despite this card promising that it does. An MCP user following the link has no usable reference for invoking the newly advertised tool, so add it to that page or stop describing the destination as containing it.
Useful? React with 👍 / 👎.
|
Preview deployed!
This is a Cloudflare Workers preview version of this PR's build. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
web/content/docs/observer.mdx (1)
26-26: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winClarify why observer-token exposure in a URL is acceptable.
Line 26 shows the observer token in the URL query string (
?key=ot_live_...), yet lines 55-56 warn that query strings end up in browser history, referrer headers, and proxy logs. An observer token faces the identical exposure surface; only its blast radius is smaller due to scope, expiry, and revocability. Add a sentence noting that observer tokens accept the same URL-exposure surface by design, because their reduced capability and revocability make that acceptable, unlike a workspace key. This avoids leaving readers to infer the distinction on their own.Also applies to: 51-69
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@web/content/docs/observer.mdx` at line 26, Add a sentence in the observer-token documentation near the URL example and the query-string warning explaining that observer tokens intentionally share the URL exposure surface, and that their limited scope, expiry, and revocability make this acceptable compared with workspace keys.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@web/content/docs/observer.mdx`:
- Line 26: Add a sentence in the observer-token documentation near the URL
example and the query-string warning explaining that observer tokens
intentionally share the URL exposure surface, and that their limited scope,
expiry, and revocability make this acceptable compared with workspace keys.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4d300c34-e02d-4c6f-98e4-c12957e825ce
📒 Files selected for processing (3)
web/content/docs/7.1.1/observer.mdxweb/content/docs/observer.mdxweb/lib/docs-nav.ts
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 3 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="web/content/docs/observer.mdx">
<violation number="1" location="web/content/docs/observer.mdx:84">
P3: On the new current Observer page, the “When to use it” link to `/docs/relay-dashboard` doesn’t resolve within the current docs. Relay Dashboard is only present in the v7.1.1 archive, so `/docs/relay-dashboard` is not in currentDocsSlugs and the router redirects readers to the archived `/docs/7.1.1/relay-dashboard` page. Since the rest of this PR is about serving current docs (and every other link on this page resolves within current docs), consider either adding a current Relay Dashboard page/slug or removing/linking elsewhere so the new page doesn’t quietly route readers to archived content.</violation>
<violation number="2" location="web/content/docs/observer.mdx:92">
P2: This card claims the Agent Relay MCP page documents `get_observer_url`, but that page doesn't currently list this tool, its inputs, or output. Readers following this link will find no reference for the newly advertised MCP tool. Either add `get_observer_url` to agent-relay-mcp.mdx or remove this claim.</violation>
<violation number="3" location="web/content/docs/observer.mdx:95">
P2: This card states the CLI reference includes the `observer` command, but reference-cli.mdx doesn't document it or its flags (--channels, --include-dms, --expires, etc.). Update the CLI reference alongside this page, or remove the claim that it covers Observer.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| <Card title="Agent Relay MCP" href="/docs/agent-relay-mcp"> | ||
| Includes `get_observer_url` for orchestrating agents. | ||
| </Card> | ||
| <Card title="CLI reference" href="/docs/reference-cli"> |
There was a problem hiding this comment.
P2: This card states the CLI reference includes the observer command, but reference-cli.mdx doesn't document it or its flags (--channels, --include-dms, --expires, etc.). Update the CLI reference alongside this page, or remove the claim that it covers Observer.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/observer.mdx, line 95:
<comment>This card states the CLI reference includes the `observer` command, but reference-cli.mdx doesn't document it or its flags (--channels, --include-dms, --expires, etc.). Update the CLI reference alongside this page, or remove the claim that it covers Observer.</comment>
<file context>
@@ -0,0 +1,101 @@
+ <Card title="Agent Relay MCP" href="/docs/agent-relay-mcp">
+ Includes `get_observer_url` for orchestrating agents.
+ </Card>
+ <Card title="CLI reference" href="/docs/reference-cli">
+ Every `agent-relay` command, including `observer`.
+ </Card>
</file context>
| <Card title="Authentication" href="/docs/authentication"> | ||
| The credential types Agent Relay issues and what each one can do. | ||
| </Card> | ||
| <Card title="Agent Relay MCP" href="/docs/agent-relay-mcp"> |
There was a problem hiding this comment.
P2: This card claims the Agent Relay MCP page documents get_observer_url, but that page doesn't currently list this tool, its inputs, or output. Readers following this link will find no reference for the newly advertised MCP tool. Either add get_observer_url to agent-relay-mcp.mdx or remove this claim.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/observer.mdx, line 92:
<comment>This card claims the Agent Relay MCP page documents `get_observer_url`, but that page doesn't currently list this tool, its inputs, or output. Readers following this link will find no reference for the newly advertised MCP tool. Either add `get_observer_url` to agent-relay-mcp.mdx or remove this claim.</comment>
<file context>
@@ -0,0 +1,101 @@
+ <Card title="Authentication" href="/docs/authentication">
+ The credential types Agent Relay issues and what each one can do.
+ </Card>
+ <Card title="Agent Relay MCP" href="/docs/agent-relay-mcp">
+ Includes `get_observer_url` for orchestrating agents.
+ </Card>
</file context>
|
|
||
| Use Observer when you want visibility without control. To chat, spawn agents, or | ||
| manage the workspace interactively, use the | ||
| [Relay Dashboard](/docs/relay-dashboard) instead. |
There was a problem hiding this comment.
P3: On the new current Observer page, the “When to use it” link to /docs/relay-dashboard doesn’t resolve within the current docs. Relay Dashboard is only present in the v7.1.1 archive, so /docs/relay-dashboard is not in currentDocsSlugs and the router redirects readers to the archived /docs/7.1.1/relay-dashboard page. Since the rest of this PR is about serving current docs (and every other link on this page resolves within current docs), consider either adding a current Relay Dashboard page/slug or removing/linking elsewhere so the new page doesn’t quietly route readers to archived content.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At web/content/docs/observer.mdx, line 84:
<comment>On the new current Observer page, the “When to use it” link to `/docs/relay-dashboard` doesn’t resolve within the current docs. Relay Dashboard is only present in the v7.1.1 archive, so `/docs/relay-dashboard` is not in currentDocsSlugs and the router redirects readers to the archived `/docs/7.1.1/relay-dashboard` page. Since the rest of this PR is about serving current docs (and every other link on this page resolves within current docs), consider either adding a current Relay Dashboard page/slug or removing/linking elsewhere so the new page doesn’t quietly route readers to archived content.</comment>
<file context>
@@ -0,0 +1,101 @@
+
+Use Observer when you want visibility without control. To chat, spawn agents, or
+manage the workspace interactively, use the
+[Relay Dashboard](/docs/relay-dashboard) instead.
+
+## Related docs
</file context>
2 participants
Summary
Observer has no page in the current docs. The
observerslug appears only inlegacyDocsNavandweb/content/docs/7.1.1/observer.mdx, so:/docs/observerresolves tov7.1.1viagetDefaultDocsVersionForSlugand redirects into the archiveAnd the archived page documents the only method it knew:
A workspace key is an administrative credential — it can send messages, spawn agents, and change workspace settings — and a URL query string is not a place to put one. Current releases ship
agent-relay observer, which mints a scoped, expiring, read-onlyot_live_token and builds the link from that.Changes
web/content/docs/observer.mdx— coversagent-relay observer, narrowing with--channels/--include-dms/--expires,observer list/observer revoke, theget_observer_urlMCP tool for orchestrating agents,--observer-url/RELAY_OBSERVER_URLfor self-hosted and staging, and a table contrasting what a workspace key can do against what an observer token can do.docsNav, so the page is reachable and/docs/observerserves current docs instead of redirecting to the archive.<Note>saying the pattern is unsafe on a current release, linking to the new page.One subtlety worth flagging for review: that link is written as an absolute URL on purpose.
rewriteLegacyDocsLinks(web/lib/docs.ts:139) rewrites bare/docs/…links inside legacy content to/docs/7.1.1/…, so a relative link would have pointed the reader back at the archived page they were already on. I simulated the rewriter against the file to confirm the absolute link passes through untouched while the pre-existingrelay-dashboardlink is still rewritten as intended.Depends on
agent-relay observerlanding in AgentWorkforce/relay#1422 — worth merging after it, since the page documents that command.Test Plan
npx next build --webpackcompiles successfully/docs/observernow prerenders —.next/server/app/docs/observer.htmlexists, where before the slug only redirectedagent-relay observer,--channels,--include-dms,--expires,--json,observer list,observer revoke,--observer-url)/docs/observerlink present in the builtquickstart.html)rewriteLegacyDocsLinksagainst the legacy file to confirm the cross-version link survivesnpx vitest run— 22 passed, 9 filespackage-lock.jsonchurn fromnpm installScreenshots
n/a
Generated by Claude Code
Summary by cubic
Add a current Observer docs page that uses scoped, expiring
ot_live_tokens and registers the page in the current docs nav, replacing the old archive-only flow that relied on unsafe workspace key URLs.web/content/docs/observer.mdxcoveringagent-relay observer, narrowing (--channels,--include-dms,--expires), token management (observer list,observer revoke), theget_observer_urlMCP tool, and self-hosted settings via--observer-url/RELAY_OBSERVER_URL.Observerpage indocsNavso/docs/observerserves current docs.Written for commit 0f7db55. Summary will update on new commits.