description, kind
| description | kind |
|---|---|
| Bind readable subagent names to Session ids and recover the mappings from the root Session. | package-reference |
@deepseek-ai/dsh-subagent-names
English | 中文
Summary
Address delegated agents by readable names such as lead/research and lead/research/checker. Bound names survive root Session reloads and keep the same spelling after agents finish. Choose this package when delegation tools need names while preserving Session ids for execution and authorization. Agents without a bound name remain addressable by id.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Mount this plugin with the naming-aware delegation tool and control tools.
Minimal configuration
Add this row to a composition providing sessionProjections:
- name: '@deepseek-ai/dsh-subagent-names'
This plugin has no configuration fields. It exposes ctx.subagentNames; the subagent service owns execution, messages, discovery, and authorization.
Choosing and finding names
A requested name segment starts with a lower-case letter and contains only lower-case letters, digits, underscores, and hyphens. Omission selects the first available agent-N under the parent's name, starting at agent-1. Reservations prevent concurrent starts from choosing the same full name. A bound name remains occupied after execution settles.
The root is lead. nameOf returns a bound full name, or the original Session id when no binding exists. resolveName accepts lead and bound full names; it rejects an unknown lead/... name and passes other ids through. The subsequent subagent operation still authorizes the caller.
Binding after startup
Resolve rootSession = ctx.subagents.rootOf(parent).session, then call reserve(rootSession, parent.id, requested?), start the child through ctx.subagents.startActivation, then call bind(rootSession, childId, reservation.name) with the successful receipt. Release the reservation with dispose() in finally, whether startup and binding succeed or fail.
Binding records the full name in the root Session. If binding fails after startup succeeds, the caller must report the already-started child id; the child remains managed by the subagent service. A crash before binding can likewise leave an unnamed child that remains addressable by id.
Understand the implementation
Implementation internals — click to expand
Each root Session stores its own name-to-id bindings. All naming operations receive that root Session explicitly; the naming service does not resolve live Agent membership. A projection recovers those bindings and excludes inherited fork records. Lookups read this root mapping without observing ancestor Sessions or joining child catalogs. Callers own transient reservations and release them after their operation.
The mapping retains one binding per named child: storage is O(n), a lookup or binding is O(n), and replaying n distinct bindings is O(n²) in the worst case because each event searches the binding array.
| File | Role |
|---|---|
src/index.ts |
Name reservations, binding, and lookup |
src/projection.ts |
Durable bindings and replay validation |
Further Exploration
These pages own execution and the model-facing tools that use names.
- Subagent service — activation ownership, catalogs, and authorization.
- Delegation tool — named creation and start acknowledgements.
- Control tools — discovery, messaging, and interruption.
- Session projections — incremental recovery.
Model Experience
Indirectly, through the delegation tool and control tools, which render names alongside Session ids and accept names as addresses.
KV Cache effect
The subagent message service reads sender names from this service automatically. This plugin adds no prompt text or tool schema. Its consumers own any model-visible name text and its cache effect.
Known Limitations and Deferred Work
Name bindings have these limits:
- Names are available after binding — the child's first request may precede its binding; this plugin adds no initial identity message.
- Names are immutable — bound names and ids cannot be reassigned or reused after an activation ends.
- Paths capture the parent's name at reservation time — an unnamed parent uses
lead/legacy:<parentId>as its prefix; a later parent binding does not rewrite the child's stored path. - Naming is explicit — callers that do not bind a name continue to use Session ids.
Dev Note
Working context for maintainers — click to expand
None.