docs: add a current Observer page built on scoped observer tokens - #44
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📝 WalkthroughWalkthroughAdded Observer documentation for read-only workspace viewing, scoped observer tokens, security boundaries, deployment configuration, CLI and MCP usage, and related links. Added Observer to the Interfaces navigation and updated versioned guidance about workspace keys. ChangesObserver documentation
Estimated code review effort: 2 (Simple) | ~15 minutes Merge Risk: ⚪ Minimal · up to This documentation change adds and links the current Observer guidance without any actionable merge-blocking risk remaining after normal checks and review. Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 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".
|
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.
All reported issues were addressed across 3 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
There was a problem hiding this comment.
All reported issues were addressed across 3 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
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
Review found the new Observer page pointing at two reference pages that did not actually cover what it promised, and one link into archived docs. - `reference-cli.mdx` called itself the complete command matrix but had no `observer` entry. Adds an Observer section covering the three commands and every flag. - `agent-relay-mcp.mdx` did not list `get_observer_url`. Adds it to the workspace tool inventory plus a section with its inputs, its return shape, and the workspace-key warning. - The "When to use it" link to `/docs/relay-dashboard` resolved to a legacy-only slug, so it silently redirected into the v7.1.1 archive — the same failure this PR set out to fix for Observer. The link is now explicitly labelled as the archive, since Relay Dashboard has no current page yet. Every internal `/docs/` link on the three touched pages now resolves within the current docs, except the one deliberate archive link. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1
Review flagged an internal inconsistency: the Observer section says all three commands accept `--workspace-key` and `--base-url`, but the "Common SDK Options" list of SDK-backed groups does not include `observer`. Adding it to that list would have been wrong. `observer` does not use `addSdkOptions` — it declares those two flags itself and has no `--token` at all, because minting an observer token requires the workspace key and an agent token cannot do it. Listing it as SDK-backed would have implied `--token` works there. Says so explicitly instead. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1
eeb0427 to
cb975f6
Compare
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
Adds a current Observer docs page that uses scoped, expiring
ot_live_tokens instead of workspace-key URLs, and updates CLI/MCP references to match. This replaces the archive-only flow and stops recommending an administrative credential in a URL.Adds /docs/observer covering
agent-relay observer(flags--channels,--include-dms,--expires,--json), token management (observer list/revoke), MCPget_observer_url, self-hosted config via--observer-url/RELAY_OBSERVER_URL, and the capability differences; notes the realtime endpoint rejectsrk_live_*.Registers "Observer" in current
docsNav, so/docs/observerserves current docs.Keeps the v7.1.1 page with a safety Note and an absolute link to the new page to bypass the legacy link rewriter.
Expands the CLI reference with the Observer commands/flags and clarifies
observeris not SDK-backed: it accepts--workspace-key/--base-urland has no--token.Updates the MCP reference to include
get_observer_urlinputs/returns and a workspace-key warning; links to the Observer page.Fixes internal
/docs/links to resolve within current docs; labels the Relay Dashboard link as an archive.Merge after the
agent-relay observercommand ships (feat(cli): addagent-relay observerto mint read-only follow-along links relay#1422).Written for commit cb975f6. Summary will update on new commits.