feat(chat): pdev subagents as steerable child sessions, one drawer for running work, pdev 0.2.0
Links
- pdev 0.2.1 release: https://github.com/superset-sh/pdev/releases/tag/v0.2.1 (source: superset-sh/router#7, #8, #9)
Summary
This PR bundles three related changes:
- pdev subagents in chat. Each pdev subagent is its own ACP child session. In the transcript, a subagent appears as an event line ("X started working" / "X finished"). Clicking the line opens the subagent in the same pane, with a breadcrumb in the pane header and Esc to go back. From there you can message or steer it, stop it, or move it to the background.
- One drawer for queued prompts and running work. It sits above the composer and holds queued prompts, running subagents and background shells, with keyboard navigation and a height cap. A subagent waiting on its own subagents shows
+Nand "waiting on N subagents". - pdev 0.2.1 bundled in the desktop and in cloud workspaces, and the chat event mapper shared by the main session and every subagent session (
SessionStream).
Also includes:
- A subagent's approvals show in the main chat, labelled with the subagent's name.
- A failed subagent stays messageable when pdev can resume it.
isMissingProcedureErrormoves to@superset/shared.- Cloud workspaces get pdev 0.2.1: a
pdevasset row inpackages/sandbox(linux-x64 release tarball, checked against the release digest), unpacked into/opt/pdev/<sha>byinstall-agent-clisand linked to/usr/local/bin/pdev; memguard ranks it as a session. Because this touches the bundle, the merge runsproduction-releaseand boxes pick it up on their next wake. - Subagents and background tasks are removed from the workspace activity menu on purpose: they live in each chat's drawer. The menu lists pages and backgrounded terminals.
Part 1: pdev subagents as child sessions
Why
Before this change, a pdev subagent ran inside one collapsed tool call. You couldn't see it working, message it, or tell it apart from the main agent. We want Claude Code's model: named subagents you can resume, a way to message them, foreground or background, and nesting. All of it goes over ACP rather than through hacks.
What / How
packages/chat-runtimeACP adapter- Implements the ACP v2 prompt lifecycle and the Subagent Sessions RFD (
subagent_update,session_message*, events arriving on the child'ssessionId). - Superset-specific parts are under
_meta["sh.superset"]: whether a subagent can be prompted or moved to the background, its name and status. Moving to the background is_sh.superset/subagent/background. - The text, tool and approval mapping now lives in one
SessionStream, used by the main session and every child session. - Approvals follow their subagent: the main turn ending doesn't cancel a running subagent's approval, stopping a subagent cancels its own, and the session status goes back to idle when nothing is running.
- Implements the ACP v2 prompt lifecycle and the Subagent Sessions RFD (
- tRPC: new
steerSubagentandbackgroundSubagentprocedures. Both are additive. Older hosts that lack them make the client fall back to "Update this host to message subagents". - What released clients see: subagent items and their text deltas stay out of what the host sends unless the client opts in with the optional
nestedSubagentsflag (ongetItems,getOutline,getItemBodies, and as?nestedSubagents=1on the session stream). Only the new desktop opts in. Released mobile, older desktops and the CLI keep a main-chat-only view, but a subagent's approval still reaches them. The chat's reply preview and rewind ignore subagent messages. - Desktop UI:
SubagentEventLinein the transcript.SubagentView, which reuses the transcript's nested-items and plugins providers.ChatPaneTitlebreadcrumb in the pane header.useSubagentTarget: the composer addresses the open subagent ("to outer"). A message sent to a running subagent shows as Queued in its view until the subagent takes it. If it can't be delivered, the text goes back to that subagent's draft, even if you've moved to another agent.- The composer takes focus whenever a subagent opens or closes, so Esc always works.
- Mobile: keeps its flat transcript, because it has no subagent view yet. It shows the " asks" label on a subagent's approvals, and it doesn't opt in to subagent items.
Key decisions
| Decision | Choice | Rationale |
|---|---|---|
| Protocol | ACP v2 + Subagent Sessions RFD; extensions only under sh.superset | Easy to migrate when ACP adopts subagents upstream; no client-side guessing |
| Going into a subagent | Opens in the same pane, breadcrumb in the header | One composer, so a message can't go to the wrong agent |
| Nested subagents | A tree: a subagent stays running while its own subagents run, and reports once | Claude Code reports nested agents to main, so outer never gets their results; checked live in its TUI |
Part 2: One drawer for queued prompts and running work
Why
Running subagents above the composer collided with the queued-prompt tray. Of the options I mocked up, you picked one drawer with two sections.
What / How
WorkDrawerhas a Queued section and a Running section. Each section collapses, with a count and, when collapsed, a summary such as "2 subagents · 1 shell".- Rows show the current step and elapsed time.
- The drawer is capped at a third of the pane and scrolls inside.
- Only top-level running subagents get a row. A subagent's own running subagents fold into its row as
+N.
Keyboard
| Key | Action |
|---|---|
| ↑ from an empty composer | Into the drawer (bottom row first); past the top row, into prompt history |
| ↓ | Back toward the composer |
| Enter on a row | Steer a queued prompt / open a subagent |
| Enter or Space on a section header | Collapse or expand the section |
| Backspace | Remove a queued prompt / stop a shell |
| Esc | Back to the composer; inside a subagent, back to its parent |
Manual QA Checklist
Done in the dev app over CDP, with pdev 0.2.0 and the real model.
Subagents
- Background subagents show as event lines; clicking one opens it with the breadcrumb, and Esc returns with the composer focused
- Steering a running subagent and messaging an idle one from its view;
send_messagefrom the main agent - Stop and Move to background; the main agent wakes when a background subagent reports
- In ask mode, a subagent's approval shows in the main chat ("pinger asks: Allow Bash: sleep 3?"); "Always allow" carries over to later subagents
- Nested
outer→inner-1/inner-2:outershows+2 · waiting on 2 subagents, then one "outer finished" and one report holding both inner results - A background shell's end wakes the agent with its exit status
Drawer
- 9 running rows: height capped, scrolls, elapsed time ticks
- Arrow keys through rows and headers into history; Enter and Space toggle a header; Enter on a row opens a subagent with the composer focused
- Collapsed header summary and padding; icons in the muted tool colour
After merging main (#8585)
- New pane header with the breadcrumb, Chat history button, Edit message, reasoning steps inside tool runs
-
/mcpstill returns "Unknown command" for pdev, same as on main: the picker supports only claude and codex - Every line main added since our old base is present, or replaced on purpose in the conflict files (
SessionView→useMainSend;acpAdaptertext handling →SessionStream)
Testing
-
bun teston the final head:Package Result packages/chat93 pass, 0 fail packages/chat-runtime362 pass, 0 fail packages/shared1437 pass, 0 fail apps/desktop8588 pass, 0 fail apps/mobile232 pass, 0 fail packages/host-service2604 pass, 2 fail The two host-service failures come from this machine, not this branch.
terminal disposal cleans up background process groupsalso fails onmainhere.apiToken refreshes the expired OAuth tokenonly times out in the full run and passes alone. -
tsc --noEmit: clean forchat,chat-runtime,shared,host-serviceandapps/desktop. -
bun run lint: clean. -
bun run check:i18n: no missing messages. -
apps/desktop/scripts/build-bundled-pdev.ts: downloads the published 0.2.1 tarball, and the checksum matches. -
packages/sandbox:bun testpasses (20),bun run buildsucceeds, and the linux-x64 tarball unpacked in an ubuntu:24.04 container runspdev --version→ 0.2.1 through the/usr/local/binlink. -
Live: a message sent to a sleeping subagent shows as Queued. It turns into the subagent's real message when the subagent picks it up, with no duplicate, and the subagent replies with it.
Compatibility
- Released desktop / mobile / CLI: the two new procedures are additive, and existing procedures keep their inputs and outputs. A client talking to an older host falls back as described above.
- Older pdev (0.1.x): still works over ACP v1, without subagent sessions. The pdev catalogue
minVersionstays ungated because the desktop bundles 0.2.1.
Known Limitations
- The Sandbox workflow's Boot twice job (not required) fails on this PR with a 404: the box fetches assets from cdn.superset.sh, and the pdev tarball is uploaded only when the merge publishes the bundle.
build --publishnow downloads an uncached asset from its row'ssourceand checks its sha256, so the publish on a fresh runner works (tested against a local fake bucket). - When a subagent's own subagents finish, its drawer row shows its last tool step for a few seconds, until it settles.
/mcpis not offered for pdev; that comes from main.- There are no new Storybook stories or screenshots; QA was done over CDP.
Rollback
Revert this PR. It has no data migrations, and the new tRPC procedures are additive. superset-sh/pdev v0.2.1 stays published, but nothing uses it once PDEV_VERSION goes back to 0.1.5.
Summary by CodeRabbit
- New Features
- Added nested subagent navigation, breadcrumbs, transcript views, status indicators, approvals, and parent context.
- Added a Work Drawer for queued prompts, active sessions, approvals, task controls, and backgrounding.
- Added support for steering active subagents and moving eligible tasks to the background.
- Improved composer drafts, history recall, keyboard navigation, and target-aware messaging.
- Added requester labels, reply actions, and localized status messages across desktop and mobile.
- Updates
- Updated bundled pdev to version 0.2.0.
- Bug Fixes
- Improved nested message handling, lifecycle previews, stale activity cleanup, and missing-procedure detection.