docs(cli): document opening a specific agent session via deep link

Merged
RO
5mo ago
+65-1

Summary

  • Document the previously-undocumented superset://v2-workspace/<id> deep-link query params used to focus a specific agent session in the desktop app (#5029): ?chatSessionId= (chat sessions), ?terminalId= (terminal sessions), and optional &focusRequestId= to force a re-focus.
  • apps/docs/content/docs/cli/cli-reference.mdx: new "Opening a specific session" subsection under workspaces open, with the kind→param mapping from agents run --json, bash examples, and a cross-platform opener note.
  • skills/superset/SKILL.md: new "Opening sessions in the desktop app" section (same scheme/table/examples plus the $SUPERSET_WORKSPACE_ID/$SUPERSET_TERMINAL_ID shortcut and the "fresh session is invisible until opened" gotcha), an --agent superset mention, and a kind note in the Agents section.

Why / Context

superset workspaces open <id> only ever targets a workspace — it fires superset://v2-workspace/<id> with no query string, and a session created via agents run has no pane and no session-list entry until you navigate to it, so a freshly created session is effectively invisible. The desktop route already parses chatSessionId/terminalId/focusRequestId and focuses/adds the matching pane, but the only way to use it was to hand-build the URL — and that was undocumented. This PR documents the workflow.

Verification (docs vs. source)

Every command, URL, param, and the kind→param mapping was checked against the code:

  • Bare URL + --print: packages/cli/src/commands/workspaces/open/command.ts
  • agents run --json → { kind, sessionId, label }; kind is chat for superset, terminal for claude/codex: packages/cli/src/commands/agents/run/command.ts + host-service agents.ts (input.agent === "superset" → runChatAgent)
  • validateSearch parses all three params and the pane is focused/added with workspace-ownership enforced: desktop v2-workspace/$workspaceId route + useConsumeAutomationRunLink (focusRequestId is part of the consume key, so it forces re-focus)
  • Cross-platform opener (open / xdg-open / start) matches the CLI's own openUrl platform branching.

Testing

  • Docs-only; reviewed rendered MDX (tables, fenced code, anchors). Both cross-reference anchors resolve.
  • Biome ignores .md/.mdx, so no lint impact.

Notes

  • The SKILL.md edit lands in one tracked file but applies in three places: plugins/superset/skills/superset is a symlink to skills/superset, and the marketing .well-known/agent-skills route reads skills/superset/SKILL.md dynamically — so the bundled plugin and the served skill stay in sync with no duplicate blobs.
  • Opened from a fork (robertn702:adorable-chimpanzee) as the author lacks direct push access.
Open in Stage

Summary by cubic

Document deep links for opening a specific agent session in the desktop app. CLI docs and skills/superset/SKILL.md now show how to build superset://v2-workspace/<workspaceId> URLs with ?chatSessionId=/?terminalId= (optional &focusRequestId=), include the kind→param mapping with a bash --json round-trip example, and align placeholder casing and opener notes.

Summary by CodeRabbit

  • Documentation
    • Added guidance for opening specific agent sessions from the CLI, including how to deep-link to chat vs. terminal sessions
    • Documented response fields used to construct session links and provided example deep-link URLs and query parameters
    • Added note to append a focusRequestId when reopening the same link and platform-specific URL-opener tips for Linux/Windows