feat(cli): add agent-relay observer to mint read-only follow-along links - #1422
feat(cli): add agent-relay observer to mint read-only follow-along links#1422willwashburn wants to merge 2 commits into
agent-relay observer to mint read-only follow-along links#1422Conversation
…links Sharing a live view of a workspace had no supported path. The engine rejects a workspace key on the realtime endpoint and only accepts a scoped `ot_live_` observer token, but nothing in the CLI or the MCP server minted one — the only routes were a hand-rolled `POST /v1/observer-tokens` or pasting an admin key into the dashboard login. So the bundled instructions told agents that observation "requires a separately provisioned observer token" and to omit the link when none exists, which in practice meant never showing one. Adds the missing primitive: - `agent-relay observer` mints a scoped token and prints the observer URL built from it. `observer list` / `observer revoke <id>` manage tokens. - `get_observer_url` MCP tool does the same for an orchestrating agent. - `@agent-relay/sdk` exports `createObserverToken`, `listObserverTokens`, and `revokeObserverToken`. Defaults are deliberately tighter than the observer dashboard's own auto-minted token (30 days, DMs included): that one backs a browser session behind an httpOnly cookie, while this one is printed as a URL meant to be pasted into chat. 24 hours, agent DMs excluded, widened explicitly via `--expires` / `--include-dms` / `--channels`. `observerUrl` refuses any credential that is not an `ot_live_` token, so the workspace-key-in-a-URL failure this command exists to prevent cannot be reintroduced by a later caller. Updates the Codex skill and Gemini extension instructions to point at the command instead of describing the link as unobtainable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1
📝 WalkthroughWalkthroughThe PR adds scoped observer-token creation, listing, revocation, and URL generation to the SDK, CLI, and MCP interface. It also updates observation guidance and reclassifies the unreleased version as Minor. ChangesObserver token workflows
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 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: 992f1d9df6
ℹ️ 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".
| .action(async (options: Record<string, unknown>) => { | ||
| await runSdk(deps, async () => { | ||
| const tokens = await deps.listObserverTokens(connection(options)); |
There was a problem hiding this comment.
When observer list or observer revoke is given --workspace-key, --base-url, or (for list) --json, Commander stores these duplicated options on the parent observer command, while this callback receives only the child command's local options object. Consequently agent-relay observer list --json still prints text, and explicit connection flags are ignored in favor of ambient credentials; the revoke action repeats the same pattern. Read optsWithGlobals() from the action command or otherwise merge the parent options before calling connection().
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/cli/src/cli/agent-relay-mcp.ts (1)
582-643: 🧹 Nitpick | 🔵 TrivialConsider an audit trail for agent-minted observer links.
get_observer_urllets an AI agent mint a follow-along link without an explicit CLI invocation by a human. Consider emitting a telemetry event or log line when a token is created through this tool, distinct fromagent-relay observer, so workspace owners can audit who exposed a follow-along view and when.🤖 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 `@packages/cli/src/cli/agent-relay-mcp.ts` around lines 582 - 643, The get_observer_url tool currently mints observer tokens without recording an audit event. Add a telemetry event or log entry immediately after successful createObserverToken validation, including the workspace, creation time, token identifier, and MCP-tool source; keep it distinct from the agent-relay observer command and avoid logging the token material or generated URL.
🤖 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 `@packages/cli/src/cli/agent-relay-mcp.ts`:
- Around line 582-643: The get_observer_url tool currently mints observer tokens
without recording an audit event. Add a telemetry event or log entry immediately
after successful createObserverToken validation, including the workspace,
creation time, token identifier, and MCP-tool source; keep it distinct from the
agent-relay observer command and avoid logging the token material or generated
URL.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 44ceb656-b252-46d8-ac8c-270d1bb53ad2
📒 Files selected for processing (11)
CHANGELOG.mdpackages/cli/src/cli/agent-relay-mcp.tspackages/cli/src/cli/bootstrap.test.tspackages/cli/src/cli/bootstrap.tspackages/cli/src/cli/commands/observer.test.tspackages/cli/src/cli/commands/observer.tspackages/cli/src/cli/lib/observer-url.tspackages/sdk/src/__tests__/thin-client.test.tspackages/sdk/src/messaging/thin-client.tsplugins/codex-relay-skill/SKILL.mdplugins/gemini-relay-extension/GEMINI.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
4 issues found and verified against the latest diff
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="packages/cli/src/cli/lib/observer-url.ts">
<violation number="1" location="packages/cli/src/cli/lib/observer-url.ts:34">
P2: Non-HTTP(S) observer URLs pass validation and receive the bearer token in their query string. Restrict dashboard bases to `http:`/`https:` so a malformed or attacker-controlled setting cannot turn the generated link into a token-exfiltrating `data:`/custom-scheme URL.</violation>
</file>
<file name="packages/cli/src/cli/agent-relay-mcp.ts">
<violation number="1" location="packages/cli/src/cli/agent-relay-mcp.ts:620">
P2: An invalid `RELAY_OBSERVER_URL` creates a live 24-hour token and then fails before returning its URL or token material, leaving an unshareable credential active. Resolve/validate the observer base URL before minting so this configuration error has no token-creation side effect.</violation>
</file>
<file name="packages/cli/src/cli/commands/observer.ts">
<violation number="1" location="packages/cli/src/cli/commands/observer.ts:87">
P3: Repeated channel names can cause `--channels` to fail despite being collapsed before the SDK request. Apply the limit to the unique filter count.</violation>
</file>
<file name="packages/cli/src/cli/commands/observer.test.ts">
<violation number="1" location="packages/cli/src/cli/commands/observer.test.ts:57">
P3: This suite leaks environment mutations into other tests because `process.env` is changed directly without restoration. Using Vitest environment stubs and calling `vi.unstubAllEnvs()` in `afterEach` would preserve test isolation.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| try { | ||
| // Fail here rather than emitting a malformed link the caller only discovers | ||
| // after pasting it somewhere public. | ||
| new URL(value); |
There was a problem hiding this comment.
P2: Non-HTTP(S) observer URLs pass validation and receive the bearer token in their query string. Restrict dashboard bases to http:/https: so a malformed or attacker-controlled setting cannot turn the generated link into a token-exfiltrating data:/custom-scheme URL.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/cli/lib/observer-url.ts, line 34:
<comment>Non-HTTP(S) observer URLs pass validation and receive the bearer token in their query string. Restrict dashboard bases to `http:`/`https:` so a malformed or attacker-controlled setting cannot turn the generated link into a token-exfiltrating `data:`/custom-scheme URL.</comment>
<file context>
@@ -0,0 +1,57 @@
+ try {
+ // Fail here rather than emitting a malformed link the caller only discovers
+ // after pasting it somewhere public.
+ new URL(value);
+ } catch {
+ throw new Error(`Invalid observer URL: ${value}`);
</file context>
| const session = getSession(); | ||
| requireWorkspaceKey(session); | ||
| const lifetimeHours = expires_in_hours ?? 24; | ||
| const token = await createObserverToken({ |
There was a problem hiding this comment.
P2: An invalid RELAY_OBSERVER_URL creates a live 24-hour token and then fails before returning its URL or token material, leaving an unshareable credential active. Resolve/validate the observer base URL before minting so this configuration error has no token-creation side effect.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/cli/agent-relay-mcp.ts, line 615:
<comment>An invalid `RELAY_OBSERVER_URL` creates a live 24-hour token and then fails before returning its URL or token material, leaving an unshareable credential active. Resolve/validate the observer base URL before minting so this configuration error has no token-creation side effect.</comment>
<file context>
@@ -577,6 +579,63 @@ function registerAgentRelayTools(
+ const session = getSession();
+ requireWorkspaceKey(session);
+ const lifetimeHours = expires_in_hours ?? 24;
+ const token = await createObserverToken({
+ workspaceKey: session.workspaceKey as string,
+ name: `observer-mcp-${Math.random().toString(36).slice(2, 10)}`,
</file context>
| if (names.length === 0) { | ||
| throw new InvalidArgumentError('Expected at least one channel name.'); | ||
| } | ||
| if (names.length > MAX_CHANNEL_FILTERS) { |
There was a problem hiding this comment.
P3: Repeated channel names can cause --channels to fail despite being collapsed before the SDK request. Apply the limit to the unique filter count.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/cli/commands/observer.ts, line 87:
<comment>Repeated channel names can cause `--channels` to fail despite being collapsed before the SDK request. Apply the limit to the unique filter count.</comment>
<file context>
@@ -0,0 +1,219 @@
+ if (names.length === 0) {
+ throw new InvalidArgumentError('Expected at least one channel name.');
+ }
+ if (names.length > MAX_CHANNEL_FILTERS) {
+ throw new InvalidArgumentError(`Expected at most ${MAX_CHANNEL_FILTERS} channel names.`);
+ }
</file context>
|
|
||
| describe('agent-relay observer', () => { | ||
| beforeEach(() => { | ||
| process.env.RELAY_WORKSPACE_KEY = WORKSPACE_KEY; |
There was a problem hiding this comment.
P3: This suite leaks environment mutations into other tests because process.env is changed directly without restoration. Using Vitest environment stubs and calling vi.unstubAllEnvs() in afterEach would preserve test isolation.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/cli/commands/observer.test.ts, line 57:
<comment>This suite leaks environment mutations into other tests because `process.env` is changed directly without restoration. Using Vitest environment stubs and calling `vi.unstubAllEnvs()` in `afterEach` would preserve test isolation.</comment>
<file context>
@@ -0,0 +1,159 @@
+
+describe('agent-relay observer', () => {
+ beforeEach(() => {
+ process.env.RELAY_WORKSPACE_KEY = WORKSPACE_KEY;
+ delete process.env.RELAY_OBSERVER_URL;
+ delete process.env.RELAY_BASE_URL;
</file context>
2 participants
Summary
Letting a human watch a workspace live had no supported path, so the guidance we ship told agents not to offer one.
The engine rejects a workspace key on the realtime endpoint (
GET /v1/ws) and accepts only a scopedot_live_observer token. But nothing in the CLI or MCP server minted one — greppingpackages/cli/srcfor "observer" returned exactly one hit,cloud-room.ts:197, which rejects observer tokens. The only real routes were a hand-rolledPOST /v1/observer-tokensor pasting an admin key into the dashboard login so it mints one server-side.So
plugins/codex-relay-skill/SKILL.mdandplugins/gemini-relay-extension/GEMINI.md(from #1405) said observation "requires a separately provisioned, read-only observer token" and to "omit the observer link" when none exists. Correct about the danger, but with no reachable happy path it means nobody ever gets a link. Meanwhile the skills repo'srelay-team/relay-fanout/relay-pipelineskills still mandate the opposite — printing the rawrk_live_key in a URL, "This is mandatory" — which is the thing #1380 is meant to stop. This PR gives all of them one satisfiable answer.What's added
agent-relay observer— mints a scoped token and prints the observer URL built from it.observer listandobserver revoke <id>manage existing tokens.get_observer_urlMCP tool — same thing for an orchestrating agent, so a lead can hand the user a link without shelling out.createObserverToken,listObserverTokens,revokeObserverTokenfrom@agent-relay/sdk.The frontend already works:
RelaySessionProvider.tsx:29in relaycast acceptsot_live_in?key=exactly likerk_live_, so a scoped token is a drop-in URL replacement with no dashboard change.Defaults, and why they differ from the dashboard's
The observer dashboard already auto-mints a token on workspace-key login (
observer-dashboard/src/lib/observer-token.ts): 30-day expiry,include_dms: true. That is right for a token backing a browser session behind an httpOnly cookie. It is wrong for a token printed as a URL and pasted into chat, so this command defaults to 24 hours with agent DMs excluded, widened explicitly:These two defaults are the main judgement calls in this PR — easy to change if you'd rather match the dashboard.
observerUrl()throws on any credential that isn't anot_live_token, so the workspace-key-in-a-URL failure this command exists to prevent can't be reintroduced by a later caller.Also updates the Codex skill and Gemini extension text to point at the command rather than describing the link as unobtainable. This is the first of several PRs from a review of the Agent Relay skills and plugins; the skills-repo side (including the
relay-*plugin skills that print raw keys) follows separately.Test Plan
packages/cli/src/cli/commands/observer.test.ts(9 tests): default posture assertsincludeDms: falseand a 24h expiry; asserts the printed URL carries the token and that the workspace key appears nowhere in output;#-stripping and dedup on--channels;--expires 24is rejected rather than guessed as hours or ms; missing token material fails loudly;observer listnever printsot_live_;observerUrlrefuses a workspace keypackages/sdk/src/__tests__/thin-client.test.ts(3 tests) covering the SDK helper's own scope/filter defaults, which the CLI tests stub outpackages/clisuite green — 899 passed, 11 skippedpackages/sdksuite green — 166 passednpm run typecheckclean (exit 0)bootstrap.test.tscommand inventory updated.observeris a group with a default action, so the leaf-path walk skips it — added an explicit assertion so the primary command can't be dropped silentlypackage-lock.jsondrift thatnpm installintroduced (committed lockfile still reads 11.2.0 vs package.json 11.4.0 — worth a separate look)agent-relay observeragainst a real workspace before merge to confirm the minted token opens the dashboardScreenshots
n/a
Generated by Claude Code