7.3 KiB
description, kind
| description | kind |
|---|---|
| Subagent conversation catalog, continuation routing UI, and '@' reference source for the dsh web client. | package-reference |
@deepseek-ai/dsh-client-ui-subagent
English | 中文
Summary
dsh-client-ui-subagent is the web client's subagent conversation feature: users browse and open subagent conversations from the parent session's header, continue them through reason-specific read-only composer states, and reference running children with the @ source. From the parent session's header, users browse the complete subagent-origin descendant lineage — each row shows mode, running activity, token usage, and active-turn duration — and open any depth with the child's exact address. A one-shot child always opens a read-only composer identifying the transcript as a completed execution record; a continuable child routes follow-up prompts through its FIFO inbox while it runs. Subagent-origin Session rows are omitted from the ordinary sidebar, so the parent header catalog is their navigation entry point.
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.
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 and the current-turn interrupt note.
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.