description, kind
| description | kind |
|---|---|
| Coordinate subagents through a durable shared task board and change waits in experimental Team compositions. | package-reference |
@deepseek-ai/dsh-experimental-agent-team
English | 中文
Summary
dsh-experimental-agent-team turns an agent and its subagents into a Team with a durable shared task board. Standard subagent tools create and message teammates by id. Team adds compare-and-set task ownership, progress waits, and a roster for the Web panel. Mount dsh-experimental-tool-agent-team for model tools. The package is experimental, and members share one checkout.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Add this package when subagents need a shared working directory, durable task board, and change waits. Mount it with @deepseek-ai/dsh-experimental-tool-agent-team for model tools.
When to choose it
Choose it when delegated agents must divide and track shared work in one checkout. Plain subagents suffice when delegated work needs no shared board. Separate working directories, coordination across processes, and automatic task-owner release are unsupported.
Smallest working setup
Mount both Team packages in a composition that already provides continuable subagents, their messaging tools, and durable session storage, such as a profile built on @deepseek-ai/dsh-base:
# smallest Team addition over a composition with continuable subagents
- name: '@deepseek-ai/dsh-experimental-agent-team'
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
For example, ask the model to start a subagent to review the diff and track its work on the task board. The one limit is optional and validated at startup:
| Field | Default | Meaning |
|---|---|---|
maxTasks |
256 |
Maximum non-deleted tasks on the board |
The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc. A row that sets maxMembers, maxMessageBytes, or disposalTimeoutMs does not activate, and dsh names the key in its startup warning; the upgrade guide lists the replacements.
Teammates
Ask the Lead to start a subagent with a unique name and a description of its work: subagent starts fresh, while subagent_fork inherits completed turns. The returned name addresses the teammate; descriptions may repeat.
Every root agent leads its own Team, and every live subagent below it, at any depth, receives Team tools. The roster lists the Lead, its direct continuable children, and historical team/member records. Deeper descendants work on the same board under their Session ids but have no roster row.
Messages between teammates
Members use standard send_message with agent names: the Lead reaches direct children, and resident continuable children reach their parent and continuable siblings. Steer delivers into the target inbox and can cold-resume children or siblings. Team stores no messages; accepted messages follow ordinary Agent persistence.
Shared task board
Any member can add a task with a title, details, optional dependencies on other tasks, and optional hints about which files it will touch. A task is claimable only when everything it depends on is complete.
A member claims a task to start work, completes it, releases it, or reopens it. The Lead can reassign a task by agent name to itself, a direct continuable child, or an active historical member. Other members claim tasks themselves. Every change is compare-and-set, so stale updates cannot overwrite newer work.
File hints produce warnings when two in-progress tasks plan to touch overlapping paths — they never block anything. Deleted tasks remain in history but disappear from the active list.
Waiting and interruption
A member can wait for the next Team change — a task update, a member's status change, or a message a member's inbox accepts — instead of polling repeatedly; the wait reports only whether it timed out, and the caller re-reads the current state afterward.
An ancestor stops a teammate's current turn with the standard interrupt_agent tool, so only the Lead interrupts its direct teammates. Interruption keeps unclaimed queued messages and leaves task ownership unchanged.
What success and failure look like
Success returns an updated task revision or a wait result. Unknown member ids, unready tasks, stale revisions, unauthorized mutations, and an exhausted task limit report a TeamError, such as TEAM_TASK_STALE_REVISION. A caller outside a live Team receives TEAM_NOT_MEMBER.
Understand the implementation
Implementation internals — click to expand
This section explains the design decisions behind the service and points at the code that realizes them; the observable behavior is fully covered in Use this package.
Design philosophy
The service is built on four commitments:
- Membership from lineage. The live Agent registry and the Lead's subagent catalog define the Team; Team stores no membership record of its own.
- Durable log, derived state. The Lead log owns tasks and child catalog facts; each target Agent owns accepted messages.
- Explicit authority. Every service method takes the exact live calling
Agent; a task owner or the Lead mutates a task, and only the Lead reassigns one. - Bounds that fail loud.
maxTasksis a validated deployment value, and exhaustion reports a typed error instead of reusing an id.
The subagent teammates Agent Note owns the membership, roster, and messaging decisions. The runtime-context identity decision owns model-facing identity.
Source map
| File | Role |
|---|---|
src/index.ts |
Plugin entry: Config schema, removed-key rejection, service registration, change notification |
src/membership.ts |
Lead and teammate resolution through the live Agent registry, and task-assignee lookup |
src/task-board.ts |
Task CAS commands, DAG validation, and derived views |
src/journal.ts |
Serialized Lead-log transactions and commit notification |
src/projection.ts |
Strict replay projection of the Lead’s continuable children and Team events, publishing the agentTeam client view |
src/task-view.ts |
Pure task readiness and write-overlap derivation shared by the task board and client view |
src/activity.ts |
One-shot change waiters and disposal release |
Team identity and membership
A root Agent whose own log carries no subagent descriptor leads the Team identified by its Session id. tryMembership() walks parentSession through the live registry; a missing parent leaves the subagent without membership. An ordinary fork carries at most an inherited descriptor, so it leads a new Team. Membership records only the root, Team id, and role.
Roster
The projection folds the Lead’s own subagent/catalog facts into rows keyed by child id, using the catalog label as description. Continuable children are included; inherited facts and other modes are skipped. Descriptions need not be unique. Historical team/member records retain their phases and descriptions and add only ids absent from the catalog. Team writes no membership records.
Messages and historical mailbox
Team sends no messages. Routes, Steer delivery, cold resume, and sender framing for send_message belong to the subagent runtime. Historical team/message/queued and team/message/delivered records and team-message sources remain decodable; Team never delivers or acknowledges them, so a historical message its target had not recorded stays undelivered.
Shared task board
Tasks are complete versioned snapshots; every mutation carries expectedRevision, and a stale caller receives TEAM_TASK_STALE_REVISION instead of overwriting a newer value. Numeric task-<n> ids require a safe-integer suffix, and id-space exhaustion reports TEAM_TASK_LIMIT instead of reusing the final id. Deleted tasks remain tombstones for replay and id stability but do not consume maxTasks or appear in listTasks(). writeScopes are normalized workspace-relative prefixes; views warn on overlap with in-progress tasks but never block claim or authorize writes. Lead reassignment resolves the root, a direct continuable child, or an active historical member by Session id, and reports TEAM_MEMBER_NOT_FOUND for anything else.
Waiting
waitForChange() waits for one task commit, member agent/status change, or member agent/inbox/inserted edge that occurs after registration, from ten seconds through one hour, and reports only whether it timed out; unloading the service releases current waits. Cancellation preserves an Error reason or reports a non-Error reason through TEAM_WAIT_ABORTED. hasActivePeer() reports whether another live member is running a turn, which lets wait_agent skip a wait that no member can end.
Durability model
Task mutations append team/task to the exact live Lead Session and flush before reporting success or waking waiters. Team events are log-only: they never enter the conversation surface, so derived model history is untouched by coordination records. Session event seq and time own ordering and timing; snapshots do not duplicate them. Teammate ids and descriptions live in the Lead's subagent/catalog, which the subagent runtime writes.
Mailbox projection and checkpoint admission preserve every decoded JSON field of accepted content outside the locally declared validators, including an own __proto__ key. Local field checks cover text, reasoning, image, and tool-call; accepted unknown tags remain opaque. Team projection cache version 5 rebuilds checkpoints from earlier cache versions from the Session log; the Session format version is unchanged.
Disposal
Unloading the service releases current waits and unregisters the projection. Team owns no Agent: teammates keep running under the subagent runtime, which owns their capacity, settlement, and teardown.
Browser projection
The agentTeam Session projection publishes the Lead Session's roster rows with their phases and errors, non-deleted task views, and any failure beside the last valid state. Its apply replaces only the touched collection; mailbox-only changes retain the client view reference and produce no frame. The subsystem reference defines the wire types.
The Web UI reads the shared Session projections and overlays activity from Session status. Task creation and updates belong to Team agents through the service and model tools. The ./client export supplies browser-safe roster, task, and projection types.
Further Exploration
Read these pages when the package-level contract is not enough. They move from the shared subsystem types to the tool surface and the decisions behind the design.
- Agent Teams subsystem — durable Team types and the
ctx.agentTeamsservice API. - tool-agent-team package — the task and wait tools, policy, and identity every member receives.
- Subagent runtime — continuable children, messaging, interruption, and lifecycle that teammates use.
- Subagent teammates Agent Note — why teammates are subagents and what Team keeps.
- Upgrade guide — replacements for the removed Team tools, service methods, and configuration keys.
- Experimental package reference — placement, publication, and dependency isolation.
Model Experience
Task views and errors
What the model sees
The model sees Team state through task-tool results; coordination events never enter the conversation. Model-facing task views identify their owner through ownerName; host views retain ownerId. Failures surface as tool errors with the TeamError message, including the current revision for stale updates.
Token effect
The domain adds no context of its own; each task-tool result costs one compact task view per returned task. Policy, identity, and tool schemas belong to @deepseek-ai/dsh-experimental-tool-agent-team.
KV Cache effect
Task commits append only log-only events to the Lead Session, so they never change any member's request prefix; task results append after it.
Known Limitations and Deferred Work
These limits describe what a team cannot do yet or what needs special operational care. They are current package constraints, not a comparison with other coordination mechanisms.
- Whole-view broadcasts — each roster or task change sends the complete roster and non-deleted task board, including descriptions, to every connected browser, even when it is viewing another Session.
- Experimental prototype with no stability promise — the package is public, but its contracts can change freely while it incubates.
- One process and one shared checkout — members share cwd and observe edits immediately; this package provides no worktree, remote member, merge, or filesystem lock.
- Advisory write scopes — Bash, formatters, code generators, and direct external writers can bypass filesystem version checks; Leads must coordinate ownership and review the final diff.
- Roster covers direct continuable children — deeper descendants share tasks and waits but have no roster row; they can claim tasks under their own ids and message only their direct parent, children, and continuable siblings.
- Membership needs a live lineage — a subagent whose parent Agent is not loaded is outside every Team, so its Team calls fail with
TEAM_NOT_MEMBER. - No automatic ownership release — inactivity, interruption, process exit, and failed work do not release a task owner.
- Historical queued messages stay undelivered —
team/message/queuedrecords without a matching delivery remain readable in the Lead log, but no member receives them.
Dev Note
Working context for maintainers — click to expand
This Dev Note is working context for maintainers and is explicitly non-authoritative.
Promotion
Promotion to a product-role group requires reviewing the public contract, limitations, test evidence, release payload, runtime dependents, and a named stable owner, per the experimental subtree rules.
Future directions
Undecided directions include nested Teams, automatic ownership release policies, and filesystem isolation via worktrees; none of these are committed.