README.md 7.9 KB
description: "Subagent conversation catalog, continuation routing UI, and '@' reference source for the dsh web client."
kind: "package-reference"
@deepseek-ai/dsh-client-ui-subagent
English | 中文
Summary
Use this package to browse every subagent conversation beneath a parent session, open any descendant, and see whether it is running together with its token usage and active-turn duration. Completed one-shot conversations open as read-only execution records. Continuable conversations accept follow-up prompts in submission order while they run and provide Stop independently. The ordinary session sidebar omits subagent conversations, so the parent header catalog is their navigation entry point. The separate @ source inserts a running child's label into a user message without resolving it into a continuation address.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The session header keeps the current session title as the lineage breadcrumb and, when the session has subagent descendants, appends a / count trigger before the header's action row; the trigger opens the descendant catalog, counts the complete subagent-only lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. Select any depth to open that child's conversation with its exact {parentSessionId, childSessionId, mode} address, or use the row's trailing arrow to open the same address in the right Sidebar, preferring a separate pane when room permits.
This package registers the dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode> resource and builtin Sidebar tab type. The resource refreshes the direct-parent catalog before it retains the child SessionReference, and releases the reference when the tab record closes. The tab renders the shared conversation.content Factory through sidebar.chat.conversation, fixes the local View to Chat, and omits the main Conversation header and width controls.
Browsing the tree
Rows display mode plus running/inactive activity and an optional log-backed title; the trailing column stacks total durable provider usage above active-turn duration. Keyboard navigation works with ArrowRight/ArrowLeft to expand and collapse branches and ArrowUp/ArrowDown, Home, End, and Escape to navigate or close the tree. An unlabeled one-shot row falls back to its session id; corrupt, unsupported, or unavailable rows remain readable but disabled.
Continuing a conversation
A continuable child with a live parent keeps the ordinary input chrome: typing and Send stay available while the child runs because every follow-up joins the child's FIFO inbox, and an independent Stop routes through subagents/interruptByParent. A continuable child whose exact parent is unavailable and which is not running elects a read-only composer explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer with input and Send disabled but its independent Stop usable.
The @ reference source
The @ source remains deliberately separate and inert: candidates are zero-RPC running children from ctx.sessions.list, picking one inserts literal @label text, and the codec projects @label. It has no command-adjudication hooks and does not resolve labels into continuation addresses.
Understand the implementation
Implementation internals — click to expand
The catalog and composer behavior are specified by the [Web subagent conversations note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md). ### Catalog derivation The header lineage renderer reads `subagentsByParent` and session summaries through the standard `useSessions` hook. The compact tree remains direct-catalog authoritative: each healthy row's `hasChildren` hint determines disclosure before interaction, a catalog level reserves the disclosure column only when at least one healthy row is a branch, and expanding a branch immediately reserves one disabled loading row per known direct descendant before lazily replacing them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. ### Duration and tokens Token totals sum the four disjoint `tokenUsage` buckets. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. ### Composer election One-shot children always elect a read-only composer. A continuable child elects one only when its exact parent is unavailable and the child is not running; otherwise the ordinary composer's Session routes prompts through `subagents/prompt`. This package never receives host context or calls a model-facing tool.Further Exploration
These pages cover the conversation surface, the host seam, and the design notes.
- ui-conversation — the chat surface hosting the header action and composer chain.
- ui-input-trigger — the suggestion machinery hosting the
@source. - subagent — the host-side capability seam behind continuable children.
- Web subagent conversations — the catalog and composer specification.
- Current-turn interrupt — the independent Stop semantics.
Model Experience
Subagent label text in the user prompt
What the model sees
Only the @ reference source affects model input: a picked candidate reaches the ordinary user message as literal @label, without a dedicated block or host-side resolution. Catalog browsing, child navigation, and persisted transcript viewing add no prompt section; accepted continuation content becomes a normal FIFO user message through the host subagent adapter.
Token effect
Conditional and append-only: the literal @label or a human follow-up adds tokens only to its new user message. Catalog and transcript operations add zero model tokens.
KV Cache effect
Append-only. This package never edits earlier request tokens.
Known Limitations and Deferred Work
These limits define what the catalog can show and what @ references mean; they are current package constraints.
- The catalog has no durable outcome — activity and timing do not distinguish completion, failure, or cancellation, and the UI exposes no Activation identity; stopping is limited to the composer's current-turn Stop for a running continuable child.
@references remain display-title text — duplicate or renamed labels are ambiguous, so they intentionally do not acquire continuation semantics.
Dev Note
Working context for maintainers — click to expand
None.Runtime invariant: No companion is published. The plugin registers a single slash source whose disposal is proven by the HMR-safety spec; it emits no Cordis events and owns no cross-plugin mutable state.