@@ -671,7 +694,7 @@ function CatalogDropdown({
className={variant === 'switcher'
? `${css.switcherTrigger} ${ancestorSwitcher ? css.ancestorSwitcherTrigger : ''}`
: css.trigger}
- aria-haspopup="tree"
+ aria-haspopup="dialog"
aria-expanded={open}
aria-label={variant === 'switcher'
? t('switcher.aria', { title: switcherDisplayTitle })
@@ -685,6 +708,7 @@ function CatalogDropdown({
cancelHoverClose()
pinnedRef.current = true
if (!open) changeOpen(true)
+ queueMicrotask(() => { menuRef.current?.focus() })
}
: () => {
cancelHoverOpen()
@@ -715,31 +739,40 @@ function CatalogDropdown({
:
}
{open && createPortal((
-
-
-
{ changeOpen(false) }}
- t={t}
- />
+
+
+ { changeOpen(false) }}
+ t={t}
+ />
+
+ {props.footerKind === 'lineage'
+ ? props.renderSlot('conversation.session.header.lineage.subagent.footer', {})
+ : props.renderSlot('conversation.session.header.actions.subagent.footer', {})}
-
+
), document.body)}
)
@@ -747,7 +780,8 @@ function CatalogDropdown({
/** Full props for the root-session catalog entry in the header actions band. */
export type SubagentCatalogActionProps =
- PropsRuntime<'conversation.session.header.actions'> & SubagentCatalogInjected & PropsLocale
+ PropsRuntime<'conversation.session.header.actions'> & InjectFace & PropsLocale
+ & Omit, 'SessionProvider'>
/**
* Session-header catalog action for root sessions: the descendant count and
@@ -758,7 +792,7 @@ export type SubagentCatalogActionProps =
* @returns The count dropdown, or null on a child session.
*/
export function SubagentCatalogAction({
- sessionId, useSessions, useSessionStatus, openChild, openChildAside, refreshProjection, t,
+ sessionId, useSessions, useSessionStatus, useFooterAvailable, openChild, openChildAside, refreshProjection, t, renderSlot,
}: SubagentCatalogActionProps) {
const isChild = useSessions(state => state.byId[sessionId]?.origin === 'subagent')
if (isChild) return null
@@ -767,8 +801,11 @@ export function SubagentCatalogAction({
key={sessionId}
rootSessionId={sessionId}
variant="count"
+ footerKind="actions"
+ renderSlot={renderSlot}
useSessions={useSessions}
useSessionStatus={useSessionStatus}
+ useFooterAvailable={useFooterAvailable}
openChild={openChild}
openChildAside={openChildAside}
refreshProjection={refreshProjection}
@@ -784,7 +821,7 @@ export function SubagentCatalogAction({
*/
export function SubagentHeaderLineage({
lineageSessionId, displayTitle, openTitle,
- useSessions, useSession, useSessionStatus, openChild, openChildAside, refreshProjection, t,
+ useSessions, useSession, useSessionStatus, useFooterAvailable, openChild, openChildAside, refreshProjection, t, renderSlot,
}: SubagentHeaderLineageProps) {
const address = useSession(session => session.subagent?.address)
const parentId = useSessions((state) => {
@@ -795,7 +832,7 @@ export function SubagentHeaderLineage({
const summary = state.byId[lineageSessionId]
return summary?.origin === 'subagent' ? summary.parentId : undefined
})
- const shared = { useSessions, useSessionStatus, openChild, openChildAside, refreshProjection, t }
+ const shared = { useSessions, useSessionStatus, useFooterAvailable, openChild, openChildAside, refreshProjection, t }
// Root sessions carry no breadcrumb; their descendant count lives in the
// header actions band (SubagentCatalogAction).
if (parentId === undefined) return null
@@ -806,6 +843,8 @@ export function SubagentHeaderLineage({
rootSessionId={parentId}
currentSessionId={lineageSessionId}
variant="switcher"
+ footerKind="lineage"
+ renderSlot={renderSlot}
displayTitle={displayTitle}
{...openTitle === undefined ? {} : { openTitle }}
{...shared}
@@ -815,6 +854,8 @@ export function SubagentHeaderLineage({
key={`children:${lineageSessionId}`}
rootSessionId={lineageSessionId}
variant="count"
+ footerKind="lineage"
+ renderSlot={renderSlot}
{...shared}
/>
)}
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 5fec53dd43..ab3eecdf50 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -15,6 +15,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-session/client'
import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
import { en, NS, zh, type SubagentKey } from './locales.ts'
+export type * from './slots.ts'
declare module '@deepseek-ai/dsh-client-ui-slots' {
interface LocaleNamespaceMap {
@@ -51,26 +52,34 @@ export function apply(ctx: ClientContext): void {
ctx.inject(['resources', 'sidebarRightTabs'], (scope) => {
registerSidebarChat(scope, ctx.locale.bind(NS))
})
- const catalogActions = (_parentSessionId: SessionId): SubagentCatalogInjected => ({
- openChild(address: SubagentAddress) {
- ctx.uiWorkspace.openSession(address)
- },
- openChildAside(address: SubagentAddress) {
- ctx.sidebarRight.openResource(subagentChatAddress(address), {
- kind: 'subagentchat',
- preferNewPane: true,
- })
- },
- refreshProjection(parentSessionId: SessionId) {
- void ctx.sessions.refreshProjections(parentSessionId)
- },
- })
+ const catalogActions = (footer: 'conversation.session.header.lineage.subagent.footer' | 'conversation.session.header.actions.subagent.footer') => {
+ const footerAvailable = {
+ getSnapshot: () => ctx.slots.entries(footer).length > 0,
+ subscribe: (listener: () => void) => ctx.slots.subscribe(footer, listener),
+ }
+ return (_parentSessionId: SessionId): SubagentCatalogInjected => ({
+ hooks: { footerAvailable },
+ openChild(address: SubagentAddress) {
+ ctx.uiWorkspace.openSession(address)
+ },
+ openChildAside(address: SubagentAddress) {
+ ctx.sidebarRight.openResource(subagentChatAddress(address), {
+ kind: 'subagentchat',
+ preferNewPane: true,
+ })
+ },
+ refreshProjection(parentSessionId: SessionId) {
+ void ctx.sessions.refreshProjections(parentSessionId)
+ },
+ })
+ }
ctx.slots.inject(
'conversation.session.header.lineage',
() => ctx.slots.register({
name: 'conversation.session.header.lineage',
locale: NS,
- inject: catalogActions,
+ inject: catalogActions('conversation.session.header.lineage.subagent.footer'),
+ children: { 'conversation.session.header.lineage.subagent.footer': { kind: 'list', scope: 'session' } },
}, SubagentHeaderLineage),
)
ctx.slots.inject(
@@ -81,7 +90,8 @@ export function apply(ctx: ClientContext): void {
// Between the preset label (-10) and background tasks (20).
order: 10,
locale: NS,
- inject: catalogActions,
+ inject: catalogActions('conversation.session.header.actions.subagent.footer'),
+ children: { 'conversation.session.header.actions.subagent.footer': { kind: 'list', scope: 'session' } },
}, SubagentCatalogAction),
)
ctx.slots.inject(
diff --git a/packages/client/ui-subagent/src/client/slots.ts b/packages/client/ui-subagent/src/client/slots.ts
new file mode 100644
index 0000000000..279c353b93
--- /dev/null
+++ b/packages/client/ui-subagent/src/client/slots.ts
@@ -0,0 +1,18 @@
+/** Extension positions below the subagent catalog in each header entry. */
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+ interface SlotMap {
+ /** Content below the root Session's subagent tree. */
+ 'conversation.session.header.actions.subagent.footer': {
+ kind: 'list'
+ scope: 'session'
+ }
+ /** Content below a descendant's sibling or child tree. */
+ 'conversation.session.header.lineage.subagent.footer': {
+ kind: 'list'
+ scope: 'session'
+ }
+ }
+}
+
+export {}
diff --git a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
index af5e16e286..5598ffb23a 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
@@ -2,7 +2,7 @@
import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
import { Context } from '@deepseek-ai/cordis'
import { stubConfigForm } from '@deepseek-ai/dsh-client-test-runtime'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, onTestFinished, vi } from 'vitest'
import type {
SessionListState, SessionSnapshot, SessionSummary,
} from '@deepseek-ai/dsh-api-session-controller/client'
@@ -108,6 +108,25 @@ describe('apply', () => {
expect(inject).toEqual(['sessions', 'uiWorkspace', 'slots', 'locale', 'sidebarRight'])
})
+ it('keeps both catalog extensions available when optional Sidebar services arrive', async () => {
+ const { ctx } = await fullBench(FAMILY)
+ onTestFinished(() => ctx.fiber.dispose())
+ for (const name of [
+ 'conversation.session.header.actions.subagent.footer',
+ 'conversation.session.header.lineage.subagent.footer',
+ ] as const) {
+ ctx.slots.register({ name, id: 'test-content' }, () => null)
+ }
+ const registerResource = vi.fn(() => () => {})
+ const registerTab = vi.fn(() => () => {})
+ ctx.provide('resources', { register: registerResource } as never)
+ ctx.provide('sidebarRightTabs', { register: registerTab } as never)
+ await vi.waitFor(() => { expect(registerResource).toHaveBeenCalledOnce() })
+ expect(registerTab).toHaveBeenCalledOnce()
+ expect(ctx.slots.entries('conversation.session.header.actions.subagent.footer')).toHaveLength(1)
+ expect(ctx.slots.entries('conversation.session.header.lineage.subagent.footer')).toHaveLength(1)
+ })
+
it('registers catalog actions and selects read-only subagent composers from session facts', async () => {
const { ctx, face } = await fullBench(FAMILY)
const catalogEntry = ctx.slots.entries('conversation.session.header.lineage')
@@ -139,7 +158,22 @@ describe('apply', () => {
const actionEntry = ctx.slots.entries('conversation.session.header.actions')
.find(entry => entry.options.id === 'subagent-catalog')!
expect(actionEntry.options.order).toBe(10)
- expect(actionEntry.inject).toBe(catalogEntry.inject)
+ const actionProps = (actionEntry.inject as (id: SessionId) => SubagentCatalogInjected)(sid('parent'))
+ for (const [name, source] of [
+ ['conversation.session.header.lineage.subagent.footer', actions.hooks.footerAvailable],
+ ['conversation.session.header.actions.subagent.footer', actionProps.hooks.footerAvailable],
+ ] as const) {
+ const changed = vi.fn()
+ const unsubscribe = source.subscribe(changed)
+ expect(source.getSnapshot()).toBe(false)
+ const remove = ctx.slots.register({ name, id: 'test-footer' }, () => null)
+ expect(source.getSnapshot()).toBe(true)
+ await vi.waitFor(() => { expect(changed).toHaveBeenCalledOnce() })
+ remove()
+ expect(source.getSnapshot()).toBe(false)
+ await vi.waitFor(() => { expect(changed).toHaveBeenCalledTimes(2) })
+ unsubscribe()
+ }
const composerEntry = ctx.slots.entries('conversation.composer')
.find(entry => entry.component === SubagentReadOnlyComposer)!
diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
index 21abd15c01..d28d09b3b5 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
@@ -114,11 +114,13 @@ function props(
...standard,
sessionId: PARENT,
useSessions,
+ useFooterAvailable: (select: (available: boolean) => T): T => select(true),
useSessionStatus: (select: (snapshot: SessionStatusSnapshot) => T): T => select(statuses),
useSession: (select: (snapshot: SessionSnapshot) => T): T => select(snapshot),
openChild: vi.fn(),
openChildAside: vi.fn(),
refreshProjection: vi.fn(),
+ renderSlot: vi.fn(() => null),
lineageSessionId: PARENT,
displayTitle: 'Parent title',
t,
@@ -149,7 +151,11 @@ function hoverCatalog(trigger: HTMLElement): void {
* session the lineage renders.
*/
function HeaderCatalog(props: SubagentHeaderLineageProps) {
- const actionProps: SubagentCatalogActionProps = { ...props, sessionId: props.lineageSessionId }
+ const { __renders: _renders, ...shared } = props
+ const actionProps: SubagentCatalogActionProps = {
+ ...shared, sessionId: props.lineageSessionId,
+ renderSlot: () => props.renderSlot('conversation.session.header.lineage.subagent.footer', {}),
+ }
return (
<>
@@ -159,6 +165,47 @@ function HeaderCatalog(props: SubagentHeaderLineageProps) {
}
describe('SubagentHeaderLineage', () => {
+ it('keeps the shared panel reachable with no children while Team mode is enabled', () => {
+ const input = props(catalog({ entries: [] }))
+ const initial = input.useSessions(state => state)
+ const mode = { enabled: true }
+ const values = { ...initial.projectionsBySession[PARENT]!.values, agentTeamMode: mode }
+ const current = {
+ ...input,
+ useSessions: (select: (snapshot: SessionListState) => T): T => select({
+ ...initial, projectionsBySession: { [PARENT]: { state: 'ready', error: null, values } },
+ }),
+ renderSlot: () => ,
+ }
+ const view = render()
+ fireEvent.click(screen.getByRole('button', { name: '0 个子智能体' }))
+ const tree = screen.getByRole('tree')
+ const board = screen.getByRole('region', { name: 'Shared tasks' })
+ expect(tree.compareDocumentPosition(board) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+ expect(screen.getAllByRole('dialog')).toHaveLength(1)
+ mode.enabled = false
+ view.rerender()
+ expect(screen.queryByRole('dialog')).toBeNull()
+ expect(screen.queryByRole('button')).toBeNull()
+ })
+
+ it('leaves task-board keys alone and dismisses the shared panel from outside focus', () => {
+ const input = props(catalog())
+ render(<> }
+ />>)
+ fireEvent.click(screen.getByRole('button', { name: '1 个子智能体,正在运行' }))
+ const expand = screen.getByRole('button', { name: 'Expand task' })
+ expand.focus()
+ fireEvent.keyDown(expand, { key: 'ArrowDown' })
+ expect(document.activeElement).toBe(expand)
+ const composer = screen.getByRole('textbox')
+ composer.focus()
+ fireEvent.keyDown(composer, { key: 'Escape' })
+ expect(screen.queryByRole('dialog')).toBeNull()
+ expect(document.activeElement).toBe(composer)
+ })
+
it('shows current catalog-only child status before Host list discovery', () => {
const input = props(catalog({ entries: [{ id: CHILD, mode: 'continuable', label: 'worker', activity: 'inactive' }] }))
const initial = input.useSessions(state => state)
@@ -349,7 +396,7 @@ describe('SubagentHeaderLineage', () => {
await advance(149)
expect(screen.queryByRole('tree')).toBeNull()
await advance(1)
- const menu = screen.getByRole('tree').parentElement!
+ const menu = screen.getByRole('dialog')
expect(menu.style.top).toBe('45px')
expect(menu.style.left).toBe('50px')
triggerRect.mockReturnValue({ bottom: 60, left: 70 } as DOMRect)
@@ -416,13 +463,13 @@ describe('SubagentHeaderLineage', () => {
const trigger = screen.getByRole('button', { name: /1 个子智能体,正在运行/ })
fireEvent.mouseOver(trigger, { relatedTarget: document.body })
await act(async () => { await vi.advanceTimersByTimeAsync(150) })
- const menu = screen.getByRole('tree').parentElement!
+ const menu = screen.getByRole('dialog')
fireEvent.mouseOut(trigger, { relatedTarget: menu })
fireEvent.mouseOver(menu, { relatedTarget: trigger })
fireEvent.mouseOut(menu, { relatedTarget: trigger })
fireEvent.mouseOver(trigger, { relatedTarget: menu })
await act(async () => { await vi.advanceTimersByTimeAsync(150) })
- expect(screen.getByRole('tree').parentElement).toBe(menu)
+ expect(screen.getByRole('dialog')).toBe(menu)
})
it('cancels pending hover dismissal when the catalog trigger is activated from the keyboard', async () => {
@@ -443,7 +490,7 @@ describe('SubagentHeaderLineage', () => {
const bounds = vi.spyOn(trigger, 'getBoundingClientRect')
bounds.mockReturnValue({ bottom: 20, left: 30 } as DOMRect)
hoverCatalog(trigger)
- const menu = screen.getByRole('tree').parentElement!
+ const menu = screen.getByRole('dialog')
expect(menu.style.top).toBe('25px')
expect(menu.style.left).toBe('30px')
diff --git a/packages/client/ui-subagent/tsconfig.json b/packages/client/ui-subagent/tsconfig.json
index 43204687f9..3fd35db9f9 100644
--- a/packages/client/ui-subagent/tsconfig.json
+++ b/packages/client/ui-subagent/tsconfig.json
@@ -58,6 +58,9 @@
},
{
"path": "../../subagent/subagent"
+ },
+ {
+ "path": "../../subagent/agent-team"
}
]
}
diff --git a/packages/experimental/README.i18n.yaml b/packages/experimental/README.i18n.yaml
index 116f3a9ec4..ef6949ebc3 100644
--- a/packages/experimental/README.i18n.yaml
+++ b/packages/experimental/README.i18n.yaml
@@ -18,8 +18,8 @@
en: b55aeb927737b90d
zh: 0b215fcb5c2c7908
/packages-experimental/packages:
- en: 372b182dbf0f662b
- zh: 7a8031c506394785
+ en: 98bc6f826d896a24
+ zh: a324e66edfaadabf
/packages-experimental/related-documentation:
en: 1cb9d3448d44e48d
zh: cd326d70a746b896
diff --git a/packages/experimental/README.md b/packages/experimental/README.md
index d8ccf0dfaa..b16c036f1a 100644
--- a/packages/experimental/README.md
+++ b/packages/experimental/README.md
@@ -60,9 +60,6 @@ Promotion requires a named product role, documented public behavior and limitati
| [`client-ui-voice-input`](client-ui-voice-input/README.md) | Microphone capture and guarded draft insertion | — |
| [`plugin-market-bundle`](plugin-market-bundle/README.md) | Default-disabled optional custom plugin markets: the market service and the Discover tab | — |
| [`voice-input-bundle`](voice-input-bundle/README.md) | Default-disabled optional voice input composition | — |
-| [`agent-team-profile`](agent-team-profile/README.md) | Agent Teams collaboration, tools, and Web UI bundle | — |
-| [`agent-team`](agent-team/README.md) | Named teammates with direct messages and a durable shared task board | `ctx.agentTeams` |
-| [`client-ui-agent-team`](client-ui-agent-team/README.md) | Team roster, task board, and teammate navigation for Web | — |
| [`auto-review`](auto-review/README.md) | Explicit Web layer for same-model review before each native or PTC inner tool call | — |
| [`subagent-oar`](subagent-oar/README.md) | Run standalone external coding-agent tasks through OAR | `ctx.subagents` |
| [`tool-subagent-oar`](tool-subagent-oar/README.md) | Select a configured external agent for each delegated task | `ctx.tools` |
@@ -80,7 +77,6 @@ Promotion requires a named product role, documented public behavior and limitati
| [`inspector`](inspector/README.md) | Cross-realm CDP hub for Host debugging, Client Runtime inspection, network capture, and Cordis trees | `ctx.inspector` |
| [`session-inspector`](session-inspector/README.md) | Sidebar tables for raw Session logs and Chat nodes | — |
| [`inspector-profile`](inspector-profile/README.md) | Optional Web bundle for Session log and Chat node inspection | — |
-| [`tool-agent-team`](tool-agent-team/README.md) | Nine tools that let the model create, message, and coordinate teammates | registers scoped tools on `ctx.tools` |
| [`tool-worktree`](tool-worktree/README.md) | Optional bundle and model tool for creating and entering worktrees | `ctx.tools` |
| [`webworker-packer`](webworker-packer/README.md) | Builds the gzip-compressed VFS image consumed by the browser worker preview | library and CLI — no ctx key |
| [`webworker-runtime`](webworker-runtime/README.md) | Runs the harness plugin tree inside a dedicated browser worker | library and worker entry — no ctx key |
diff --git a/packages/experimental/README.zh.md b/packages/experimental/README.zh.md
index 35b805ef06..9149ffaf45 100644
--- a/packages/experimental/README.zh.md
+++ b/packages/experimental/README.zh.md
@@ -60,9 +60,6 @@ kind: "package-group"
| [`client-ui-voice-input`](client-ui-voice-input/README.zh.md) | 麦克风录音与版本检查后的草稿插入 | — |
| [`plugin-market-bundle`](plugin-market-bundle/README.zh.md) | 默认禁用的可选自定义插件市场:市场服务和「发现」标签页 | — |
| [`voice-input-bundle`](voice-input-bundle/README.zh.md) | 默认禁用的可选语音输入组合 | — |
-| [`agent-team-profile`](agent-team-profile/README.zh.md) | Agent Teams 协作、工具与 Web UI 组合包 | — |
-| [`agent-team`](agent-team/README.zh.md) | 具名 teammate,成员之间直接消息与持久共享任务板 | `ctx.agentTeams` |
-| [`client-ui-agent-team`](client-ui-agent-team/README.zh.md) | Web Team roster、任务板与 teammate 导航 | — |
| [`auto-review`](auto-review/README.zh.md) | 显式 Web 层,在每个原生或 PTC inner 工具调用前使用同一模型审查 | — |
| [`subagent-oar`](subagent-oar/README.zh.md) | 通过 OAR 执行外部编程智能体的独立任务 | `ctx.subagents` |
| [`tool-subagent-oar`](tool-subagent-oar/README.zh.md) | 为每项委派任务选择配置的外部代理 | `ctx.tools` |
@@ -80,7 +77,6 @@ kind: "package-group"
| [`inspector`](inspector/README.zh.md) | 用于 Host 调试、Client Runtime 检查、网络采集与 Cordis 树的跨 realm CDP hub | `ctx.inspector` |
| [`session-inspector`](session-inspector/README.zh.md) | 展示原始 Session 日志与 Chat 节点的 Sidebar 表格 | — |
| [`inspector-profile`](inspector-profile/README.zh.md) | 用于 Session 日志与 Chat 节点检查的可选 Web 组合包 | — |
-| [`tool-agent-team`](tool-agent-team/README.zh.md) | 让模型创建、发消息与协调 teammate 的九个工具 | 按作用域注册工具到 `ctx.tools` |
| [`tool-worktree`](tool-worktree/README.zh.md) | 创建并进入工作树的可选 bundle 与模型工具 | `ctx.tools` |
| [`webworker-packer`](webworker-packer/README.zh.md) | 构建浏览器 worker 预览所消费的 gzip 压缩虚拟文件系统(VFS)镜像 | 库与 CLI(命令行界面),不使用 ctx key |
| [`webworker-runtime`](webworker-runtime/README.zh.md) | 在专用浏览器 worker 中运行 harness 插件树 | 库与 worker 入口,不使用 ctx key |
diff --git a/packages/experimental/agent-team-profile/README.i18n.yaml b/packages/experimental/agent-team-profile/README.i18n.yaml
deleted file mode 100644
index de775f9675..0000000000
--- a/packages/experimental/agent-team-profile/README.i18n.yaml
+++ /dev/null
@@ -1,52 +0,0 @@
-# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write packages/experimental/agent-team-profile/README.md
-/:
- en: 85a54a9cb0eb8da8
- zh: 8a539c319bb3183c
-/deepseek-ai-dsh-experimental-agent-team-profile:
- en: 3deb4b95d9e58c8d
- zh: 0ba043a54428445e
-/deepseek-ai-dsh-experimental-agent-team-profile/summary:
- en: 2c91c8496255494b
- zh: 586b4da00a095f8b
-/deepseek-ai-dsh-experimental-agent-team-profile/table-of-contents:
- en: d152484eb41ac6b4
- zh: 09388d293f9be9cb
-/deepseek-ai-dsh-experimental-agent-team-profile/use-this-package:
- en: d9b1343930f52a4e
- zh: 75e8058593eefc13
-/deepseek-ai-dsh-experimental-agent-team-profile/use-this-package/install-into-a-profile:
- en: 5cf7eca0a485ebc2
- zh: c95185bd2f748bad
-/deepseek-ai-dsh-experimental-agent-team-profile/use-this-package/what-you-get:
- en: d53b1ac69fd2946b
- zh: b00823f309149839
-/deepseek-ai-dsh-experimental-agent-team-profile/understand-the-implementation:
- en: 55a4275896c1ca29
- zh: 8c106158d71ba3cf
-/deepseek-ai-dsh-experimental-agent-team-profile/further-exploration:
- en: 71334ea16b48dced
- zh: f72c0fcb724df3d2
-/deepseek-ai-dsh-experimental-agent-team-profile/model-experience:
- en: 215e7ba838619b7b
- zh: a311da3843709f90
-/deepseek-ai-dsh-experimental-agent-team-profile/model-experience/team-policy-and-tools:
- en: 8e1e365ff3b0dfb2
- zh: c6c91fbf1e1df934
-/deepseek-ai-dsh-experimental-agent-team-profile/model-experience/team-policy-and-tools/what-the-model-sees:
- en: 4cc2461ae0f6fcb7
- zh: 0958ed6b6540b53f
-/deepseek-ai-dsh-experimental-agent-team-profile/model-experience/team-policy-and-tools/token-effect:
- en: 0e6ffba596c37146
- zh: 36ee7e8d52c571ef
-/deepseek-ai-dsh-experimental-agent-team-profile/model-experience/team-policy-and-tools/kv-cache-effect:
- en: 5d78a48233aaa341
- zh: 03ea892500980ff0
-/deepseek-ai-dsh-experimental-agent-team-profile/known-limitations-and-deferred-work:
- en: db34d3c6ba8169cc
- zh: cb0103e7a2295421
-/deepseek-ai-dsh-experimental-agent-team-profile/known-limitations-and-deferred-work/dev-note:
- en: e67f633dc6fe7773
- zh: 3bb0c20c93f16f98
diff --git a/packages/experimental/agent-team-profile/README.md b/packages/experimental/agent-team-profile/README.md
deleted file mode 100644
index 82901a2ae9..0000000000
--- a/packages/experimental/agent-team-profile/README.md
+++ /dev/null
@@ -1,119 +0,0 @@
----
-description: "Enable a shared task board, task tools, and Web task panel with one experimental bundle."
-kind: "package-bundle"
----
-
-# @deepseek-ai/dsh-experimental-agent-team-profile
-
-English | [中文](README.zh.md)
-
-## Summary
-
-`dsh-experimental-agent-team-profile` adds the [Agent Teams](../agent-team/README.md) task board, task tools, and Web task panel to an existing subagent tree. Base-profile delegation, messaging, waiting, and member navigation stay available independently. The bundle ships with dsh switched off. Enable it from the Plugins page or add it to an initialized profile.
-
-## Table of Contents
-
-- [Use this package](#use-this-package)
-- [Understand the implementation](#understand-the-implementation)
-- [Further Exploration](#further-exploration)
-- [Model Experience](#model-experience)
-- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
-- [Dev Note](#dev-note)
-
------
-
-
-## Use this package
-
-Installing this bundle makes Agent Teams available. New Sessions default to off; enable **Use Agent Teams** in the model and reasoning menu, or run `/team on` from the root Session.
-
-### Install into a profile
-
-Add the package to an initialized profile, then run a task that asks the Lead to delegate work:
-
-```sh
-dsh plugin --profile headless add @deepseek-ai/dsh-experimental-agent-team-profile
-dsh --profile headless "Use Agent Teams to split this task between two teammates, wait, and summarize."
-```
-
-The profile must already contain `@deepseek-ai/dsh-base`, whose Subagent services, providers, and tools this layer relies on. Removing the package with `dsh plugin --profile remove @deepseek-ai/dsh-experimental-agent-team-profile` removes the bundle from the profile's ordered layer list.
-
-Enable Agent Teams on the Web or Desktop Plugins page to activate both tools and UI. For a CLI Web profile, use:
-
-```sh
-dsh plugin --profile web add @deepseek-ai/dsh-experimental-agent-team-profile
-```
-
-In an existing profile’s `package.json`, keep `@deepseek-ai/dsh-experimental-agent-team-profile` in `dsh.profile.bundles` and remove the separate `@deepseek-ai/dsh-experimental-agent-team-web-profile` entry. User patches targeting `ui-agent-team` still apply. A user patch that sets a removed Team key keeps that Team row from activating; the [upgrade guide](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md) lists the removed keys and tools.
-
-### What you get
-
-The layer adds the task domain, four task-board tools, and task UI without disabling base rows. The Lead uses `subagent` for fresh context or `subagent_fork` for inherited history. Standard controls address agents by id.
-
-In Web and Desktop conversations, the [Team UI](../client-ui-agent-team/README.md) displays shared tasks; ordinary subagent navigation opens member conversations. The bundle switch controls task tools and task UI. The Plugins page reads the bundle’s [icon](icon.svg) from `package.json.icon`, including while disabled.
-
------
-
-
-## Understand the implementation
-
-
-Implementation internals — click to expand
-
-The package's runtime content is [`cordis.patch.yml`](cordis.patch.yml). Applied after `dsh-base`, the patch only inserts rows: the Team service with `maxTasks: 256`, the Team tools, and the UI. The UI plugin has an inert Host entry; only the Web Client loader mounts its browser entry, so headless needs no Web server.
-
-| File | Role |
-|---|---|
-| [`cordis.patch.yml`](cordis.patch.yml) | Ordered patch over `dsh-base` |
-| [`src/index.ts`](src/index.ts) | Empty module entry; the patch is the runtime content |
-
-
-
------
-
-
-## Further Exploration
-
-- [Experimental packages](../README.md) — incubation status and publication policy.
-- [Agent Teams service](../agent-team/README.md) — durable shared tasks and in-memory wait signals.
-- [Agent Teams tools](../tool-agent-team/README.md) — task tools and shared-board policy.
-- [Agent Teams browser UI](../client-ui-agent-team/README.md) — the shared task panel.
-- [Base bundle](../../bundle/base/README.md) — the profile layer this patch extends.
-
------
-
-
-## Model Experience
-
-### Team policy and tools
-
-#### What the model sees
-
-The task policy, required Team identity, and four task schemas belong to [`@deepseek-ai/dsh-experimental-tool-agent-team`](../tool-agent-team/README.md). This bundle changes composition only; ordinary control tools and inbox waiting remain owned by the base-profile subagent controls.
-
-#### Token effect
-
-The bundle adds the task policy, runtime identity, and four schemas owned by `@deepseek-ai/dsh-experimental-tool-agent-team`; it contributes no prompt text of its own.
-
-#### KV Cache effect
-
-Every member, including `subagent_fork` children, receives the same Team policy and tool schemas, so a fork keeps its parent's request prefix; enabling or disabling the bundle changes both for every member. Team identity is appended through runtime-context snapshots; [Team tools](../tool-agent-team/README.md#model-experience) define snapshot reuse.
-
-## Known Limitations and Deferred Work
-
-
-
-- **Opt-in only** — the package ships with the installation switched off; no shipped CLI, Web, SDK, ACP, or Python profile enables it.
-- **Workflow children share the board** — continuable Workflow `agent()` descendants receive task tools and use ordinary subagent discovery and communication.
-- **Shared checkout** — every teammate observes the same working directory; this bundle adds no worktree isolation or filesystem locking.
-- **Base profile required** — teammates are created and reached through the Subagent services, providers, and tools that `dsh-base` mounts; the layer is not a standalone profile.
-
-
-### Dev Note
-
-
-Working context for maintainers — click to expand
-
-None.
-
-
diff --git a/packages/experimental/agent-team-profile/README.zh.md b/packages/experimental/agent-team-profile/README.zh.md
deleted file mode 100644
index a52a291636..0000000000
--- a/packages/experimental/agent-team-profile/README.zh.md
+++ /dev/null
@@ -1,119 +0,0 @@
----
-description: "通过一个实验性 bundle 启用共享任务板、任务工具和 Web 任务面板。"
-kind: "package-bundle"
----
-
-# @deepseek-ai/dsh-experimental-agent-team-profile
-
-[English](README.md) | 中文
-
-## 概述
-
-`dsh-experimental-agent-team-profile` 为现有 subagent(子智能体)树添加 [Agent Teams](../agent-team/README.zh.md) 任务板、任务工具和 Web 任务面板。基础 profile 的委派、通信、等待和成员导航独立保持可用。此 bundle 随 dsh 分发时默认关闭。可从插件页启用,或添加到已初始化的 profile。
-
-## 目录
-
-- [使用本包](#use-this-package)
-- [理解实现](#understand-the-implementation)
-- [进一步探索](#further-exploration)
-- [模型体验](#model-experience)
-- [已知限制与延期工作](#known-limitations-and-deferred-work)
-- [开发备注](#dev-note)
-
------
-
-
-## 使用本包
-
-安装本组合后可以使用 Agent Teams。新 Session 默认关闭;在模型与推理等级菜单中打开**使用智能体团队**,或从根 Session 执行 `/team on`。
-
-### 安装到 profile
-
-将本包添加到已初始化的 profile,然后运行一个要求 Lead 委派工作的任务:
-
-```sh
-dsh plugin --profile headless add @deepseek-ai/dsh-experimental-agent-team-profile
-dsh --profile headless "Use Agent Teams to split this task between two teammates, wait, and summarize."
-```
-
-profile 必须已经包含 `@deepseek-ai/dsh-base`,本层依赖其中的 Subagent 服务、提供方与工具。执行 `dsh plugin --profile remove @deepseek-ai/dsh-experimental-agent-team-profile` 移除本包时,bundle 也会从 profile 的有序层列表中移除。
-
-在 Web 或 Desktop 的插件页开启「智能体团队」,即可同时启用工具与界面。CLI 的 Web profile 也可使用以下命令:
-
-```sh
-dsh plugin --profile web add @deepseek-ai/dsh-experimental-agent-team-profile
-```
-
-已有 profile 的 `package.json` 中,`dsh.profile.bundles` 应只保留 `@deepseek-ai/dsh-experimental-agent-team-profile`,删除独立的 `@deepseek-ai/dsh-experimental-agent-team-web-profile` 条目。用户 patch 中的 `ui-agent-team` 配置仍然有效。设置已移除 Team 键的用户 patch 会使对应 Team 配置行无法激活;[升级指南](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md)列出已移除的键与工具。
-
-### 获得的功能
-
-此层添加任务域、四个任务板工具和任务 UI,不禁用基础条目。Lead 使用 `subagent` 获取新上下文,或使用 `subagent_fork` 继承历史。标准控制工具按 id 寻址 agent。
-
-在 Web 和 Desktop 对话中,[Team UI](../client-ui-agent-team/README.zh.md)显示共享任务;普通 subagent 导航打开成员对话。bundle 开关控制任务工具和任务 UI。插件页从 `package.json.icon` 读取 bundle 的[图标](icon.svg),禁用时也会显示。
-
------
-
-
-## 理解实现
-
-
-实现细节——点击展开
-
-本包的运行时内容是 [`cordis.patch.yml`](cordis.patch.yml)。在 `dsh-base` 之后应用时,patch 只插入配置行:带 `maxTasks: 256` 的 Team 服务、Team 工具和 UI。UI 插件的 Host 入口不执行逻辑;只有 Web 客户端加载器会挂载其浏览器入口,因此 headless 无需启动 Web 服务。
-
-| 文件 | 职责 |
-|---|---|
-| [`cordis.patch.yml`](cordis.patch.yml) | 叠加在 `dsh-base` 之上的有序 patch |
-| [`src/index.ts`](src/index.ts) | 空模块入口;patch 是运行时内容 |
-
-
-
------
-
-
-## 进一步探索
-
-- [实验性包](../README.zh.md)——孵化状态与发布规则。
-- [Agent Teams 服务](../agent-team/README.zh.md) — 持久化共享任务和内存等待信号。
-- [Agent Teams 工具](../tool-agent-team/README.zh.md) — 任务工具和共享任务板策略。
-- [Agent Teams 浏览器 UI](../client-ui-agent-team/README.zh.md) — 共享任务面板。
-- [Base bundle](../../bundle/base/README.zh.md)——本 patch 扩展的 profile 层。
-
------
-
-
-## 模型体验
-
-### Team 策略与工具
-
-#### 模型会看到什么
-
-任务策略、必需 Team 身份和四个任务 schema 属于 [`@deepseek-ai/dsh-experimental-tool-agent-team`](../tool-agent-team/README.zh.md)。此 bundle 只改变组合;普通控制工具和收件箱等待仍由基础 profile 的 subagent 控制工具负责。
-
-#### Token 影响
-
-bundle 添加 `@deepseek-ai/dsh-experimental-tool-agent-team` 所有的任务策略、运行时身份和四个 schema;自身不提供提示文本。
-
-#### KV Cache 影响
-
-每个成员(包括 `subagent_fork` 子级)都收到相同的 Team 策略与工具 schema,因此 fork 保留父级请求前缀;启用或禁用本 bundle 会为每个成员同时改变两者。Team 身份通过 runtime-context 快照追加;[Team 工具](../tool-agent-team/README.zh.md#model-experience)定义快照复用方式。
-
-## 已知限制与延期工作
-
-
-
-- **仅显式启用**——本包随安装提供但默认关闭;随附 CLI、Web、SDK、ACP 与 Python profile 都不会启用它。
-- **Workflow 子级共享任务板** — 可继续执行的 Workflow `agent()` 后代接收任务工具,并使用普通 subagent 发现与通信。
-- **共享 checkout**——所有 teammate 都观察同一个工作目录;本 bundle 不提供 worktree 隔离或文件系统锁。
-- **需要 base profile**——teammate 通过 `dsh-base` 挂载的 Subagent 服务、提供方与工具创建和联系;本层不是独立 profile。
-
-
-### 开发备注
-
-
-维护者的工作上下文——点击展开
-
-无。
-
-
diff --git a/packages/experimental/agent-team-profile/cordis.patch.yml b/packages/experimental/agent-team-profile/cordis.patch.yml
deleted file mode 100644
index 703ee74513..0000000000
--- a/packages/experimental/agent-team-profile/cordis.patch.yml
+++ /dev/null
@@ -1,15 +0,0 @@
-# Experimental Agent Teams profile layer. Apply after dsh-base: teammates are
-# subagents, so the base delegation and messaging tools stay mounted and
-# this layer only adds the Team task board, task guidance, and panel.
-
-- insert:
- - id: agent-team
- name: '@deepseek-ai/dsh-experimental-agent-team'
- config:
- maxTasks: 256
-
- - id: tool-agent-team
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
-
- - id: ui-agent-team
- name: '@deepseek-ai/dsh-experimental-client-ui-agent-team'
diff --git a/packages/experimental/agent-team-profile/icon.svg b/packages/experimental/agent-team-profile/icon.svg
deleted file mode 100644
index 488848231e..0000000000
--- a/packages/experimental/agent-team-profile/icon.svg
+++ /dev/null
@@ -1,12 +0,0 @@
-
diff --git a/packages/experimental/agent-team-profile/locale/en.json b/packages/experimental/agent-team-profile/locale/en.json
deleted file mode 100644
index 3d51ce13a8..0000000000
--- a/packages/experimental/agent-team-profile/locale/en.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "meta": {
- "title": "Agent Teams",
- "description": "Add shared task-board tools and a task panel to the subagent tree."
- }
-}
diff --git a/packages/experimental/agent-team-profile/locale/zh.json b/packages/experimental/agent-team-profile/locale/zh.json
deleted file mode 100644
index 2777461e58..0000000000
--- a/packages/experimental/agent-team-profile/locale/zh.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "meta": {
- "title": "智能体团队",
- "description": "为子智能体树添加共享任务板工具与任务面板。"
- }
-}
diff --git a/packages/experimental/agent-team-profile/package.json b/packages/experimental/agent-team-profile/package.json
deleted file mode 100644
index 597a6e41a3..0000000000
--- a/packages/experimental/agent-team-profile/package.json
+++ /dev/null
@@ -1,53 +0,0 @@
-{
- "name": "@deepseek-ai/dsh-experimental-agent-team-profile",
- "description": "Agent Teams collaboration, tools, and Web UI in one experimental bundle",
- "version": "0.2.1-rc.2",
- "icon": "./icon.svg",
- "publishConfig": {
- "access": "public"
- },
- "repository": {
- "type": "git",
- "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
- "directory": "packages/experimental/agent-team-profile"
- },
- "type": "module",
- "main": "lib/index.js",
- "types": "lib/types/index.d.ts",
- "exports": {
- ".": {
- "types": "./lib/types/index.d.ts",
- "default": "./lib/index.js"
- },
- "./cordis.patch.yml": "./cordis.patch.yml",
- "./locale/*.json": "./locale/*.json",
- "./src/*": "./src/*",
- "./package.json": "./package.json"
- },
- "files": [
- "icon.svg",
- "locale/*.json",
- "lib/index.js",
- "cordis.patch.yml",
- "lib/types/**/*.d.ts"
- ],
- "license": "MIT",
- "dsh": {
- "bundle": {
- "patch": "./cordis.patch.yml"
- }
- },
- "dependencies": {
- "@deepseek-ai/dsh-experimental-agent-team": "workspace:*",
- "@deepseek-ai/dsh-experimental-client-ui-agent-team": "workspace:*",
- "@deepseek-ai/dsh-experimental-tool-agent-team": "workspace:*"
- },
- "peerDependencies": {
- "@deepseek-ai/cordis": "workspace:~"
- },
- "devDependencies": {
- "@deepseek-ai/cordis-plugin-include": "workspace:~",
- "@deepseek-ai/cordis": "workspace:~",
- "js-yaml": "^4.3.2"
- }
-}
diff --git a/packages/experimental/agent-team-profile/src/index.ts b/packages/experimental/agent-team-profile/src/index.ts
deleted file mode 100644
index 25d4e92224..0000000000
--- a/packages/experimental/agent-team-profile/src/index.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-/**
- * @deepseek-ai/dsh-experimental-agent-team-profile — experimental Agent Teams profile bundle.
- * The package's runtime content is its `dsh.bundle.patch` document; this
- * module exports no runtime API.
- * @module @deepseek-ai/dsh-experimental-agent-team-profile
- */
-
-export {}
diff --git a/packages/experimental/agent-team-profile/tests/profile.spec.ts b/packages/experimental/agent-team-profile/tests/profile.spec.ts
deleted file mode 100644
index 55ca7418fa..0000000000
--- a/packages/experimental/agent-team-profile/tests/profile.spec.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-/** The experimental bundle must carry one parseable, insert-only Team layer. */
-
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { resolve } from 'node:path'
-import { describe, expect, it } from 'vitest'
-import * as yaml from 'js-yaml'
-import { entryListSchema } from '@deepseek-ai/cordis-plugin-include'
-
-describe('Agent Teams profile bundle', () => {
- it('declares a public parseable layer with Team-owned controls', () => {
- const root = fileURLToPath(new URL('..', import.meta.url))
- const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')) as {
- private?: boolean
- publishConfig?: { access?: string }
- dependencies?: Record
- dsh?: { bundle?: { patch?: string } }
- }
- expect(manifest.private).toBeUndefined()
- expect(manifest.publishConfig?.access).toBe('public')
- expect(manifest.dsh?.bundle?.patch).toBe('./cordis.patch.yml')
- expect(manifest.dependencies).toMatchObject({
- '@deepseek-ai/dsh-experimental-agent-team': 'workspace:*',
- '@deepseek-ai/dsh-experimental-client-ui-agent-team': 'workspace:*',
- '@deepseek-ai/dsh-experimental-tool-agent-team': 'workspace:*',
- })
-
- const parsed = yaml.load(
- readFileSync(resolve(root, manifest.dsh!.bundle!.patch!), 'utf8'),
- { schema: entryListSchema },
- )
- expect(Array.isArray(parsed)).toBe(true)
- const patches = parsed as {
- id?: string
- disabled?: boolean
- config?: Record
- insert?: { id?: string; name?: string; config?: Record }[]
- }[]
- // Teammates are subagents: the layer keeps every delegation and messaging row mounted.
- expect(patches.filter(patch => patch.disabled === true)).toEqual([])
- const inserted = patches.flatMap(patch => patch.insert ?? [])
- expect(inserted.find(entry => entry.id === 'agent-team')).toMatchObject({
- name: '@deepseek-ai/dsh-experimental-agent-team',
- config: { maxTasks: 256 },
- })
- expect(inserted.find(entry => entry.id === 'tool-agent-team')).toEqual({
- id: 'tool-agent-team',
- name: '@deepseek-ai/dsh-experimental-tool-agent-team',
- })
- expect(inserted.find(entry => entry.id === 'ui-agent-team')).toMatchObject({
- name: '@deepseek-ai/dsh-experimental-client-ui-agent-team',
- })
- })
-})
diff --git a/packages/experimental/agent-team-profile/tsconfig.json b/packages/experimental/agent-team-profile/tsconfig.json
deleted file mode 100644
index c1eaa3f96e..0000000000
--- a/packages/experimental/agent-team-profile/tsconfig.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
- "extends": "../../../tsconfig.base.json",
- "compilerOptions": {
- "rootDir": "src",
- "outDir": "lib/types"
- },
- "include": [
- "src"
- ],
- "references": [
- {
- "path": "../../../vendor/cordis"
- },
- {
- "path": "../agent-team"
- },
- {
- "path": "../tool-agent-team"
- }
- ]
-}
diff --git a/packages/experimental/agent-team/README.i18n.yaml b/packages/experimental/agent-team/README.i18n.yaml
deleted file mode 100644
index 3db2bc7fac..0000000000
--- a/packages/experimental/agent-team/README.i18n.yaml
+++ /dev/null
@@ -1,103 +0,0 @@
-# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write packages/experimental/agent-team/README.md
-/:
- en: d26e678a9efd33b0
- zh: b20b1c565005d152
-/deepseek-ai-dsh-experimental-agent-team:
- en: b28084855adcdabd
- zh: 59e3d49c3d63baf9
-/deepseek-ai-dsh-experimental-agent-team/summary:
- en: ef6ddcbb3c5c6d7b
- zh: 81caab2bd6c12a7e
-/deepseek-ai-dsh-experimental-agent-team/table-of-contents:
- en: d152484eb41ac6b4
- zh: 09388d293f9be9cb
-/deepseek-ai-dsh-experimental-agent-team/use-this-package:
- en: 96321d3a3f0621a0
- zh: a58d3272df75bb7b
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/when-to-choose-it:
- en: 41e193fafb0b96f9
- zh: 3265330fe77b3707
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/smallest-working-setup:
- en: e316c9ce74bb9630
- zh: e7874163c70d8d67
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/teammates:
- en: a52935db7fa328e1
- zh: 6081f1e8bb75d0ca
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/messages-between-teammates:
- en: ea0bf3fb3213feef
- zh: 0af8ce3160d2fd5d
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/shared-task-board:
- en: 8ace88f5b3c32eeb
- zh: 2e0111b4a7f72651
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/waiting-and-interruption:
- en: 2a8172e07ec20808
- zh: 8aa93e8556517b92
-/deepseek-ai-dsh-experimental-agent-team/use-this-package/what-success-and-failure-look-like:
- en: 36814f2b06dc2359
- zh: c46af795bc89942f
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation:
- en: 6a18034f1ccc247a
- zh: e08b0eb0ccb41ea8
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/design-philosophy:
- en: 8b9ed8b31facd102
- zh: fe6678ab9e2b2c0f
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/source-map:
- en: fdb608bd196db6c3
- zh: e699bbb116af6b4c
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/team-identity-and-membership:
- en: 6edb88f9d3fde16a
- zh: 7918022f3e09ef46
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/task-assignees:
- en: fb370a3606dfe1bf
- zh: 67e3de3c5ebe0758
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/messages-and-historical-mailbox:
- en: 813078d6f281ebc0
- zh: 106887aaf0760e95
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/shared-task-board:
- en: a3eaccd15b02cc8f
- zh: c2829d437a1dfe57
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/task-board-wait-signals:
- en: 027a7ccc996435f5
- zh: 3b95dc637691c03b
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/durability-model:
- en: 6a157930f0bef14a
- zh: c29b976450c1fded
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/disposal:
- en: a8baf51f2fcd6d49
- zh: 357c8db36823fe0e
-/deepseek-ai-dsh-experimental-agent-team/understand-the-implementation/browser-projection:
- en: 11d31cdabfbe8942
- zh: faab17cdeb9a0c8c
-/deepseek-ai-dsh-experimental-agent-team/further-exploration:
- en: 91d96c24ad22c546
- zh: 66f519175fefd944
-/deepseek-ai-dsh-experimental-agent-team/model-experience:
- en: 215e7ba838619b7b
- zh: a311da3843709f90
-/deepseek-ai-dsh-experimental-agent-team/model-experience/task-views-and-errors:
- en: 8b29cb821f80db40
- zh: 43e402736a553ce5
-/deepseek-ai-dsh-experimental-agent-team/model-experience/task-views-and-errors/what-the-model-sees:
- en: bc7d5135ea812e71
- zh: 24fd4df413683aad
-/deepseek-ai-dsh-experimental-agent-team/model-experience/task-views-and-errors/token-effect:
- en: f8857619242bb16e
- zh: aca99dc785e83d56
-/deepseek-ai-dsh-experimental-agent-team/model-experience/task-views-and-errors/kv-cache-effect:
- en: 28354a0f44ef61aa
- zh: e3007733c50e5514
-/deepseek-ai-dsh-experimental-agent-team/known-limitations-and-deferred-work:
- en: 208fdd33e8a1be9a
- zh: bc67492ad17d218f
-/deepseek-ai-dsh-experimental-agent-team/known-limitations-and-deferred-work/dev-note:
- en: 498e4cf9fe5741a7
- zh: 9d2bab630e655c99
-/deepseek-ai-dsh-experimental-agent-team/known-limitations-and-deferred-work/dev-note/promotion:
- en: 3d126e3b1015e4ce
- zh: 22f0d18e2ce5c30f
-/deepseek-ai-dsh-experimental-agent-team/known-limitations-and-deferred-work/dev-note/future-directions:
- en: 39d7ee66217a58eb
- zh: 229016fb44c10ce5
diff --git a/packages/experimental/client-ui-agent-team/README.i18n.yaml b/packages/experimental/client-ui-agent-team/README.i18n.yaml
deleted file mode 100644
index cfca3b5a21..0000000000
--- a/packages/experimental/client-ui-agent-team/README.i18n.yaml
+++ /dev/null
@@ -1,40 +0,0 @@
-# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write packages/experimental/client-ui-agent-team/README.md
-/:
- en: ab268088c47877d5
- zh: d721251ef9c9c473
-/deepseek-ai-dsh-experimental-client-ui-agent-team:
- en: 447e3c2bbf1ea3c6
- zh: 25bba08497976d12
-/deepseek-ai-dsh-experimental-client-ui-agent-team/summary:
- en: 715ca15901c33d8c
- zh: 98c09a343f4ea680
-/deepseek-ai-dsh-experimental-client-ui-agent-team/table-of-contents:
- en: d152484eb41ac6b4
- zh: 09388d293f9be9cb
-/deepseek-ai-dsh-experimental-client-ui-agent-team/use-this-package:
- en: c86ee20fce90cf0c
- zh: 52127ab35418f56a
-/deepseek-ai-dsh-experimental-client-ui-agent-team/use-this-package/inspect-the-task-board:
- en: d565ccd7b37d24c5
- zh: c9e780a9972c9373
-/deepseek-ai-dsh-experimental-client-ui-agent-team/understand-the-implementation:
- en: 395ed32cf10bbb58
- zh: a96230289ec9dcb3
-/deepseek-ai-dsh-experimental-client-ui-agent-team/further-exploration:
- en: 09134c781f6a4ba8
- zh: 2f9d4582053b3384
-/deepseek-ai-dsh-experimental-client-ui-agent-team/model-experience:
- en: 47ebeba07d72759d
- zh: 8fe8133f6dd845a9
-/deepseek-ai-dsh-experimental-client-ui-agent-team/model-experience/kv-cache-effect:
- en: b51b320f5e4dacfc
- zh: 6695947c3f9fed28
-/deepseek-ai-dsh-experimental-client-ui-agent-team/known-limitations-and-deferred-work:
- en: 4bcd998233424ac6
- zh: a73617f461e2dcbe
-/deepseek-ai-dsh-experimental-client-ui-agent-team/known-limitations-and-deferred-work/dev-note:
- en: e67f633dc6fe7773
- zh: 3bb0c20c93f16f98
diff --git a/packages/experimental/client-ui-agent-team/README.md b/packages/experimental/client-ui-agent-team/README.md
deleted file mode 100644
index 3df47f0356..0000000000
--- a/packages/experimental/client-ui-agent-team/README.md
+++ /dev/null
@@ -1,98 +0,0 @@
----
-description: "Inspect the experimental shared task board from the Web conversation header."
-kind: "package-reference"
----
-
-# @deepseek-ai/dsh-experimental-client-ui-agent-team
-
-English | [中文](README.zh.md)
-
-## Summary
-
-This package adds a shared task-board panel to the Web conversation header. Host projection frames keep task state current without a refresh control. Ordinary subagent navigation owns the member list and teammate conversations. Choose this package through the experimental Agent Teams bundle; it adds no model-facing input.
-
-## Table of Contents
-
-- [Use this package](#use-this-package)
-- [Understand the implementation](#understand-the-implementation)
-- [Further Exploration](#further-exploration)
-- [Model Experience](#model-experience)
-- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
-- [Dev Note](#dev-note)
-
------
-
-
-## Use this package
-
-In the root conversation’s model and reasoning menu, turn on **Use Agent Teams**. New Sessions default to off. The shared task-board action appears while enabled; members remain in the existing Subagent tree. Turning it off retains tasks and subagents. The switch waits for the saved projection and reports failures through the menu host.
-
-Enable this package through [`@deepseek-ai/dsh-experimental-agent-team-profile`](../agent-team-profile/README.md), which supplies the Team service, tools, and Web UI together. The Web Client loader mounts the `/client` export; the root Host export is inert, and the package has no user configuration fields.
-
-### Inspect the task board
-
-Ready pending tasks use idle, blocked pending tasks use warning, in-progress tasks use ongoing, and completed tasks use done.
-
-The read-only board shows task identity, owner label, blockers, readiness, advisory write scopes, and overlap warnings. The root owner is labeled Lead; other owners use the subagent catalog label, then the Session title, then the Session id. Long descriptions can expand. The heading shows the task count and an empty board has a short explanation. Agents mutate tasks through tools; the panel provides no mutation controls. A projection failure appears above the last valid tasks.
-
------
-
-
-## Understand the implementation
-
-
-Implementation internals — click to expand
-
-The Client export registers its locale dictionaries and conversation-header and model-menu slots through Cordis effects; it mounts no Remote namespace. Disposing the plugin fiber removes its registrations.
-
-The panel renders outside the conversation container and stays within the viewport. Hover opens it after 150ms; leaving the trigger and panel closes it after 120ms. Clicking pins the panel and moves focus into it. Outside clicks and Escape dismiss it; Escape returns focus when focus was inside. A narrow header uses an icon trigger that opens on click. The panel resolves the root through Session ancestry and reads its `agentTeam` projection. Incomplete ancestry or missing projection data leaves the board unavailable; conversation changes close the panel.
-
-| File | Role |
-|---|---|
-| [`src/client/mount.ts`](src/client/mount.ts) | Locale and header-slot registrations |
-| [`src/client/TeamAction.tsx`](src/client/TeamAction.tsx) | Projection-derived task board and panel interaction state |
-| [`src/client/locales.ts`](src/client/locales.ts) | English and Chinese panel copy |
-| [`src/index.ts`](src/index.ts) | Inert Host entry |
-
-
-
------
-
-
-## Further Exploration
-
-- [Agent Teams bundle](../agent-team-profile/README.md) — the published opt-in bundle that mounts this Client plugin.
-- [Agent Teams service](../agent-team/README.md) — authoritative task and projection behavior.
-- [Conversation UI](../../client/ui-conversation/README.md) — the stable header slot and addressed-subagent navigation surface.
-- [Experimental packages](../README.md) — incubation status and publication policy.
-
------
-
-
-## Model Experience
-
-None, as this browser projection registers no model-facing input.
-
-#### KV Cache effect
-
-No direct effect; the Team tools and ordinary conversation submission own any later model-visible use.
-
-## Known Limitations and Deferred Work
-
-
-
-- **No mailbox timeline** — the panel displays tasks, not messages.
-- **Late plugin activation** — after enabling Agent Teams in an already-open conversation, reload the page to receive its Team projection.
-- **Missing owner labels** — unread Session or catalog metadata leaves an id label until ordinary loading supplies a description.
-- **Member navigation is separate** — use the ordinary subagent header to open teammate conversations.
-- **No lifecycle or workspace controls** — the panel cannot spawn, rename, delete, or interrupt teammates, and write scopes remain advisory metadata.
-
-
-### Dev Note
-
-
-Working context for maintainers — click to expand
-
-None.
-
-
diff --git a/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx b/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx
deleted file mode 100644
index 88d3d0c163..0000000000
--- a/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx
+++ /dev/null
@@ -1,267 +0,0 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import { createPortal } from 'react-dom'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type {
- TeamTaskView as TeamTask,
-} from '@deepseek-ai/dsh-experimental-agent-team/client'
-import type {} from '@deepseek-ai/dsh-api-session-controller/client'
-import {
- IconChevronDownOutlineRegular,
- IconFlatListOutlineRegular, StateDot,
- useAnchoredPosition, useDismissOnOutsidePointer, type StateDotState,
-} from '@deepseek-ai/dsh-client-ui-primitives'
-import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
-import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { NS, type TeamKey } from './locales.ts'
-import css from './TeamAction.module.css'
-import { teamRootId } from './team-root.ts'
-
-/** Full props of the task-board conversation-header action. */
-export type TeamActionProps =
- PropsRuntime<'conversation.session.header.actions'> & PropsLocale
-
-function statusKey(status: TeamTask['status']): TeamKey {
- switch (status) {
- case 'pending': return 'status.pending'
- case 'in_progress': return 'status.in_progress'
- case 'completed': return 'status.completed'
- /* v8 ignore next -- Team views omit deleted task tombstones. */
- case 'deleted': return 'status.completed'
- }
-}
-
-function taskDotState(task: TeamTask): StateDotState {
- switch (task.status) {
- case 'pending': return task.ready ? 'idle' : 'warning'
- case 'in_progress': return 'ongoing'
- case 'completed': return 'done'
- /* v8 ignore next -- Team views omit deleted task tombstones. */
- case 'deleted': return 'idle'
- }
-}
-
-/** Task card with a two-line description clamp expanded from a toggle in the meta row. */
-function TaskCard({ task, rootId, useSessions, t }: {
- task: TeamTask
- rootId: SessionId
- useSessions: TeamActionProps['useSessions']
- t: TranslateNS
-}) {
- const owner = useSessions((state) => {
- if (task.ownerId === undefined) return undefined
- if (task.ownerId === rootId) return t('lead')
- const summary = state.byId[task.ownerId]
- const parentId = summary?.parentId ?? rootId
- const catalog = state.projectionsBySession[parentId]?.values.subagentCatalog
- return catalog?.find(child => child.id === task.ownerId)?.label ?? summary?.title ?? summary?.displayTitle ?? task.ownerId
- })
- const [expanded, setExpanded] = useState(false)
- const [clamped, setClamped] = useState(false)
- const textRef = useRef(null)
- useLayoutEffect(() => {
- if (expanded) return
- const paragraph = textRef.current
- /* v8 ignore next -- the paragraph mounts in the same commit as the effect. */
- if (paragraph === null) return
- const measure = (): void => { setClamped(paragraph.scrollHeight > paragraph.clientHeight + 1) }
- measure()
- if (typeof ResizeObserver === 'undefined') return
- const observer = new ResizeObserver(measure)
- observer.observe(paragraph)
- return () => { observer.disconnect() }
- }, [task.description, expanded])
- return (
-
-
- {task.subject}
-
-
- {t(statusKey(task.status))}
-
-
- {task.description}
-
- {(clamped || expanded) && (
-
- )}
- {task.id}
- {t('owner')}: {owner ?? t('unowned')}
- {task.status === 'pending' && {task.ready ? t('ready') : t('blocked')}}
- {task.blockedBy.length > 0 && {t('blockedBy')}: {task.blockedBy.join(', ')}}
- {task.writeScopes.length > 0 && {t('writeScopes')}: {task.writeScopes.join(', ')}}
- {task.writeScopeWarnings.map(warning => {warning})}
-
-
- )
-}
-
-/** Render the root Session’s read-only task board from any descendant conversation. */
-export function TeamAction({
- sessionId, useSession, useSessions, t,
-}: TeamActionProps) {
- const [open, setOpen] = useState(false)
- const rootRef = useRef(null)
- const triggerRef = useRef(null)
- const triggerLabelRef = useRef(null)
- const panelRef = useRef(null)
- const position = useAnchoredPosition({
- open, anchorRef: triggerRef, panelRef, gap: 5, margin: 16,
- })
- const positioned = position !== null
- const parentId = useSession(snapshot => snapshot.subagent?.address.parentSessionId)
- const rootId = useSessions(state => teamRootId(sessionId, parentId, state.byId))
- const team = useSessions(state => rootId === undefined ? undefined : state.projectionsBySession[rootId]?.values.agentTeam)
- const enabled = useSessions(state => rootId !== undefined && state.projectionsBySession[rootId]?.values.agentTeamMode?.enabled === true)
- const opening = useSession(snapshot => snapshot.openState === 'loading')
- const listing = useSessions(state => state.phase === 'pending')
- const hoverTimer = useRef | undefined>(undefined)
- const pinnedRef = useRef(false)
-
- const cancelHoverChange = (): void => {
- clearTimeout(hoverTimer.current)
- hoverTimer.current = undefined
- }
-
- useEffect(() => {
- cancelHoverChange()
- pinnedRef.current = false
- setOpen(false)
- }, [sessionId, enabled])
-
- useEffect(() => cancelHoverChange, [])
-
- useLayoutEffect(() => {
- if (open && positioned && pinnedRef.current) panelRef.current?.focus()
- }, [open, positioned])
-
- const changeOpen = (next: boolean): void => {
- cancelHoverChange()
- if (!next) pinnedRef.current = false
- setOpen(next)
- }
-
- const scheduleHoverOpen = (): void => {
- cancelHoverChange()
- if (open) return
- const label = triggerLabelRef.current
- /* v8 ignore next -- the label mounts with the trigger that received the hover. */
- if (label === null) return
- // Icon-only trigger (label collapsed by the header container query):
- // hover-open would surprise on such a small target, so only click opens.
- if (getComputedStyle(label).display === 'none') return
- hoverTimer.current = setTimeout(() => {
- hoverTimer.current = undefined
- changeOpen(true)
- }, 150)
- }
-
- const scheduleHoverClose = (): void => {
- cancelHoverChange()
- if (pinnedRef.current) return
- hoverTimer.current = setTimeout(() => {
- hoverTimer.current = undefined
- changeOpen(false)
- }, 120)
- }
-
- useDismissOnOutsidePointer(rootRef, open, changeOpen, panelRef)
-
- useEffect(() => {
- if (!open) return
- const dismiss = (event: KeyboardEvent): void => {
- if (event.key !== 'Escape') return
- event.preventDefault()
- cancelHoverChange()
- pinnedRef.current = false
- setOpen(false)
- if (panelRef.current?.contains(document.activeElement)) triggerRef.current?.focus()
- }
- document.addEventListener('keydown', dismiss)
- return () => { document.removeEventListener('keydown', dismiss) }
- }, [open])
-
- if (!enabled) return null
-
- const compact = team !== undefined && team.tasks.length === 0
-
- return (
-
-
- {open && createPortal(
-
-
- {team === undefined && (
-
-
- {t(opening || listing ? 'loading' : 'unavailable')}
-
- )}
- {team !== undefined && (
- <>
- {team.failure !== undefined && (
-
{t('failure', { message: team.failure })}
- )}
-
- {team.tasks.length === 0
- ? {t('empty')}
- : (
- <>
- {t('tasks')}{team.tasks.length}
-
- {team.tasks.map(task => (
-
- ))}
-
- >
- )}
-
- >
- )}
-
-
,
- document.body,
- )}
-
- )
-}
diff --git a/packages/experimental/client-ui-agent-team/tsconfig.json b/packages/experimental/client-ui-agent-team/tsconfig.json
deleted file mode 100644
index f19f9a7052..0000000000
--- a/packages/experimental/client-ui-agent-team/tsconfig.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
- "extends": "../../../tsconfig.base.client.json",
- "compilerOptions": {
- "rootDir": "src",
- "outDir": "lib/types"
- },
- "include": ["src"],
- "references": [
- { "path": "../../../vendor/cordis" },
- { "path": "../agent-team" },
- { "path": "../../api/session-controller/tsconfig.client.json" },
- { "path": "../../api/remotes/tsconfig.client.json" },
- { "path": "../../client/ui-model-selection" },
- { "path": "../../client/locale/tsconfig.client.json" },
- { "path": "../../client/store" },
- { "path": "../../client/ui-conversation/tsconfig.client.json" },
- { "path": "../../client/ui-primitives" },
- { "path": "../../client/ui-renderer" },
- { "path": "../../client/ui-slots" },
- { "path": "../../core/session" }
- ]
-}
diff --git a/packages/experimental/tool-agent-team/README.i18n.yaml b/packages/experimental/tool-agent-team/README.i18n.yaml
deleted file mode 100644
index 38475870bf..0000000000
--- a/packages/experimental/tool-agent-team/README.i18n.yaml
+++ /dev/null
@@ -1,103 +0,0 @@
-# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write packages/experimental/tool-agent-team/README.md
-/:
- en: 94dd051cb18a417e
- zh: 931747bd5b4a22b1
-/deepseek-ai-dsh-experimental-tool-agent-team:
- en: 0b01a243291821bc
- zh: 0dadd38d709ae9bd
-/deepseek-ai-dsh-experimental-tool-agent-team/summary:
- en: cc67d8d145a8ffb9
- zh: dec0d9798d1e5382
-/deepseek-ai-dsh-experimental-tool-agent-team/table-of-contents:
- en: d152484eb41ac6b4
- zh: 09388d293f9be9cb
-/deepseek-ai-dsh-experimental-tool-agent-team/use-this-package:
- en: 507d9af0af88d60f
- zh: abedd36f14e1b2ae
-/deepseek-ai-dsh-experimental-tool-agent-team/use-this-package/when-to-choose-it:
- en: c27d5457e1183675
- zh: 3c36d513e6400446
-/deepseek-ai-dsh-experimental-tool-agent-team/use-this-package/smallest-working-example:
- en: 6af7bd1afa2f61c4
- zh: 16c479ead42a2b35
-/deepseek-ai-dsh-experimental-tool-agent-team/use-this-package/what-the-model-can-do:
- en: f4c91b124496d1a6
- zh: a2149d32e11d634a
-/deepseek-ai-dsh-experimental-tool-agent-team/use-this-package/what-success-and-failure-look-like:
- en: bf1eb0e693610f5b
- zh: 2b29e5cf63623909
-/deepseek-ai-dsh-experimental-tool-agent-team/understand-the-implementation:
- en: 3952eb1d9de1f988
- zh: 789d51b88f41b710
-/deepseek-ai-dsh-experimental-tool-agent-team/understand-the-implementation/design-philosophy:
- en: 9b3218d9dd0019e4
- zh: cefbcdbdb91648ab
-/deepseek-ai-dsh-experimental-tool-agent-team/understand-the-implementation/source-map:
- en: 29ff96b23b25b13e
- zh: 7d2cdf9be86d1ed4
-/deepseek-ai-dsh-experimental-tool-agent-team/understand-the-implementation/policy-and-tools:
- en: f557dca7db212fa9
- zh: 2b91f9dc363f9f39
-/deepseek-ai-dsh-experimental-tool-agent-team/understand-the-implementation/scoped-registration-and-teardown:
- en: ef8a0940f658d225
- zh: c13048bcda07d006
-/deepseek-ai-dsh-experimental-tool-agent-team/further-exploration:
- en: 87d4f26b5d6e0361
- zh: 1a012fa95808e8fa
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience:
- en: 215e7ba838619b7b
- zh: a311da3843709f90
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-policy-system-prompt:
- en: 8757dc3caca9e4e2
- zh: fd0b7535a1b24189
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-policy-system-prompt/what-the-model-sees:
- en: 25079a70c9a3ed87
- zh: 34301e390669a887
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-policy-system-prompt/what-the-model-sees/team-policy:
- en: 824ebdbe434d7b6c
- zh: 6a442dbca7cf3625
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-policy-system-prompt/token-effect:
- en: 7e2583f482a60938
- zh: d3e68b204cd3d2b3
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-policy-system-prompt/kv-cache-effect:
- en: 6723f8e3f2497338
- zh: ca68851b279362e1
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-identity-runtime-context:
- en: ed8642015d306d6d
- zh: 31496981d115ba40
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-identity-runtime-context/what-the-model-sees:
- en: c34616cd061c33be
- zh: c039b9dd9804f8ac
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-identity-runtime-context/what-the-model-sees/root-identity:
- en: 58d2b04f507baa5f
- zh: 773786c59605a154
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-identity-runtime-context/what-the-model-sees/teammate-identity:
- en: f0d12764966d3005
- zh: 365df450e96cb6e1
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-identity-runtime-context/token-effect:
- en: b9c8f7524fbe3204
- zh: 6c61dfb24b4b677a
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/team-identity-runtime-context/kv-cache-effect:
- en: 32488ff4b3134dbf
- zh: 5b76b6a325597ddb
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/task-tool-schemas:
- en: d6918434714cf05a
- zh: eef799d16e0c8f4b
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/task-tool-schemas/what-the-model-sees:
- en: 412492eb494e3c79
- zh: dbd3f316e14e6f42
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/task-tool-schemas/token-effect:
- en: 5ae789db90ce9606
- zh: 3b26fe33c811815c
-/deepseek-ai-dsh-experimental-tool-agent-team/model-experience/task-tool-schemas/kv-cache-effect:
- en: 41bfcd6adb8058f5
- zh: 73363ee21021a96a
-/deepseek-ai-dsh-experimental-tool-agent-team/known-limitations-and-deferred-work:
- en: 265236b3e73e4939
- zh: 34b5bbc724072e35
-/deepseek-ai-dsh-experimental-tool-agent-team/known-limitations-and-deferred-work/dev-note:
- en: e67f633dc6fe7773
- zh: 3bb0c20c93f16f98
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index 62e766bc14..ef089e46c9 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -1329,7 +1329,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
slotInject: '',
declaredBy: 'an entry in \'conversation.input.model\' (client-ui-model-selection), so it exists while that entry is mounted',
occupants: [
- 'experimental-client-ui-agent-team TeamModeToggle id \'agent-team\'',
+ 'client-ui-agent-team TeamModeToggle id \'agent-team\'',
],
replaceRisk: 'none',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.input.model.options\', () => ctx.slots.register(\n { name: \'conversation.input.model.options\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
@@ -1736,12 +1736,68 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
'client-ui-agent-preset AgentPresetLabel id \'agent-preset\'',
'client-ui-jobs JobListAction id \'job-list\'',
'client-ui-subagent SubagentCatalogAction id \'subagent-catalog\'',
- 'experimental-client-ui-agent-team TeamAction id \'agent-team\'',
],
replaceRisk: 'none',
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.session.header.actions\', () => ctx.slots.register(\n { name: \'conversation.session.header.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
source: 'packages/client/ui-conversation/src/client/contract/slots.ts:229',
},
+ {
+ key: 'conversation.session.header.actions.subagent.footer',
+ kind: 'list',
+ scope: 'session',
+ summary: 'Content below the root Session\'s subagent tree.',
+ doc: 'Content below the root Session\'s subagent tree.',
+ registerOptions: [
+ {
+ name: 'id',
+ requirement: 'required',
+ type: 'string',
+ doc: 'Your cell key. Use an id of your own: a fresh id is added beside the shipped entries, while reusing a shipped id puts you in THAT cell and replaces it. Owners that filter by id address you by it.',
+ },
+ {
+ name: 'order',
+ requirement: 'optional',
+ type: 'number',
+ doc: 'Position among the entries, ascending (default 0).',
+ },
+ {
+ name: 'label',
+ requirement: 'optional',
+ type: 'string | (() => string)',
+ doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
+ },
+ ],
+ ownerProps: [],
+ ownerPropsReferences: [],
+ standardProps: [
+ 'useRemoteAccess: (action: RemoteEndpoint) => boolean',
+ 'useResource: UseResource',
+ 'useWorkspaces: SnapshotSelectorHook',
+ 'usePanelInfo: UsePanelInfo',
+ 'useSessions: UseSessions',
+ 'useSessionStatus: UseSessionStatus',
+ 'useSessionRetainInfo: UseSessionRetainInfo',
+ 'useSessionAccess: (sessionId: SessionId, action: RemoteEndpoint) => boolean',
+ 'useWorkspaceAccess: (workspaceId: WorkspaceId, action: RemoteEndpoint) => boolean',
+ 'useChat: UseChat',
+ 'useConversation: UseConversation',
+ 'useInput: SnapshotSelectorHook',
+ 'inputActions: InputActions',
+ 'useSession: SessionSnapshotSelector',
+ 'sessionId: SessionId',
+ 'useProjection: UseProjection',
+ 'useAccess: (action: RemoteEndpoint) => boolean',
+ 'useTrajectory: UseTrajectory',
+ ],
+ keyDomain: '',
+ hookContext: '',
+ slotInject: '',
+ declaredBy: 'an entry in \'conversation.session.header.actions\' (client-ui-subagent), so it exists while that entry is mounted',
+ occupants: [],
+ replaceRisk: 'none',
+ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.session.header.actions.subagent.footer\', () => ctx.slots.register(\n { name: \'conversation.session.header.actions.subagent.footer\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
+ source: 'packages/client/ui-subagent/src/client/slots.ts:6',
+ },
{
key: 'conversation.session.header.corner',
kind: 'single',
@@ -1828,6 +1884,63 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.session.header.lineage\', () => ctx.slots.register(\n { name: \'conversation.session.header.lineage\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
source: 'packages/client/ui-conversation/src/client/contract/slots.ts:223',
},
+ {
+ key: 'conversation.session.header.lineage.subagent.footer',
+ kind: 'list',
+ scope: 'session',
+ summary: 'Content below a descendant\'s sibling or child tree.',
+ doc: 'Content below a descendant\'s sibling or child tree.',
+ registerOptions: [
+ {
+ name: 'id',
+ requirement: 'required',
+ type: 'string',
+ doc: 'Your cell key. Use an id of your own: a fresh id is added beside the shipped entries, while reusing a shipped id puts you in THAT cell and replaces it. Owners that filter by id address you by it.',
+ },
+ {
+ name: 'order',
+ requirement: 'optional',
+ type: 'number',
+ doc: 'Position among the entries, ascending (default 0).',
+ },
+ {
+ name: 'label',
+ requirement: 'optional',
+ type: 'string | (() => string)',
+ doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
+ },
+ ],
+ ownerProps: [],
+ ownerPropsReferences: [],
+ standardProps: [
+ 'useRemoteAccess: (action: RemoteEndpoint) => boolean',
+ 'useResource: UseResource',
+ 'useWorkspaces: SnapshotSelectorHook',
+ 'usePanelInfo: UsePanelInfo',
+ 'useSessions: UseSessions',
+ 'useSessionStatus: UseSessionStatus',
+ 'useSessionRetainInfo: UseSessionRetainInfo',
+ 'useSessionAccess: (sessionId: SessionId, action: RemoteEndpoint) => boolean',
+ 'useWorkspaceAccess: (workspaceId: WorkspaceId, action: RemoteEndpoint) => boolean',
+ 'useChat: UseChat',
+ 'useConversation: UseConversation',
+ 'useInput: SnapshotSelectorHook',
+ 'inputActions: InputActions',
+ 'useSession: SessionSnapshotSelector',
+ 'sessionId: SessionId',
+ 'useProjection: UseProjection',
+ 'useAccess: (action: RemoteEndpoint) => boolean',
+ 'useTrajectory: UseTrajectory',
+ ],
+ keyDomain: '',
+ hookContext: '',
+ slotInject: '',
+ declaredBy: 'an entry in \'conversation.session.header.lineage\' (client-ui-subagent), so it exists while that entry is mounted',
+ occupants: [],
+ replaceRisk: 'none',
+ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.session.header.lineage.subagent.footer\', () => ctx.slots.register(\n { name: \'conversation.session.header.lineage.subagent.footer\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
+ source: 'packages/client/ui-subagent/src/client/slots.ts:11',
+ },
{
key: 'conversation.session.header.utilities',
kind: 'list',
diff --git a/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md b/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md
index 21541aba1b..debf3895bc 100644
--- a/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md
+++ b/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md
@@ -68,6 +68,7 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
| `@deepseek-ai/dsh-client-resources` | no | Unified client resource model: protocol-registered providers turn URL addresses into live values, consumed through the useResource global standard hook |
| `@deepseek-ai/dsh-client-shortcuts` | yes | Application keyboard command registry and physical-key routing |
| `@deepseek-ai/dsh-client-ui-agent-preset` | no | Agent-preset surfaces: the default for later sessions, this session's seat, and the composition editor |
+| `@deepseek-ai/dsh-client-ui-agent-team` | no | Web shared task board for a subagent tree |
| `@deepseek-ai/dsh-client-ui-approval` | no | Approval composer takeover over the scoped Remote Event waterfall |
| `@deepseek-ai/dsh-client-ui-attachment` | no | Dynamic attachment presentation plugin for conversation input, message-image, and trajectory image slots |
| `@deepseek-ai/dsh-client-ui-brand-official` | no | Official DeepSeek Harness brand occupants for the Web client's sidebar slots |
@@ -184,14 +185,12 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
| Package | Config | Description |
|---|---|---|
-| `@deepseek-ai/dsh-experimental-agent-team` | yes | Shared task DAG and change waits for subagent trees |
| `@deepseek-ai/dsh-experimental-api-speech-to-text` | yes | Authenticated experimental speech transcription for browser clients |
| `@deepseek-ai/dsh-experimental-auto-review` | no | Per-tool LLM authorization review for the DeepSeek Harness Auto permission preset |
| `@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp` | yes | Experimental per-Session Chromium browser tools through chrome-devtools-mcp |
| `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp` | yes | Experimental per-Session Chromium browser tools through @playwright/mcp |
| `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` | yes | Experimental Stagehand browser tools with separately configured native models |
| `@deepseek-ai/dsh-experimental-claude-code-mods` | yes | Experimental bridge: load Claude Code mods (hooks modules) and run their hook chains on DeepSeek Harness extension points |
-| `@deepseek-ai/dsh-experimental-client-ui-agent-team` | no | Web shared task board for a subagent tree |
| `@deepseek-ai/dsh-experimental-client-ui-claude-code-mods` | no | Web band above the prompt for Claude Code mods: draws each session's mod tree and sends button presses back to the bridge |
| `@deepseek-ai/dsh-experimental-client-ui-cot-translation` | yes | Optional machine translation of expanded reasoning, preserving original Session text |
| `@deepseek-ai/dsh-experimental-client-ui-voice-input` | no | Record speech and insert editable text into the conversation draft |
@@ -204,7 +203,6 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
| `@deepseek-ai/dsh-experimental-speech-to-text` | yes | Experimental speech recognition with independently selectable providers |
| `@deepseek-ai/dsh-experimental-speech-to-text-sensevoice` | yes | Local SenseVoice ONNX transcription with a managed sherpa-onnx process |
| `@deepseek-ai/dsh-experimental-subagent-oar` | yes | Experimental one-shot subagents through OAR runtimes |
-| `@deepseek-ai/dsh-experimental-tool-agent-team` | yes | Scoped model-facing Agent Teams tools over ctx.agentTeams |
| `@deepseek-ai/dsh-experimental-tool-subagent-oar` | yes | Delegate standalone tasks to configured external subagent providers |
| `@deepseek-ai/dsh-experimental-tool-worktree` | no | Model tool that creates and enters a new Git worktree |
| `@deepseek-ai/dsh-experimental-translator` | yes | Machine translation with reusable Session results |
@@ -443,6 +441,7 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
| Package | Config | Description |
|---|---|---|
+| `@deepseek-ai/dsh-agent-team` | yes | Shared task DAG and change waits for subagent trees |
| `@deepseek-ai/dsh-subagent` | yes | Abstract subagent seam (ctx.subagents): named-provider registry for delegating to child agents |
| `@deepseek-ai/dsh-subagent-acp` | yes | Out-of-process ACP subagent backend: drives a child agent in a spawned subprocess over the Agent Client Protocol |
| `@deepseek-ai/dsh-subagent-claude-code` | yes | One-shot Claude Code subagent provider over the official Agent SDK |
@@ -450,6 +449,7 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
| `@deepseek-ai/dsh-subagent-dsh-sdk` | yes | Out-of-process SDK subagent backend: drives a child DeepSeek Harness runtime subprocess over stdio JSON-RPC through the TypeScript SDK client |
| `@deepseek-ai/dsh-subagent-fork-in-process` | yes | In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log |
| `@deepseek-ai/dsh-subagent-spawn-in-process` | yes | In-process spawn subagent backend: runs a fresh child agent on ctx.agents |
+| `@deepseek-ai/dsh-tool-agent-team` | yes | Scoped model-facing Agent Teams tools over ctx.agentTeams |
| `@deepseek-ai/dsh-tool-subagent` | yes | Model-facing subagent delegation tool over the ctx.subagents seam |
| `@deepseek-ai/dsh-tool-subagent-control` | no | Shared messaging, interruption, and child discovery tools for subagents |
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index c69de6ed65..cc789d42a1 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/README.i18n.yaml
@@ -15,8 +15,8 @@
en: 1eb35b015a6c423f
zh: a8a3dceee2c9e943
/subagent-subagent-capability-family/packages:
- en: 6e34528cfd8a3b2c
- zh: 88655c4fbe96c861
+ en: f2df23bb3d65caf3
+ zh: a2755a3af4d8a54d
/subagent-subagent-capability-family/related-documentation:
en: e525958323eebabe
zh: d32725ee5393ad33
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index e030cf9a78..8a64706955 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -24,6 +24,8 @@ The subagent package family lets an agent delegate a task to a child, continue t
| Package | Role | ctx key |
|---|---|---|
+| [`agent-team/`](agent-team/README.md) | Shared task board and saved Team mode for a subagent tree | `ctx.agentTeams` |
+| [`tool-agent-team/`](tool-agent-team/README.md) | Exposes shared task tools while Team mode is enabled | registers on `ctx.tools` |
| [`subagent/`](subagent/README.md) | Defines the delegation service: provider registry, one-shot runs, continuable children, and discovery | `ctx.subagents` |
| [`subagent-spawn-in-process/`](subagent-spawn-in-process/README.md) | Runs a fresh in-process child | registers on `ctx.subagents` |
| [`subagent-fork-in-process/`](subagent-fork-in-process/README.md) | Runs an in-process child seeded from the parent's completed history | registers on `ctx.subagents` |
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index 4f501d2ee9..b5517ff4a1 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -24,6 +24,8 @@ subagent 包家族让 agent(智能体)将任务委派给子 agent、继续
| 包 | 职责 | ctx 键 |
|---|---|---|
+| [`agent-team/`](agent-team/README.zh.md) | 子智能体树的共享任务板与持久化 Team 模式 | `ctx.agentTeams` |
+| [`tool-agent-team/`](tool-agent-team/README.zh.md) | Team 模式开启时提供共享任务工具 | 注册到 `ctx.tools` |
| [`subagent/`](subagent/README.zh.md) | 定义委派服务:提供方注册表、一次性运行、可继续子级与发现 | `ctx.subagents` |
| [`subagent-spawn-in-process/`](subagent-spawn-in-process/README.zh.md) | 运行全新的进程内子 agent | 注册到 `ctx.subagents` |
| [`subagent-fork-in-process/`](subagent-fork-in-process/README.zh.md) | 运行从父级已完成历史派生的进程内子 agent | 注册到 `ctx.subagents` |
diff --git a/packages/subagent/agent-team/README.i18n.yaml b/packages/subagent/agent-team/README.i18n.yaml
new file mode 100644
index 0000000000..82bc460036
--- /dev/null
+++ b/packages/subagent/agent-team/README.i18n.yaml
@@ -0,0 +1,100 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write packages/subagent/agent-team/README.md
+/:
+ en: 03bfe939e62d80aa
+ zh: 9db4ba086a4ed6f4
+/deepseek-ai-dsh-agent-team:
+ en: 80b485e2799df851
+ zh: 31770395bc932701
+/deepseek-ai-dsh-agent-team/summary:
+ en: 308b7d3adf3dc2ea
+ zh: 08406c822fbc8b4b
+/deepseek-ai-dsh-agent-team/table-of-contents:
+ en: d152484eb41ac6b4
+ zh: 09388d293f9be9cb
+/deepseek-ai-dsh-agent-team/use-this-package:
+ en: 71f23f135c89f3f4
+ zh: ba886d534675837b
+/deepseek-ai-dsh-agent-team/use-this-package/when-to-choose-it:
+ en: 41e193fafb0b96f9
+ zh: 3265330fe77b3707
+/deepseek-ai-dsh-agent-team/use-this-package/smallest-working-setup:
+ en: b3fb4a4c7a3d5277
+ zh: 4cae69ad39027a21
+/deepseek-ai-dsh-agent-team/use-this-package/teammates:
+ en: a52935db7fa328e1
+ zh: 6081f1e8bb75d0ca
+/deepseek-ai-dsh-agent-team/use-this-package/messages-between-teammates:
+ en: ea0bf3fb3213feef
+ zh: 0af8ce3160d2fd5d
+/deepseek-ai-dsh-agent-team/use-this-package/shared-task-board:
+ en: 8ace88f5b3c32eeb
+ zh: 2e0111b4a7f72651
+/deepseek-ai-dsh-agent-team/use-this-package/waiting-and-interruption:
+ en: 2a8172e07ec20808
+ zh: 8aa93e8556517b92
+/deepseek-ai-dsh-agent-team/use-this-package/what-success-and-failure-look-like:
+ en: 36814f2b06dc2359
+ zh: c46af795bc89942f
+/deepseek-ai-dsh-agent-team/understand-the-implementation:
+ en: 6a18034f1ccc247a
+ zh: e08b0eb0ccb41ea8
+/deepseek-ai-dsh-agent-team/understand-the-implementation/design-philosophy:
+ en: 8b9ed8b31facd102
+ zh: fe6678ab9e2b2c0f
+/deepseek-ai-dsh-agent-team/understand-the-implementation/source-map:
+ en: fdb608bd196db6c3
+ zh: e699bbb116af6b4c
+/deepseek-ai-dsh-agent-team/understand-the-implementation/team-identity-and-membership:
+ en: 6edb88f9d3fde16a
+ zh: 7918022f3e09ef46
+/deepseek-ai-dsh-agent-team/understand-the-implementation/task-assignees:
+ en: fb370a3606dfe1bf
+ zh: 67e3de3c5ebe0758
+/deepseek-ai-dsh-agent-team/understand-the-implementation/messages-and-historical-mailbox:
+ en: 813078d6f281ebc0
+ zh: 106887aaf0760e95
+/deepseek-ai-dsh-agent-team/understand-the-implementation/shared-task-board:
+ en: a3eaccd15b02cc8f
+ zh: c2829d437a1dfe57
+/deepseek-ai-dsh-agent-team/understand-the-implementation/task-board-wait-signals:
+ en: 027a7ccc996435f5
+ zh: 3b95dc637691c03b
+/deepseek-ai-dsh-agent-team/understand-the-implementation/durability-model:
+ en: 6a157930f0bef14a
+ zh: c29b976450c1fded
+/deepseek-ai-dsh-agent-team/understand-the-implementation/disposal:
+ en: a8baf51f2fcd6d49
+ zh: 357c8db36823fe0e
+/deepseek-ai-dsh-agent-team/understand-the-implementation/browser-projection:
+ en: 40bbc604de932447
+ zh: 19dcd492551792c5
+/deepseek-ai-dsh-agent-team/further-exploration:
+ en: 84b5ec5de64726da
+ zh: 25305f7dc054336f
+/deepseek-ai-dsh-agent-team/model-experience:
+ en: 215e7ba838619b7b
+ zh: a311da3843709f90
+/deepseek-ai-dsh-agent-team/model-experience/task-views-and-errors:
+ en: 8b29cb821f80db40
+ zh: 43e402736a553ce5
+/deepseek-ai-dsh-agent-team/model-experience/task-views-and-errors/what-the-model-sees:
+ en: bc7d5135ea812e71
+ zh: 24fd4df413683aad
+/deepseek-ai-dsh-agent-team/model-experience/task-views-and-errors/token-effect:
+ en: f8857619242bb16e
+ zh: aca99dc785e83d56
+/deepseek-ai-dsh-agent-team/model-experience/task-views-and-errors/kv-cache-effect:
+ en: 28354a0f44ef61aa
+ zh: e3007733c50e5514
+/deepseek-ai-dsh-agent-team/known-limitations-and-deferred-work:
+ en: ee7ee8f5c77955cd
+ zh: 24fec7209490ede1
+/deepseek-ai-dsh-agent-team/known-limitations-and-deferred-work/dev-note:
+ en: 498e4cf9fe5741a7
+ zh: 9d2bab630e655c99
+/deepseek-ai-dsh-agent-team/known-limitations-and-deferred-work/dev-note/future-directions:
+ en: 39d7ee66217a58eb
+ zh: 229016fb44c10ce5
diff --git a/packages/subagent/agent-team/README.md b/packages/subagent/agent-team/README.md
new file mode 100644
index 0000000000..944782c411
--- /dev/null
+++ b/packages/subagent/agent-team/README.md
@@ -0,0 +1,216 @@
+---
+description: "Coordinate subagents through a durable shared task board and in-memory wait signals in Team-enabled Sessions."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-agent-team
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-agent-team` adds a durable shared task board to an existing subagent tree. Members use standard subagent tools to discover and contact one another. Team adds compare-and-set task ownership and signals all resident Agents in the tree after each task commit is flushed. Mount `dsh-tool-agent-team` for task tools. Members share one checkout.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+
+## Use this package
+
+New Sessions default to Team mode off. See the [Session-mode upgrade guide](../../../docs/upgrade-guide/v0.2.1-rc.2/session-team-mode/guide.md). Select **Use Agent Teams** in the model and reasoning menu, or run `/team on` in the root Session. `/team off` removes Team tools and guidance for the entire tree while retaining tasks and subagents. The saved selection survives restart; a historical task board without a saved selection remains enabled. Deployments may set `enabledByDefault: true` for Sessions without a saved selection or historical tasks.
+
+Add this package when subagents need durable shared task ownership and dependencies. Mount it with `@deepseek-ai/dsh-tool-agent-team` for model tools.
+
+### When to choose it
+
+Choose it when delegated agents must divide and track shared work. Plain subagents suffice when no shared board is needed. Team does not create isolated working directories, coordinate across processes, or automatically release task owners.
+
+### 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`:
+
+```yaml
+# smallest Team addition over a composition with continuable subagents
+- name: '@deepseek-ai/dsh-agent-team'
+- name: '@deepseek-ai/dsh-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](../../../docs/config-catalog.md#deepseek-aidsh-agent-team) 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](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md) lists the replacements.
+
+### Teammates
+
+Ask the Lead to start a subagent with a sibling-unique `name` and a `description` of its work: `subagent` starts fresh, while `subagent_fork` inherits completed turns. The returned full path addresses the teammate; descriptions may repeat.
+
+Every root agent and its descendants form one Team. Task assignment accepts the root or any reachable continuable descendant discovered by the subagent runtime, at any depth. Historical roster records remain readable but grant no assignment authority.
+
+### Messages between teammates
+
+Members use standard `list_agents` to discover the tree and `send_message` to contact another member by full agent path. The subagent runtime owns routing, sender attribution, and cold restoration. Task-board signals address all resident Agents in the same tree and never restore a cold member.
+
+### 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 root can reassign a task to itself or any reachable continuable descendant by full agent path. 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
+
+The standard `wait_agent` tool waits for the exact caller’s next-step inbox and works without Team mode; see [subagent controls](../tool-subagent-control/README.md#wait_agent). Team mode also ends an active wait when a task-board commit finishes flushing. Re-read the board after waiting. A change outside an active wait is not retained and cannot make a later wait return immediately.
+
+An ancestor stops a descendant’s current turn with the standard `interrupt_agent` tool. Interruption keeps unclaimed queued messages and leaves task ownership unchanged.
+
+### What success and failure look like
+
+Success returns the committed task revision. Unknown owners, unready tasks, stale revisions, unauthorized mutations, and exhausted task limits report typed errors.
+
+-----
+
+
+## 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](#use-this-package).
+
+### Design philosophy
+
+The service is built on four commitments:
+
+- **One tree identity.** The subagent runtime resolves the root and discovers descendants; Team maintains no second membership authority.
+- **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.** `maxTasks` is a validated deployment value, and exhaustion reports a typed error instead of reusing an id.
+
+The [task-board wait decision](../../../.agents/notes/implemented/architecture/2026-10-19-team-task-board-inbox.md) owns task-board wait signals and the separation from ordinary subagent controls.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry, configuration validation, and task service registration |
+| [`src/task-board.ts`](src/task-board.ts) | Task CAS commands, DAG validation, and derived views |
+| [`src/journal.ts`](src/journal.ts) | Serialized Lead-log transactions and commit notification |
+| [`src/projection.ts`](src/projection.ts) | Strict replay of historical roster, tasks, and mailbox records, publishing the `agentTeam` client view |
+| [`src/task-view.ts`](src/task-view.ts) | Pure task readiness and write-overlap derivation shared by the task board and client view |
+
+### Team identity and membership
+
+The subagent service resolves the exact live caller’s root through `subagents.rootOf()`. Intermediate creators may be offline. An ordinary Session fork leads a new tree. Team uses that root Session as the board owner without a separate membership object.
+
+### Task assignees
+
+Reassignment resolves the root or a continuable descendant through the same discovery used by `list_agents`. Historical `team/member` records remain decode-only and cannot authorize assignment.
+
+### Messages and historical mailbox
+
+Peer messaging, Steer delivery, cold resume, and sender framing belong to the subagent runtime. Task-board changes use in-memory wait signals. Historical `team/message/queued` and `team/message/delivered` records and `team-message` sources remain decodable but are never delivered or acknowledged.
+
+### Shared task board
+
+Tasks are complete versioned snapshots. Mutations require `expectedRevision`; stale updates report `TEAM_TASK_STALE_REVISION`. Numeric `task-` ids stay within the safe-integer range. Deleted tasks remain replay tombstones but do not consume `maxTasks` or appear in `listTasks()`. Normalized workspace-relative `writeScopes` warn about overlapping in-progress work without blocking claims or authorizing writes.
+
+### Task-board wait signals
+
+After a successful append and flush, Team emits an Agent-scoped in-memory signal for all resident Agents in the same tree, including the caller and root. The signal ends only an active wait. It adds no inbox entry or unread state, never starts an idle turn, and never restores a cold member. Changes between waits are not replayed to the next wait.
+
+### Durability model
+
+`Service.init` awaits registration of the `agentTeam` projection before publishing service readiness. The journal retains the returned handle and reads task state through `stateOf(session)`; callers use the Team service rather than registering another reader.
+
+Task mutations honor cancellation before appending `team/task` to the exact live root Session, then flush before emitting wait signals. Cancellation cannot retract an appended record. A flush failure raises `TEAM_TASK_PERSISTENCE_UNCONFIRMED` with the task id and revision: the task is already visible, but durability is unknown. Read that task before retrying. Task records remain log-only; signals are not messages or persisted events. The wait tool records its result through the normal tool pipeline. No committed task or historical payload generation is rewritten.
+
+Mailbox projection and checkpoint admission preserve decoded JSON fields outside locally declared validators, including an own `__proto__` key. Historical payload generations remain unchanged; projection caches rebuild from the Session log when their cache version changes.
+
+### Disposal
+
+Unloading the service unregisters the projection. The retained handle remains readable and folds Session events on demand while admitted work settles. Team owns no Agent: teammates remain under the subagent runtime, which owns their capacity, settlement, and teardown.
+
+### Browser projection
+
+The `agentTeam` projection publishes non-deleted task views and any failure beside the last valid state. Historical member fields remain in persisted projection state for decoding compatibility, are omitted from the browser view, and grant no runtime authority. A failed projection rejects subsequent Team reads and mutations without appending further Team events. The [subsystem reference](../../../docs/subsystems/agent-team.md#web-projection) defines the wire types.
+
+The [Web UI](../../client/ui-agent-team/README.md) displays tasks only. Ordinary subagent navigation owns the member list; task owner labels reuse Session and catalog data with an id fallback.
+
+
+
+-----
+
+
+## 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](../../../docs/subsystems/agent-team.md) — durable Team types and the `ctx.agentTeams` service API.
+- [tool-agent-team package](../tool-agent-team/README.md) — task tools and shared-board policy.
+- [Subagent runtime](../subagent/README.md) — continuable children, messaging, interruption, and lifecycle that teammates use.
+- [Subagent teammates Agent Note](../../../.agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.md) — why teammates are subagents and what Team keeps.
+- [Upgrade guide](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md) — replacements for the removed Team tools, service methods, and configuration keys.
+
+-----
+
+
+## Model Experience
+
+### Task views and errors
+
+#### What the model sees
+
+The model reads task views through task-tool results. Model-facing views identify owners by `ownerName`; host views retain `ownerId`; stale updates report the current revision. A task-board signal ends an active `wait_agent` call without supplying task contents. The model re-reads current tasks before acting.
+
+#### Token effect
+
+Each task result adds a compact task view. Wait signals add no message text.
+
+#### KV Cache effect
+
+Task records stay outside model history. Task and wait results append after the reusable request prefix.
+
+## 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 task change sends the complete non-deleted board to connected browsers.
+- **One process** — members can observe shared filesystem edits; 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.
+- **Notices reach live local members only** — cold members are not restored, and idle members remain idle until explicitly resumed.
+
+- **Communication stays within one tree** — members cannot message unrelated Teams; only ancestors can interrupt descendants.
+- **Membership needs a live Team root** — members keep their Team role when an intermediate creator finishes or is released; a missing root leaves them without an active Team.
+- **No automatic ownership release** — inactivity, interruption, process exit, and failed work do not release a task owner.
+- **Historical queued messages stay undelivered** — `team/message/queued` records 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.
+
+#### Future directions
+
+Undecided directions include automatic ownership release and filesystem isolation via worktrees; neither is committed.
+
+
diff --git a/packages/subagent/agent-team/README.zh.md b/packages/subagent/agent-team/README.zh.md
new file mode 100644
index 0000000000..26e71fca0d
--- /dev/null
+++ b/packages/subagent/agent-team/README.zh.md
@@ -0,0 +1,216 @@
+---
+description: "在开启 Team 的 Session 中通过持久化共享任务板和内存等待信号协调 subagent。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-agent-team
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-agent-team` 为现有 subagent(子智能体)树添加持久化共享任务板。成员使用标准 subagent 工具发现和联系彼此。Team 提供比较并交换的任务归属更新,并在任务提交刷盘后向树中所有驻留 Agent 发出信号。挂载 `dsh-tool-agent-team` 可提供任务工具。成员共享同一检出目录。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+
+## 使用本包
+
+新 Session 默认关闭 Team 模式。参见[会话模式升级指南](../../../docs/upgrade-guide/v0.2.1-rc.2/session-team-mode/guide.zh.md)。在模型与推理等级菜单中打开**使用智能体团队**,或在根 Session 执行 `/team on`。`/team off` 移除整棵树的 Team 工具和提示词,同时保留任务与子代理。选择重启后仍有效;没有保存选择的历史任务板保持开启。部署可设置 `enabledByDefault: true`,为未保存选择且没有历史任务的 Session 指定初始模式。
+
+当 subagent 需要持久化共享任务归属和依赖关系时,添加此包。与 `@deepseek-ai/dsh-tool-agent-team` 一起挂载可提供模型工具。
+
+### 何时选择
+
+委派 agent 需要划分和跟踪共享工作时选择此包。无需共享任务板时,普通 subagent 已足够。Team 不创建隔离工作目录、不跨进程协调,也不自动释放任务所有者。
+
+### 最小工作配置
+
+
+
+在已经提供 continuable subagent、其消息工具和持久会话存储的组合(例如基于 `@deepseek-ai/dsh-base` 的 profile)中挂载两个 Team 包:
+
+```yaml
+# smallest Team addition over a composition with continuable subagents
+- name: '@deepseek-ai/dsh-agent-team'
+- name: '@deepseek-ai/dsh-tool-agent-team'
+```
+
+例如,让模型启动子代理审查差异,并在任务板上跟踪工作。唯一的限制是可选项,在启动时校验:
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxTasks` | `256` | 任务板上最多的未删除任务数 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-agent-team)是每个受支持字段及其 JSDoc 的穷尽式真源。设置 `maxMembers`、`maxMessageBytes` 或 `disposalTimeoutMs` 的配置行不会激活,dsh 会在启动警告中指出该键;[升级指南](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md)列出替代方式。
+
+### Teammate
+
+让 Lead 使用同级内唯一的 `name` 和工作 `description` 启动子代理:`subagent` 从全新上下文开始,`subagent_fork` 继承已完成轮次。返回的完整路径用于寻址队友;描述可以重复。
+
+每个根 agent 及其后代组成一个 Team。任务可分配给根 agent 或 subagent 运行时发现的任意深度的可继续执行后代。历史名册记录仍可读取,但不授予分配权限。
+
+### teammate 之间的消息
+
+成员通过标准 `list_agents` 发现整棵树,并通过 `send_message` 按完整 agent 路径联系另一成员。subagent 运行时负责路由、发送方归属和冷恢复。任务板信号面向同树所有驻留 Agent,绝不恢复冷成员。
+
+### 共享任务板
+
+任何成员都可以添加任务,包含标题、详情、对其他任务的可选依赖,以及可选的文件触及提示。只有其全部依赖完成后,任务才可 claim。
+
+成员可认领任务开始工作、完成任务、释放任务或重新打开任务。根 agent 可按完整 agent 路径将任务重新分配给自身或任意可达的可继续执行后代。其他成员自行认领任务。所有变更均采用比较并交换,过期更新无法覆盖较新的工作。
+
+当两个 in-progress 任务计划触及重叠路径时,文件提示会产生警告——它们绝不阻止任何操作。已删除任务保留在历史中,但从活动列表中消失。
+
+### 等待与中断
+
+标准 `wait_agent` 工具等待当前调用者的下一步收件箱,无需 Team 模式即可使用;参见 [subagent 控制工具](../tool-subagent-control/README.zh.md#wait_agent)。Team 模式还会在任务板提交完成刷盘后结束正在进行的等待。等待结束后重新读取任务板。不在等待期间发生的变更不会保留,也不能使后续等待立即返回。
+
+祖先通过标准 `interrupt_agent` 工具停止后代的当前轮次。中断保留尚未认领的排队消息,也不改变任务归属。
+
+### 成功与失败的表现
+
+成功时返回已提交的任务修订。未知所有者、未就绪任务、过期修订、未授权修改和任务数量耗尽会报告类型化错误。
+
+-----
+
+
+## 理解实现
+
+
+实现细节——点击展开
+
+本节解释服务背后的设计决策并指出实现它们的代码位置;可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+本服务建立在四项承诺之上:
+
+- **一棵树、一套身份。** subagent 运行时解析根并发现后代;Team 不维护第二套成员权限来源。
+- **持久日志、派生状态。** Lead 日志拥有任务和子级目录事实;每个目标 Agent 拥有已接受的消息。
+- **显式权限。** 每个服务方法都接收确切的 live 调用方 `Agent`;任务 owner 或 Lead 可以变更任务,只有 Lead 可以 reassign。
+- **超出上限时明确失败。** `maxTasks` 是经过校验的部署值,耗尽时报告类型化错误,而不是复用 id。
+
+[任务板等待决策](../../../.agents/notes/implemented/architecture/2026-10-19-team-task-board-inbox.zh.md)负责说明任务板等待信号及其与普通 subagent 控制工具的职责划分。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口、配置校验和任务服务注册 |
+| [`src/task-board.ts`](src/task-board.ts) | 任务 CAS 命令、DAG 校验与派生视图 |
+| [`src/journal.ts`](src/journal.ts) | 串行化的 Lead 日志事务与提交通知 |
+| [`src/projection.ts`](src/projection.ts) | 严格回放历史成员、任务和邮箱记录,发布 `agentTeam` 客户端视图 |
+| [`src/task-view.ts`](src/task-view.ts) | 任务板与客户端视图共用的纯任务就绪性和写入重叠推导 |
+
+### Team 身份与成员关系
+
+subagent 服务通过 `subagents.rootOf()` 解析当前在线调用者的根。中间创建者可以离线。普通 Session fork 会成为一棵新树的根。Team 使用该根 Session 作为任务板所有者,不另设成员对象。
+
+### 任务受让者
+
+重新分配通过与 `list_agents` 相同的发现机制解析根或可继续执行后代。历史 `team/member` 记录仅供解码,不能授权分配。
+
+### 消息与历史 mailbox
+
+成员通信、Steer 投递、冷恢复和发送方包装属于 subagent 运行时。任务板变更使用内存等待信号。历史 `team/message/queued`、`team/message/delivered` 记录和 `team-message` 来源仍可解码,但绝不再投递或确认。
+
+### 共享任务板
+
+任务是完整的版本化快照。修改必须携带 `expectedRevision`;过期更新报告 `TEAM_TASK_STALE_REVISION`。数字形式的 `task-` id 保持在安全整数范围内。删除的任务保留为重放墓碑,但不占用 `maxTasks`,也不出现在 `listTasks()` 中。规范化的工作区相对 `writeScopes` 会警告进行中工作的重叠,而不阻止认领或授权写入。
+
+### 任务板等待信号
+
+成功追加并刷盘后,Team 向同树所有驻留 Agent(包括调用者和根)发出以 Agent 为作用域的内存信号。信号仅结束正在进行的等待,不增加收件箱条目或未读状态,绝不启动空闲轮次,也不恢复冷成员。两次等待之间的变更不会向下一次等待重放。
+
+### 持久性模型
+
+`Service.init` 等待 `agentTeam` 投影注册完成后才发布服务就绪状态。日志持有返回的 handle,通过 `stateOf(session)` 读取任务状态;调用者使用 Team 服务,不另行注册 reader。
+
+任务修改在向当前在线根 Session 追加 `team/task` 前响应取消,随后刷盘并发出等待信号。取消不能撤回已追加的记录。刷盘失败以 `TEAM_TASK_PERSISTENCE_UNCONFIRMED` 报告任务 id 和修订号:任务已可见,但持久性未知。重试前先读取该任务。任务记录仅保留在日志中;信号不是消息,也不是持久化事件。等待工具通过普通工具流水线记录结果。不重写已提交任务或历史载荷代次。
+
+邮箱投影和检查点接纳保留本地声明校验器之外的已解码 JSON 字段,包括自身的 `__proto__` 键。历史载荷代次保持不变;投影缓存版本变化时从 Session 日志重建。
+
+### Dispose
+
+卸载服务会注销投影。保留的 handle 仍可读取,并在已获准工作收尾期间按需折叠 Session 事件。Team 不拥有 Agent:队友仍由 subagent 运行时管理,容量、收尾和拆除均由后者负责。
+
+### 浏览器投影
+
+`agentTeam` 投影发布未删除任务视图,并在最后有效状态旁报告失败。历史成员字段保留在持久化投影状态中以供解码,不发送到浏览器,也不授予运行时权限。投影失败后,后续 Team 读取和修改均报错,不再追加 Team 事件。[子系统参考](../../../docs/subsystems/agent-team.zh.md#web-projection)定义线上的类型。
+
+[Web UI](../../client/ui-agent-team/README.zh.md)仅展示任务。普通 subagent 导航负责成员列表;任务所有者标签复用 Session 和目录数据,缺失时使用 id。
+
+
+
+-----
+
+
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享子系统类型逐步进入工具表面与设计背后的决策。
+
+- [Agent Teams 子系统](../../../docs/subsystems/agent-team.zh.md)——持久 Team 类型与 `ctx.agentTeams` 服务 API。
+- [tool-agent-team 包](../tool-agent-team/README.zh.md) — 任务工具和共享任务板策略。
+- [Subagent 运行时](../subagent/README.zh.md)——teammate 使用的可继续子级、消息、中断与生命周期。
+- [subagent teammate Agent Note](../../../.agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.zh.md)——为何 teammate 是subagent,以及 Team 保留了什么。
+- [升级指南](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md)——已移除的 Team 工具、服务方法与配置键的替代方式。
+
+-----
+
+
+## 模型体验
+
+### 任务视图与错误
+
+#### 模型看到什么
+
+模型通过任务工具结果读取任务视图。面向模型的视图以 `ownerName` 标识所有者,host 视图保留 `ownerId`;过期更新报告当前修订。任务板信号结束正在进行的 `wait_agent` 调用,不提供任务内容。模型在行动前重新读取当前任务。
+
+#### Token 影响
+
+每个任务结果增加一个紧凑任务视图。等待信号不增加消息文本。
+
+#### KV Cache 影响
+
+任务记录保持在模型历史之外。任务和等待结果追加在可复用请求前缀之后。
+
+## 已知限制与延期工作
+
+
+
+
+这些限制说明一支团队目前不能做什么、或哪些方面需要特别的运维关注。它们是当前包约束,不是与其他协作机制的对比。
+
+- **全量视图广播** — 每次任务变更向已连接浏览器发送完整的未删除任务板。
+- **单进程** — 成员可观察共享文件系统编辑;此包不提供 worktree、远程成员、合并或文件系统锁。
+- **write scope 仅作提示**——Bash、formatter、代码生成器与直接外部写入可以绕过文件版本检查;Lead 必须协调 owner 并检查最终 diff。
+- **通知仅到达本地在线成员** — 不恢复冷成员,空闲成员在被明确恢复前仍保持空闲。
+
+- **通信限定在一棵树内**——成员不能向无关 Team 发消息;只有祖先能中断后代。
+- **成员关系需要在线 Team 根**——中间创建者完成或释放后,成员保留 Team 身份;根缺失时不再属于活动 Team。
+- **不会自动释放 owner**——成员不活动、interrupt、进程退出与工作失败都不会释放任务 owner。
+- **历史排队消息保持未投递**——没有对应投递记录的 `team/message/queued` 记录仍可在 Lead 日志中读取,但不会有成员收到它们。
+
+
+### 开发备注
+
+
+维护者的工作上下文——点击展开
+
+本开发备注是维护者的工作上下文,明确不具权威性。
+
+#### 未来方向
+
+尚未决定的方向包括自动释放归属和通过 worktree 隔离文件系统;两者均未承诺。
+
+
diff --git a/packages/subagent/agent-team/locale/en.json b/packages/subagent/agent-team/locale/en.json
new file mode 100644
index 0000000000..008ecd360b
--- /dev/null
+++ b/packages/subagent/agent-team/locale/en.json
@@ -0,0 +1,6 @@
+{
+ "meta": {
+ "title": "Team Collaboration",
+ "description": "Manage the shared task board for a subagent tree."
+ }
+}
diff --git a/packages/subagent/agent-team/locale/zh.json b/packages/subagent/agent-team/locale/zh.json
new file mode 100644
index 0000000000..bd6301f19f
--- /dev/null
+++ b/packages/subagent/agent-team/locale/zh.json
@@ -0,0 +1,6 @@
+{
+ "meta": {
+ "title": "团队协作",
+ "description": "管理子代理树的共享任务看板。"
+ }
+}
diff --git a/packages/subagent/agent-team/package.json b/packages/subagent/agent-team/package.json
new file mode 100644
index 0000000000..554fa42f9e
--- /dev/null
+++ b/packages/subagent/agent-team/package.json
@@ -0,0 +1,69 @@
+{
+ "name": "@deepseek-ai/dsh-agent-team",
+ "description": "Shared task DAG and change waits for subagent trees",
+ "version": "0.2.1-rc.2",
+ "publishConfig": {
+ "access": "public"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+ "directory": "packages/subagent/agent-team"
+ },
+ "type": "module",
+ "main": "lib/index.js",
+ "types": "lib/types/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./lib/types/index.d.ts",
+ "default": "./lib/index.js"
+ },
+ "./client": {
+ "types": "./lib/types/client.d.ts",
+ "default": "./lib/types/client.js"
+ },
+ "./types": {
+ "types": "./lib/types/types.d.ts",
+ "default": "./lib/types/types.js"
+ },
+ "./locale/*.json": "./locale/*.json",
+ "./src/*": "./src/*",
+ "./package.json": "./package.json"
+ },
+ "files": [
+ "locale/*.json",
+ "lib/index.js",
+ "lib/types/**/*.js",
+ "lib/types/**/*.d.ts"
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@deepseek-ai/dsh-brand": "workspace:*",
+ "@deepseek-ai/schemastery": "workspace:~",
+ "zod": "4.4.3"
+ },
+ "peerDependencies": {
+ "@deepseek-ai/cordis": "workspace:~",
+ "@deepseek-ai/dsh-agent": "workspace:*",
+ "@deepseek-ai/dsh-llm": "workspace:*",
+ "@deepseek-ai/dsh-session": "workspace:*",
+ "@deepseek-ai/dsh-session-projection": "workspace:*",
+ "@deepseek-ai/dsh-subagent": "workspace:*",
+ "@deepseek-ai/dsh-commands": "workspace:*"
+ },
+ "devDependencies": {
+ "@deepseek-ai/cordis": "workspace:~",
+ "@deepseek-ai/dsh-agent": "workspace:*",
+ "@deepseek-ai/dsh-agent-loop": "workspace:*",
+ "@deepseek-ai/dsh-agent-loop-testkit": "workspace:*",
+ "@deepseek-ai/dsh-llm": "workspace:*",
+ "@deepseek-ai/dsh-session": "workspace:*",
+ "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
+ "@deepseek-ai/dsh-session-projection": "workspace:*",
+ "@deepseek-ai/dsh-session-query": "workspace:*",
+ "@deepseek-ai/dsh-subagent": "workspace:*",
+ "@deepseek-ai/dsh-subagent-fork-in-process": "workspace:*",
+ "@deepseek-ai/dsh-subagent-spawn-in-process": "workspace:*",
+ "@deepseek-ai/dsh-commands": "workspace:*"
+ }
+}
diff --git a/packages/subagent/agent-team/src/client.ts b/packages/subagent/agent-team/src/client.ts
new file mode 100644
index 0000000000..1650a046ec
--- /dev/null
+++ b/packages/subagent/agent-team/src/client.ts
@@ -0,0 +1,10 @@
+/** Client-safe Agent Teams task views plus the `agentTeam` projection vocabulary. */
+
+export type {
+ TeamMemberPhase,
+ TeamProjection,
+ TeamModeProjection,
+ TeamTaskId,
+ TeamTaskStatus,
+ TeamTaskView,
+} from './types.ts'
diff --git a/packages/subagent/agent-team/src/error.ts b/packages/subagent/agent-team/src/error.ts
new file mode 100644
index 0000000000..51fab6f81c
--- /dev/null
+++ b/packages/subagent/agent-team/src/error.ts
@@ -0,0 +1,11 @@
+/** Typed Agent Teams failures. */
+
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+
+/** Stable failure raised by the Team domain. */
+export class TeamError extends HarnessError {
+ constructor(message: string, code: string, options?: ErrorOptions) {
+ super(message, code, options)
+ this.name = 'TeamError'
+ }
+}
diff --git a/packages/subagent/agent-team/src/index.ts b/packages/subagent/agent-team/src/index.ts
new file mode 100644
index 0000000000..994c39d6ac
--- /dev/null
+++ b/packages/subagent/agent-team/src/index.ts
@@ -0,0 +1,196 @@
+/** Shared task boards owned by subagent tree roots. */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { CommandDefinitionId } from '@deepseek-ai/dsh-commands/brand'
+import type {} from '@deepseek-ai/dsh-commands'
+import type { ProjectionHandle } from '@deepseek-ai/dsh-session-projection'
+import { teamModeProjection, type TeamModeState } from './mode.ts'
+import { emitAgentEvent } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { TeamError } from './error.ts'
+import { TeamJournal } from './journal.ts'
+import { teamProjectionDefinition } from './projection.ts'
+import { TeamTaskBoard } from './task-board.ts'
+import { TeamTaskId } from './types.ts'
+import type {
+ Config,
+ CreateTeamTaskRequest,
+ TeamTaskView,
+ UpdateTeamTaskRequest,
+} from './types.ts'
+
+export type * from './types.ts'
+export { TeamId, TeamMessageId, TeamTaskId } from './types.ts'
+export { TeamError } from './error.ts'
+
+declare module '@deepseek-ai/cordis' {
+ interface Events {
+ /**
+ * A root Session's Team selection changed in memory; descendants observe the same mode.
+ * @mode parallel
+ * @param root - exact live root whose selection changed.
+ */
+ 'team/mode-changed'(root: Agent): void
+ }
+ interface Context {
+ agentTeams: TeamService
+ }
+}
+
+const DEFAULT_MAX_TASKS = 256
+
+/** Configuration keys removed when Team reused subagent creation and messaging. */
+const REMOVED_CONFIG_KEYS = ['maxMembers', 'maxMessageBytes', 'disposalTimeoutMs'] as const
+
+/** Validate one positive safe-integer deployment limit. */
+function positiveLimit(name: string, value: number): number {
+ if (!Number.isSafeInteger(value) || value < 1) {
+ throw new TeamError(`${name} must be a positive safe integer`, 'TEAM_INVALID_CONFIG')
+ }
+ return value
+}
+
+/** Agent Teams service backed by the exact live Lead Session log. */
+export class TeamService extends Service {
+ static inject = ['agents', 'sessions', 'sessionProjections', 'subagents']
+
+ static Config: z = z.object({
+ enabledByDefault: z.boolean().default(false),
+ maxTasks: z.number().step(1).min(1).default(DEFAULT_MAX_TASKS),
+ })
+
+ private readonly enabledByDefault: boolean
+ private mode!: ProjectionHandle
+ private readonly maxTasks: number
+ private journal!: TeamJournal
+ private tasks!: TeamTaskBoard
+
+ constructor(ctx: Context, config: Config = {}) {
+ super(ctx, 'agentTeams')
+ for (const key of REMOVED_CONFIG_KEYS) {
+ if (Object.hasOwn(config, key)) {
+ throw new TeamError(
+ `agent-team: ${key} is no longer supported; teammates are subagents, so subagent limits and inbox delivery apply`,
+ 'TEAM_INVALID_CONFIG',
+ )
+ }
+ }
+ this.enabledByDefault = config.enabledByDefault ?? false
+ this.maxTasks = positiveLimit('maxTasks', config.maxTasks ?? DEFAULT_MAX_TASKS)
+ }
+
+ protected async [Service.init](): Promise {
+ const ctx = this.ctx
+ this.mode = await ctx.sessionProjections.register(teamModeProjection(this.enabledByDefault))
+ const teamProjectionHandle = await ctx.sessionProjections.register(teamProjectionDefinition)
+ this.journal = new TeamJournal(ctx, teamProjectionHandle, (root) => {
+ for (const agent of ctx.agents.list()) {
+ if (agent === root || ctx.agents.isOwnedBy(agent.id, root)) {
+ emitAgentEvent(ctx, agent, 'agent/wait-notified', {})
+ }
+ }
+ })
+ this.tasks = new TeamTaskBoard(ctx, this.journal, this.maxTasks, root => this.isEnabled(root))
+ ctx.inject(['commands'], (scope) => {
+ scope.commands.register({
+ definitionId: CommandDefinitionId('@deepseek-ai/dsh-experimental-agent-team'),
+ name: 'team',
+ description: 'Enable or disable Agent Teams for this Session',
+ input: { hint: 'on|off', attachments: false },
+ handler: async ({ agent, rawInput, signal }) => {
+ const selection = rawInput.trim()
+ if (selection !== 'on' && selection !== 'off') {
+ return { kind: 'error', text: 'Use /team on or /team off.' }
+ }
+ await this.setEnabled(agent, selection === 'on', signal)
+ return { kind: 'success', text: selection === 'on' ? 'Agent Teams enabled.' : 'Agent Teams disabled.' }
+ },
+ })
+ })
+ }
+
+ /**
+ * Read the Team selection shared by the caller's subagent tree.
+ * @param caller - exact live root or descendant.
+ * @returns whether Team tools and guidance are enabled.
+ */
+ isEnabled(caller: Agent): boolean {
+ const root = this.ctx.subagents.rootOf(caller)
+ return this.mode.stateOf(root.session).enabled ?? this.enabledByDefault
+ }
+
+ /**
+ * Save a root Session's Team selection without stopping children or deleting tasks.
+ * Tasks already admitted finish before the selection commits. Subsequent task calls
+ * use the new mode, and current waits end after the selection is flushed.
+ * @param caller - exact live root whose tree receives the selection.
+ * @param enabled - selected Team mode.
+ * @param signal - cancellation checked before appending a queued selection.
+ * @returns fulfillment after the selection flushes and scoped consumers update.
+ * @throws when called by a descendant or persistence fails. An appended selection remains active;
+ * retrying the same selection synchronizes consumers and flushes without a duplicate event.
+ */
+ async setEnabled(caller: Agent, enabled: boolean, signal?: AbortSignal): Promise {
+ const root = this.ctx.subagents.rootOf(caller)
+ if (root !== caller) throw new TeamError('change Team mode from the root Session', 'TEAM_LEAD_REQUIRED')
+ await this.journal.transact(root.id, async () => {
+ signal?.throwIfAborted()
+ this.ctx.subagents.rootOf(caller)
+ if (this.isEnabled(root) !== enabled) root.session.append('team/mode', { enabled })
+ await this.ctx.parallel('team/mode-changed', root)
+ await this.ctx.sessions.flush(root.session)
+ for (const agent of this.ctx.agents.list()) {
+ if (agent === root || this.ctx.agents.isOwnedBy(agent.id, root)) {
+ emitAgentEvent(this.ctx, agent, 'agent/wait-notified', {})
+ }
+ }
+ })
+ }
+
+ /**
+ * Create one unowned pending task in the Team Lead log.
+ * @param caller - exact live Team member creating the task.
+ * @param request - task text, blockers, and advisory write scopes.
+ * @param signal - cancellation before the task event is appended; omitted means no cancellation.
+ * @returns the revision-one task view.
+ * @throws TEAM_TASK_PERSISTENCE_UNCONFIRMED when the task is visible but durability is unknown; read it before retrying.
+ */
+ async createTask(caller: Agent, request: CreateTeamTaskRequest, signal?: AbortSignal): Promise {
+ return await this.tasks.create(caller, this.ctx.subagents.rootOf(caller), request, signal)
+ }
+
+ /**
+ * Return one task, including a deleted tombstone.
+ * @param caller - exact live Team member reading the task.
+ * @param id - Team-local task identity.
+ * @returns the latest task value and derived readiness diagnostics.
+ */
+ getTask(caller: Agent, id: TeamTaskId): TeamTaskView {
+ return this.tasks.get(this.ctx.subagents.rootOf(caller), id)
+ }
+
+ /**
+ * List current non-deleted tasks in numeric creation order.
+ * @param caller - exact live Team member reading the board.
+ * @returns detached current task views.
+ */
+ listTasks(caller: Agent): TeamTaskView[] {
+ return this.tasks.list(this.ctx.subagents.rootOf(caller))
+ }
+
+ /**
+ * Compare-and-set one authorized task transition.
+ * @param caller - exact live Team member authorizing the mutation.
+ * @param request - task identity, expected revision, action, and action fields.
+ * @param signal - cancellation before the task event is appended; omitted means no cancellation.
+ * @returns the committed next task revision.
+ * @throws TEAM_TASK_PERSISTENCE_UNCONFIRMED when the task is visible but durability is unknown; read it before retrying.
+ */
+ async updateTask(caller: Agent, request: UpdateTeamTaskRequest, signal?: AbortSignal): Promise {
+ return await this.tasks.update(caller, this.ctx.subagents.rootOf(caller), request, signal)
+ }
+
+}
+
+export default TeamService
diff --git a/packages/subagent/agent-team/src/journal.ts b/packages/subagent/agent-team/src/journal.ts
new file mode 100644
index 0000000000..f19696c735
--- /dev/null
+++ b/packages/subagent/agent-team/src/journal.ts
@@ -0,0 +1,77 @@
+/** Serialized Team transactions over the exact live Lead Session log. */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ProjectionHandle } from '@deepseek-ai/dsh-session-projection'
+import type { Context } from '@deepseek-ai/cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { TeamProjectionState, TeamState } from './projection.ts'
+
+import { TeamId } from './types.ts'
+import { TeamError } from './error.ts'
+import type { TeamTaskSnapshot } from './types.ts'
+
+/** Owns per-Lead transaction order and committed Team event publication. */
+export class TeamJournal {
+ private readonly tails = new Map>()
+
+ /**
+ * @param ctx - Team service context with the injected Session service.
+ * @param teamProjectionHandle - Team state registration owned by the Team service.
+ * @param onCommit - synchronous notification after the Team event flush succeeds.
+ */
+ constructor(
+ private readonly ctx: Context,
+ private readonly teamProjectionHandle: ProjectionHandle,
+ private readonly onCommit: (root: Agent) => void,
+ ) {}
+
+ /**
+ * Read authoritative Team state for one exact live Lead.
+ * @param root - exact live Team Lead.
+ * @returns current projected state selected by the Lead Team id.
+ * @throws when the durable Team projection has failed.
+ */
+ state(root: Agent): TeamState {
+ const projection = this.teamProjectionHandle.stateOf(root.session)
+ if (projection.failure !== undefined) throw new Error(projection.failure)
+ return projection
+ }
+
+ /**
+ * Serialize one Lead's asynchronous mutation operation.
+ * @param rootId - Lead Session identity selecting the transaction queue.
+ * @param operation - complete read-check-append operation.
+ * @returns the operation result.
+ */
+ async transact(rootId: SessionId, operation: () => Promise): Promise {
+ const prior = this.tails.get(rootId) ?? Promise.resolve()
+ const run = prior.then(operation, operation)
+ const tail = run.then(() => undefined, () => undefined)
+ this.tails.set(rootId, tail)
+ try {
+ return await run
+ } finally {
+ if (this.tails.get(rootId) === tail) this.tails.delete(rootId)
+ }
+ }
+
+ /**
+ * Commit a task before notifying current waits in its tree.
+ * @param root - live tree root whose Session stores the task.
+ * @param task - complete committed task revision.
+ * @throws TEAM_TASK_PERSISTENCE_UNCONFIRMED after append when durability cannot be confirmed; read the task before retrying.
+ */
+ async appendAndFlush(root: Agent, task: TeamTaskSnapshot): Promise {
+ root.session.append('team/task', { version: 2, teamId: TeamId(root.id), task })
+ try {
+ await this.ctx.sessions.flush(root.session)
+ } catch (error: unknown) {
+ throw new TeamError(
+ `task "${task.id}" revision ${task.revision} is visible, but persistence was not confirmed; read the task before retrying`,
+ 'TEAM_TASK_PERSISTENCE_UNCONFIRMED',
+ { cause: error },
+ )
+ }
+ this.onCommit(root)
+ }
+}
diff --git a/packages/subagent/agent-team/src/mode.ts b/packages/subagent/agent-team/src/mode.ts
new file mode 100644
index 0000000000..fceac248ed
--- /dev/null
+++ b/packages/subagent/agent-team/src/mode.ts
@@ -0,0 +1,38 @@
+/** Durable Team enablement, including Sessions created before the mode selector. */
+
+import { z } from 'zod'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import type { TeamModeProjection } from './types.ts'
+
+/** Null means no Session-specific selection or historical task exists. */
+export interface TeamModeState {
+ readonly enabled: boolean | null
+}
+
+type ModeDefinition = ProjectionDefinition<'agentTeamMode', TeamModeState>
+
+/**
+ * Create the mode projection using the deployment's initial selection.
+ * @param enabledByDefault - initial mode for Sessions without a saved selection or task.
+ * @returns the projection definition; historical task boards stay enabled until explicitly disabled.
+ */
+export function teamModeProjection(enabledByDefault: boolean): ModeDefinition & { wire: NonNullable } {
+ const on = { enabled: true }
+ const off = { enabled: false }
+ const selectionSchema = z.object({ enabled: z.boolean() }).strict()
+ return {
+ key: 'agentTeamMode',
+ stateVersion: 1,
+ stateSchema: z.object({ enabled: z.boolean().nullable() }).strict(),
+ init: () => ({ enabled: null }),
+ apply: (state, event) => {
+ if (event.type === 'team/mode') return selectionSchema.parse(event.data)
+ if (state.enabled === null && event.type === 'team/task') return { enabled: true }
+ return state
+ },
+ wire: {
+ viewSchema: selectionSchema,
+ view: (state): TeamModeProjection => (state.enabled ?? enabledByDefault) ? on : off,
+ },
+ } satisfies ProjectionDefinition<'agentTeamMode', TeamModeState>
+}
diff --git a/packages/subagent/agent-team/src/projection.ts b/packages/subagent/agent-team/src/projection.ts
new file mode 100644
index 0000000000..4bc4b30275
--- /dev/null
+++ b/packages/subagent/agent-team/src/projection.ts
@@ -0,0 +1,366 @@
+/** Team state projected incrementally from committed Session events, with a durable-only client view. */
+
+import { z } from 'zod'
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, SessionEventMap, SessionId } from '@deepseek-ai/dsh-session'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import type {
+ TeamId,
+ TeamMemberSnapshot,
+ TeamMessageId,
+ TeamMessageSnapshot,
+ TeamProjection,
+ TeamTaskSnapshot,
+ TeamTaskView,
+} from './types.ts'
+import {
+ TeamId as toTeamId,
+ TeamMessageId as toTeamMessageId,
+ TeamTaskId as toTeamTaskId,
+} from './types.ts'
+import { assertTaskGraphCandidate } from './task-graph.ts'
+import { projectTaskView } from './task-view.ts'
+
+const nonNegativeSafeInteger = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)
+const positiveSafeInteger = nonNegativeSafeInteger.min(1)
+const sessionIdSchema = z.string().min(1).transform(value => brandString(value))
+const teamIdSchema = z.string().min(1).transform(value => toTeamId(value))
+const numericTaskIdPattern = /^task-(\d+)$/u
+const teamTaskIdSchema = z.string().min(1).refine((value) => {
+ const match = numericTaskIdPattern.exec(value)
+ return match === null || Number.isSafeInteger(Number(match[1]))
+}, { message: 'numeric task id suffix must be a safe integer' }).transform(value => toTeamTaskId(value))
+const teamMessageIdSchema = z.string().min(1).transform(value => toTeamMessageId(value))
+
+const coreContentBlockTypes = new Set(['text', 'reasoning', 'image', 'tool-call', 'tool-result'])
+const imageAttachmentSchema = z.object({
+ attachmentId: z.string().min(1),
+ mediaType: z.enum(['image/png', 'image/jpeg', 'image/webp', 'image/gif']),
+ bytes: nonNegativeSafeInteger,
+ width: positiveSafeInteger,
+ height: positiveSafeInteger,
+ name: z.string().optional(),
+}).strict()
+
+// Validate the listed variants; retired tool-result tags cannot enter the
+// merge-extensible fallback for JSON-decoded plugin content.
+const contentBlockSchema: z.ZodType = z.lazy(() => z.union([
+ z.object({ type: z.literal('text'), text: z.string() }).strict(),
+ z.object({ type: z.literal('reasoning'), text: z.string() }).strict(),
+ z.object({ type: z.literal('image'), attachment: imageAttachmentSchema }).strict(),
+ z.object({
+ type: z.literal('tool-call'),
+ id: z.string().min(1),
+ name: z.string(),
+ arguments: z.string(),
+ }).strict(),
+ // Keep unknown JSON objects by reference; loose-object parsing drops their own __proto__ keys.
+ z.custom((value) => {
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+ const type = (value as { type?: unknown }).type
+ return typeof type === 'string' && type.length > 0 && !coreContentBlockTypes.has(type)
+ }),
+])) as z.ZodType
+
+const teamMemberSnapshotSchema = z.object({
+ id: sessionIdSchema,
+ name: z.string(),
+ description: z.string(),
+ provider: z.string(),
+ context: z.enum(['fresh', 'fork']),
+ phase: z.enum(['provisioning', 'active', 'failed']),
+ error: z.string().optional(),
+}).strict() as z.ZodType
+
+const teamTaskSnapshotSchema = z.object({
+ id: teamTaskIdSchema,
+ revision: positiveSafeInteger,
+ subject: z.string(),
+ description: z.string(),
+ status: z.enum(['pending', 'in_progress', 'completed', 'deleted']),
+ ownerId: sessionIdSchema.optional(),
+ blockedBy: z.array(teamTaskIdSchema),
+ writeScopes: z.array(z.string()),
+}).strict() as z.ZodType
+
+const teamMessageSnapshotSchema = z.object({
+ id: teamMessageIdSchema,
+ senderId: sessionIdSchema,
+ senderName: z.string(),
+ targetId: sessionIdSchema,
+ content: z.array(contentBlockSchema),
+}).strict() as z.ZodType
+
+const teamEventSelectorSchema = z.object({
+ version: nonNegativeSafeInteger,
+ teamId: teamIdSchema,
+}).loose()
+
+const teamMemberEventSchema = z.object({
+ version: z.literal(2),
+ teamId: teamIdSchema,
+ member: teamMemberSnapshotSchema,
+}).strict() as z.ZodType
+
+const teamTaskEventSchema = z.object({
+ version: z.literal(2),
+ teamId: teamIdSchema,
+ task: teamTaskSnapshotSchema,
+}).strict() as z.ZodType
+
+const teamMessageQueuedEventSchema = z.object({
+ version: z.literal(2),
+ teamId: teamIdSchema,
+ message: teamMessageSnapshotSchema,
+}).strict() as z.ZodType
+
+const teamMessageDeliveredEventSchema = z.object({
+ version: z.literal(2),
+ teamId: teamIdSchema,
+ messageId: teamMessageIdSchema,
+ targetId: sessionIdSchema,
+}).strict() as z.ZodType
+
+/**
+ * Current Team state selected by durable Team identity. Every applied Team
+ * event produces a new state object and replaces only the collection it
+ * touched; untouched collections keep their references.
+ */
+export interface TeamState {
+ readonly id: TeamId
+ /** Historical roster records written by earlier Team builds. */
+ readonly members: readonly TeamMemberSnapshot[]
+ readonly tasks: readonly TeamTaskSnapshot[]
+ readonly messages: readonly TeamMessageSnapshot[]
+ readonly delivered: readonly TeamMessageId[]
+ readonly nextTaskNumber: number
+}
+
+/**
+ * Construct empty state for one Team identity.
+ * @param rootId - root Session identity.
+ * @returns empty Team state.
+ */
+export function emptyTeamState(rootId: SessionId): TeamProjectionState {
+ return {
+ id: toTeamId(rootId),
+ members: [],
+ tasks: [],
+ messages: [],
+ delivered: [],
+ nextTaskNumber: 1,
+ }
+}
+
+/** Checkpoint-safe state for the Team owned by the projected Session. */
+export interface TeamProjectionState extends TeamState {
+ readonly failure?: string
+}
+
+const teamProjectionEntrySchema = z.object({
+ id: teamIdSchema,
+ members: z.array(teamMemberSnapshotSchema),
+ tasks: z.array(teamTaskSnapshotSchema),
+ messages: z.array(teamMessageSnapshotSchema),
+ delivered: z.array(teamMessageIdSchema),
+ nextTaskNumber: positiveSafeInteger,
+ failure: z.string().optional(),
+}).strict() as z.ZodType
+
+/** Whether one event belongs to the Team domain. */
+export type TeamEventType =
+ | 'team/member'
+ | 'team/task'
+ | 'team/message/queued'
+ | 'team/message/delivered'
+
+/** One event owned by the Team domain. */
+type TeamSessionEvent = SessionEvent
+
+/**
+ * Test whether a Session event belongs to the Team domain.
+ * @param event - candidate Session event.
+ * @returns whether the event has a Team-owned type.
+ */
+export function isTeamEvent(event: SessionEvent): event is TeamSessionEvent {
+ return event.type === 'team/member'
+ || event.type === 'team/task'
+ || event.type === 'team/message/queued'
+ || event.type === 'team/message/delivered'
+}
+
+/** Decode one persisted Team value and retain the schema failure as its cause. */
+function parsePersisted(type: TeamEventType, schema: z.ZodType, value: unknown): T {
+ try {
+ return schema.parse(value)
+ } catch (error: unknown) {
+ throw new Error(`persisted Agent Teams ${type} payload is invalid`, { cause: error })
+ }
+}
+
+/** Decode the complete current-version payload selected by one Team event type. */
+function parseCurrentTeamEvent(event: TeamSessionEvent): TeamSessionEvent {
+ switch (event.type) {
+ case 'team/member':
+ return { ...event, data: parsePersisted(event.type, teamMemberEventSchema, event.data) }
+ case 'team/task':
+ return { ...event, data: parsePersisted(event.type, teamTaskEventSchema, event.data) }
+ case 'team/message/queued':
+ return { ...event, data: parsePersisted(event.type, teamMessageQueuedEventSchema, event.data) }
+ case 'team/message/delivered':
+ return { ...event, data: parsePersisted(event.type, teamMessageDeliveredEventSchema, event.data) }
+ /* v8 ignore next 2 -- TeamEventType is closed and every member is handled above. */
+ default:
+ return event
+ }
+}
+
+function applyProjectionEvent(state: TeamProjectionState, event: SessionEvent): TeamProjectionState {
+ if (state.failure !== undefined) return state
+ if (!isTeamEvent(event)) return state
+ try {
+ const selector = parsePersisted(event.type, teamEventSelectorSchema, event.data)
+ if (selector.teamId !== state.id) return state
+ if (selector.version !== 2) {
+ throw new Error(`unsupported Agent Teams event version ${String(selector.version)}`)
+ }
+ return applyCurrentTeamEvent(state, parseCurrentTeamEvent(event))
+ } catch (error: unknown) {
+ /* v8 ignore next -- the owned Team transition throws Error instances. */
+ return { ...state, failure: error instanceof Error ? error.message : String(error) }
+ }
+}
+
+function replaceAt(items: readonly T[], index: number, item: T): T[] {
+ const next = [...items]
+ if (index < 0) next.push(item)
+ else next[index] = item
+ return next
+}
+
+function applyCurrentTeamEvent(state: TeamProjectionState, event: TeamSessionEvent): TeamProjectionState {
+ switch (event.type) {
+ case 'team/member': {
+ const member = event.data.member
+ const index = state.members.findIndex(candidate => candidate.id === member.id)
+ const prior = state.members[index]
+ const named = state.members.find(candidate => candidate.name === member.name)
+ if (named !== undefined && named.id !== member.id) {
+ throw new Error(`teammate name "${member.name}" is reused by another member`)
+ }
+ if (prior === undefined) {
+ if (member.phase !== 'provisioning') throw new Error(`teammate "${member.name}" must begin provisioning`)
+ } else {
+ if (prior.name !== member.name || prior.provider !== member.provider || prior.context !== member.context) {
+ throw new Error(`teammate "${member.id}" changed immutable identity fields`)
+ }
+ if (prior.phase !== 'provisioning' || member.phase === 'provisioning') {
+ throw new Error(`teammate "${member.name}" has an invalid ${prior.phase} -> ${member.phase} transition`)
+ }
+ }
+ return { ...state, members: replaceAt(state.members, index, member) }
+ }
+ case 'team/task': {
+ const task = event.data.task
+ const index = state.tasks.findIndex(candidate => candidate.id === task.id)
+ const prior = state.tasks[index]
+ if (prior === undefined && task.revision !== 1) {
+ throw new Error(`team task "${task.id}" must begin at revision 1`)
+ }
+ if (prior !== undefined && task.revision !== prior.revision + 1) {
+ throw new Error(`team task "${task.id}" revision is not contiguous`)
+ }
+ assertTaskGraphCandidate(state.tasks, task)
+ let nextTaskNumber = state.nextTaskNumber
+ const match = numericTaskIdPattern.exec(task.id)
+ if (match !== null) {
+ const number = Number(match[1])
+ nextTaskNumber = Math.max(
+ nextTaskNumber,
+ number === Number.MAX_SAFE_INTEGER ? number : number + 1,
+ )
+ }
+ return { ...state, tasks: replaceAt(state.tasks, index, task), nextTaskNumber }
+ }
+ case 'team/message/queued': {
+ const message = event.data.message
+ if (state.messages.some(candidate => candidate.id === message.id)) {
+ throw new Error(`team message "${message.id}" was queued twice`)
+ }
+ return { ...state, messages: [...state.messages, message] }
+ }
+ case 'team/message/delivered': {
+ const queued = state.messages.find(message => message.id === event.data.messageId)
+ if (queued === undefined) throw new Error(`team message "${event.data.messageId}" was delivered before queueing`)
+ if (queued.targetId !== event.data.targetId) throw new Error(`team message "${event.data.messageId}" target changed`)
+ if (state.delivered.includes(event.data.messageId)) throw new Error(`team message "${event.data.messageId}" was delivered twice`)
+ return { ...state, delivered: [...state.delivered, event.data.messageId] }
+ }
+ /* v8 ignore next 2 -- TeamEventType is closed and every member is handled above. */
+ default:
+ return state
+ }
+}
+
+const teamTaskViewSchema = z.object({
+ id: teamTaskIdSchema,
+ revision: positiveSafeInteger,
+ subject: z.string(),
+ description: z.string(),
+ status: z.enum(['pending', 'in_progress', 'completed', 'deleted']),
+ blockedBy: z.array(teamTaskIdSchema),
+ writeScopes: z.array(z.string()),
+ ownerId: sessionIdSchema.optional(),
+ ready: z.boolean(),
+ writeScopeWarnings: z.array(z.string()),
+}).strict() as z.ZodType
+
+const teamProjectionSchema = z.object({
+ tasks: z.array(teamTaskViewSchema),
+ failure: z.string().optional(),
+}).strict() as z.ZodType
+
+/** Client views keyed by their task collection; historical roster and mailbox changes publish nothing. */
+const teamProjectionViews = new WeakMap()
+
+function buildTeamProjection(state: TeamProjectionState): TeamProjection {
+ return {
+ tasks: state.tasks
+ .filter(task => task.status !== 'deleted')
+ .map(task => projectTaskView(state, task)),
+ ...state.failure === undefined ? {} : { failure: state.failure },
+ }
+}
+
+/**
+ * Durable client view of one Team state. Historical roster and mailbox changes reuse the
+ * previous view reference, so the live drive publishes nothing for them.
+ * A failure is terminal: later events retain the failed state reference and
+ * do not republish its view.
+ * @param state - current Team state.
+ * @returns the non-deleted task board, plus any projection failure.
+ */
+export function teamProjectionView(state: TeamProjectionState): TeamProjection {
+ if (state.failure !== undefined) return buildTeamProjection(state)
+ let view = teamProjectionViews.get(state.tasks)
+ if (view === undefined) {
+ view = buildTeamProjection(state)
+ teamProjectionViews.set(state.tasks, view)
+ }
+ return view
+}
+
+/**
+ * Team projection selected by the projected Session identity; the wire view
+ * carries the task board. Current subagents are
+ * supplied separately by the existing `subagentCatalog` projection.
+ */
+export const teamProjectionDefinition = {
+ key: 'agentTeam',
+ stateVersion: 4,
+ stateSchema: teamProjectionEntrySchema,
+ init: (header, _inheritedEventCount) => emptyTeamState(header.id),
+ apply: applyProjectionEvent,
+ wire: { viewSchema: teamProjectionSchema, view: teamProjectionView },
+} satisfies ProjectionDefinition<'agentTeam', TeamProjectionState>
diff --git a/packages/subagent/agent-team/src/task-board.ts b/packages/subagent/agent-team/src/task-board.ts
new file mode 100644
index 0000000000..73d90f6ebb
--- /dev/null
+++ b/packages/subagent/agent-team/src/task-board.ts
@@ -0,0 +1,279 @@
+/** Shared Team task DAG commands and runtime-enriched views. */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { Context } from '@deepseek-ai/cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-subagent'
+import { TeamError } from './error.ts'
+import type { TeamJournal } from './journal.ts'
+import type { TeamState } from './projection.ts'
+import { assertTaskGraphCandidate, TeamTaskGraphError } from './task-graph.ts'
+import type { TeamTaskGraphViolation } from './task-graph.ts'
+import { TeamTaskId } from './types.ts'
+import type {
+ CreateTeamTaskRequest,
+ TeamTaskSnapshot,
+ TeamTaskView,
+ UpdateTeamTaskRequest,
+} from './types.ts'
+import { projectTaskView, taskReady } from './task-view.ts'
+import { requiredText, writeScope } from './validation.ts'
+
+const TASK_GRAPH_ERROR_CODES: Record = {
+ missing: 'TEAM_TASK_NOT_FOUND',
+ duplicate: 'TEAM_INVALID_ARGUMENT',
+ cycle: 'TEAM_TASK_DEPENDENCY_CYCLE',
+}
+
+/** Owns Team task limits, authorization, transitions, and derived views. */
+export class TeamTaskBoard {
+ /**
+ * @param ctx - subagent discovery for task assignees.
+ * @param journal - authoritative Lead-log transaction owner.
+ * @param maxTasks - maximum non-deleted tasks retained by one Team.
+ * @param enabled - whether the root permits task-board operations.
+ */
+ constructor(
+ private readonly ctx: Context,
+ private readonly journal: TeamJournal,
+ private readonly maxTasks: number,
+ private readonly enabled: (root: Agent) => boolean,
+ ) {}
+
+ private state(root: Agent) {
+ if (!this.enabled(root)) throw new TeamError('enable Agent Teams for this Session before using the task board', 'TEAM_DISABLED')
+ return this.journal.state(root)
+ }
+
+ /**
+ * Create one unowned pending task in the Team Lead log.
+ * @param caller - exact live Agent creating the task.
+ * @param root - live subagent tree root owning the board.
+ * @param request - task text, blockers, and advisory write scopes.
+ * @param signal - cancellation before append; omitted means no cancellation.
+ * @returns the revision-one task view.
+ */
+ async create(caller: Agent, root: Agent, request: CreateTeamTaskRequest, signal?: AbortSignal): Promise {
+ return this.journal.transact(root.id, async () => {
+ signal?.throwIfAborted()
+ const state = this.state(root)
+ const active = state.tasks.filter(task => task.status !== 'deleted').length
+ if (active >= this.maxTasks) {
+ throw new TeamError(`Team task limit ${this.maxTasks} reached`, 'TEAM_TASK_LIMIT')
+ }
+ const id = TeamTaskId(`task-${state.nextTaskNumber}`)
+ if (state.tasks.some(task => task.id === id)) {
+ throw new TeamError('Team task id space exhausted', 'TEAM_TASK_LIMIT')
+ }
+ const task: TeamTaskSnapshot = {
+ id,
+ revision: 1,
+ subject: requiredText(request.subject, 'subject', 200),
+ description: requiredText(request.description, 'description', 16_384),
+ status: 'pending',
+ blockedBy: this.dependencies(request.blockedBy ?? [], state),
+ writeScopes: this.writeScopes(request.writeScopes ?? []),
+ }
+ this.assertTaskGraph(state, task)
+ // The transaction queue may outlive its caller.
+ this.ctx.subagents.rootOf(caller)
+ await this.journal.appendAndFlush(root, task)
+ return projectTaskView(state, task)
+ })
+ }
+
+ /**
+ * Return one task, including a deleted tombstone.
+ * @param root - live subagent tree root owning the board.
+ * @param id - Team-local task identity.
+ * @returns the latest task value and derived readiness diagnostics.
+ */
+ get(root: Agent, id: TeamTaskId): TeamTaskView {
+ const state = this.state(root)
+ const task = state.tasks.find(candidate => candidate.id === id)
+ if (task === undefined) throw new TeamError(`team task "${id}" not found`, 'TEAM_TASK_NOT_FOUND')
+ return projectTaskView(state, task)
+ }
+
+ /**
+ * List current non-deleted tasks in numeric creation order.
+ * @param root - live subagent tree root owning the board.
+ * @returns detached current task views.
+ */
+ list(root: Agent): TeamTaskView[] {
+ const state = this.state(root)
+ return state.tasks
+ .filter(task => task.status !== 'deleted')
+ .map(task => projectTaskView(state, task))
+ }
+
+ /**
+ * Compare-and-set one authorized task transition.
+ * @param caller - exact live Team member authorizing the mutation.
+ * @param root - live subagent tree root owning the board.
+ * @param request - task identity, expected revision, action, and action fields.
+ * @param signal - cancellation before append; omitted means no cancellation.
+ * @returns the committed next task revision.
+ */
+ async update(
+ caller: Agent,
+ root: Agent,
+ request: UpdateTeamTaskRequest,
+ signal?: AbortSignal,
+ ): Promise {
+ return this.journal.transact(root.id, async () => {
+ signal?.throwIfAborted()
+ const state = this.state(root)
+ const current = state.tasks.find(task => task.id === request.taskId)
+ if (current === undefined) throw new TeamError(`team task "${request.taskId}" not found`, 'TEAM_TASK_NOT_FOUND')
+ if (current.revision !== request.expectedRevision) {
+ throw new TeamError(
+ `stale team task "${current.id}" revision ${request.expectedRevision}; current revision is ${current.revision}`,
+ 'TEAM_TASK_STALE_REVISION',
+ )
+ }
+ if (current.status === 'deleted') throw new TeamError(`team task "${current.id}" is deleted`, 'TEAM_TASK_DELETED')
+ const lead = caller === root
+ const owner = current.ownerId === caller.id
+ const authorizeOwner = (): void => {
+ if (!lead && !owner) throw new TeamError('task mutation requires its owner or Team Lead', 'TEAM_TASK_UNAUTHORIZED')
+ }
+ let next: TeamTaskSnapshot
+ switch (request.action) {
+ case 'claim':
+ if (current.ownerId !== undefined && current.ownerId !== caller.id) {
+ throw new TeamError(`team task "${current.id}" is owned by another member`, 'TEAM_TASK_ALREADY_CLAIMED')
+ }
+ if (current.status !== 'pending' || !taskReady(state, current)) {
+ throw new TeamError(`team task "${current.id}" is not ready to claim`, 'TEAM_TASK_BLOCKED')
+ }
+ next = { ...current, status: 'in_progress', ownerId: caller.id }
+ break
+ case 'release':
+ authorizeOwner()
+ if (current.status !== 'in_progress') throw new TeamError('only an in-progress task can be released', 'TEAM_TASK_INVALID_TRANSITION')
+ next = this.withoutOwner({ ...current, status: 'pending' })
+ break
+ case 'edit':
+ authorizeOwner()
+ if (request.subject === undefined && request.description === undefined && request.writeScopes === undefined) {
+ throw new TeamError('task edit requires subject, description, or write_scopes', 'TEAM_INVALID_ARGUMENT')
+ }
+ next = {
+ ...current,
+ ...request.subject === undefined ? {} : { subject: requiredText(request.subject, 'subject', 200) },
+ ...request.description === undefined
+ ? {}
+ : { description: requiredText(request.description, 'description', 16_384) },
+ ...request.writeScopes === undefined ? {} : { writeScopes: this.writeScopes(request.writeScopes) },
+ }
+ break
+ case 'set_dependencies':
+ authorizeOwner()
+ if (request.blockedBy === undefined) throw new TeamError('set_dependencies requires blocked_by', 'TEAM_INVALID_ARGUMENT')
+ next = { ...current, blockedBy: this.dependencies(request.blockedBy, state, current.id) }
+ break
+ case 'complete':
+ authorizeOwner()
+ if (current.status !== 'in_progress') throw new TeamError('only an in-progress task can complete', 'TEAM_TASK_INVALID_TRANSITION')
+ next = { ...current, status: 'completed' }
+ break
+ case 'reopen':
+ authorizeOwner()
+ if (current.status !== 'completed') throw new TeamError('only a completed task can reopen', 'TEAM_TASK_INVALID_TRANSITION')
+ next = this.withoutOwner({ ...current, status: 'pending' })
+ break
+ case 'reassign': {
+ if (!lead) throw new TeamError('only the Team Lead can reassign tasks', 'TEAM_LEAD_REQUIRED')
+ if (current.status !== 'pending' && current.status !== 'in_progress') {
+ throw new TeamError(
+ 'only a pending or in-progress task can be reassigned',
+ 'TEAM_TASK_INVALID_TRANSITION',
+ )
+ }
+ if (request.owner === undefined) {
+ next = this.withoutOwner({ ...current, status: 'pending' })
+ break
+ }
+ if (!taskReady(state, current)) throw new TeamError(`team task "${current.id}" is blocked`, 'TEAM_TASK_BLOCKED')
+ next = { ...current, status: 'in_progress', ownerId: await this.resolveAssignee(root, request.owner, signal) }
+ break
+ }
+ case 'delete': {
+ authorizeOwner()
+ const dependent = state.tasks.find(task =>
+ task.status !== 'deleted' && task.id !== current.id && task.blockedBy.includes(current.id))
+ if (dependent !== undefined) {
+ throw new TeamError(`team task "${current.id}" still blocks "${dependent.id}"`, 'TEAM_TASK_HAS_DEPENDENTS')
+ }
+ next = { ...current, status: 'deleted' }
+ break
+ }
+ /* v8 ignore next 2 -- TeamTaskAction is closed and every member is handled above. */
+ default:
+ throw new TeamError(`unsupported task action ${String(request.action)}`, 'TEAM_INVALID_ARGUMENT')
+ }
+ const task: TeamTaskSnapshot = {
+ ...next,
+ revision: current.revision + 1,
+ }
+ this.assertTaskGraph(state, task)
+ signal?.throwIfAborted()
+ // Queueing and assignee discovery may outlive the caller.
+ this.ctx.subagents.rootOf(caller)
+ await this.journal.appendAndFlush(root, task)
+ return projectTaskView(state, task)
+ })
+ }
+
+ /** Resolve a task owner through the same durable tree used by Agent discovery. */
+ private async resolveAssignee(root: Agent, target: SessionId, signal?: AbortSignal): Promise {
+ if (target === root.id) return target
+ const descendants = await this.ctx.subagents.listDescendants(root.id, signal)
+ if (descendants.some(entry => entry.kind !== 'diagnostic' && entry.mode === 'continuable' && entry.id === target)) return target
+ throw new TeamError(`agent "${target}" is not a continuable descendant of this task board's root`, 'TEAM_MEMBER_NOT_FOUND')
+ }
+
+ /** Validate and de-duplicate dependency ids against the current task graph. */
+ private dependencies(
+ values: readonly TeamTaskId[],
+ state: TeamState,
+ self?: TeamTaskId,
+ ): TeamTaskId[] {
+ const seen = new Set()
+ const result: TeamTaskId[] = []
+ for (const id of values) {
+ if (id === self) throw new TeamError('a team task cannot block itself', 'TEAM_TASK_DEPENDENCY_CYCLE')
+ if (seen.has(id)) throw new TeamError(`duplicate blocker "${id}"`, 'TEAM_INVALID_ARGUMENT')
+ const task = state.tasks.find(candidate => candidate.id === id)
+ if (task === undefined || task.status === 'deleted') {
+ throw new TeamError(`blocker task "${id}" not found`, 'TEAM_TASK_NOT_FOUND')
+ }
+ seen.add(id)
+ result.push(id)
+ }
+ return result
+ }
+
+ /** Normalize and de-duplicate task write scopes. */
+ private writeScopes(values: readonly string[]): string[] {
+ return [...new Set(values.map(writeScope))]
+ }
+
+ /** Map shared task-graph validation onto stable command error codes. */
+ private assertTaskGraph(state: TeamState, candidate: TeamTaskSnapshot): void {
+ try {
+ assertTaskGraphCandidate(state.tasks, candidate)
+ } catch (error: unknown) {
+ /* v8 ignore next -- the shared validator is the only statement in the try and throws this exact error. */
+ if (!(error instanceof TeamTaskGraphError)) throw error
+ throw new TeamError(error.message, TASK_GRAPH_ERROR_CODES[error.violation], { cause: error })
+ }
+ }
+
+ /** Remove an optional owner field under exactOptionalPropertyTypes. */
+ private withoutOwner(task: TeamTaskSnapshot): TeamTaskSnapshot {
+ const { ownerId: _ownerId, ...without } = task
+ return without
+ }
+}
diff --git a/packages/subagent/agent-team/src/task-graph.ts b/packages/subagent/agent-team/src/task-graph.ts
new file mode 100644
index 0000000000..bd61b953bc
--- /dev/null
+++ b/packages/subagent/agent-team/src/task-graph.ts
@@ -0,0 +1,69 @@
+/** Complete dependency validation for current Team task snapshots. */
+
+import type { TeamTaskId, TeamTaskSnapshot } from './types.ts'
+
+/** Task dependency relation rejected by the shared graph validator. */
+export type TeamTaskGraphViolation = 'missing' | 'duplicate' | 'cycle'
+
+/** Package-private task dependency failure retained for command error mapping. */
+export class TeamTaskGraphError extends Error {
+ /**
+ * @param message - concrete invalid dependency relation.
+ * @param violation - stable relation category used by Team commands.
+ */
+ constructor(message: string, readonly violation: TeamTaskGraphViolation) {
+ super(message)
+ this.name = 'TeamTaskGraphError'
+ }
+}
+
+/**
+ * Validate the complete active task graph after replacing one candidate snapshot.
+ * @param current - current task snapshots before the candidate event.
+ * @param candidate - new or next-revision task snapshot.
+ * @throws {TeamTaskGraphError} when an active dependency is missing, duplicated, self-referential, or cyclic.
+ */
+export function assertTaskGraphCandidate(
+ current: readonly TeamTaskSnapshot[],
+ candidate: TeamTaskSnapshot,
+): void {
+ const tasks = new Map(current.map(task => [task.id, task]))
+ tasks.set(candidate.id, candidate)
+
+ for (const task of tasks.values()) {
+ if (task.status === 'deleted') continue
+ const seen = new Set()
+ for (const blockerId of task.blockedBy) {
+ if (blockerId === task.id) {
+ throw new TeamTaskGraphError(`team task "${task.id}" cannot block itself`, 'cycle')
+ }
+ if (seen.has(blockerId)) {
+ throw new TeamTaskGraphError(`team task "${task.id}" repeats blocker "${blockerId}"`, 'duplicate')
+ }
+ const blocker = tasks.get(blockerId)
+ if (blocker === undefined || blocker.status === 'deleted') {
+ throw new TeamTaskGraphError(
+ `blocker task "${blockerId}" for "${task.id}" is missing or deleted`,
+ 'missing',
+ )
+ }
+ seen.add(blockerId)
+ }
+ }
+
+ const visiting = new Set()
+ const visited = new Set()
+ const visit = (id: TeamTaskId): void => {
+ if (visiting.has(id)) {
+ throw new TeamTaskGraphError(`task dependency cycle includes "${id}"`, 'cycle')
+ }
+ if (visited.has(id)) return
+ const task = tasks.get(id)
+ if (task === undefined || task.status === 'deleted') return
+ visiting.add(id)
+ for (const blockerId of task.blockedBy) visit(blockerId)
+ visiting.delete(id)
+ visited.add(id)
+ }
+ for (const task of tasks.values()) visit(task.id)
+}
diff --git a/packages/subagent/agent-team/src/task-view.ts b/packages/subagent/agent-team/src/task-view.ts
new file mode 100644
index 0000000000..fbee689617
--- /dev/null
+++ b/packages/subagent/agent-team/src/task-view.ts
@@ -0,0 +1,55 @@
+/** Pure task-view derivation shared by the task board and the client projection. */
+
+import type { TeamState } from './projection.ts'
+import type { TeamTaskSnapshot, TeamTaskView } from './types.ts'
+
+/**
+ * Whether two normalized file or directory prefixes overlap on path components.
+ * @param left - normalized write scope.
+ * @param right - normalized write scope.
+ * @returns whether either scope contains the other.
+ */
+function scopesOverlap(left: string, right: string): boolean {
+ return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)
+}
+
+/**
+ * Whether every current blocker of one task completed.
+ * @param state - Team state supplying sibling tasks.
+ * @param task - durable task snapshot to test.
+ * @returns whether the task has no incomplete blockers.
+ */
+export function taskReady(state: TeamState, task: TeamTaskSnapshot): boolean {
+ return task.blockedBy.every(id => state.tasks.find(candidate => candidate.id === id)?.status === 'completed')
+}
+
+/**
+ * Derive one task view with owner id, readiness, and advisory write overlaps.
+ * A committing caller may pass its pre-append state because `task` supplies the
+ * new value explicitly; blocker readiness, and other task scopes
+ * do not change when that snapshot is appended.
+ * @param state - Team state supplying sibling tasks for readiness and overlap checks.
+ * @param task - durable task snapshot to view.
+ * @returns a detached task view.
+ */
+export function projectTaskView(state: TeamState, task: TeamTaskSnapshot): TeamTaskView {
+ const warnings = new Set()
+ for (const other of state.tasks) {
+ if (other.id === task.id || other.status !== 'in_progress') continue
+ if (task.writeScopes.some(left => other.writeScopes.some(right => scopesOverlap(left, right)))) {
+ warnings.add(`write scopes overlap with ${other.id}`)
+ }
+ }
+ return {
+ id: task.id,
+ revision: task.revision,
+ subject: task.subject,
+ description: task.description,
+ status: task.status,
+ blockedBy: [...task.blockedBy],
+ writeScopes: [...task.writeScopes],
+ ...task.ownerId === undefined ? {} : { ownerId: task.ownerId },
+ ready: task.status === 'pending' && taskReady(state, task),
+ writeScopeWarnings: [...warnings],
+ }
+}
diff --git a/packages/subagent/agent-team/src/types.ts b/packages/subagent/agent-team/src/types.ts
new file mode 100644
index 0000000000..429da7ad7c
--- /dev/null
+++ b/packages/subagent/agent-team/src/types.ts
@@ -0,0 +1,199 @@
+/** Public Agent Teams identities, durable records, and service request values. */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/** Identifies the implicit team rooted at one top-level Session. */
+export type TeamId = Branded<'TeamId'>
+
+/**
+ * Brand one root Session identity as its implicit Team identity.
+ * @param id - Root Session identity.
+ * @returns the same string branded as a Team identity.
+ */
+export function TeamId(id: SessionId | string): TeamId {
+ return id as TeamId
+}
+
+/** Stable identifier for one task in a Team. */
+export type TeamTaskId = Branded<'TeamTaskId'>
+
+/**
+ * Brand a validated task id.
+ * @param id - Team-local task identity.
+ * @returns the same string branded as a Team task identity.
+ */
+export function TeamTaskId(id: string): TeamTaskId {
+ return id as TeamTaskId
+}
+
+/** Stable identifier for one durable peer message. */
+export type TeamMessageId = Branded<'TeamMessageId'>
+
+/**
+ * Brand a generated peer-message id.
+ * @param id - Durable mailbox message identity.
+ * @returns the same string branded as a Team message identity.
+ */
+export function TeamMessageId(id: string): TeamMessageId {
+ return id as TeamMessageId
+}
+
+/**
+ * Teammate lifecycle. Continuable children of the Lead are always `active`;
+ * `provisioning` and `failed` appear only in historical roster records.
+ */
+export type TeamMemberPhase = 'provisioning' | 'active' | 'failed'
+
+/** Historical roster value written by earlier Team builds on every teammate lifecycle change. */
+export interface TeamMemberSnapshot {
+ readonly id: SessionId
+ readonly name: string
+ readonly description: string
+ readonly provider: string
+ readonly context: 'fresh' | 'fork'
+ readonly phase: TeamMemberPhase
+ readonly error?: string
+}
+
+/** Durable task lifecycle. */
+export type TeamTaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted'
+
+/** Whole durable task snapshot; every mutation increments {@link revision}. */
+export interface TeamTaskSnapshot {
+ readonly id: TeamTaskId
+ readonly revision: number
+ readonly subject: string
+ readonly description: string
+ readonly status: TeamTaskStatus
+ readonly ownerId?: SessionId
+ readonly blockedBy: TeamTaskId[]
+ readonly writeScopes: string[]
+}
+
+/** Runtime-enriched task view returned to tools and hosts. */
+export interface TeamTaskView {
+ readonly id: TeamTaskId
+ readonly revision: number
+ readonly subject: string
+ readonly description: string
+ readonly status: TeamTaskStatus
+ readonly blockedBy: TeamTaskId[]
+ readonly writeScopes: string[]
+ readonly ownerId?: SessionId
+ readonly ready: boolean
+ readonly writeScopeWarnings: string[]
+}
+
+/**
+ * Durable Team state published to browser clients through the Lead Session's
+ * `agentTeam` projection. `failure` names the first rejected persisted Team
+ * record; tasks then stay at the last valid state.
+ */
+export interface TeamProjection {
+ readonly tasks: TeamTaskView[]
+ readonly failure?: string
+}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+ interface SessionProjectionMap {
+ /** Durable roster and non-deleted task board of the Team rooted at the projected Session. */
+ agentTeam: TeamProjection
+ }
+}
+
+/** One peer message recorded by the historical Team mailbox. */
+export interface TeamMessageSnapshot {
+ readonly id: TeamMessageId
+ readonly senderId: SessionId
+ readonly senderName: string
+ readonly targetId: SessionId
+ readonly content: ContentBlock[]
+}
+
+/** Source recorded by a target Session for one historical Team mailbox delivery. */
+export interface TeamMessageSource {
+ readonly kind: 'team-message'
+ readonly teamId: TeamId
+ readonly messageId: TeamMessageId
+ readonly senderId: SessionId
+ readonly senderName: string
+}
+
+declare module '@deepseek-ai/dsh-llm' {
+ interface MessageSourceMap {
+ 'team-message': TeamMessageSource
+ }
+}
+
+/** Persisted Team selection, shared by a root Session and its descendants. */
+export interface TeamModeProjection {
+ readonly enabled: boolean
+}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+ interface SessionProjectionMap {
+ /** Whether the root Session enables the shared task board and Team guidance. */
+ agentTeamMode: TeamModeProjection
+ }
+}
+
+/** Team-service deployment limits and initial mode. */
+export interface Config {
+ /** Team mode before a Session records a selection or a shared task. Defaults to false. */
+ readonly enabledByDefault?: boolean
+ /** Maximum non-deleted tasks retained by one Team. */
+ readonly maxTasks?: number
+}
+
+/** Input for creating one shared task. */
+export interface CreateTeamTaskRequest {
+ readonly subject: string
+ readonly description: string
+ readonly blockedBy?: readonly TeamTaskId[]
+ readonly writeScopes?: readonly string[]
+}
+
+/** Supported task mutation actions. */
+export type TeamTaskAction =
+ | 'claim'
+ | 'release'
+ | 'edit'
+ | 'set_dependencies'
+ | 'complete'
+ | 'reopen'
+ | 'reassign'
+ | 'delete'
+
+/** Compare-and-set mutation of one shared task. */
+export interface UpdateTeamTaskRequest {
+ readonly taskId: TeamTaskId
+ readonly expectedRevision: number
+ readonly action: TeamTaskAction
+ readonly subject?: string
+ readonly description?: string
+ readonly blockedBy?: readonly TeamTaskId[]
+ readonly writeScopes?: readonly string[]
+ readonly owner?: SessionId
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+ interface SessionEventMap {
+ /** User-selected Team mode; child Agents use the selection of their runtime root. */
+ 'team/mode': { enabled: boolean }
+ /** Historical teammate lifecycle value; new teammates are continuable entries in the Lead's subagent catalog. */
+ 'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot }
+ /** Whole shared-task value, stored only in the Team Lead Session. */
+ 'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot }
+ /** Historical mailbox enqueue; new sends use the target Agent inbox. */
+ 'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot }
+ /** Historical acknowledgement that the target Session recorded a queued message. */
+ 'team/message/delivered': {
+ version: 2
+ teamId: TeamId
+ messageId: TeamMessageId
+ targetId: SessionId
+ }
+ }
+}
diff --git a/packages/subagent/agent-team/src/validation.ts b/packages/subagent/agent-team/src/validation.ts
new file mode 100644
index 0000000000..01de64f57c
--- /dev/null
+++ b/packages/subagent/agent-team/src/validation.ts
@@ -0,0 +1,34 @@
+/** Input normalization shared by Team roster and task commands. */
+
+import { TeamError } from './error.ts'
+
+/**
+ * Normalize one required human-authored string.
+ * @param value - raw input value.
+ * @param field - diagnostic field name.
+ * @param maxLength - maximum normalized character count.
+ * @returns trimmed non-empty text.
+ */
+export function requiredText(value: string, field: string, maxLength: number): string {
+ const text = value.trim()
+ if (text.length === 0) throw new TeamError(`${field} must be non-empty`, 'TEAM_INVALID_ARGUMENT')
+ if (text.length > maxLength) {
+ throw new TeamError(`${field} exceeds ${maxLength} characters`, 'TEAM_INVALID_ARGUMENT')
+ }
+ return text
+}
+
+/**
+ * Normalize one workspace-relative path prefix without treating it as a lock.
+ * @param value - user-authored path prefix.
+ * @returns normalized slash-separated prefix.
+ */
+export function writeScope(value: string): string {
+ const normalized = value.replaceAll('\\', '/').replace(/^\.\//u, '').replace(/\/+$/u, '')
+ const segments = normalized.split('/')
+ if (normalized.length === 0 || normalized.startsWith('/') || /^[a-z]:/iu.test(normalized)
+ || segments.some(segment => segment.length === 0 || segment === '.' || segment === '..')) {
+ throw new TeamError(`invalid workspace-relative write scope ${JSON.stringify(value)}`, 'TEAM_INVALID_WRITE_SCOPE')
+ }
+ return normalized
+}
diff --git a/packages/subagent/agent-team/tests/built-lib.e2e.ts b/packages/subagent/agent-team/tests/built-lib.e2e.ts
new file mode 100644
index 0000000000..5ca729e8f9
--- /dev/null
+++ b/packages/subagent/agent-team/tests/built-lib.e2e.ts
@@ -0,0 +1,59 @@
+/** Plain-Node smoke for the built Agent Teams service. */
+
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const packageDir = fileURLToPath(new URL('..', import.meta.url))
+const root = resolve(packageDir, '../../..')
+const artifact = (path: string): string => join(root, path)
+const artifactUrl = (path: string): string => pathToFileURL(artifact(path)).href
+
+const requiredArtifacts = [
+ 'packages/subagent/agent-team/lib/index.js',
+].every(path => existsSync(artifact(path)))
+
+describe.skipIf(!requiredArtifacts)('Agent Teams built LIB service', () => {
+ it('loads the Host service under plain Node', async () => {
+ const urls = {
+ host: artifactUrl('packages/subagent/agent-team/lib/index.js'),
+ }
+ const script = `
+ const host = await import(${JSON.stringify(urls.host)})
+ console.log(JSON.stringify({
+ className: host.default.name,
+ }))
+ `
+
+ const result = await runPlainNode(script)
+ expect(result.exitCode, `stderr:\n${result.stderr}`).toBe(0)
+ const output = JSON.parse(result.stdout.trim().split('\n').at(-1) ?? '{}') as {
+ className: string
+ }
+ expect(output).toEqual({
+ className: 'TeamService',
+ })
+ })
+})
+
+function runPlainNode(script: string): Promise<{
+ readonly exitCode: number | null
+ readonly stdout: string
+ readonly stderr: string
+}> {
+ return new Promise((resolveRun) => {
+ execFile(process.execPath, ['--input-type=module', '-e', script], {
+ cwd: packageDir,
+ encoding: 'utf8',
+ timeout: 30_000,
+ }, (error, stdout, stderr) => {
+ resolveRun({
+ exitCode: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+ stdout,
+ stderr,
+ })
+ })
+ })
+}
diff --git a/packages/subagent/agent-team/tests/persistence.spec.ts b/packages/subagent/agent-team/tests/persistence.spec.ts
new file mode 100644
index 0000000000..aeda56b3ce
--- /dev/null
+++ b/packages/subagent/agent-team/tests/persistence.spec.ts
@@ -0,0 +1,219 @@
+import { randomUUID } from 'node:crypto'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
+import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import { mountWorkingDirectoryFixture } from '../../subagent/tests/working-directory-fixture.ts'
+import TeamService, { TeamId, TeamMessageId } from '../src/index.ts'
+import { teamProjectionDefinition } from '../src/projection.ts'
+import type { TeamMemberSnapshot, TeamMessageSnapshot, TeamTaskSnapshot } from '../src/index.ts'
+import { TestSessionQuery } from './test-session-query.ts'
+
+const SIGNAL = new AbortController().signal
+const PERSISTENCE_TEST_TIMEOUT_MS = 15_000
+const roots: string[] = []
+const contexts = new Set()
+
+/** Detached durable Team read through the same projection definition as the service. */
+function durable(agent: Agent): {
+ members: readonly TeamMemberSnapshot[]
+ tasks: readonly TeamTaskSnapshot[]
+ pendingMessages: readonly TeamMessageSnapshot[]
+} {
+ let projected = teamProjectionDefinition.init(agent.session.header, agent.session.inheritedEventCount)
+ for (const event of agent.session.snapshotEvents()) projected = teamProjectionDefinition.apply(projected, event)
+ if (projected.failure !== undefined) throw new Error(projected.failure)
+ const state = projected
+ return {
+ members: state.members,
+ tasks: state.tasks,
+ pendingMessages: state.messages.filter(message => !state.delivered.includes(message.id)),
+ }
+}
+
+async function disposeContext(ctx: Context): Promise {
+ try {
+ await ctx.fiber.dispose()
+ } finally {
+ contexts.delete(ctx)
+ }
+}
+
+afterEach(async () => {
+ const failures: unknown[] = []
+ for (const ctx of [...contexts].reverse()) {
+ try {
+ await disposeContext(ctx)
+ } catch (error: unknown) {
+ failures.push(error)
+ }
+ }
+ for (const root of roots.splice(0)) {
+ try {
+ await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+ } catch (error: unknown) {
+ failures.push(error)
+ }
+ }
+ if (failures.length > 0) throw new AggregateError(failures, 'Agent Teams persistence test cleanup failed')
+})
+
+interface PersistenceMount {
+ readonly name: string
+ mount(ctx: Context, root: string): Promise<{ dispose(): Promise }>
+}
+
+const backends: PersistenceMount[] = [
+ {
+ name: 'JSONL',
+ mount: async (ctx, root) => await ctx.plugin(JsonlSessionPersistence, {
+ root: join(root, 'jsonl'),
+ compression: 'none',
+ }),
+ },
+]
+
+async function stack(
+ backend: PersistenceMount,
+ root: string,
+ script: ConstructorParameters[0],
+ enabledByDefault = true,
+) {
+ const ctx = new Context()
+ contexts.add(ctx)
+ await mountAgentLoopTestDependencies(ctx)
+ await mountWorkingDirectoryFixture(ctx)
+ await backend.mount(ctx, root)
+ await ctx.plugin(TestSessionQuery)
+ await ctx.plugin(AgentLoop, { agents: [] })
+ await ctx.plugin(SubagentService)
+ await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+ await ctx.plugin(TeamService, { enabledByDefault })
+ const adapter = new MockAdapter(script)
+ ctx.llm.registerAdapter(['mock'], adapter)
+ return {
+ ctx,
+ adapter,
+ dispose: async () => { await disposeContext(ctx) },
+ }
+}
+
+for (const backend of backends) {
+ describe(`${backend.name} Agent Teams recovery`, () => {
+ it('restores the saved mode and retains tasks while disabled', async () => {
+ const storageRoot = mkdtempSync(join(tmpdir(), 'dsh-team-mode-'))
+ roots.push(storageRoot)
+ const id = SessionId('saved-mode')
+ const first = await stack(backend, storageRoot, [], false)
+ const lead = await first.ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' })
+ expect(first.ctx.agentTeams.isEnabled(lead)).toBe(false)
+ await first.ctx.agentTeams.setEnabled(lead, true)
+ const task = await first.ctx.agentTeams.createTask(lead, { subject: 'saved', description: 'retained while off' })
+ await first.ctx.agentTeams.setEnabled(lead, false)
+ await first.dispose()
+ const second = await stack(backend, storageRoot, [], true)
+ const resumed = await second.ctx.agents.resume({ resumeSessionId: id, agentOptions: { provider: 'mock', model: 'mock' } })
+ expect(second.ctx.agentTeams.isEnabled(resumed.agent)).toBe(false)
+ expect(second.ctx.sessionProjections.snapshot(resumed.agent.session).values.agentTeamMode).toEqual({ enabled: false })
+ await second.ctx.agentTeams.setEnabled(resumed.agent, true)
+ expect(second.ctx.agentTeams.listTasks(resumed.agent)).toEqual([task])
+ })
+
+ it('restores continuable teammates and tasks from the Lead log after restart', {
+ timeout: PERSISTENCE_TEST_TIMEOUT_MS,
+ }, async () => {
+ const storageRoot = mkdtempSync(join(tmpdir(), `dsh-team-restart-${backend.name.toLowerCase()}-`))
+ roots.push(storageRoot)
+ const rootId = SessionId(`${backend.name.toLowerCase()}-restart-root`)
+
+ const first = await stack(backend, storageRoot, [textResponse('initial teammate answer')])
+ const firstLead = await first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
+ const started = await first.ctx.subagents.startActivation({ name: `child-${randomUUID()}`,
+ provider: 'spawn',
+ label: 'restart worker',
+ request: { prompt: [{ type: 'text', text: 'finish before restart' }], parent: firstLead },
+ signal: SIGNAL,
+ delivery: 'caller',
+ })
+ await vi.waitFor(() => { expect(first.ctx.agents.get(started.childId)).toBeUndefined() }, { timeout: 5_000 })
+ const created = await first.ctx.agentTeams.createTask(firstLead, { subject: 'carry over', description: 'survives restart' })
+ await first.ctx.sessions.flush(firstLead.session)
+ await first.dispose()
+
+ const second = await stack(backend, storageRoot, [], false)
+ const rootHandle = await second.ctx.agents.resume({
+ resumeSessionId: rootId,
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ const projections = second.ctx.sessionProjections.snapshot(rootHandle.agent.session).values
+ expect(projections.agentTeam).toMatchObject({
+ tasks: [{ id: created.id, subject: 'carry over' }],
+ })
+ expect(projections.subagentCatalog).toMatchObject([
+ { id: started.childId, mode: 'continuable', label: 'restart worker' },
+ ])
+ await expect(second.ctx.agentTeams.updateTask(rootHandle.agent, {
+ taskId: created.id, expectedRevision: 1, action: 'reassign', owner: started.childId,
+ })).resolves.toMatchObject({ ownerId: started.childId })
+ expect(second.adapter.requests).toEqual([])
+ await rootHandle.dispose()
+ await second.dispose()
+ })
+
+ it('keeps historical roster records and queued mail readable without delivering them after restart', {
+ timeout: PERSISTENCE_TEST_TIMEOUT_MS,
+ }, async () => {
+ const storageRoot = mkdtempSync(join(tmpdir(), `dsh-team-mail-${backend.name.toLowerCase()}-`))
+ roots.push(storageRoot)
+ const rootId = SessionId(`${backend.name.toLowerCase()}-mail-root`)
+ const childId = SessionId('historical-worker')
+
+ const first = await stack(backend, storageRoot, [])
+ const firstLead = await first.ctx.agentLoop.create(rootId, { provider: 'mock', model: 'mock' })
+ const historical: TeamMemberSnapshot = {
+ id: childId,
+ name: 'mail-worker',
+ description: 'historical mailbox target',
+ provider: 'spawn',
+ context: 'fresh',
+ phase: 'provisioning',
+ }
+ const message = {
+ id: TeamMessageId('legacy-pending'), senderId: rootId, senderName: 'lead', targetId: childId,
+ content: [{ type: 'text' as const, text: 'historical pending context' }],
+ }
+ firstLead.session.append('team/member', { version: 2, teamId: TeamId(rootId), member: historical })
+ firstLead.session.append('team/member', { version: 2, teamId: TeamId(rootId), member: { ...historical, phase: 'active' } })
+ firstLead.session.append('team/message/queued', { version: 2, teamId: TeamId(rootId), message })
+ await first.ctx.sessions.flush(firstLead.session)
+ await first.dispose()
+
+ const second = await stack(backend, storageRoot, [])
+ const rootHandle = await second.ctx.agents.resume({
+ resumeSessionId: rootId,
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ expect(durable(rootHandle.agent)).toMatchObject({
+ members: [{ ...historical, phase: 'active' }],
+ pendingMessages: [message],
+ })
+ const projections = second.ctx.sessionProjections.snapshot(rootHandle.agent.session).values
+ expect(projections.agentTeam).toEqual({ tasks: [] })
+ expect(second.ctx.agents.get(childId)).toBeUndefined()
+ expect(second.adapter.requests).toEqual([])
+
+ await rootHandle.dispose()
+ await second.dispose()
+ })
+ })
+}
diff --git a/packages/subagent/agent-team/tests/projection-events.spec.ts b/packages/subagent/agent-team/tests/projection-events.spec.ts
new file mode 100644
index 0000000000..40cc2ae1c0
--- /dev/null
+++ b/packages/subagent/agent-team/tests/projection-events.spec.ts
@@ -0,0 +1,587 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SessionEventMap, SessionEventType } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import { teamProjectionDefinition, teamProjectionView } from '../src/projection.ts'
+import type { TeamProjectionState, TeamState } from '../src/projection.ts'
+import { TeamId, TeamMessageId, TeamTaskId } from '../src/types.ts'
+import type { TeamMemberSnapshot, TeamMessageSnapshot, TeamTaskSnapshot } from '../src/types.ts'
+
+const ROOT = SessionId('team-root')
+const TEAM = TeamId(ROOT)
+const CHILD = SessionId('child-a')
+
+function event>(type: T, data: SessionEventMap[T], seq: SessionSeq): SessionEvent {
+ return { type, data, seq, time: seq } as unknown as SessionEvent
+}
+
+function project(rootId: SessionId, events: readonly SessionEvent[], inherited = 0): TeamProjectionState {
+ let state = teamProjectionDefinition.init({
+ version: SESSION_FORMAT_VERSION,
+ id: rootId,
+ createdAt: 0,
+ isSeeded: inherited > 0,
+ }, SessionLogOffset(inherited))
+ for (const event of events) state = teamProjectionDefinition.apply(state, event)
+ return state
+}
+
+function teamState(projected: TeamProjectionState): TeamState {
+ if (projected.failure !== undefined) throw new Error(projected.failure)
+ return projected
+}
+
+function projectTeam(rootId: SessionId, events: readonly SessionEvent[]): TeamState {
+ return teamState(project(rootId, events))
+}
+
+/** Queued-minus-delivered mail retained by the projection. */
+function pending(state: TeamState): TeamMessageSnapshot[] {
+ return state.messages.filter(message => !state.delivered.includes(message.id))
+}
+
+/** Whether one Team state contains no projected records. */
+function isEmptyState(state: TeamState): boolean {
+ return state.members.length === 0 && state.tasks.length === 0
+ && state.messages.length === 0 && state.delivered.length === 0
+}
+
+function member(overrides: Partial = {}): TeamMemberSnapshot {
+ return {
+ id: CHILD,
+ name: 'worker-a',
+ description: 'worker',
+ provider: 'spawn',
+ context: 'fresh',
+ phase: 'provisioning',
+ ...overrides,
+ }
+}
+
+function task(overrides: Partial = {}): TeamTaskSnapshot {
+ return {
+ id: TeamTaskId('task-1'),
+ revision: 1,
+ subject: 'subject',
+ description: 'description',
+ status: 'pending',
+ blockedBy: [],
+ writeScopes: [],
+ ...overrides,
+ }
+}
+
+/** One parent catalog fact for a continuable child. */
+function catalog(childId: string, seq: number, description = `${childId} task`): SessionEvent<'subagent/catalog'> {
+ return {
+ type: 'subagent/catalog',
+ seq: SessionSeq(seq),
+ time: seq,
+ data: { version: 0, childId: SessionId(childId), childCreatedAt: seq, mode: 'continuable', label: description },
+ }
+}
+
+function message(overrides: Partial = {}): TeamMessageSnapshot {
+ return {
+ id: TeamMessageId('message-1'),
+ senderId: ROOT,
+ senderName: 'lead',
+ targetId: CHILD,
+ content: [{ type: 'text', text: 'hello' }],
+ ...overrides,
+ }
+}
+
+describe('Agent Teams projection events', () => {
+ it('rejects retired tool-result content when restoring a native V4 Team checkpoint', async () => {
+ const ctx = new Context()
+ onTestFinished(() => ctx.fiber.dispose())
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(SessionProjectionRegistry)
+ await ctx.sessionProjections.register(teamProjectionDefinition)
+ const session = ctx.sessions.create(ROOT)
+ const restore = (val: unknown) => ctx.sessionProjections.restore({
+ agentTeam: { ver: teamProjectionDefinition.stateVersion, seq: -1, val },
+ }, [], SessionLogOffset(0), session.header, SessionLogOffset(0))
+ const valid = { ...project(ROOT, []), messages: [message()] }
+ expect(restore(JSON.parse(JSON.stringify(valid))).checkpoint['agentTeam']?.val).toEqual(valid)
+ const retiredMessage = message({ content: [{
+ type: 'tool-result', toolCallId: 'retired', content: [{ type: 'text', text: 'old result' }],
+ }] as unknown as TeamMessageSnapshot['content'] })
+ const retired = { ...valid, messages: [retiredMessage] }
+ expect(() => restore(JSON.parse(JSON.stringify(retired)))).toThrow()
+ expect(() => projectTeam(ROOT, [event('team/message/queued', {
+ version: 2, teamId: TEAM, message: retiredMessage,
+ }, SessionSeq(0))])).toThrow(/team\/message\/queued payload is invalid/)
+ })
+
+ it('projects current-team records independently from inherited records', () => {
+ const records: SessionEvent[] = [
+ event('team/member', { version: 2, teamId: TeamId('ancestor'), member: member() }, SessionSeq(0)),
+ event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(1)),
+ event('team/member', {
+ version: 2,
+ teamId: TEAM,
+ member: member({ phase: 'active' }),
+ }, SessionSeq(2)),
+ event('team/task', { version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-7') }) }, SessionSeq(3)),
+ event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(4)),
+ ]
+ const projected = project(ROOT, records)
+ const state = teamState(projected)
+
+ expect(state).toMatchObject({ id: TEAM })
+ expect(state.members).toHaveLength(1)
+ expect(state.tasks).toHaveLength(1)
+ expect(pending(state)).toHaveLength(1)
+ expect(state.nextTaskNumber).toBe(8)
+ expect(state.members.find(member => member.id === CHILD)?.name).toBe('worker-a')
+ expect(teamProjectionDefinition.stateSchema.parse(JSON.parse(JSON.stringify(projected))))
+ .toEqual(projected)
+ })
+
+ it('enforces teammate identity and lifecycle', () => {
+ const base = event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0))
+ expect(() => projectTeam(ROOT, [event('team/member', {
+ version: 2,
+ teamId: TEAM,
+ member: member({ phase: 'active' }),
+ }, SessionSeq(0))])).toThrow(/must begin provisioning/)
+ expect(() => projectTeam(ROOT, [base, event('team/member', {
+ version: 2,
+ teamId: TEAM,
+ member: member({ name: 'renamed', phase: 'active' }),
+ }, SessionSeq(1))])).toThrow(/immutable identity/)
+ expect(() => projectTeam(ROOT, [base, event('team/member', {
+ version: 2,
+ teamId: TEAM,
+ member: member({ phase: 'active' }),
+ }, SessionSeq(1)), event('team/member', {
+ version: 2,
+ teamId: TEAM,
+ member: member({ phase: 'failed' }),
+ }, SessionSeq(2))])).toThrow(/invalid active -> failed/)
+
+ const duplicateName = member({ id: SessionId('child-b') })
+ expect(() => projectTeam(ROOT, [base, event('team/member', {
+ version: 2,
+ teamId: TEAM,
+ member: duplicateName,
+ }, SessionSeq(1))])).toThrow(/name .* reused/)
+ })
+
+ it('enforces task revision continuity', () => {
+ const first = event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0))
+ expect(() => projectTeam(ROOT, [event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ revision: 2 }),
+ }, SessionSeq(0))])).toThrow(/begin at revision 1/)
+ expect(() => projectTeam(ROOT, [first, event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ revision: 3 }),
+ }, SessionSeq(1))])).toThrow(/revision is not contiguous/)
+ })
+
+ it('rejects every invalid persisted task dependency relation', () => {
+ const first = event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0))
+ const second = event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({
+ id: TeamTaskId('task-2'),
+ blockedBy: [TeamTaskId('task-1')],
+ }),
+ }, SessionSeq(1))
+ const invalid: Array<{ records: SessionEvent[]; message: RegExp }> = [
+ {
+ records: [event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ blockedBy: [TeamTaskId('missing')] }),
+ }, SessionSeq(0))],
+ message: /blocker task "missing" .* is missing or deleted/,
+ },
+ {
+ records: [event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ blockedBy: [TeamTaskId('task-1')] }),
+ }, SessionSeq(0))],
+ message: /cannot block itself/,
+ },
+ {
+ records: [first, event('team/task', {
+ ...second.data,
+ task: { ...second.data.task, blockedBy: [TeamTaskId('task-1'), TeamTaskId('task-1')] },
+ }, SessionSeq(1))],
+ message: /repeats blocker/,
+ },
+ {
+ records: [first, second, event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ revision: 2, blockedBy: [TeamTaskId('task-2')] }),
+ }, SessionSeq(2))],
+ message: /dependency cycle/,
+ },
+ {
+ records: [first, second, event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ revision: 2, status: 'deleted' }),
+ }, SessionSeq(2))],
+ message: /blocker task "task-1" .* is missing or deleted/,
+ },
+ ]
+
+ for (const { records, message: expected } of invalid) {
+ expect(() => projectTeam(ROOT, records)).toThrow(expected)
+ }
+ })
+
+ it('leaves numeric allocation unchanged for a branded nonstandard task id', () => {
+ const state = projectTeam(ROOT, [event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ id: TeamTaskId('external-task') }),
+ }, SessionSeq(0))])
+ expect(state.nextTaskNumber).toBe(1)
+ })
+
+ it('rejects a persisted numeric task id outside the safe integer range', () => {
+ expect(() => projectTeam(ROOT, [event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task({ id: TeamTaskId('task-9007199254740992') }),
+ }, SessionSeq(0))])).toThrow(/persisted Agent Teams team\/task payload is invalid/)
+ })
+
+ it('enforces mailbox queue and acknowledgement relations', () => {
+ const queued = event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(0))
+ const delivered = event('team/message/delivered', {
+ version: 2,
+ teamId: TEAM,
+ messageId: TeamMessageId('message-1'),
+ targetId: CHILD,
+ }, SessionSeq(1))
+ expect(pending(projectTeam(ROOT, [queued, delivered]))).toEqual([])
+ expect(() => projectTeam(ROOT, [queued, queued])).toThrow(/queued twice/)
+ expect(() => projectTeam(ROOT, [delivered])).toThrow(/delivered before queueing/)
+ expect(() => projectTeam(ROOT, [queued, event('team/message/delivered', {
+ ...delivered.data,
+ targetId: SessionId('other'),
+ }, SessionSeq(1))])).toThrow(/target changed/)
+ expect(() => projectTeam(ROOT, [queued, delivered, { ...delivered, seq: SessionSeq(2) }])).toThrow(/delivered twice/)
+ })
+
+ it('validates every current-version persisted payload before projecting it', () => {
+ const malformed = [
+ {
+ ...event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0)),
+ data: { version: 2, teamId: TEAM, member: { ...member(), name: 42 } },
+ },
+ {
+ ...event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0)),
+ data: { version: 2, teamId: TEAM, task: { ...task(), blockedBy: [42] } },
+ },
+ {
+ ...event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(0)),
+ data: {
+ version: 2,
+ teamId: TEAM,
+ message: { ...message(), content: [{ type: 'text', text: 42 }] },
+ },
+ },
+ {
+ ...event('team/message/delivered', {
+ version: 2,
+ teamId: TEAM,
+ messageId: TeamMessageId('message-1'),
+ targetId: CHILD,
+ }, SessionSeq(0)),
+ data: {
+ version: 2,
+ teamId: TEAM,
+ messageId: TeamMessageId('message-1'),
+ targetId: 42,
+ },
+ },
+ {
+ ...event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0)),
+ data: { version: 2, teamId: TEAM, member: member(), unexpected: true },
+ },
+ {
+ ...event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(0)),
+ data: { version: 2, teamId: 42, task: task() },
+ },
+ ] as unknown as SessionEvent[]
+
+ for (const candidate of malformed) {
+ expect(() => projectTeam(ROOT, [candidate]))
+ .toThrow(/persisted Agent Teams .* payload is invalid/)
+ }
+ })
+
+ it('retains merge-extensible content blocks while rejecting malformed core variants', () => {
+ const extension = { type: 'plugin/custom', payload: { value: 1 } } as never
+ const state = projectTeam(ROOT, [event('team/message/queued', {
+ version: 2,
+ teamId: TEAM,
+ message: message({ content: [extension] }),
+ }, SessionSeq(0))])
+ expect(pending(state)[0]?.content).toEqual([extension])
+ })
+
+ it('preserves opaque JSON through projection and checkpoints', () => {
+ const extension = JSON.parse('{"type":"plugin/custom","__proto__":{"saved":true},"constructor":{"saved":false},"content":[{"__proto__":{"nested":true},"opaque":true}]}') as ContentBlock
+ const content = [extension]
+ const queued = event('team/message/queued', { version: 2, teamId: TEAM, message: message({ content }) }, SessionSeq(0))
+ const before = JSON.stringify(queued)
+ const projected = projectTeam(ROOT, [queued])
+ expect(projected.messages[0]?.content).toEqual(content)
+ const checkpoint = teamProjectionDefinition.stateSchema.parse(JSON.parse(JSON.stringify(projected)))
+ expect(JSON.stringify(checkpoint)).toBe(JSON.stringify(projected))
+ expect(JSON.stringify(queued)).toBe(before)
+ const block = checkpoint.messages[0]!.content[0]!
+ expect(Object.hasOwn(block, '__proto__')).toBe(true)
+ expect(Object.getPrototypeOf(block)).toBe(Object.prototype)
+ })
+
+ it.each([
+ null, [], 3,
+ { type: '' },
+ { type: null },
+ { type: 'text', text: false },
+ ])('rejects malformed content in events and checkpoints: %j', (block) => {
+ const content: unknown = [block]
+ const saved = message({ content: content as ContentBlock[] })
+ const queued = event('team/message/queued', { version: 2, teamId: TEAM, message: saved }, SessionSeq(0))
+ expect(() => projectTeam(ROOT, [queued])).toThrow(/team\/message\/queued payload is invalid/)
+ expect(() => teamProjectionDefinition.stateSchema.parse({ ...project(ROOT, []), messages: [saved] })).toThrow()
+ })
+
+ it('rebuilds lossy version-3 Team checkpoints from the original log', async () => {
+ const ctx = new Context()
+ const registry = ctx.plugin(SessionProjectionRegistry)
+ try {
+ await registry
+ await ctx.sessionProjections.register(teamProjectionDefinition)
+ const extension = JSON.parse('{"type":"plugin/custom","__proto__":{"saved":true}}') as ContentBlock
+ const queued = event('team/message/queued', {
+ version: 2, teamId: TEAM, message: message({ content: [extension] }),
+ }, SessionSeq(0))
+ const oldContent: unknown = [{ type: 'plugin/custom' }]
+ const oldState = project(ROOT, [event('team/message/queued', {
+ version: 2, teamId: TEAM, message: message({ content: oldContent as ContentBlock[] }),
+ }, SessionSeq(0))])
+ const restored = ctx.sessionProjections.restore(
+ { agentTeam: { ver: 3, seq: SessionSeq(0), val: oldState } },
+ [queued],
+ SessionLogOffset(0),
+ { version: SESSION_FORMAT_VERSION, id: ROOT, createdAt: 0, isSeeded: false },
+ SessionLogOffset(0),
+ )
+ const state = teamProjectionDefinition.stateSchema.parse(restored.checkpoint['agentTeam']!.val)
+ expect(state.messages[0]?.content).toEqual([extension])
+ } finally {
+ await registry.dispose()
+ }
+ })
+
+ it('records unsupported event versions without applying them', () => {
+ const invalid = event('team/task', {
+ version: 1 as 2,
+ teamId: TEAM,
+ task: task(),
+ }, SessionSeq(0))
+ const later = event('team/task', {
+ version: 2,
+ teamId: TEAM,
+ task: task(),
+ }, SessionSeq(1))
+ const state = project(ROOT, [invalid, later])
+ expect(state.failure).toMatch(/unsupported Agent Teams event version 1/)
+ expect(isEmptyState(state)).toBe(true)
+ })
+
+ it('isolates unsupported inherited Team records from the current Team', () => {
+ const inherited = event('team/task', {
+ version: 1 as 2,
+ teamId: TeamId('ancestor'),
+ task: task(),
+ }, SessionSeq(0))
+ const projected = project(ROOT, [inherited])
+ expect(projected.failure).toBeUndefined()
+ expect(isEmptyState(teamState(projected))).toBe(true)
+ })
+
+ it('ignores malformed current-version records inherited from another Team', () => {
+ const inherited = {
+ ...event('team/task', {
+ version: 2,
+ teamId: TeamId('ancestor'),
+ task: task(),
+ }, SessionSeq(0)),
+ data: {
+ version: 2,
+ teamId: TeamId('ancestor'),
+ task: { ...task(), subject: 42 },
+ },
+ } as unknown as SessionEvent
+ expect(isEmptyState(projectTeam(ROOT, [inherited]))).toBe(true)
+ })
+
+ it('leaves subagent catalog events to their owning projection', () => {
+ const state = project(ROOT, [])
+ const next = teamProjectionDefinition.apply(state, catalog('child', 0))
+ expect(next).toBe(state)
+ expect(teamProjectionView(next)).toEqual({ tasks: [] })
+ })
+
+ describe('copy-on-write state and client view', () => {
+ const memberEvent = event('team/member', { version: 2, teamId: TEAM, member: member() }, SessionSeq(0))
+ const taskEvent = event('team/task', { version: 2, teamId: TEAM, task: task() }, SessionSeq(1))
+ const queuedEvent = event('team/message/queued', { version: 2, teamId: TEAM, message: message() }, SessionSeq(2))
+ const deliveredEvent = event('team/message/delivered', {
+ version: 2, teamId: TEAM, messageId: TeamMessageId('message-1'), targetId: CHILD,
+ }, SessionSeq(3))
+
+ it('returns the same state for unrelated events and a new state that replaces only the touched collection', () => {
+ const initial = project(ROOT, [])
+ expect(teamProjectionDefinition.apply(initial, { type: 'turn/start', data: { turn: 1 }, seq: 0, time: 0 } as SessionEvent)).toBe(initial)
+ expect(teamProjectionDefinition.apply(initial, event('team/member', {
+ version: 2, teamId: TeamId('ancestor'), member: member(),
+ }, SessionSeq(0)))).toBe(initial)
+
+ const withMember = teamProjectionDefinition.apply(initial, memberEvent)
+ expect(withMember).not.toBe(initial)
+ expect(initial.members).toEqual([])
+ expect(withMember.members).toHaveLength(1)
+ expect(withMember.tasks).toBe(initial.tasks)
+
+ const withTask = teamProjectionDefinition.apply(withMember, taskEvent)
+ expect(withTask.members).toBe(withMember.members)
+ expect(withTask.tasks).not.toBe(withMember.tasks)
+ expect(withMember.tasks).toEqual([])
+
+ const withMail = teamProjectionDefinition.apply(withTask, queuedEvent)
+ expect(withMail.members).toBe(withTask.members)
+ expect(withMail.tasks).toBe(withTask.tasks)
+ expect(withMail.messages).not.toBe(withTask.messages)
+ expect(withTask.messages).toEqual([])
+
+ const withReceipt = teamProjectionDefinition.apply(withMail, deliveredEvent)
+ expect(withReceipt.delivered).not.toBe(withMail.delivered)
+ expect(withMail.delivered).toEqual([])
+ expect(teamProjectionDefinition.apply(withReceipt, { ...deliveredEvent, seq: SessionSeq(4) })).not.toBe(withReceipt)
+ })
+
+ it('enters failure through a new state that keeps the last valid collections', () => {
+ const valid = project(ROOT, [memberEvent, taskEvent])
+ const failed = teamProjectionDefinition.apply(valid, event('team/task', {
+ version: 1 as 2, teamId: TEAM, task: task(),
+ }, SessionSeq(2)))
+ expect(failed).not.toBe(valid)
+ expect(valid.failure).toBeUndefined()
+ expect(failed.failure).toMatch(/unsupported Agent Teams event version 1/)
+ expect(failed.members).toBe(valid.members)
+ expect(failed.tasks).toBe(valid.tasks)
+ expect(teamProjectionDefinition.apply(failed, queuedEvent)).toBe(failed)
+ })
+
+ it('views durable roster and non-deleted derived tasks and reuses the view across mailbox-only changes', () => {
+ const activeMember = event('team/member', { version: 2, teamId: TEAM, member: member({ phase: 'active' }) }, SessionSeq(1))
+ const claimed = event('team/task', {
+ version: 2, teamId: TEAM, task: task({ revision: 2, status: 'in_progress', ownerId: CHILD, writeScopes: ['src'] }),
+ }, SessionSeq(2))
+ const blocked = event('team/task', {
+ version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-2'), blockedBy: [TeamTaskId('task-1')], writeScopes: ['src/web'] }),
+ }, SessionSeq(3))
+ const leadOwned = event('team/task', {
+ version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-3'), revision: 1, status: 'in_progress', ownerId: ROOT }),
+ }, SessionSeq(4))
+ const deleted = event('team/task', {
+ version: 2, teamId: TEAM, task: task({ id: TeamTaskId('task-3'), revision: 2, status: 'deleted', ownerId: ROOT }),
+ }, SessionSeq(5))
+ const state = project(ROOT, [memberEvent, activeMember, taskEvent, claimed, blocked, leadOwned, deleted])
+ const view = teamProjectionView(state)
+ expect(teamProjectionDefinition.wire.viewSchema.parse(view)).toEqual(view)
+ expect(view).toEqual({
+ tasks: [
+ {
+ id: 'task-1', revision: 2, subject: 'subject', description: 'description', status: 'in_progress',
+ blockedBy: [], writeScopes: ['src'], ownerId: CHILD, ready: false, writeScopeWarnings: [],
+ },
+ {
+ id: 'task-2', revision: 1, subject: 'subject', description: 'description', status: 'pending',
+ blockedBy: ['task-1'], writeScopes: ['src/web'], ready: false, writeScopeWarnings: ['write scopes overlap with task-1'],
+ },
+ ],
+ })
+ expect(view).not.toHaveProperty('failure')
+ expect(teamProjectionView(state)).toBe(view)
+
+ const withMail = teamProjectionDefinition.apply(state, { ...queuedEvent, seq: SessionSeq(6) })
+ expect(teamProjectionView(withMail)).toBe(view)
+ const withMember = teamProjectionDefinition.apply(withMail, event('team/member', {
+ version: 2, teamId: TEAM, member: member({ id: SessionId('child-b'), name: 'worker-b' }),
+ }, SessionSeq(7)))
+ expect(teamProjectionView(withMember)).toBe(view)
+ expect(withMember.members).toHaveLength(2)
+ })
+
+ it('publishes the failure with the last valid tasks', () => {
+ const state = project(ROOT, [memberEvent, taskEvent, event('team/task', {
+ version: 1 as 2, teamId: TEAM, task: task(),
+ }, SessionSeq(2))])
+ const view = teamProjectionView(state)
+ expect(view.failure).toMatch(/unsupported Agent Teams event version 1/)
+ expect(view).not.toHaveProperty('members')
+ expect(view.tasks).toHaveLength(1)
+ expect(teamProjectionDefinition.wire.viewSchema.parse(view)).toEqual(view)
+ })
+
+ it('drives live agentTeam publications per Session through the projection registry', async () => {
+ const ctx = new Context()
+ onTestFinished(() => ctx.fiber.dispose())
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(SessionProjectionRegistry)
+ await ctx.sessionProjections.register(teamProjectionDefinition)
+ const published: Array<{ session: SessionId; key: string; value: unknown }> = []
+ ctx.sessionProjections.onChanged((session, key, value) => {
+ published.push({ session: session.id, key, value })
+ })
+ const lead = ctx.sessions.create(ROOT)
+ const other = ctx.sessions.create(SessionId('other-root'))
+ expect(ctx.sessionProjections.snapshot(lead).values['agentTeam']).toEqual({
+ tasks: [],
+ })
+
+ lead.append('team/task', taskEvent.data)
+ expect(published).toHaveLength(1)
+ expect(published[0]).toMatchObject({
+ session: ROOT,
+ key: 'agentTeam',
+ value: { tasks: [{ id: 'task-1', ready: true }] },
+ })
+
+ lead.append('team/message/queued', queuedEvent.data)
+ lead.append('turn/start', { turn: 1 })
+ expect(published).toHaveLength(1)
+
+ other.append('team/task', { version: 2, teamId: TeamId(other.id), task: task() })
+ expect(published).toHaveLength(2)
+ expect(published[1]).toMatchObject({
+ session: other.id,
+ value: { tasks: [{ id: 'task-1' }] },
+ })
+ expect(ctx.sessionProjections.snapshot(lead).values['agentTeam']).toMatchObject({
+ tasks: [{ id: 'task-1' }],
+ })
+ })
+ })
+})
diff --git a/packages/subagent/agent-team/tests/session-mode-fixture.ts b/packages/subagent/agent-team/tests/session-mode-fixture.ts
new file mode 100644
index 0000000000..65d6505286
--- /dev/null
+++ b/packages/subagent/agent-team/tests/session-mode-fixture.ts
@@ -0,0 +1,27 @@
+/** Exercise Session mode commands through assembled headless and SDK profiles. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-commands'
+import type {} from '@deepseek-ai/dsh-agent-loop'
+import type {} from '../src/index.ts'
+
+/** Runtime dependencies of the keyless mode fixture. */
+export const inject = ['commands', 'agentTeams']
+
+/**
+ * Enable the root before its first request and disable it before its second.
+ * @param ctx - assembled profile context.
+ */
+export function apply(ctx: Context): void {
+ ctx.on('agent/created', async ({ agent }) => {
+ if (agent.session.header.parentSession !== undefined) return
+ if (ctx.agentTeams.isEnabled(agent)) throw new Error('new Session must default to Team off')
+ await ctx.commands.execute(agent, '/team on', [], new AbortController().signal)
+ })
+ ctx.on('agent/pre-step', async ({ agent, step }, next) => {
+ if (agent.session.header.parentSession === undefined && step === 2) {
+ await ctx.commands.execute(agent, '/team off', [], new AbortController().signal)
+ }
+ return next()
+ })
+}
diff --git a/packages/subagent/agent-team/tests/team.spec.ts b/packages/subagent/agent-team/tests/team.spec.ts
new file mode 100644
index 0000000000..107f890fe9
--- /dev/null
+++ b/packages/subagent/agent-team/tests/team.spec.ts
@@ -0,0 +1,739 @@
+import { randomUUID } from 'node:crypto'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionLogOffset, SessionId } from '@deepseek-ai/dsh-session'
+import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import Commands from '@deepseek-ai/dsh-commands'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork-in-process'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
+import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import { mountWorkingDirectoryFixture } from '../../subagent/tests/working-directory-fixture.ts'
+import TeamService, { TeamId, TeamTaskId } from '../src/index.ts'
+import { teamProjectionDefinition } from '../src/projection.ts'
+import type { TeamProjectionState } from '../src/projection.ts'
+import { TestSessionQuery } from './test-session-query.ts'
+
+const SIGNAL = new AbortController().signal
+const roots: string[] = []
+const contexts: Context[] = []
+
+/** Resident idle recipients exercise delivery without scheduling model work. */
+async function resident(ctx: Context, root: Agent, id: string): Promise {
+ return (await ctx.agents.create({
+ sessionId: SessionId(id), parentAgent: root, agentOptions: { provider: 'mock', model: 'mock' },
+ })).agent
+}
+
+afterEach(async () => {
+ vi.useRealTimers()
+ vi.restoreAllMocks()
+ for (const ctx of contexts.splice(0).reverse()) await ctx.fiber.dispose()
+ for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+/** Detached Team state folded through the same projection definition as the service. */
+function durable(agent: Agent): TeamProjectionState {
+ let projected = teamProjectionDefinition.init(agent.session.header, agent.session.inheritedEventCount)
+ for (const event of agent.session.snapshotEvents()) projected = teamProjectionDefinition.apply(projected, event)
+ if (projected.failure !== undefined) throw new Error(projected.failure)
+ return projected
+}
+
+async function setup(
+ script: ConstructorParameters[0],
+ config: ConstructorParameters[1] = {},
+) {
+ const ctx = new Context()
+ contexts.push(ctx)
+ await mountAgentLoopTestDependencies(ctx)
+ await mountWorkingDirectoryFixture(ctx)
+ const storageRoot = mkdtempSync(join(tmpdir(), 'dsh-team-'))
+ roots.push(storageRoot)
+ await ctx.plugin(JsonlSessionPersistence, { root: storageRoot })
+ await ctx.plugin(TestSessionQuery)
+ await ctx.plugin(AgentLoop, { agents: [] })
+ await ctx.plugin(SubagentService)
+ await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+ await ctx.plugin(SubagentFork, { providerName: 'fork' })
+ const teamFiber = await ctx.plugin(TeamService, { enabledByDefault: true, ...config })
+ const adapter = new MockAdapter(script)
+ ctx.llm.registerAdapter(['mock'], adapter)
+ const lead = await ctx.agentLoop.create(SessionId('team-root'), { provider: 'mock', model: 'mock' })
+ return { ctx, lead, adapter, storageRoot, teamFiber }
+}
+
+function content(text: string) {
+ return [{ type: 'text' as const, text }]
+}
+
+/** Start one teammate: a continuable child of the Lead. */
+async function spawn(ctx: Context, lead: Agent, description: string | undefined, provider = 'spawn'): Promise {
+ const started = await ctx.subagents.startActivation({ name: `child-${randomUUID()}`,
+ provider,
+ label: `${description ?? 'shared'} responsibility`,
+ request: { prompt: content(`${description ?? 'shared'} initial`), parent: lead },
+ signal: SIGNAL,
+ delivery: 'parent',
+ })
+ return started.childId
+}
+
+async function waitNoAgent(ctx: Context, id: SessionId): Promise {
+ await vi.waitFor(() => { expect(ctx.agents.get(id)).toBeUndefined() }, { timeout: 5_000 })
+}
+
+async function waitRunning(ctx: Context, id: SessionId): Promise {
+ return vi.waitFor(() => {
+ const agent = ctx.agents.get(id)
+ expect(agent?.status).toBe('running')
+ return agent!
+ }, { timeout: 5_000 })
+}
+
+describe('Tree-owned task boards', () => {
+ it('executes root mode commands and rejects unknown selections without changing mode', async () => {
+ const { ctx, lead } = await setup([], { enabledByDefault: false })
+ await ctx.plugin(Commands)
+ expect(ctx.agentTeams.isEnabled(lead)).toBe(false)
+ await expect(ctx.commands.execute(lead, '/team maybe', [], SIGNAL)).resolves.toMatchObject({ result: { kind: 'error' } })
+ expect(ctx.agentTeams.isEnabled(lead)).toBe(false)
+ for (const [command, enabled] of [['on', true], ['off', false]] as const) {
+ await expect(ctx.commands.execute(lead, `/team ${command}`, [], SIGNAL)).resolves.toMatchObject({ result: { kind: 'success' } })
+ expect(ctx.agentTeams.isEnabled(lead)).toBe(enabled)
+ }
+ })
+
+ it('rejects disabled task access and descendant mode changes without appending', async () => {
+ const { ctx, lead } = await setup([], { enabledByDefault: false })
+ const child = await resident(ctx, lead, 'mode-child')
+ expect(ctx.agentTeams.isEnabled(lead)).toBe(false)
+ expect(() => ctx.agentTeams.listTasks(lead)).toThrow('enable Agent Teams')
+ await expect(ctx.agentTeams.createTask(lead, { subject: 'off', description: 'off' })).rejects.toThrow('enable Agent Teams')
+ await expect(ctx.agentTeams.setEnabled(child, true)).rejects.toThrow('root Session')
+ const cancel = new AbortController()
+ cancel.abort(new Error('cancelled selection'))
+ await expect(ctx.agentTeams.setEnabled(lead, true, cancel.signal)).rejects.toThrow('cancelled selection')
+ expect(lead.session.ownEvents().filter(event => event.type === 'team/mode')).toEqual([])
+ })
+
+ it('rejects reads and mutations after a Team projection fails', async () => {
+ const { ctx, lead } = await setup([])
+ lead.session.append('team/task', {
+ version: 2,
+ teamId: TeamId(lead.id),
+ task: {
+ id: TeamTaskId('task-1'), revision: 2, subject: 'invalid', description: 'missing initial revision',
+ status: 'pending', blockedBy: [], writeScopes: [],
+ },
+ })
+ expect(() => ctx.agentTeams.listTasks(lead)).toThrow('must begin at revision 1')
+ const eventCount = lead.session.snapshotEvents().length
+ await expect(ctx.agentTeams.createTask(lead, { subject: 'blocked', description: 'blocked' }))
+ .rejects.toThrow('must begin at revision 1')
+ expect(lead.session.snapshotEvents()).toHaveLength(eventCount)
+ })
+
+ it('propagates unavailable subagent runtime errors', async () => {
+ const { ctx, lead } = await setup([])
+ const failure = new Error('runtime unavailable')
+ vi.spyOn(ctx.subagents, 'rootOf').mockImplementation(() => { throw failure })
+ expect(() => ctx.agentTeams.listTasks(lead)).toThrow(failure)
+ })
+
+ it('rejects task limits that are not positive safe integers and removed configuration keys', async () => {
+ for (const value of [0, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+ await expect(setup([], { maxTasks: value })).rejects.toThrow()
+ }
+ for (const key of ['maxMembers', 'maxMessageBytes', 'disposalTimeoutMs']) {
+ await expect(setup([], { [key]: 1 })).rejects.toThrow(`${key} is no longer supported`)
+ }
+ })
+
+ it('makes every root a Lead and every live subagent below it a teammate', async () => {
+ const { ctx, lead } = await setup(['hang', 'hang', 'hang'])
+ const named = await waitRunning(ctx, await spawn(ctx, lead, 'alpha'))
+ const unnamed = await waitRunning(ctx, await spawn(ctx, lead, undefined))
+ const grandchildId = (await ctx.subagents.startActivation({ name: `child-${randomUUID()}`,
+ provider: 'spawn', label: 'nested', delivery: 'caller', signal: SIGNAL,
+ request: { prompt: content('nested'), parent: named },
+ })).childId
+ const grandchild = await waitRunning(ctx, grandchildId)
+
+ const shared = await ctx.agentTeams.createTask(lead, { subject: 'shared', description: 'visible at every depth' })
+ for (const agent of [lead, named, unnamed, grandchild]) {
+ expect(ctx.agentTeams.getTask(agent, shared.id).id).toBe(shared.id)
+ }
+
+ await ctx.subagents.drainChildren(lead, [named.id])
+ await waitNoAgent(ctx, named.id)
+ const task = await ctx.agentTeams.createTask(grandchild, { subject: 'still active', description: 'creator offline' })
+ expect(ctx.agentTeams.listTasks(lead).map(row => row.id)).toContain(task.id)
+
+ const impostor = { ...lead } as Agent
+ expect(() => ctx.agentTeams.listTasks(impostor)).toThrow(expect.objectContaining({ code: 'UNAUTHORIZED' }))
+
+ await ctx.subagents.drainDescendants([lead])
+ await Promise.all([waitNoAgent(ctx, grandchild.id), waitNoAgent(ctx, named.id), waitNoAgent(ctx, unnamed.id)])
+ })
+
+ it('treats an ordinary fork as a new Root Team and filters inherited Team state', async () => {
+ const { ctx, lead } = await setup([textResponse('alpha done')])
+ const alpha = await spawn(ctx, lead, 'alpha')
+ await waitNoAgent(ctx, alpha)
+ await ctx.agentTeams.createTask(lead, { subject: 'parent task', description: 'belongs to parent' })
+ const handle = await ctx.agents.create({
+ sessionId: SessionId('ordinary-fork'),
+ seed: lead.session.snapshotEvents(),
+ meta: { parentSession: lead.id, isSeeded: true },
+ inheritedEventCount: SessionLogOffset(lead.session.seq),
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+
+ expect(durable(handle.agent)).toMatchObject({ members: [], tasks: [] })
+ const task = await ctx.agentTeams.createTask(handle.agent, { subject: 'fork task', description: 'independent' })
+ await expect(ctx.agentTeams.updateTask(handle.agent, {
+ taskId: task.id, expectedRevision: 1, action: 'reassign', owner: alpha,
+ })).rejects.toMatchObject({ code: 'TEAM_MEMBER_NOT_FOUND' })
+ await handle.dispose()
+ })
+
+ it('assigns deep descendants by id and rejects historical roster authority', async () => {
+ const { ctx, lead } = await setup(['hang', 'hang'])
+ const child = await waitRunning(ctx, await spawn(ctx, lead, 'parent'))
+ const grandchild = await waitRunning(ctx, await spawn(ctx, child, 'nested'))
+ const task = await ctx.agentTeams.createTask(lead, { subject: 'nested work', description: 'deep assignment' })
+ const assigned = await ctx.agentTeams.updateTask(lead, {
+ taskId: task.id, expectedRevision: task.revision, action: 'reassign', owner: grandchild.id,
+ })
+ expect(assigned.ownerId).toBe(grandchild.id)
+ for (const phase of ['provisioning', 'active'] as const) {
+ lead.session.append('team/member', {
+ version: 2, teamId: TeamId(lead.id),
+ member: { id: SessionId('old-child'), name: 'legacy', description: 'old', provider: 'spawn', context: 'fresh', phase },
+ })
+ }
+ for (const owner of [SessionId('old-child'), SessionId('nested'), SessionId('unrelated-root')]) {
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: task.id, expectedRevision: assigned.revision, action: 'reassign', owner,
+ })).rejects.toMatchObject({ code: 'TEAM_MEMBER_NOT_FOUND' })
+ }
+ })
+
+ it('constructs with the default task limit and serializes concurrent task commits', async () => {
+ const { ctx, lead, teamFiber } = await setup([])
+ await teamFiber.dispose()
+ class DirectTeamService extends TeamService {
+ initialize(): Promise { return this[Service.init]() }
+ }
+ const direct = new DirectTeamService(ctx)
+ await direct.initialize()
+ expect(direct.isEnabled(lead)).toBe(false)
+ await direct.setEnabled(lead, true)
+ const [first, second] = await Promise.all([
+ direct.createTask(lead, { subject: 'one', description: 'one' }),
+ direct.createTask(lead, { subject: 'two', description: 'two' }),
+ ])
+ expect([first.id, second.id]).toEqual([TeamTaskId('task-1'), TeamTaskId('task-2')])
+ })
+
+ it.each([
+ ['create', 'disposed'], ['claim', 'disposed'], ['create', 'cancelled'], ['claim', 'cancelled'],
+ ] as const)('rejects a queued %s after its caller is %s', async (action, stopped) => {
+ const { ctx, lead } = await setup([])
+ const child = await ctx.agents.create({
+ sessionId: SessionId('queued-caller'), parentAgent: lead, agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ const task = await ctx.agentTeams.createTask(lead, { subject: 'existing', description: 'remains unclaimed' })
+ const flush = ctx.sessions.flush.bind(ctx.sessions)
+ const entered = Promise.withResolvers()
+ const release = Promise.withResolvers()
+ vi.spyOn(ctx.sessions, 'flush').mockImplementationOnce(async (session) => {
+ entered.resolve(undefined)
+ await release.promise
+ return await flush(session)
+ })
+ const creating = ctx.agentTeams.createTask(lead, { subject: 'blocking', description: 'holds the transaction queue' })
+ try {
+ await entered.promise
+ const controller = new AbortController()
+ const queued = action === 'create'
+ ? ctx.agentTeams.createTask(child.agent, { subject: 'stopped', description: 'must not be committed' }, controller.signal)
+ : ctx.agentTeams.updateTask(child.agent, { taskId: task.id, expectedRevision: task.revision, action: 'claim' }, controller.signal)
+ const rejected = expect(queued).rejects.toMatchObject(stopped === 'disposed' ? { code: 'UNAUTHORIZED' } : { name: 'AbortError' })
+ if (stopped === 'disposed') await child.dispose()
+ else controller.abort()
+ release.resolve(undefined)
+ await creating
+ await rejected
+ expect(ctx.agentTeams.listTasks(lead).map(item => item.subject)).toEqual(['existing', 'blocking'])
+ expect(ctx.agentTeams.getTask(lead, task.id)).toMatchObject({ revision: 1, status: 'pending' })
+ expect(lead.inbox.nextStep).toHaveLength(0)
+ } finally {
+ release.resolve(undefined)
+ await creating
+ }
+ })
+
+ it('does not treat a descriptor-backed Session without a parent as a Team member', async () => {
+ const { ctx, lead } = await setup([])
+ lead.session.append('subagent/descriptor', { version: 3, mode: 'continuable', provider: 'spawn', label: 'forged' })
+ expect(() => ctx.agentTeams.listTasks(lead)).toThrow(expect.objectContaining({ code: 'UNAUTHORIZED' }))
+ })
+
+ it('does not reinterpret an orphaned subagent child as a Team root', async () => {
+ const { ctx } = await setup([textResponse('ordinary child done'), textResponse('orphan turn')])
+ const parent = await ctx.agents.create({
+ sessionId: SessionId('temporary-parent'),
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ const child = await spawn(ctx, parent.agent, 'orphan')
+ await waitNoAgent(ctx, child)
+ await parent.dispose()
+ const orphan = await ctx.agents.resume({
+ resumeSessionId: child,
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ expect(() => ctx.agentTeams.listTasks(orphan.agent)).toThrow(expect.objectContaining({ code: 'UNAUTHORIZED' }))
+ orphan.agent.followup(createUserMessage({ content: content('run without a Team'), source: { kind: 'user' } }))
+ await orphan.agent.whenIdle()
+ await orphan.dispose()
+
+ const rootWithOfflineSource = await ctx.agents.create({
+ sessionId: SessionId('orphan-ordinary-root'),
+ meta: { parentSession: SessionId('absent-parent') },
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ expect(ctx.agentTeams.listTasks(rootWithOfflineSource.agent)).toEqual([])
+ await rootWithOfflineSource.dispose()
+ })
+})
+
+describe('Team shared task DAG', () => {
+ it('fails loudly when the durable numeric task id space is exhausted', async () => {
+ const { ctx, lead } = await setup([])
+ const id = TeamTaskId(`task-${Number.MAX_SAFE_INTEGER}`)
+ lead.session.append('team/task', {
+ version: 2,
+ teamId: TeamId(lead.id),
+ task: {
+ id,
+ revision: 1,
+ subject: 'last numeric task',
+ description: 'occupies the final safe numeric task id',
+ status: 'pending',
+ blockedBy: [],
+ writeScopes: [],
+ },
+ })
+ await ctx.sessions.flush(lead.session)
+
+ await expect(ctx.agentTeams.createTask(lead, {
+ subject: 'cannot allocate',
+ description: 'no safe numeric task id remains',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_LIMIT' })
+ })
+
+ it('bounds non-deleted tasks while retaining deleted task ids as tombstones', async () => {
+ const { ctx, lead } = await setup([], { maxTasks: 1 })
+ const first = await ctx.agentTeams.createTask(lead, { subject: 'first', description: 'first task' })
+ await expect(ctx.agentTeams.createTask(lead, { subject: 'overflow', description: 'overflow task' }))
+ .rejects.toMatchObject({ code: 'TEAM_TASK_LIMIT' })
+
+ const deleted = await ctx.agentTeams.updateTask(lead, {
+ taskId: first.id,
+ expectedRevision: first.revision,
+ action: 'delete',
+ })
+ const second = await ctx.agentTeams.createTask(lead, { subject: 'second', description: 'second task' })
+ expect(deleted.status).toBe('deleted')
+ expect(second.id).toBe(TeamTaskId('task-2'))
+ expect(ctx.agentTeams.getTask(lead, first.id).status).toBe('deleted')
+ expect(ctx.agentTeams.listTasks(lead).map(task => task.id)).toEqual([second.id])
+ })
+
+ it('enforces CAS, ownership, dependencies, transitions, and write-scope warnings', async () => {
+ const { ctx, lead } = await setup(['hang', 'hang', textResponse('beta integrated update')])
+ const firstMember = await spawn(ctx, lead, 'alpha')
+ const alpha = await waitRunning(ctx, firstMember)
+ const secondMember = await spawn(ctx, lead, 'beta')
+ const beta = await waitRunning(ctx, secondMember)
+
+ const first = await ctx.agentTeams.createTask(alpha, {
+ subject: 'first',
+ description: 'first task',
+ writeScopes: ['src', './src', 'src'],
+ })
+ const second = await ctx.agentTeams.createTask(beta, {
+ subject: 'second',
+ description: 'second task',
+ blockedBy: [first.id],
+ writeScopes: ['src/feature'],
+ })
+ expect(first.writeScopes).toEqual(['src'])
+ await expect(ctx.agentTeams.updateTask(beta, {
+ taskId: second.id,
+ expectedRevision: second.revision,
+ action: 'claim',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_BLOCKED' })
+
+ const claimed = await ctx.agentTeams.updateTask(alpha, {
+ taskId: first.id,
+ expectedRevision: first.revision,
+ action: 'claim',
+ })
+ await expect(ctx.agentTeams.updateTask(beta, {
+ taskId: first.id,
+ expectedRevision: claimed.revision,
+ action: 'claim',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_ALREADY_CLAIMED' })
+ expect(ctx.agentTeams.getTask(beta, second.id)).toMatchObject({
+ ready: false,
+ writeScopeWarnings: [`write scopes overlap with ${first.id}`],
+ })
+ await expect(ctx.agentTeams.updateTask(beta, {
+ taskId: first.id,
+ expectedRevision: claimed.revision,
+ action: 'edit',
+ subject: 'stolen',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_UNAUTHORIZED' })
+ await expect(ctx.agentTeams.updateTask(alpha, {
+ taskId: first.id,
+ expectedRevision: first.revision,
+ action: 'complete',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_STALE_REVISION' })
+
+ const completed = await ctx.agentTeams.updateTask(alpha, {
+ taskId: first.id,
+ expectedRevision: claimed.revision,
+ action: 'complete',
+ })
+ expect(completed.status).toBe('completed')
+ expect(ctx.agentTeams.getTask(beta, second.id).ready).toBe(true)
+ const secondClaim = await ctx.agentTeams.updateTask(beta, {
+ taskId: second.id,
+ expectedRevision: second.revision,
+ action: 'claim',
+ })
+ const released = await ctx.agentTeams.updateTask(beta, {
+ taskId: second.id,
+ expectedRevision: secondClaim.revision,
+ action: 'release',
+ })
+ expect(released).toMatchObject({ status: 'pending', ready: true })
+ expect('ownerId' in released).toBe(false)
+
+ await ctx.subagents.drainChildren(lead, [alpha.id, beta.id])
+ await Promise.all([waitNoAgent(ctx, alpha.id), waitNoAgent(ctx, beta.id)])
+ })
+
+ it('rejects malformed scopes and every invalid dependency relation', async () => {
+ const { ctx, lead } = await setup([])
+ const first = await ctx.agentTeams.createTask(lead, { subject: 'one', description: 'one' })
+ const second = await ctx.agentTeams.createTask(lead, {
+ subject: 'two', description: 'two', blockedBy: [first.id],
+ })
+ await expect(ctx.agentTeams.createTask(lead, {
+ subject: 'bad', description: 'bad', blockedBy: [TeamTaskId('missing')],
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_NOT_FOUND' })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: first.id,
+ expectedRevision: first.revision,
+ action: 'set_dependencies',
+ blockedBy: [second.id],
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_DEPENDENCY_CYCLE' })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: first.id,
+ expectedRevision: first.revision,
+ action: 'set_dependencies',
+ blockedBy: [first.id],
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_DEPENDENCY_CYCLE' })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: first.id,
+ expectedRevision: first.revision,
+ action: 'set_dependencies',
+ blockedBy: [second.id, second.id],
+ })).rejects.toMatchObject({ code: 'TEAM_INVALID_ARGUMENT' })
+ for (const scope of ['', '.', '..', '/root', 'C:\\root', 'C:root', 'a//b', 'a/../b']) {
+ await expect(ctx.agentTeams.createTask(lead, {
+ subject: 'scope', description: 'scope', writeScopes: [scope],
+ })).rejects.toMatchObject({ code: 'TEAM_INVALID_WRITE_SCOPE' })
+ }
+ })
+
+ it('rejects incomplete mutations, invalid transitions, and deletion of a live blocker', async () => {
+ const { ctx, lead } = await setup([])
+ await expect(ctx.agentTeams.createTask(lead, { subject: ' ', description: 'invalid' }))
+ .rejects.toMatchObject({ code: 'TEAM_INVALID_ARGUMENT' })
+ await expect(ctx.agentTeams.createTask(lead, { subject: 'invalid', description: '' }))
+ .rejects.toMatchObject({ code: 'TEAM_INVALID_ARGUMENT' })
+ await expect(ctx.agentTeams.createTask(lead, { subject: 'x'.repeat(201), description: 'too long' }))
+ .rejects.toMatchObject({ code: 'TEAM_INVALID_ARGUMENT' })
+ const blocker = await ctx.agentTeams.createTask(lead, { subject: 'blocker', description: 'blocker' })
+ await ctx.agentTeams.createTask(lead, {
+ subject: 'dependent', description: 'dependent', blockedBy: [blocker.id],
+ })
+ expect(() => ctx.agentTeams.getTask(lead, TeamTaskId('missing')))
+ .toThrow(expect.objectContaining({ code: 'TEAM_TASK_NOT_FOUND' }))
+ for (const action of ['release', 'complete', 'reopen'] as const) {
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: blocker.id,
+ expectedRevision: blocker.revision,
+ action,
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_INVALID_TRANSITION' })
+ }
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: blocker.id,
+ expectedRevision: blocker.revision,
+ action: 'edit',
+ })).rejects.toMatchObject({ code: 'TEAM_INVALID_ARGUMENT' })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: blocker.id,
+ expectedRevision: blocker.revision,
+ action: 'set_dependencies',
+ })).rejects.toMatchObject({ code: 'TEAM_INVALID_ARGUMENT' })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: blocker.id,
+ expectedRevision: blocker.revision,
+ action: 'delete',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_HAS_DEPENDENTS' })
+ })
+
+ it('supports Lead reassignment, completion, reopen, and deletion permissions', async () => {
+ const { ctx, lead } = await setup(['hang'])
+ const started = await spawn(ctx, lead, 'owner')
+ const owner = await waitRunning(ctx, started)
+ const task = await ctx.agentTeams.createTask(owner, { subject: 'lifecycle', description: 'lifecycle' })
+ const assigned = await ctx.agentTeams.updateTask(lead, {
+ taskId: task.id,
+ expectedRevision: task.revision,
+ action: 'reassign',
+ owner: owner.id,
+ })
+ await expect(ctx.agentTeams.updateTask(owner, {
+ taskId: task.id,
+ expectedRevision: assigned.revision,
+ action: 'reassign',
+ owner: lead.id,
+ })).rejects.toMatchObject({ code: 'TEAM_LEAD_REQUIRED' })
+ const complete = await ctx.agentTeams.updateTask(owner, {
+ taskId: task.id,
+ expectedRevision: assigned.revision,
+ action: 'complete',
+ })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: task.id,
+ expectedRevision: complete.revision,
+ action: 'reassign',
+ owner: lead.id,
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_INVALID_TRANSITION' })
+ const reopened = await ctx.agentTeams.updateTask(owner, {
+ taskId: task.id,
+ expectedRevision: complete.revision,
+ action: 'reopen',
+ })
+ const claimed = await ctx.agentTeams.updateTask(owner, {
+ taskId: task.id,
+ expectedRevision: reopened.revision,
+ action: 'claim',
+ })
+ const deleted = await ctx.agentTeams.updateTask(owner, {
+ taskId: task.id,
+ expectedRevision: claimed.revision,
+ action: 'delete',
+ })
+ expect(deleted.status).toBe('deleted')
+ expect(ctx.agentTeams.listTasks(lead)).toEqual([])
+ await expect(ctx.agentTeams.updateTask(owner, {
+ taskId: task.id,
+ expectedRevision: deleted.revision,
+ action: 'edit',
+ subject: 'late',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_DELETED' })
+ await ctx.subagents.drainChildren(lead, [owner.id])
+ await waitNoAgent(ctx, owner.id)
+ })
+
+ it('covers partial edits, Lead ownership, unassignment, and blocked reassignment', async () => {
+ const { ctx, lead } = await setup(['hang'])
+ const started = await spawn(ctx, lead, 'editor')
+ const editor = await waitRunning(ctx, started)
+ const blocker = await ctx.agentTeams.createTask(lead, { subject: 'blocker', description: 'blocker' })
+ const task = await ctx.agentTeams.createTask(lead, {
+ subject: 'draft',
+ description: 'draft description',
+ blockedBy: [blocker.id],
+ })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: TeamTaskId('missing-update'), expectedRevision: 1, action: 'delete',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_NOT_FOUND' })
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: task.id, expectedRevision: task.revision, action: 'reassign', owner: editor.id,
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_BLOCKED' })
+
+ const leadClaim = await ctx.agentTeams.updateTask(lead, {
+ taskId: blocker.id, expectedRevision: blocker.revision, action: 'claim',
+ })
+ expect(leadClaim.ownerId).toBe(lead.id)
+ const completedBlocker = await ctx.agentTeams.updateTask(lead, {
+ taskId: blocker.id, expectedRevision: leadClaim.revision, action: 'complete',
+ })
+ expect(completedBlocker.status).toBe('completed')
+ const assigned = await ctx.agentTeams.updateTask(lead, {
+ taskId: task.id, expectedRevision: task.revision, action: 'reassign', owner: editor.id,
+ })
+ const subject = await ctx.agentTeams.updateTask(editor, {
+ taskId: task.id, expectedRevision: assigned.revision, action: 'edit', subject: 'edited subject',
+ })
+ const description = await ctx.agentTeams.updateTask(editor, {
+ taskId: task.id,
+ expectedRevision: subject.revision,
+ action: 'edit',
+ description: 'edited description',
+ })
+ const scopes = await ctx.agentTeams.updateTask(editor, {
+ taskId: task.id,
+ expectedRevision: description.revision,
+ action: 'edit',
+ writeScopes: ['src/nested'],
+ })
+ expect(scopes).toMatchObject({
+ subject: 'edited subject',
+ description: 'edited description',
+ writeScopes: ['src/nested'],
+ })
+ const unassigned = await ctx.agentTeams.updateTask(lead, {
+ taskId: task.id, expectedRevision: scopes.revision, action: 'reassign',
+ })
+ expect(unassigned).toMatchObject({ status: 'pending' })
+ expect('ownerId' in unassigned).toBe(false)
+
+ const broad = await ctx.agentTeams.createTask(lead, {
+ subject: 'broad scope', description: 'broad scope', writeScopes: ['src'],
+ })
+ const narrow = await ctx.agentTeams.createTask(lead, {
+ subject: 'narrow scope', description: 'narrow scope', writeScopes: ['src/nested'],
+ })
+ const disjoint = await ctx.agentTeams.createTask(lead, {
+ subject: 'disjoint scope', description: 'disjoint scope', writeScopes: ['docs'],
+ })
+ await ctx.agentTeams.updateTask(lead, {
+ taskId: broad.id, expectedRevision: broad.revision, action: 'claim',
+ })
+ await ctx.agentTeams.updateTask(lead, {
+ taskId: narrow.id, expectedRevision: narrow.revision, action: 'claim',
+ })
+ await ctx.agentTeams.updateTask(lead, {
+ taskId: disjoint.id, expectedRevision: disjoint.revision, action: 'claim',
+ })
+ expect(ctx.agentTeams.getTask(lead, broad.id).writeScopeWarnings)
+ .toEqual([`write scopes overlap with ${narrow.id}`])
+
+ const rootAssigned = await ctx.agentTeams.updateTask(lead, {
+ taskId: task.id, expectedRevision: unassigned.revision, action: 'reassign', owner: lead.id,
+ })
+ expect(rootAssigned).toMatchObject({ status: 'in_progress', ownerId: lead.id })
+
+ await ctx.subagents.drainChildren(lead, [editor.id])
+ await waitNoAgent(ctx, editor.id)
+ })
+})
+
+describe('Task-board wait notifications', () => {
+ it('notifies the root and every resident descendant without writing inboxes or starting idle agents', async () => {
+ const { ctx, lead, adapter } = await setup([])
+ const alpha = await resident(ctx, lead, 'notify-alpha')
+ const beta = (await ctx.agents.create({
+ sessionId: SessionId('notify-beta'), parentAgent: lead, meta: { parentSession: alpha.id },
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })).agent
+ const unrelated = await ctx.agentLoop.create(SessionId('unrelated'), { provider: 'mock', model: 'mock' })
+ const notified: Agent[] = []
+ const rootNotifications: Agent[] = []
+ const betaNotifications: Agent[] = []
+ ctx.on('agent/wait-notified', ({ agent }) => { notified.push(agent) })
+ lead.ctx.on('agent/wait-notified', ({ agent }) => { rootNotifications.push(agent) })
+ beta.ctx.on('agent/wait-notified', ({ agent }) => { betaNotifications.push(agent) })
+ const first = await ctx.agentTeams.createTask(lead, { subject: 'one', description: 'first change' })
+ await ctx.agentTeams.updateTask(beta, {
+ taskId: first.id, expectedRevision: first.revision, action: 'claim',
+ })
+ expect(notified).toEqual([lead, alpha, beta, lead, alpha, beta])
+ expect(rootNotifications).toEqual([lead, lead])
+ expect(betaNotifications).toEqual([beta, beta])
+ for (const agent of [lead, alpha, beta, unrelated]) {
+ expect(agent.inbox.nextStep).toHaveLength(0)
+ expect(agent.inbox.nextTurn).toHaveLength(0)
+ expect(agent.status).toBe('idle')
+ expect(agent.session.snapshotEvents().filter(event => event.type === 'agent/inbox/spliced')).toHaveLength(0)
+ }
+ expect(adapter.requests).toHaveLength(0)
+ })
+
+ it('publishes notifications only after persistence succeeds', async () => {
+ const { ctx, lead } = await setup([])
+ const child = await resident(ctx, lead, 'flush-recipient')
+ const notified: Agent[] = []
+ ctx.on('agent/wait-notified', ({ agent }) => { notified.push(agent) })
+ const flush = ctx.sessions.flush.bind(ctx.sessions)
+ const entered = Promise.withResolvers()
+ const release = Promise.withResolvers()
+ vi.spyOn(ctx.sessions, 'flush').mockImplementationOnce(async (session) => {
+ entered.resolve(undefined)
+ await release.promise
+ return await flush(session)
+ })
+ const creating = ctx.agentTeams.createTask(lead, { subject: 'one', description: 'wait for flush' })
+ try {
+ await entered.promise
+ expect(notified).toEqual([])
+ } finally {
+ release.resolve(undefined)
+ await creating
+ }
+ expect(notified).toEqual([lead, child])
+ notified.length = 0
+ vi.spyOn(ctx.sessions, 'flush').mockRejectedValueOnce(new Error('storage unavailable'))
+ await expect(ctx.agentTeams.createTask(lead, { subject: 'two', description: 'failed flush' })).rejects.toMatchObject({
+ code: 'TEAM_TASK_PERSISTENCE_UNCONFIRMED',
+ message: 'task "task-2" revision 1 is visible, but persistence was not confirmed; read the task before retrying',
+ cause: new Error('storage unavailable'),
+ })
+ expect(ctx.agentTeams.getTask(lead, TeamTaskId('task-2'))).toMatchObject({ subject: 'two', revision: 1 })
+ expect(ctx.agentTeams.listTasks(lead)).toHaveLength(2)
+ expect(notified).toEqual([])
+ await expect(ctx.agentTeams.updateTask(lead, {
+ taskId: TeamTaskId('task-1'), expectedRevision: 99, action: 'claim',
+ })).rejects.toMatchObject({ code: 'TEAM_TASK_STALE_REVISION' })
+ expect(notified).toEqual([])
+ })
+
+ it('contains listener failures and continues notifying the same agent and later recipients', async () => {
+ const { ctx, lead } = await setup([])
+ const child = await resident(ctx, lead, 'healthy-recipient')
+ const warnings: string[] = []
+ ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+ lead.ctx.on('agent/wait-notified', () => { throw new Error('sync listener') })
+ lead.ctx.on('agent/wait-notified', () => Promise.reject(new Error('async listener')) as never)
+ const notified: Agent[] = []
+ ctx.on('agent/wait-notified', ({ agent }) => { notified.push(agent) })
+ const task = await ctx.agentTeams.createTask(lead, { subject: 'committed', description: 'listener failure' })
+ expect(task).toMatchObject({ id: 'task-1', revision: 1 })
+ expect(notified).toEqual([lead, child])
+ expect(warnings).toEqual([
+ 'agent event "agent/wait-notified" listener threw: Error: sync listener',
+ 'agent event "agent/wait-notified" listener rejected: Error: async listener',
+ ])
+ await using stored = await ctx.sessionPersistence.open(lead.id, 'read')
+ const events = (await stored.read()).events.filter(event => event.type === 'team/task')
+ expect(events).toHaveLength(1)
+ expect(events[0]!.data).toMatchObject({ task: { id: task.id, revision: 1, subject: 'committed' } })
+ })
+})
diff --git a/packages/subagent/agent-team/tests/test-session-query.ts b/packages/subagent/agent-team/tests/test-session-query.ts
new file mode 100644
index 0000000000..be2778eee3
--- /dev/null
+++ b/packages/subagent/agent-team/tests/test-session-query.ts
@@ -0,0 +1,14 @@
+/** Concrete Session query using the standard live and persisted projections. */
+
+import SessionQueryEngine from '@deepseek-ai/dsh-session-query'
+
+/** Session query implementation whose search faces are outside these tests. */
+export class TestSessionQuery extends SessionQueryEngine {
+ override searchSessions(): Promise {
+ return Promise.reject(new Error('session search is not configured in this test'))
+ }
+
+ override searchEvents(): Promise {
+ return Promise.reject(new Error('event search is not configured in this test'))
+ }
+}
diff --git a/packages/subagent/agent-team/tsconfig.json b/packages/subagent/agent-team/tsconfig.json
new file mode 100644
index 0000000000..c1d42f2329
--- /dev/null
+++ b/packages/subagent/agent-team/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "rootDir": "src",
+ "outDir": "lib/types"
+ },
+ "include": ["src"],
+ "references": [
+ { "path": "../../../vendor/cosmokit" },
+ { "path": "../../../vendor/schemastery" },
+ { "path": "../../../vendor/cordis" },
+ { "path": "../../util/brand" },
+ { "path": "../../interaction/commands" },
+ { "path": "../../llm/llm" },
+ { "path": "../../core/session" },
+ { "path": "../../core/agent" },
+ { "path": "../subagent" },
+ { "path": "../../session/session-projection" }
+ ]
+}
diff --git a/packages/subagent/agent-team/tsdown.config.ts b/packages/subagent/agent-team/tsdown.config.ts
new file mode 100644
index 0000000000..f96442ba55
--- /dev/null
+++ b/packages/subagent/agent-team/tsdown.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the runtime as a self-contained package export. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/subagent/tool-agent-team/README.i18n.yaml b/packages/subagent/tool-agent-team/README.i18n.yaml
new file mode 100644
index 0000000000..3c418bb2cf
--- /dev/null
+++ b/packages/subagent/tool-agent-team/README.i18n.yaml
@@ -0,0 +1,103 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write packages/subagent/tool-agent-team/README.md
+/:
+ en: ca1947ba4777c2a0
+ zh: bed18854b761aae4
+/deepseek-ai-dsh-tool-agent-team:
+ en: eb00a9f551eeca17
+ zh: a59692cd060109e0
+/deepseek-ai-dsh-tool-agent-team/summary:
+ en: 656bbce0b74cc562
+ zh: 20212fe57a0b04cc
+/deepseek-ai-dsh-tool-agent-team/table-of-contents:
+ en: d152484eb41ac6b4
+ zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-agent-team/use-this-package:
+ en: 5434a32624f78cb8
+ zh: 6f4d57cdaa6b71c8
+/deepseek-ai-dsh-tool-agent-team/use-this-package/when-to-choose-it:
+ en: c27d5457e1183675
+ zh: 3c36d513e6400446
+/deepseek-ai-dsh-tool-agent-team/use-this-package/smallest-working-example:
+ en: d822dbf57a814a5a
+ zh: f1dd543cbb42fbb5
+/deepseek-ai-dsh-tool-agent-team/use-this-package/what-the-model-can-do:
+ en: f4c91b124496d1a6
+ zh: a2149d32e11d634a
+/deepseek-ai-dsh-tool-agent-team/use-this-package/what-success-and-failure-look-like:
+ en: bf1eb0e693610f5b
+ zh: 2b29e5cf63623909
+/deepseek-ai-dsh-tool-agent-team/understand-the-implementation:
+ en: 3952eb1d9de1f988
+ zh: 789d51b88f41b710
+/deepseek-ai-dsh-tool-agent-team/understand-the-implementation/design-philosophy:
+ en: 9b3218d9dd0019e4
+ zh: cefbcdbdb91648ab
+/deepseek-ai-dsh-tool-agent-team/understand-the-implementation/source-map:
+ en: 29ff96b23b25b13e
+ zh: 7d2cdf9be86d1ed4
+/deepseek-ai-dsh-tool-agent-team/understand-the-implementation/policy-and-tools:
+ en: f557dca7db212fa9
+ zh: 2b91f9dc363f9f39
+/deepseek-ai-dsh-tool-agent-team/understand-the-implementation/scoped-registration-and-teardown:
+ en: ef8a0940f658d225
+ zh: c13048bcda07d006
+/deepseek-ai-dsh-tool-agent-team/further-exploration:
+ en: b45e8b275a1174ed
+ zh: 4c983de55cec7a8f
+/deepseek-ai-dsh-tool-agent-team/model-experience:
+ en: 215e7ba838619b7b
+ zh: a311da3843709f90
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-policy-system-prompt:
+ en: 8757dc3caca9e4e2
+ zh: fd0b7535a1b24189
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-policy-system-prompt/what-the-model-sees:
+ en: 25079a70c9a3ed87
+ zh: 34301e390669a887
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-policy-system-prompt/what-the-model-sees/team-policy:
+ en: 824ebdbe434d7b6c
+ zh: 6a442dbca7cf3625
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-policy-system-prompt/token-effect:
+ en: 7e2583f482a60938
+ zh: d3e68b204cd3d2b3
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-policy-system-prompt/kv-cache-effect:
+ en: 6723f8e3f2497338
+ zh: ca68851b279362e1
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-identity-runtime-context:
+ en: ed8642015d306d6d
+ zh: 31496981d115ba40
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-identity-runtime-context/what-the-model-sees:
+ en: c34616cd061c33be
+ zh: c039b9dd9804f8ac
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-identity-runtime-context/what-the-model-sees/root-identity:
+ en: 58d2b04f507baa5f
+ zh: 773786c59605a154
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-identity-runtime-context/what-the-model-sees/teammate-identity:
+ en: f0d12764966d3005
+ zh: 365df450e96cb6e1
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-identity-runtime-context/token-effect:
+ en: b9c8f7524fbe3204
+ zh: 6c61dfb24b4b677a
+/deepseek-ai-dsh-tool-agent-team/model-experience/team-identity-runtime-context/kv-cache-effect:
+ en: 32488ff4b3134dbf
+ zh: 5b76b6a325597ddb
+/deepseek-ai-dsh-tool-agent-team/model-experience/task-tool-schemas:
+ en: d6918434714cf05a
+ zh: eef799d16e0c8f4b
+/deepseek-ai-dsh-tool-agent-team/model-experience/task-tool-schemas/what-the-model-sees:
+ en: 60ebf4743dac10a4
+ zh: 2543f538b52a2980
+/deepseek-ai-dsh-tool-agent-team/model-experience/task-tool-schemas/token-effect:
+ en: 5ae789db90ce9606
+ zh: 3b26fe33c811815c
+/deepseek-ai-dsh-tool-agent-team/model-experience/task-tool-schemas/kv-cache-effect:
+ en: 41bfcd6adb8058f5
+ zh: 73363ee21021a96a
+/deepseek-ai-dsh-tool-agent-team/known-limitations-and-deferred-work:
+ en: 863e528107d3b510
+ zh: bd0551f1f7e4607f
+/deepseek-ai-dsh-tool-agent-team/known-limitations-and-deferred-work/dev-note:
+ en: e67f633dc6fe7773
+ zh: 3bb0c20c93f16f98
diff --git a/packages/subagent/tool-agent-team/README.md b/packages/subagent/tool-agent-team/README.md
new file mode 100644
index 0000000000..7c0bf90e7d
--- /dev/null
+++ b/packages/subagent/tool-agent-team/README.md
@@ -0,0 +1,200 @@
+---
+description: "Four task-board tools and shared-task guidance for Team-enabled Sessions."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-agent-team
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package lets every agent in a subagent tree create, claim, and complete shared tasks. It adds four task schemas, shared-board guidance, and required Team identity. Ordinary subagent controls own discovery, messaging, interruption, and inbox waiting. The base bundle loads the service and tools; new Sessions default to Team mode off.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+
+## Use this package
+
+Team tools and guidance are installed only while the root Session enables Team mode. Mode changes update all resident descendants; ordinary subagent controls remain available.
+
+Mount this package with `@deepseek-ai/dsh-agent-team` when models need the shared board. The root and descendants receive identical task schemas and task policy.
+
+### When to choose it
+
+Choose it whenever the Team domain is mounted and models should use the board; without it, the board is reachable only through `ctx.agentTeams`. Teammates are created and reached through the standard `subagent`, `subagent_fork`, `send_message`, `list_agents`, and `interrupt_agent` tools, so the composition also needs `@deepseek-ai/dsh-tool-subagent` and `@deepseek-ai/dsh-tool-subagent-control`.
+
+### Smallest working example
+
+The plugin takes no configuration; mount it beside the Team domain as in the [agent-team setup](../agent-team/README.md#smallest-working-setup):
+
+```yaml
+- id: tool-agent-team
+ name: '@deepseek-ai/dsh-tool-agent-team'
+```
+
+A row that sets `interrupt`, `freshProvider`, or `forkProvider` does not activate, and dsh names the key in its startup warning. The [upgrade guide](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md) maps the removed tools and keys to their replacements, and the generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-agent-team) records the empty configuration.
+
+Ask the Lead to start a subagent to review the diff, add a review task, and wait for its result. The `description` explains the subagent’s work; the returned full path addresses it.
+
+### What the model can do
+
+The task tools complement the ordinary subagent controls:
+
+- **Manage the task board** — `team_task_create`, `team_task_list`, `team_task_get`, and `team_task_update` add, browse, read, and update shared tasks.
+- **Wait for inbox input** — `wait_agent` belongs to `@deepseek-ai/dsh-tool-subagent-control` and remains available without this package.
+- **Create and reach teammates** — `subagent`, `subagent_fork`, `send_message`, `list_agents`, and `interrupt_agent` come from the subagent tool packages and are unchanged by this package.
+
+Task `owner` arguments and `ownerName` results use full agent paths. The root may reassign to itself or any reachable continuable descendant; historical roster records grant no authority. Other agents claim ready tasks themselves. Updates enforce ownership and revision checks.
+
+### What success and failure look like
+
+Task tools return compact JSON task views or pages. Stale revisions, unauthorized actions, and unready tasks return errors.
+
+-----
+
+
+## Understand the implementation
+
+
+Implementation internals — click to expand
+
+This section explains the design decisions behind the adapter and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The adapter is built on four commitments:
+
+- **Agent-scoped registration.** Every live Agent receives its task tools and policy on its own `ctx`; the service resolves tree authority when called.
+- **One tool family.** Team registers no messaging, listing, or interruption tool; the standard subagent tools serve Leads and teammates alike.
+- **Declared results, compact JSON.** Every tool declares its complete result schema and renders that value as compact JSON, so the compiler checks `execute` against what the model is promised and no result spends tokens on indentation.
+- **The domain owns authority.** Tools delegate to `ctx.agentTeams`, which enforces Lead authority and revision checks; the adapter adds no weaker path.
+
+The [subagent teammates Agent Note](../../../.agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.md) owns the model-facing and scoping decisions.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry, removed-key rejection, Team policy and identity, and four scoped task tools |
+
+### Policy and tools
+
+One `team:policy` section, required `team:identity` context, and four task schemas are registered on each Agent scope, including fork children. Identity comes from `ctx.subagents.rootOf(agent)`, without a separate membership service. Communication and waiting belong to [subagent controls](../tool-subagent-control/README.md); the subagent runtime delivers final results.
+
+### Scoped registration and teardown
+
+Installation covers current live Agents and subscribes to `agent/created`. Agent disposal and plugin HMR unwind registrations in reverse order; a failed install cannot leave a partial scope.
+
+
+
+-----
+
+
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the domain service to the exact schemas and the decisions behind the design.
+
+- [agent-team package](../agent-team/README.md) — the `ctx.agentTeams` domain service behind these tools.
+- [Agent Teams subsystem](../../../docs/subsystems/agent-team.md) — durable Team types and service API.
+- [Subagent control tools](../tool-subagent-control/README.md) — messaging, listing, interruption, and inbox waiting.
+- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-agent-team) — every tool schema the model receives.
+- [Subagent teammates Agent Note](../../../.agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.md) — model-facing, scoping, and tool-family decisions.
+
+-----
+
+
+## Model Experience
+
+### Team policy system prompt
+
+#### What the model sees
+
+Every Team member's system prompt carries one `team:policy` section; the Lead and every teammate see the same text:
+
+##### Team policy
+
+```markdown
+A shared task board is available to every agent in your subagent tree. Task owners are full agent paths from list_agents. The root can reassign tasks to itself or any continuable descendant; other agents claim ready tasks themselves.
+
+Read tasks with team_task_list or team_task_get, claim with the current revision, perform the work, then complete the task. Dependencies determine readiness; write scopes describe expected edits and overlapping scopes are advisory, not locks. Task readiness does not start an agent.
+
+Task changes end current wait_agent calls in your subagent tree. Changes outside a wait are not retained as notifications, and no task-board messages are added to an inbox. After wait_agent returns, read the latest tasks before acting. Task changes do not start idle agents; use send_message when an agent needs to continue working.
+```
+
+#### Token effect
+
+The section is a fixed cost on every request of every Team member.
+
+#### KV Cache effect
+
+The text is identical for the Lead and every descendant and does not change while the plugin stays loaded, so it keeps a stable system-prompt prefix, including between a parent and its `subagent_fork` child. Loading or unloading the plugin changes the system prompt of every member and invalidates their cached prefixes.
+
+### Team identity runtime context
+
+#### What the model sees
+
+Required `team:identity` context uses the following text, replacing `` with the JSON-encoded full path derived from the subagent tree. If the root is unavailable, the context reports that fact and permits independent work. Optional-context suppression cannot remove this identity; the ordinary runtime-context mechanism restores it after compaction.
+
+##### Root identity
+
+```markdown
+You are the Team Lead. Your name is lead.
+```
+
+##### Teammate identity
+
+```markdown
+Your name is . You are a teammate in the Team led by "lead".
+```
+
+#### Token effect
+
+Identity is part of the full runtime-context snapshot. Stable retained context adds no new message.
+
+#### KV Cache effect
+
+Identity appends through runtime context while shared system text stays identical across members. An ordinary Session fork in Team mode receives its own root identity; actual provider cache reuse remains best-effort.
+
+### Task tool schemas
+
+#### What the model sees
+
+Every member receives the same four task schemas in the [generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-agent-team). Results are compact JSON task views or pages. Root-only reassignment is enforced at execution, not through different schemas.
+
+#### Token effect
+
+The four schemas are a fixed cost per request. Tool results add compact JSON; `team_task_list` returns at most 100 tasks per page.
+
+#### KV Cache effect
+
+The schemas are identical for the Lead and every descendant, including `subagent_fork` children, so a fork's tool list matches its parent's request prefix. Tool results append after the reusable prefix. Loading or unloading the plugin changes every member's tool list and invalidates their cached prefixes.
+
+## Known Limitations and Deferred Work
+
+
+
+These limits describe what the policy and tools cannot guarantee for a team. They are current package constraints, not a comparison with other collaboration surfaces.
+
+- **Prompt policy is coordination, not confinement** — it cannot stop Bash or external processes from writing overlapping files.
+- **Task authority needs a live root** — tool availability does not guarantee that the caller’s root remains available when an operation executes.
+- **No Web controls** — browser task-board presentation is outside this runtime package.
+
+
+### Dev Note
+
+
+Working context for maintainers — click to expand
+
+None.
+
+
diff --git a/packages/subagent/tool-agent-team/README.zh.md b/packages/subagent/tool-agent-team/README.zh.md
new file mode 100644
index 0000000000..4714d99836
--- /dev/null
+++ b/packages/subagent/tool-agent-team/README.zh.md
@@ -0,0 +1,200 @@
+---
+description: "为开启 Team 的 Session提供四个任务板工具和共享任务指导。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-agent-team
+
+[English](README.md) | 中文
+
+## 概述
+
+此包让 subagent(子智能体)树中的每个 agent 创建、认领并完成共享任务。它添加四个任务 schema、共享任务板指导和必需的 Team 身份。普通 subagent 控制工具负责发现、通信、中断和收件箱等待。基础 bundle 加载服务与工具;新 Session 默认关闭 Team 模式。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+
+## 使用本包
+
+仅当根 Session 开启 Team 模式时安装 Team 工具和提示词。模式变更同步到全部驻留后代;普通 subagent 控制工具始终可用。
+
+模型需要共享任务板时,将此包与 `@deepseek-ai/dsh-agent-team` 一起挂载。根和后代接收相同的任务 schema 和任务策略。
+
+### 何时选择
+
+只要挂载了 Team 领域包且模型需要使用任务板,就选择本包;没有它时,只能通过 `ctx.agentTeams` 访问任务板。teammate 通过标准 `subagent`、`subagent_fork`、`send_message`、`list_agents` 与 `interrupt_agent` 工具创建和联系,因此组合还需要 `@deepseek-ai/dsh-tool-subagent` 与 `@deepseek-ai/dsh-tool-subagent-control`。
+
+### 最小工作示例
+
+本插件不接受配置;按照 [agent-team 配置](../agent-team/README.zh.md#smallest-working-setup),把它挂载在 Team 领域包旁边:
+
+```yaml
+- id: tool-agent-team
+ name: '@deepseek-ai/dsh-tool-agent-team'
+```
+
+设置 `interrupt`、`freshProvider` 或 `forkProvider` 的配置行不会激活,dsh 会在启动警告中指出该键。[升级指南](../../../docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md)把已移除的工具与键对应到替代方式,生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-agent-team)记录空配置。
+
+让 Lead 启动子代理审查差异、创建审查任务并等待结果。`description` 说明子代理的工作;返回的完整路径用于寻址。
+
+### 模型能做什么
+
+任务工具补充普通 subagent 控制工具:
+
+- **管理任务板**——`team_task_create`、`team_task_list`、`team_task_get` 与 `team_task_update` 添加、浏览、读取与更新共享任务。
+- **等待收件箱输入** — `wait_agent` 属于 `@deepseek-ai/dsh-tool-subagent-control`,无需此包即可使用。
+- **创建和联系队友**——`subagent`、`subagent_fork`、`send_message`、`list_agents` 和 `interrupt_agent` 来自子代理工具包,本包不修改它们。
+
+任务 `owner` 参数和 `ownerName` 结果使用完整 agent 路径。根可将任务重新分配给自身或任意可达的可继续执行后代;历史名册记录不授予权限。其他 agent 自行认领就绪任务。更新会检查归属和修订。
+
+### 成功与失败的表现
+
+任务工具返回紧凑的 JSON 任务视图或分页。过期修订、未授权操作和未就绪任务返回错误。
+
+-----
+
+
+## 理解实现
+
+
+实现细节——点击展开
+
+本节解释适配器背后的设计决策并指出实现它们的代码位置;可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+适配器建立在四项承诺之上:
+
+- **按 Agent 注册。** 每个在线 Agent 在自身 `ctx` 上接收任务工具和策略;服务在调用时解析树权限。
+- **一个工具族。** Team 不注册消息、列表或中断工具;标准 subagent 工具同样服务 Lead 与 teammate。
+- **声明式结果,紧凑 JSON。** 每个工具都声明完整结果 schema,并把该值渲染为紧凑 JSON,因此编译器会对照向模型承诺的结果检查 `execute`,任何结果都不会在缩进上消耗 token。
+- **领域掌握裁决权。** 工具委托给 `ctx.agentTeams`,后者强制执行 Lead 权限与 revision 校验;适配器不添加更弱的路径。
+
+[subagent teammate Agent Note](../../../.agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.zh.md)负责模型侧与 scoping 决策。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口、已移除键拒绝、Team 策略与身份,以及四个作用域内任务工具 |
+
+### 策略与工具
+
+每个 Agent 作用域均注册一个 `team:policy` 段落、必需的 `team:identity` 上下文和四个任务 schema,包括 fork 子级。身份从 `ctx.subagents.rootOf(agent)` 派生,不使用独立成员关系服务。通信和等待属于 [subagent 控制工具](../tool-subagent-control/README.zh.md);subagent 运行时负责投递最终结果。
+
+### 按作用域注册与拆除
+
+安装覆盖当前在线 Agent,并订阅 `agent/created`。Agent 释放和插件 HMR 按逆序撤销注册;安装失败不会留下部分作用域。
+
+
+
+-----
+
+
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从领域服务逐步进入精确 schema 与设计背后的决策。
+
+- [agent-team 包](../agent-team/README.zh.md)——这些工具背后的 `ctx.agentTeams` 领域服务。
+- [Agent Teams 子系统](../../../docs/subsystems/agent-team.zh.md)——持久 Team 类型与服务 API。
+- [subagent 控制工具](../tool-subagent-control/README.zh.md) — 通信、列表、中断和收件箱等待。
+- [生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-agent-team)——模型接收的每个工具 schema。
+- [subagent teammate Agent Note](../../../.agents/notes/implemented/architecture/2026-10-15-agent-teams-as-subagents.zh.md)——模型侧、scoping 与工具族决策。
+
+-----
+
+
+## 模型体验
+
+### Team 策略 system prompt
+
+#### 模型看到什么
+
+每个 Team 成员的 system prompt 都包含一个 `team:policy` 段落;Lead 与每个 teammate 看到相同的文本:
+
+##### Team 策略
+
+```markdown
+A shared task board is available to every agent in your subagent tree. Task owners are full agent paths from list_agents. The root can reassign tasks to itself or any continuable descendant; other agents claim ready tasks themselves.
+
+Read tasks with team_task_list or team_task_get, claim with the current revision, perform the work, then complete the task. Dependencies determine readiness; write scopes describe expected edits and overlapping scopes are advisory, not locks. Task readiness does not start an agent.
+
+Task changes end current wait_agent calls in your subagent tree. Changes outside a wait are not retained as notifications, and no task-board messages are added to an inbox. After wait_agent returns, read the latest tasks before acting. Task changes do not start idle agents; use send_message when an agent needs to continue working.
+```
+
+#### Token 影响
+
+该段落是每个 Team 成员每次请求的固定成本。
+
+#### KV Cache 影响
+
+该文本对 Lead 与每个后代都相同,并且在插件保持加载期间不会变化,因此它保持稳定的 system prompt 前缀,包括父级与其 `subagent_fork` 子级之间。加载或卸载插件会改变每个成员的 system prompt,并使其已缓存前缀失效。
+
+### Team 身份运行时上下文
+
+#### 模型看到什么
+
+必需的 `team:identity` 上下文使用以下文本,将 `` 替换为从 subagent 树派生的 JSON 编码完整路径。根不可用时,上下文明确报告该事实并允许独立工作。可选上下文抑制不能移除该身份;普通运行时上下文机制会在压缩后恢复它。
+
+##### 根身份
+
+```markdown
+You are the Team Lead. Your name is lead.
+```
+
+##### 队友身份
+
+```markdown
+Your name is . You are a teammate in the Team led by "lead".
+```
+
+#### Token 影响
+
+身份属于完整运行时上下文快照。已保留的稳定上下文不会新增消息。
+
+#### KV Cache 影响
+
+身份通过运行时上下文追加,成员共享的系统文本保持一致。Team 模式中的普通 Session fork 获得自身的根身份;实际提供方的缓存复用仍为尽力而为。
+
+### 任务工具 schema
+
+#### 模型看到什么
+
+每个成员接收[生成工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-agent-team)中的相同四个任务 schema。结果是紧凑的 JSON 任务视图或分页。仅根可重新分配的限制在执行时实施,而非通过不同 schema 实施。
+
+#### Token 影响
+
+四个 schema 为每次请求的固定开销。工具结果增加紧凑 JSON;`team_task_list` 每页最多返回 100 个任务。
+
+#### KV Cache 影响
+
+这些 schema 对 Lead 与每个后代(包括 `subagent_fork` 子级)都相同,因此 fork 的工具列表与父级请求前缀一致。工具结果追加在可复用前缀之后。加载或卸载插件会改变每个成员的工具列表,并使其已缓存前缀失效。
+
+## 已知限制与延期工作
+
+
+
+这些限制说明策略与工具无法为一支团队保证什么。它们是当前包约束,不是与其他协作方式的对比。
+
+- **提示词策略只负责协调,不负责 confinement**——它无法阻止 Bash 或外部进程写入重叠文件。
+- **任务权限需要在线根** — 工具可用不保证操作执行时调用者的根仍在线。
+- **无 Web 控件** — 浏览器任务板展示不属于此运行时包。
+
+
+### 开发备注
+
+
+维护者的工作上下文——点击展开
+
+无。
+
+
diff --git a/packages/subagent/tool-agent-team/locale/en.json b/packages/subagent/tool-agent-team/locale/en.json
new file mode 100644
index 0000000000..0acebfefb9
--- /dev/null
+++ b/packages/subagent/tool-agent-team/locale/en.json
@@ -0,0 +1,6 @@
+{
+ "meta": {
+ "title": "Team Tools",
+ "description": "Give agents tools to manage their shared task board."
+ }
+}
diff --git a/packages/subagent/tool-agent-team/locale/zh.json b/packages/subagent/tool-agent-team/locale/zh.json
new file mode 100644
index 0000000000..feb762d77b
--- /dev/null
+++ b/packages/subagent/tool-agent-team/locale/zh.json
@@ -0,0 +1,6 @@
+{
+ "meta": {
+ "title": "团队工具",
+ "description": "为智能体提供共享任务板管理工具。"
+ }
+}
diff --git a/packages/subagent/tool-agent-team/package.json b/packages/subagent/tool-agent-team/package.json
new file mode 100644
index 0000000000..30d3d2d48c
--- /dev/null
+++ b/packages/subagent/tool-agent-team/package.json
@@ -0,0 +1,63 @@
+{
+ "name": "@deepseek-ai/dsh-tool-agent-team",
+ "description": "Scoped model-facing Agent Teams tools over ctx.agentTeams",
+ "version": "0.2.1-rc.2",
+ "publishConfig": {
+ "access": "public"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+ "directory": "packages/subagent/tool-agent-team"
+ },
+ "type": "module",
+ "main": "lib/index.js",
+ "types": "lib/types/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./lib/types/index.d.ts",
+ "default": "./lib/index.js"
+ },
+ "./locale/*.json": "./locale/*.json",
+ "./src/*": "./src/*",
+ "./package.json": "./package.json"
+ },
+ "files": [
+ "locale/*.json",
+ "lib/index.js",
+ "lib/types/**/*.d.ts"
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@deepseek-ai/schemastery": "workspace:~"
+ },
+ "peerDependencies": {
+ "@deepseek-ai/dsh-agent": "workspace:*",
+ "@deepseek-ai/dsh-session": "workspace:*",
+ "@deepseek-ai/dsh-subagent": "workspace:*",
+ "@deepseek-ai/dsh-system-prompt": "workspace:*",
+ "@deepseek-ai/dsh-agent-team": "workspace:*",
+ "@deepseek-ai/dsh-tools": "workspace:*",
+ "@deepseek-ai/cordis": "workspace:~"
+ },
+ "devDependencies": {
+ "@deepseek-ai/dsh-agent": "workspace:*",
+ "@deepseek-ai/dsh-agent-loop": "workspace:*",
+ "@deepseek-ai/dsh-agent-loop-testkit": "workspace:*",
+ "@deepseek-ai/dsh-session": "workspace:*",
+ "@deepseek-ai/dsh-session-projection": "workspace:*",
+ "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
+ "@deepseek-ai/dsh-session-query": "workspace:*",
+ "@deepseek-ai/dsh-scope": "workspace:*",
+ "@deepseek-ai/dsh-subagent": "workspace:*",
+ "@deepseek-ai/dsh-subagent-fork-in-process": "workspace:*",
+ "@deepseek-ai/dsh-subagent-spawn-in-process": "workspace:*",
+ "@deepseek-ai/dsh-tool-subagent-control": "workspace:*",
+ "@deepseek-ai/dsh-system-prompt": "workspace:*",
+ "@deepseek-ai/dsh-agent-team": "workspace:*",
+ "@deepseek-ai/dsh-tools": "workspace:*",
+ "@deepseek-ai/cordis": "workspace:~",
+ "@deepseek-ai/dsh-llm": "workspace:*",
+ "@deepseek-ai/dsh-llm-deepseek": "workspace:*"
+ }
+}
diff --git a/packages/subagent/tool-agent-team/src/index.ts b/packages/subagent/tool-agent-team/src/index.ts
new file mode 100644
index 0000000000..18ba19d1ed
--- /dev/null
+++ b/packages/subagent/tool-agent-team/src/index.ts
@@ -0,0 +1,297 @@
+/** Scoped model-facing task-board tools for the opt-in Agent Teams runtime. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import { SubagentError } from '@deepseek-ai/dsh-subagent'
+import { TeamTaskId, type TeamTaskView } from '@deepseek-ai/dsh-agent-team'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { InferValue, ValueSchemaSpec } from '@deepseek-ai/dsh-tools'
+
+/** Cordis plugin name. */
+export const name = 'tool-agent-team'
+/** Services required by the Team tool plugin. */
+export const inject = ['agents', 'agentTeams', 'subagents', 'tools', 'systemPrompt']
+
+/** The Team tool plugin takes no configuration. */
+export type Config = Record
+
+/** Loader schema for the opt-in Team tool plugin. */
+export const Config: z = z.object({})
+
+/** Configuration keys removed when Team reused subagent creation and messaging. */
+const REMOVED_CONFIG_KEYS = ['interrupt', 'freshProvider', 'forkProvider'] as const
+
+/** Model-facing collaboration guidance shared by Lead and teammates. */
+const TEAM_POLICY = `A shared task board is available to every agent in your subagent tree. Task owners are full agent paths from list_agents. The root can reassign tasks to itself or any continuable descendant; other agents claim ready tasks themselves.
+
+Read tasks with team_task_list or team_task_get, claim with the current revision, perform the work, then complete the task. Dependencies determine readiness; write scopes describe expected edits and overlapping scopes are advisory, not locks. Task readiness does not start an agent.
+
+Task changes end current wait_agent calls in your subagent tree. Changes outside a wait are not retained as notifications, and no task-board messages are added to an inbox. After wait_agent returns, read the latest tasks before acting. Task changes do not start idle agents; use send_message when an agent needs to continue working.`
+
+/** One shared task, matching the public `TeamTaskView`. */
+const TASK_VIEW_SCHEMA = {
+ type: 'object',
+ additionalProperties: false,
+ properties: {
+ id: { type: 'string', required: true },
+ revision: { type: 'integer', required: true },
+ subject: { type: 'string', required: true },
+ description: { type: 'string', required: true },
+ status: { type: 'string', required: true, enum: ['pending', 'in_progress', 'completed', 'deleted'] },
+ ownerName: { type: 'string' },
+ blockedBy: { type: 'array', required: true, items: { type: 'string' } },
+ writeScopes: { type: 'array', required: true, items: { type: 'string' } },
+ ready: { type: 'boolean', required: true },
+ writeScopeWarnings: { type: 'array', required: true, items: { type: 'string' } },
+ },
+} as const
+
+const TASK_LIST_VALUE_SCHEMA = {
+ type: 'object',
+ additionalProperties: false,
+ properties: {
+ tasks: { type: 'array', required: true, items: TASK_VIEW_SCHEMA },
+ nextCursor: { type: 'integer' },
+ },
+} as const
+
+/**
+ * Declare one canonical output schema with compact model-facing JSON. Every
+ * Team result is a fixed record, so the declared schema is what makes the
+ * compiler check `execute` against the value the model is promised.
+ * @param schema - canonical value schema for one tool.
+ * @returns the `output` declaration accepted by {@link defineTool}.
+ */
+function jsonOutput(schema: S): {
+ schema: S
+ render: (args: unknown, value: InferValue) => [{ type: 'text'; text: string }]
+} {
+ return {
+ schema,
+ render: (_args: unknown, value: InferValue) => [{ type: 'text', text: JSON.stringify(value) }],
+ }
+}
+
+type NamedTaskView = Omit & { readonly ownerName?: string }
+
+/** Project task owners from live activations or parent catalogs. */
+async function namedTasks(ctx: Context, caller: Agent, tasks: readonly TeamTaskView[], signal: AbortSignal): Promise {
+ const root = ctx.subagents.rootOf(caller)
+ const names = new Map([[root.id, 'lead']])
+ const missing = new Set()
+ for (const { ownerId } of tasks) {
+ if (ownerId === undefined || names.has(ownerId)) continue
+ const agent = ctx.agents.get(ownerId)
+ if (agent === undefined) missing.add(ownerId)
+ else names.set(ownerId, ctx.subagents.nameOf(agent))
+ }
+ if (missing.size > 0) {
+ for (const entry of await ctx.subagents.listDescendants(root.id, signal)) {
+ names.set(entry.id, `lead/${entry.path}`)
+ }
+ }
+ return tasks.map(({ ownerId, ...view }) => ({
+ ...view,
+ ...ownerId === undefined ? {} : { ownerName: names.get(ownerId) ?? `legacy:${ownerId}` },
+ }))
+}
+
+/** Recover the exact caller guaranteed by Agent-scoped tool discovery. */
+function callingAgent(agent: Agent | undefined, toolName: string): Agent {
+ /* v8 ignore next 2 -- Team tools are registered only in an exact Agent scope, so discovery supplies this carrier. */
+ if (agent === undefined) throw new Error(`${toolName} requires a calling Agent`)
+ return agent
+}
+
+/** Register the complete Team tool set in one exact Agent scope. */
+function install(agent: Agent, ctx: Context): () => void {
+ const scoped = agent.ctx
+ const disposers: Array<() => unknown> = []
+ const register = (disposer: () => unknown): void => { disposers.push(disposer) }
+ try {
+ register(scoped.systemPrompt.section({
+ name: 'team:policy',
+ order: scoped.systemPrompt.getSectionOrder('TEAM_POLICY'),
+ text: TEAM_POLICY,
+ }))
+ register(scoped.systemPrompt.context({
+ name: 'team:identity',
+ order: scoped.systemPrompt.getContextOrder('TEAM_IDENTITY'),
+ required: true,
+ interpolate: false,
+ text: () => {
+ try {
+ const root = ctx.subagents.rootOf(agent)
+ return root === agent
+ ? 'You are the Team Lead. Your name is lead.'
+ : `Your name is ${JSON.stringify(ctx.subagents.nameOf(agent))}. You are a teammate in the Team led by ${JSON.stringify(ctx.subagents.nameOf(root))}.`
+ } catch (error: unknown) {
+ if (!(error instanceof SubagentError) || error.code !== 'UNAUTHORIZED') throw error
+ return 'Your Team root agent is unavailable. Continue independent work; Team discovery and messaging require an active root.'
+ }
+ },
+ }))
+ register(scoped.tools.register(defineTool({
+ name: 'team_task_create',
+ description: 'Create one unowned pending task on the shared Team task board.',
+ parameters: {
+ subject: { type: 'string', required: true, description: 'Concise task title.' },
+ description: { type: 'string', required: true, description: 'Complete task details and acceptance criteria.' },
+ blocked_by: { type: 'array', items: { type: 'string' }, description: 'Task ids that must complete first.' },
+ write_scopes: {
+ type: 'array',
+ items: { type: 'string' },
+ description: 'Advisory workspace-relative file or directory prefixes this task expects to modify.',
+ },
+ },
+ output: jsonOutput(TASK_VIEW_SCHEMA),
+ async execute(args, exec) {
+ const caller = callingAgent(exec.agent, 'team_task_create')
+ const task = await ctx.agentTeams.createTask(caller, {
+ subject: args.subject,
+ description: args.description,
+ ...args.blocked_by === undefined ? {} : { blockedBy: args.blocked_by.map(TeamTaskId) },
+ ...args.write_scopes === undefined ? {} : { writeScopes: args.write_scopes },
+ }, exec.signal)
+ return (await namedTasks(ctx, caller, [task], exec.signal))[0] as NamedTaskView
+ },
+ })))
+
+ register(scoped.tools.register(defineTool({
+ name: 'team_task_list',
+ description: 'List shared tasks, including readiness, owner, revision, blockers, and write-scope warnings.',
+ parameters: {
+ status: {
+ type: 'string',
+ enum: ['pending', 'in_progress', 'completed'],
+ description: 'Optional exact status filter.',
+ },
+ owner: { type: 'string', description: 'Optional exact ownerName filter; use unowned for tasks without an owner.' },
+ ready: { type: 'boolean', description: 'Optional readiness filter.' },
+ cursor: { type: 'integer', description: 'Zero-based result offset. Defaults to 0.' },
+ limit: { type: 'integer', description: 'Number of rows, 1 through 100. Defaults to 50.' },
+ },
+ output: jsonOutput(TASK_LIST_VALUE_SCHEMA),
+ async execute(args, exec) {
+ const status = args.status
+ const caller = callingAgent(exec.agent, 'team_task_list')
+ const filtered = (await namedTasks(ctx, caller, ctx.agentTeams.listTasks(caller), exec.signal)).filter(task =>
+ (status === undefined || task.status === status)
+ && (args.owner === undefined || (args.owner === 'unowned' ? task.ownerName === undefined : task.ownerName === args.owner))
+ && (args.ready === undefined || task.ready === args.ready))
+ const cursor = args.cursor ?? 0
+ const limit = args.limit ?? 50
+ if (!Number.isSafeInteger(cursor) || cursor < 0) throw new Error('cursor must be a non-negative safe integer')
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('limit must be an integer from 1 through 100')
+ return Promise.resolve({
+ tasks: filtered.slice(cursor, cursor + limit),
+ ...(cursor + limit < filtered.length ? { nextCursor: cursor + limit } : {}),
+ })
+ },
+ })))
+
+ register(scoped.tools.register(defineTool({
+ name: 'team_task_get',
+ description: 'Read the complete latest value of one shared task before changing or executing it.',
+ parameters: {
+ task_id: { type: 'string', required: true, description: 'Shared task id.' },
+ },
+ output: jsonOutput(TASK_VIEW_SCHEMA),
+ async execute(args, exec) {
+ const caller = callingAgent(exec.agent, 'team_task_get')
+ const task = ctx.agentTeams.getTask(caller, TeamTaskId(args.task_id))
+ return (await namedTasks(ctx, caller, [task], exec.signal))[0] as NamedTaskView
+ },
+ })))
+
+ register(scoped.tools.register(defineTool({
+ name: 'team_task_update',
+ description: 'Compare-and-set a shared task action using the latest revision from team_task_get or team_task_list.',
+ parameters: {
+ task_id: { type: 'string', required: true, description: 'Shared task id.' },
+ expected_revision: { type: 'integer', required: true, description: 'Current task revision used as the CAS precondition.' },
+ action: {
+ type: 'string',
+ required: true,
+ enum: ['claim', 'release', 'edit', 'set_dependencies', 'complete', 'reopen', 'reassign', 'delete'],
+ description: 'Task transition to apply.',
+ },
+ subject: { type: 'string', description: 'Replacement title for edit.' },
+ description: { type: 'string', description: 'Replacement details for edit.' },
+ blocked_by: { type: 'array', items: { type: 'string' }, description: 'Complete blocker list for set_dependencies.' },
+ write_scopes: { type: 'array', items: { type: 'string' }, description: 'Replacement advisory write scopes for edit.' },
+ owner: { type: 'string', description: 'Full agent path of the root or any continuable descendant for root-only reassign; omit to unassign.' },
+ },
+ output: jsonOutput(TASK_VIEW_SCHEMA),
+ async execute(args, exec) {
+ const caller = callingAgent(exec.agent, 'team_task_update')
+ const owner = args.owner === undefined ? undefined
+ : await ctx.subagents.resolveName(caller, args.owner, exec.signal)
+ const task = await ctx.agentTeams.updateTask(caller, {
+ taskId: TeamTaskId(args.task_id),
+ expectedRevision: args.expected_revision,
+ action: args.action,
+ ...args.subject === undefined ? {} : { subject: args.subject },
+ ...args.description === undefined ? {} : { description: args.description },
+ ...args.blocked_by === undefined ? {} : { blockedBy: args.blocked_by.map(TeamTaskId) },
+ ...args.write_scopes === undefined ? {} : { writeScopes: args.write_scopes },
+ ...owner === undefined ? {} : { owner },
+ }, exec.signal)
+ return (await namedTasks(ctx, caller, [task], exec.signal))[0] as NamedTaskView
+ },
+ })))
+ } catch (error: unknown) {
+ for (const dispose of disposers.reverse()) void dispose()
+ throw error
+ }
+ return () => {
+ for (const dispose of disposers.reverse()) void dispose()
+ }
+}
+
+/**
+ * Install Team tools in every live or subsequently published Team member scope.
+ * @param ctx - context carrying the Agent registry, Team and subagent services, tools, and system prompt.
+ * @param config - the empty plugin configuration; removed keys fail at load.
+ */
+export function apply(ctx: Context, config: Config = {}): void {
+ for (const key of REMOVED_CONFIG_KEYS) {
+ if (Object.hasOwn(config, key)) {
+ throw new Error(`tool-agent-team: ${key} is no longer supported; create teammates with a subagent tool`)
+ }
+ }
+ const installed = new Map void>()
+ const maybeInstall = (agent: Agent): void => {
+ let enabled: boolean
+ try {
+ enabled = ctx.agentTeams.isEnabled(agent)
+ } catch (error: unknown) {
+ if (!(error instanceof SubagentError) || error.code !== 'UNAUTHORIZED') throw error
+ // An independently resumed child has no active root to supply Team mode.
+ enabled = false
+ }
+ if (enabled) {
+ if (!installed.has(agent)) installed.set(agent, install(agent, ctx))
+ } else {
+ installed.get(agent)?.()
+ installed.delete(agent)
+ }
+ }
+ for (const agent of ctx.agents.list()) maybeInstall(agent)
+ ctx.on('agent/created', ({ agent }) => { maybeInstall(agent) })
+ ctx.on('team/mode-changed', (root) => {
+ for (const agent of ctx.agents.list()) {
+ if (agent === root || ctx.agents.isOwnedBy(agent.id, root)) maybeInstall(agent)
+ }
+ })
+ ctx.on('agent/disposed', ({ agent }) => {
+ installed.get(agent)?.()
+ installed.delete(agent)
+ })
+ ctx.effect(() => () => {
+ for (const dispose of installed.values()) dispose()
+ installed.clear()
+ }, 'tool-team.scopedTools()')
+}
diff --git a/packages/subagent/tool-agent-team/tests/tool-team.spec.ts b/packages/subagent/tool-agent-team/tests/tool-team.spec.ts
new file mode 100644
index 0000000000..d295ffbeba
--- /dev/null
+++ b/packages/subagent/tool-agent-team/tests/tool-team.spec.ts
@@ -0,0 +1,800 @@
+import { randomUUID } from 'node:crypto'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { ToolCallId, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { scopeOf } from '@deepseek-ai/dsh-scope'
+import { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import SessionQueryEngine from '@deepseek-ai/dsh-session-query'
+import SubagentService, { SubagentError } from '@deepseek-ai/dsh-subagent'
+import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork-in-process'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
+import { renderPrompt, renderContextSnapshot } from '@deepseek-ai/dsh-system-prompt'
+import * as ToolSubagentControl from '@deepseek-ai/dsh-tool-subagent-control'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import { resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+import { serialize } from '@deepseek-ai/dsh-llm-deepseek/src/serialize.ts'
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import { mountWorkingDirectoryFixture } from '../../subagent/tests/working-directory-fixture.ts'
+import TeamService, { TeamId } from '../../agent-team/src/index.ts'
+import * as toolTeam from '../src/index.ts'
+
+function serializeRequest(request: GenerateOptions) {
+ const connection = resolveAdapterOptions({ models: [{ id: request.model, systemPromptUpdate: 'in-history' }] })
+ return serialize(request, connection, request.messages, new Map(), () => undefined)
+}
+
+function runtimeContextText(request: GenerateOptions) {
+ const context = request.messages.findLast(message => message.source?.kind === 'runtime-context')
+ return context?.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n')
+}
+
+const SIGNAL = new AbortController().signal
+const TEAM_TOOLS = [
+ 'team_task_create',
+ 'team_task_get',
+ 'team_task_list',
+ 'team_task_update',
+]
+const leadIdentity = (_agent: Agent): string => 'You are the Team Lead. Your name is lead.'
+
+const roots: string[] = []
+const contexts = new Set()
+let callNumber = 0
+
+/** Session query implementation whose search faces are outside these tests. */
+class TestSessionQuery extends SessionQueryEngine {
+ override searchSessions(): Promise {
+ return Promise.reject(new Error('session search is not configured in this test'))
+ }
+
+ override searchEvents(): Promise {
+ return Promise.reject(new Error('event search is not configured in this test'))
+ }
+}
+
+afterEach(async () => {
+ vi.useRealTimers()
+ vi.restoreAllMocks()
+ for (const ctx of contexts) await ctx.fiber.dispose()
+ contexts.clear()
+ for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+async function setup(script: ConstructorParameters[0], enabledByDefault = true) {
+ const ctx = new Context()
+ contexts.add(ctx)
+ await mountAgentLoopTestDependencies(ctx)
+ await mountWorkingDirectoryFixture(ctx)
+ const storageRoot = mkdtempSync(join(tmpdir(), 'dsh-tool-team-'))
+ roots.push(storageRoot)
+ await ctx.plugin(JsonlSessionPersistence, { root: storageRoot })
+ await ctx.plugin(TestSessionQuery)
+ await ctx.plugin(AgentLoop, { agents: [] })
+ await ctx.plugin(SubagentService)
+ await ctx.plugin(ToolSubagentControl)
+ await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+ await ctx.plugin(SubagentFork, { providerName: 'fork' })
+ await ctx.plugin(TeamService, { enabledByDefault })
+ const fiber = await ctx.plugin(toolTeam)
+ const adapter = new MockAdapter(script)
+ ctx.llm.registerAdapter(['mock'], adapter)
+ const lead = await ctx.agentLoop.create(SessionId('tool-team-lead'), { provider: 'mock', model: 'mock' })
+ return { ctx, lead, fiber, adapter }
+}
+
+function execute(
+ ctx: Context,
+ agent: Agent | undefined,
+ name: string,
+ args: unknown,
+ signal: AbortSignal = SIGNAL,
+) {
+ return ctx.tools.execute({
+ callId: ToolCallId(`team-call-${++callNumber}`),
+ name,
+ arguments: args,
+ signal,
+ ...agent === undefined ? {} : { agent },
+ })
+}
+
+function text(result: Awaited>): string {
+ return result.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('')
+}
+
+/** Observe wait subscription before committing a competing task change. */
+async function startWait(ctx: Context, agent: Agent) {
+ const entered = Promise.withResolvers()
+ const off = ctx.on('tools/execute', (exec, next) => {
+ const result = next()
+ if (exec.name === 'wait_agent' && exec.agent === agent) entered.resolve(undefined)
+ return result
+ })
+ const result = execute(ctx, agent, 'wait_agent', { timeout_ms: 10_000 })
+ await entered.promise
+ off()
+ return { result }
+}
+
+/** Start a continuable child of the Lead with a task description. */
+async function spawn(ctx: Context, lead: Agent, description: string | undefined, prompt: string, provider = 'spawn'): Promise {
+ const started = await ctx.subagents.startActivation({ name: `child-${randomUUID()}`,
+ provider,
+ label: `${description ?? 'shared'} task`,
+ request: { prompt: [{ type: 'text', text: prompt }], parent: lead },
+ signal: SIGNAL,
+ delivery: 'parent',
+ })
+ return started.childId
+}
+
+async function assembly(ctx: Context, agent: Agent) {
+ const scope = scopeOf(agent.ctx)
+ if (scope === undefined) throw new Error('expected Agent scope')
+ return ctx.systemPrompt.assemble({ scope, agent })
+}
+
+function teamTools(assembled: Awaited>): string[] {
+ return assembled.tools.map(schema => schema.name).filter(name => TEAM_TOOLS.includes(name)).sort()
+}
+
+function teammateIdentity(_lead: Agent): string {
+ return 'You are a teammate in the Team led by \"lead\".'
+}
+
+async function runTurn(agent: Agent, text: string): Promise {
+ agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }))
+ await agent.whenIdle()
+}
+
+async function waitRunning(ctx: Context, id: SessionId): Promise {
+ return vi.waitFor(() => {
+ const child = ctx.agents.get(id)
+ expect(child?.status).toBe('running')
+ return child!
+ }, { timeout: 5_000 })
+}
+
+async function waitNoAgent(ctx: Context, id: SessionId): Promise {
+ await vi.waitFor(() => { expect(ctx.agents.get(id)).toBeUndefined() }, { timeout: 5_000 })
+}
+
+async function interrupt(ctx: Context, lead: Agent, target: SessionId): Promise {
+ await ctx.subagents.drainChildren(lead, [target])
+}
+
+describe('dsh-tool-team', () => {
+ it.each([true, false])('cancels reassignment without appending when discovery observes cancellation: %s', async (observesCancellation) => {
+ const { ctx, lead } = await setup(['hang'])
+ const childId = await spawn(ctx, lead, 'worker', 'stay running')
+ await waitRunning(ctx, childId)
+ const task = await ctx.agentTeams.createTask(lead, { subject: 'work', description: 'assign work' })
+ const entered = Promise.withResolvers()
+ const release = Promise.withResolvers()
+ const discover = ctx.subagents.listDescendants.bind(ctx.subagents)
+ const lookup = vi.spyOn(ctx.subagents, 'listDescendants').mockImplementationOnce(async (...args) => {
+ entered.resolve(undefined)
+ await release.promise
+ return discover(args[0], observesCancellation ? args[1] : undefined)
+ })
+ const controller = new AbortController()
+ const result = execute(ctx, lead, 'team_task_update', {
+ task_id: task.id, expected_revision: task.revision, action: 'reassign', owner: ctx.subagents.nameOf(ctx.agents.get(childId)!),
+ }, controller.signal)
+ try {
+ await entered.promise
+ expect(lookup.mock.calls[0]?.[1]).toBeInstanceOf(AbortSignal)
+ controller.abort(new Error('stop assignment'))
+ } finally {
+ release.resolve(undefined)
+ }
+ expect(await result).toMatchObject({ isError: true })
+ expect(ctx.agentTeams.getTask(lead, task.id)).toEqual(task)
+ await using stored = await ctx.sessionPersistence.open(lead.id, 'read')
+ expect((await stored.read()).events.filter(event => event.type === 'team/task')).toHaveLength(1)
+ })
+
+ it('adds task tools, policy, and scoped identity to the shared subagent controls', async () => {
+ const { ctx, lead } = await setup(['hang', 'hang'])
+ const leadAssembly = await assembly(ctx, lead)
+ expect(teamTools(leadAssembly)).toEqual(TEAM_TOOLS)
+ const leadPrompt = renderPrompt(leadAssembly)
+ expect(leadPrompt).toContain('A shared task board is available to every agent in your subagent tree')
+ expect(leadPrompt).toContain('Task readiness does not start an agent')
+ expect(leadPrompt).toContain('Task changes end current wait_agent calls')
+ expect(renderContextSnapshot(leadAssembly)).toContain(leadIdentity(lead))
+ expect((await ctx.systemPrompt.assemble()).contexts.some(context => context.name === 'team:identity')).toBe(false)
+ expect(leadAssembly.tools.map(schema => schema.name)).not.toContain('spawn_teammate')
+ // Messaging, listing, and interruption stay the global subagent controls.
+ for (const name of ['send_message', 'list_agents', 'interrupt_agent', 'wait_agent']) {
+ expect(ctx.tools.get(name, scopeOf(lead.ctx))).toBe(ctx.tools.get(name))
+ }
+
+ const namedId = await spawn(ctx, lead, 'reviewer', 'stay available')
+ const unnamedId = await spawn(ctx, lead, undefined, 'stay available too')
+ for (const id of [namedId, unnamedId]) {
+ const child = await waitRunning(ctx, id)
+ const childAssembly = await assembly(ctx, child)
+ expect(teamTools(childAssembly)).toEqual(TEAM_TOOLS)
+ expect(renderPrompt(childAssembly)).toBe(leadPrompt)
+ expect(renderContextSnapshot(childAssembly)).toContain(teammateIdentity(lead))
+ expect(ctx.tools.get('send_message', scopeOf(child.ctx))).toBe(ctx.tools.get('send_message'))
+ }
+ await interrupt(ctx, lead, namedId)
+ await interrupt(ctx, lead, unnamedId)
+ await Promise.all([waitNoAgent(ctx, namedId), waitNoAgent(ctx, unnamedId)])
+ })
+
+ it.each([
+ ['spawn', undefined], ['fork', undefined], ['fork', 'in-history'],
+ ] as const)('records %s teammate identity with update mode %s and keeps the wire prefix', async (provider, systemPromptUpdate) => {
+ const { ctx, lead, adapter } = await setup([textResponse('parent answer'), textResponse('child answer')])
+ if (systemPromptUpdate !== undefined) adapter.systemPromptUpdate = systemPromptUpdate
+ await runTurn(lead, 'Parent task')
+ const parentRequest = serializeRequest(adapter.requests[0]!)
+ const parentHistory = structuredClone(lead.session.deriveMessages())
+ const childId = await spawn(ctx, lead, 'reviewer', 'Review the work', provider)
+ await waitNoAgent(ctx, childId)
+ const childRequest = serializeRequest(adapter.requests[1]!)
+ expect(childRequest.tools).toEqual(parentRequest.tools)
+ expect(childRequest.system).toEqual(parentRequest.system)
+ if (provider === 'fork') {
+ expect(childRequest.messages.slice(0, parentRequest.messages.length)).toEqual(parentRequest.messages)
+ expect(adapter.requests[1]!.messages.slice(0, parentHistory.length)).toEqual(parentHistory)
+ } else {
+ expect(JSON.stringify(childRequest.messages)).not.toContain('Parent task')
+ }
+ expect(runtimeContextText(adapter.requests[1]!)).toContain(teammateIdentity(lead))
+ })
+
+ it('appends the new Lead id after inherited history in an ordinary fork', async () => {
+ const { ctx, lead, adapter } = await setup([textResponse('parent answer'), textResponse('fork answer')])
+ await runTurn(lead, 'Parent task')
+ const seed = lead.session.snapshotEvents()
+ const handle = await ctx.agents.create({
+ sessionId: SessionId('ordinary-team-fork'),
+ seed,
+ inheritedEventCount: SessionLogOffset(seed.length),
+ meta: { parentSession: lead.id, isSeeded: true },
+ agentOptions: { provider: 'mock', model: 'mock' },
+ signal: SIGNAL,
+ })
+ await runTurn(handle.agent, 'Continue independently')
+ const parentRequest = serializeRequest(adapter.requests[0]!)
+ const childRequest = serializeRequest(adapter.requests[1]!)
+ expect(childRequest.tools).toEqual(parentRequest.tools)
+ expect(childRequest.messages.slice(0, parentRequest.messages.length)).toEqual(parentRequest.messages)
+ expect(childRequest.messages.at(-1)?.content).toContainEqual({ type: 'text', text: 'Continue independently' })
+ expect(runtimeContextText(adapter.requests[1]!)).toContain(leadIdentity(handle.agent))
+ expect(JSON.stringify(childRequest.messages)).not.toContain('system-reminder')
+ expect(handle.agent.session.snapshotEvents().slice(0, seed.length)).toEqual(seed)
+ expect(ctx.subagents.rootOf(handle.agent)).toBe(handle.agent)
+ await handle.dispose()
+ })
+
+ it('identifies nested descendants with the tree root rather than their direct parent', async () => {
+ const { ctx, lead } = await setup([])
+ const child = await ctx.agents.create({
+ sessionId: SessionId('identity-child'), parentAgent: lead,
+ meta: { parentSession: lead.id, origin: 'subagent' },
+ })
+ const nested = await ctx.agents.create({
+ sessionId: SessionId('identity-nested'), parentAgent: lead,
+ meta: { parentSession: child.agent.id, origin: 'subagent' },
+ })
+ lead.session.append('subagent/catalog', { version: 0, childId: child.agent.id, childCreatedAt: 1, mode: 'continuable', label: 'Child', name: 'child' })
+ child.agent.session.append('subagent/catalog', { version: 0, childId: nested.agent.id, childCreatedAt: 1, mode: 'continuable', label: 'Nested', name: 'nested' })
+ expect(renderContextSnapshot(await assembly(ctx, nested.agent))).toContain(teammateIdentity(lead))
+ expect(renderContextSnapshot(await assembly(ctx, nested.agent))).not.toContain(`Team led by ${JSON.stringify(ctx.subagents.nameOf(child.agent))}`)
+ })
+
+ it.each([undefined, 'in-history'] as const)('appends current Lead identity to a teammate fork with update mode %s', async (systemPromptUpdate) => {
+ const { ctx, lead, adapter } = await setup([textResponse('review done'), textResponse('lead notified'), textResponse('fork answer')])
+ if (systemPromptUpdate !== undefined) adapter.systemPromptUpdate = systemPromptUpdate
+ const teammateId = await spawn(ctx, lead, 'reviewer', 'Review the work')
+ await waitNoAgent(ctx, teammateId)
+ await using persisted = await ctx.sessionPersistence.open(teammateId, 'read')
+ const { events: seed } = await persisted.read()
+ const handle = await ctx.agents.create({
+ sessionId: SessionId('fork-from-teammate'),
+ seed,
+ inheritedEventCount: SessionLogOffset(seed.length),
+ meta: { parentSession: teammateId, isSeeded: true },
+ agentOptions: { provider: 'mock', model: 'mock' },
+ signal: SIGNAL,
+ })
+ try {
+ const inheritedHistory = structuredClone(handle.agent.session.deriveMessages())
+ await runTurn(handle.agent, 'Continue independently')
+ const original = serializeRequest(adapter.requests.find(request => request.sessionId === teammateId)!)
+ const forkRequest = adapter.requests.find(request => request.sessionId === handle.agent.id)!
+ const fork = serializeRequest(forkRequest)
+ expect(fork.tools).toEqual(original.tools)
+ expect(fork.messages.slice(0, original.messages.length)).toEqual(original.messages)
+ expect(forkRequest.messages.slice(0, inheritedHistory.length)).toEqual(inheritedHistory)
+ expect(runtimeContextText(forkRequest)).toContain(leadIdentity(handle.agent))
+ expect(handle.agent.session.snapshotEvents().slice(0, seed.length)).toEqual(seed)
+ } finally {
+ await handle.dispose()
+ }
+ })
+
+ it('restores compacted identity and does not repeat an unchanged retained snapshot', async () => {
+ const { ctx, lead, adapter } = await setup([
+ toolCallResponse('first-list', 'team_task_list', {}),
+ toolCallResponse('second-list', 'team_task_list', {}),
+ textResponse('done'),
+ ])
+ ctx.on('agent/pre-step', async ({ agent, step }, next) => {
+ if (step === 3) {
+ const identity = agent.session.snapshotEvents().find(event => event.type === 'user/message'
+ && event.data.source.kind === 'runtime-context')
+ if (identity === undefined) throw new Error('expected teammate runtime context')
+ agent.session.append('user/message', createUserMessage({
+ content: [{ type: 'text', text: 'Compacted earlier context.' }],
+ source: { kind: 'test-compaction' },
+ }), {
+ surfaceOp: { op: 'replace', startSeq: identity.seq, endSeq: identity.seq },
+ sourceEventSeqs: [identity.seq],
+ })
+ }
+ return next()
+ })
+ const childId = await spawn(ctx, lead, 'reviewer', 'Review the work')
+ await waitNoAgent(ctx, childId)
+ for (const request of adapter.requests.filter(request => request.sessionId === childId)) {
+ const snapshots = request.messages.filter(message => message.source?.kind === 'runtime-context')
+ expect(snapshots).toHaveLength(1)
+ expect(runtimeContextText(request)).toContain(teammateIdentity(lead))
+ }
+ await using persisted = await ctx.sessionPersistence.open(childId, 'read')
+ const { events } = await persisted.read()
+ expect(events.filter(event => event.type === 'user/message'
+ && event.data.source.kind === 'runtime-context')).toHaveLength(2)
+ })
+
+ it('keeps required Team identities when optional runtime context is suppressed', async () => {
+ const { ctx, lead, adapter } = await setup([textResponse('worker done')])
+ ctx.systemPrompt.suppressRuntimeContext()
+ const childId = await spawn(ctx, lead, 'reviewer', 'Review the work')
+ await waitNoAgent(ctx, childId)
+ expect(renderContextSnapshot(await assembly(ctx, lead))).toContain(leadIdentity(lead))
+ expect(runtimeContextText(adapter.requests[0]!)).toContain(teammateIdentity(lead))
+ })
+
+ it('keeps ordinary inbox waiting when the task plugin unloads', async () => {
+ const { ctx, lead, fiber } = await setup([])
+ await fiber.dispose()
+ lead.inject(createUserMessage({ content: [{ type: 'text', text: 'pending input' }], source: { kind: 'user' } }))
+ const result = await execute(ctx, lead, 'wait_agent', {})
+ expect(result.isError).toBe(false)
+ expect(JSON.parse(text(result))).toEqual({ timedOut: false })
+ expect(lead.inbox.nextStep).toHaveLength(1)
+ })
+
+ it('adapts task CAS operations and waits to canonical JSON', async () => {
+ const { ctx, lead } = await setup(['hang'])
+ const childId = await spawn(ctx, lead, 'json-worker', 'wait')
+ const child = await waitRunning(ctx, childId)
+
+ const created = await execute(ctx, lead, 'team_task_create', {
+ subject: 'tool task',
+ description: 'created through tool',
+ blocked_by: [],
+ write_scopes: ['src/team'],
+ })
+ // Every Team result reaches the model as compact JSON: indentation would
+ // spend tokens on every task and wait result without adding meaning.
+ expect(text(created)).toBe(JSON.stringify(JSON.parse(text(created))))
+ const task = JSON.parse(text(created)) as { id: string; revision: number }
+ const listed = await execute(ctx, child, 'team_task_list', { ready: true, limit: 1 })
+ expect(JSON.parse(text(listed))).toMatchObject({ tasks: [{ id: task.id, ready: true }] })
+ const read = await execute(ctx, child, 'team_task_get', { task_id: task.id })
+ expect(JSON.parse(text(read))).toMatchObject({ id: task.id, revision: 1 })
+ const claimed = await execute(ctx, child, 'team_task_update', {
+ task_id: task.id,
+ expected_revision: task.revision,
+ action: 'claim',
+ })
+ expect(JSON.parse(text(claimed))).toMatchObject({ status: 'in_progress', ownerName: ctx.subagents.nameOf(ctx.agents.get(childId)!) })
+ const stale = await execute(ctx, lead, 'team_task_update', {
+ task_id: task.id,
+ expected_revision: task.revision,
+ action: 'delete',
+ })
+ expect(stale.isError).toBe(true)
+ expect(text(stale)).toContain('stale team task')
+
+ lead.inbox.clear()
+ const { result: wait } = await startWait(ctx, lead)
+ const completed = await execute(ctx, child, 'team_task_update', {
+ task_id: task.id, expected_revision: 2, action: 'complete',
+ })
+ expect(completed.isError).toBe(false)
+ expect(JSON.parse(text(await wait))).toEqual({ timedOut: false })
+
+ await interrupt(ctx, lead, childId)
+ await waitNoAgent(ctx, childId)
+ })
+
+ it('adapts optional task filters, mutations, pagination, and default waiting', async () => {
+ const { ctx, lead } = await setup(['hang'])
+ const childId = await spawn(ctx, lead, 'fork-worker', 'stay active', 'fork')
+ await waitRunning(ctx, childId)
+
+ const firstResult = await execute(ctx, lead, 'team_task_create', {
+ subject: 'first', description: 'first task',
+ })
+ const secondResult = await execute(ctx, lead, 'team_task_create', {
+ subject: 'second', description: 'second task',
+ })
+ const first = JSON.parse(text(firstResult)) as { id: string; revision: number }
+ const second = JSON.parse(text(secondResult)) as { id: string; revision: number }
+ const claimed = await execute(ctx, lead, 'team_task_update', {
+ task_id: first.id, expected_revision: first.revision, action: 'claim',
+ })
+ const claim = JSON.parse(text(claimed)) as { revision: number }
+
+ expect(JSON.parse(text(await execute(ctx, lead, 'team_task_list', {
+ status: 'in_progress', owner: 'lead', cursor: 0, limit: 1,
+ })))).toMatchObject({ tasks: [{ id: first.id }] })
+ expect(JSON.parse(text(await execute(ctx, lead, 'team_task_list', {
+ owner: 'unowned', limit: 1,
+ })))).toMatchObject({ tasks: [{ id: second.id }] })
+ expect(JSON.parse(text(await execute(ctx, lead, 'team_task_list', {
+ cursor: 0, limit: 1,
+ })))).toMatchObject({ nextCursor: 1 })
+ expect(JSON.parse(text(await execute(ctx, lead, 'team_task_list', {
+ cursor: 1,
+ })))).not.toHaveProperty('nextCursor')
+ expect((await execute(ctx, lead, 'team_task_list', { cursor: -1 })).isError).toBe(true)
+ expect((await execute(ctx, lead, 'team_task_list', { limit: 101 })).isError).toBe(true)
+
+ const edited = await execute(ctx, lead, 'team_task_update', {
+ task_id: first.id,
+ expected_revision: claim.revision,
+ action: 'edit',
+ subject: 'edited',
+ description: 'edited description',
+ write_scopes: ['src/team'],
+ })
+ const edit = JSON.parse(text(edited)) as { revision: number }
+ const dependencies = await execute(ctx, lead, 'team_task_update', {
+ task_id: first.id,
+ expected_revision: edit.revision,
+ action: 'set_dependencies',
+ blocked_by: [second.id],
+ })
+ expect(dependencies.isError).toBe(false)
+ const dependency = JSON.parse(text(dependencies)) as { revision: number }
+ expect((await execute(ctx, lead, 'team_task_update', {
+ task_id: first.id,
+ expected_revision: dependency.revision,
+ action: 'reassign',
+ owner: ctx.subagents.nameOf(ctx.agents.get(childId)!),
+ })).isError).toBe(true)
+
+ const child = ctx.agents.get(childId)!
+ child.inbox.clear()
+ const { result: wait } = await startWait(ctx, child)
+ const wake = await execute(ctx, lead, 'team_task_create', { subject: 'wake', description: 'notify waiting child' })
+ expect(wake.isError).toBe(false)
+ expect(JSON.parse(text(await wait))).toEqual({ timedOut: false })
+
+ await interrupt(ctx, lead, childId)
+ await waitNoAgent(ctx, childId)
+ })
+
+ it('retains a settled task owner’s catalog name and rejects its legacy alias', async () => {
+ const { ctx, lead } = await setup([textResponse('done')])
+ const id = await spawn(ctx, lead, 'reviewer', 'review')
+ await waitNoAgent(ctx, id)
+ const [entry] = await ctx.subagents.listChildren(lead.id)
+ const task = await ctx.agentTeams.createTask(lead, { subject: 'Review', description: 'Review history' })
+ const updated = await execute(ctx, lead, 'team_task_update', {
+ task_id: task.id, expected_revision: task.revision, action: 'reassign', owner: `lead/${entry!.name}`,
+ })
+ expect(JSON.parse(text(updated))).toMatchObject({ ownerName: `lead/${entry!.name}` })
+ expect(JSON.parse(text(await execute(ctx, lead, 'team_task_list', {}))))
+ .toMatchObject({ tasks: [{ ownerName: `lead/${entry!.name}` }] })
+ expect((await execute(ctx, lead, 'team_task_update', {
+ task_id: task.id, expected_revision: 2, action: 'reassign', owner: `legacy:${id}`,
+ })).isError).toBe(true)
+ })
+
+ it('retains an uncataloged historical task owner as a legacy id', async () => {
+ const { ctx, lead } = await setup([])
+ const task = await ctx.agentTeams.createTask(lead, { subject: 'Review', description: 'Read old ownership' })
+ const { ready: _ready, writeScopeWarnings: _warnings, ...saved } = task
+ lead.session.append('team/task', {
+ version: 2, teamId: TeamId(lead.id),
+ task: { ...saved, revision: 2, ownerId: SessionId('missing-worker') },
+ })
+ expect(JSON.parse(text(await execute(ctx, lead, 'team_task_get', { task_id: task.id }))))
+ .toMatchObject({ ownerName: 'legacy:missing-worker' })
+ })
+
+ it.each([false, true])('rejects historical roster assignments without a readable continuable target (cataloged: %s)', async (cataloged) => {
+ const { ctx, lead } = await setup([])
+ const id = SessionId('historical-worker')
+ for (const phase of ['provisioning', 'active'] as const) lead.session.append('team/member', {
+ version: 2, teamId: TeamId(lead.id),
+ member: { id, name: 'old-name', description: 'historical member', provider: 'spawn', context: 'fresh', phase },
+ })
+ if (cataloged) lead.session.append('subagent/catalog', { version: 0, childId: id, childCreatedAt: 1, mode: 'continuable', label: 'Old child' })
+ const created = await ctx.agentTeams.createTask(lead, { subject: 'Review', description: 'Review history' })
+ expect((await execute(ctx, lead, 'team_task_update', {
+ task_id: created.id, expected_revision: created.revision, action: 'reassign',
+ owner: cataloged ? 'lead/legacy:historical-worker' : 'legacy:historical-worker',
+ })).isError).toBe(true)
+ expect((await execute(ctx, lead, 'send_message', { name: 'legacy:historical-worker', message: 'hello' })).isError).toBe(true)
+ expect((await execute(ctx, lead, 'team_task_update', {
+ task_id: created.id, expected_revision: 2, action: 'reassign', owner: 'legacy:missing',
+ })).isError).toBe(true)
+ })
+
+ it('removes and reinstalls every scoped registration across plugin HMR without stopping the child', async () => {
+ const { ctx, lead, fiber } = await setup(['hang'])
+ const childId = await spawn(ctx, lead, 'hmr-worker', 'wait')
+ const child = await waitRunning(ctx, childId)
+
+ await fiber.dispose()
+ for (const agent of [lead, child]) {
+ const assembled = await assembly(ctx, agent)
+ expect(teamTools(assembled)).toEqual([])
+ expect(assembled.contexts.some(context => context.name === 'team:identity')).toBe(false)
+ }
+ expect(ctx.agents.get(childId)).toBe(child)
+
+ const replacement = await ctx.plugin(toolTeam)
+ for (const agent of [lead, child]) {
+ const assembled = await assembly(ctx, agent)
+ expect(teamTools(assembled)).toEqual(TEAM_TOOLS)
+ expect(assembled.contexts.filter(context => context.name === 'team:identity')).toHaveLength(1)
+ expect(renderContextSnapshot(assembled)).toContain(agent === lead ? leadIdentity(lead) : teammateIdentity(lead))
+ }
+ expect(child.status).toBe('running')
+ await interrupt(ctx, lead, childId)
+ await waitNoAgent(ctx, childId)
+ await replacement.dispose()
+ })
+
+ it('installs tools once when the plugin activates between Session and Agent creation announcements', async () => {
+ const { ctx, lead, fiber } = await setup([])
+ await fiber.dispose()
+ const id = SessionId('install-during-publication')
+ const stop = ctx.on('session/created', (session) => {
+ if (session.id === id) toolTeam.apply(ctx)
+ })
+ try {
+ const child = await ctx.agents.create({
+ sessionId: id, parentAgent: lead, agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ expect(teamTools(await assembly(ctx, child.agent))).toEqual(TEAM_TOOLS)
+ const created = await execute(ctx, child.agent, 'team_task_create', {
+ subject: 'installed once', description: 'created during the publication overlap',
+ })
+ expect(created.isError).toBe(false)
+ expect(JSON.parse(text(created))).toMatchObject({ id: 'task-1', revision: 1 })
+ await child.dispose()
+ } finally {
+ stop()
+ }
+ })
+
+ it('ends every current wait in the committing tree without waking an unrelated tree', async () => {
+ const { ctx, lead, adapter } = await setup([])
+ const child = await ctx.agents.create({
+ sessionId: SessionId('waiting-child'), parentAgent: lead, agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ const unrelated = await ctx.agents.create({
+ sessionId: SessionId('unrelated-root'), agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ vi.useFakeTimers()
+ const first = await startWait(ctx, lead)
+ const second = await startWait(ctx, lead)
+ const descendant = await startWait(ctx, child.agent)
+ const separate = await startWait(ctx, unrelated.agent)
+ const committed = await execute(ctx, lead, 'team_task_create', { subject: 'committed', description: 'wake current waits' })
+ expect(committed.isError).toBe(false)
+ for (const result of await Promise.all([first.result, second.result, descendant.result])) {
+ expect(result).toMatchObject({ isError: false, value: { timedOut: false } })
+ }
+ expect(vi.getTimerCount()).toBe(1)
+ for (const agent of [lead, child.agent, unrelated.agent]) {
+ expect(agent.inbox.nextStep).toHaveLength(0)
+ expect(agent.inbox.nextTurn).toHaveLength(0)
+ expect(agent.status).toBe('idle')
+ }
+ expect(adapter.requests).toHaveLength(0)
+ const later = await startWait(ctx, lead)
+ await vi.advanceTimersByTimeAsync(10_000)
+ for (const result of await Promise.all([separate.result, later.result])) {
+ expect(result).toMatchObject({ isError: false, value: { timedOut: true } })
+ }
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
+ it('keeps waiting until a task flush succeeds and ignores a failed flush', async () => {
+ const { ctx, lead } = await setup([])
+ vi.useFakeTimers()
+ const flush = ctx.sessions.flush.bind(ctx.sessions)
+ const entered = Promise.withResolvers()
+ const release = Promise.withResolvers()
+ vi.spyOn(ctx.sessions, 'flush').mockImplementationOnce(async (session) => {
+ entered.resolve(undefined)
+ await release.promise
+ return await flush(session)
+ })
+ const waiting = await startWait(ctx, lead)
+ let returned = false
+ void waiting.result.then(() => { returned = true })
+ const creating = execute(ctx, lead, 'team_task_create', { subject: 'committed', description: 'wait for flush' })
+ try {
+ await entered.promise
+ await vi.advanceTimersByTimeAsync(9_999)
+ expect(returned).toBe(false)
+ } finally {
+ release.resolve(undefined)
+ expect((await creating).isError).toBe(false)
+ }
+ expect(await waiting.result).toMatchObject({ isError: false, value: { timedOut: false } })
+ const afterCommit = await startWait(ctx, lead)
+ vi.spyOn(ctx.sessions, 'flush').mockRejectedValueOnce(new Error('storage unavailable'))
+ const failed = await execute(ctx, lead, 'team_task_create', { subject: 'failed', description: 'flush fails' })
+ expect(failed.isError).toBe(true)
+ expect(text(failed)).toContain('task "task-2" revision 1 is visible, but persistence was not confirmed')
+ expect(text(failed)).toContain('read the task before retrying')
+ expect(ctx.agentTeams.listTasks(lead).map(task => task.subject)).toEqual(['committed', 'failed'])
+ await vi.advanceTimersByTimeAsync(10_000)
+ expect(await afterCommit.result).toMatchObject({ isError: false, value: { timedOut: true } })
+ })
+
+ it('rolls back partial scoped installation after a same-scope collision', async () => {
+ const { ctx, lead, fiber } = await setup([])
+ await fiber.dispose()
+ lead.ctx.tools.register(defineContentToolFixture({
+ name: 'team_task_create',
+ description: 'intentional collision',
+ parameters: {},
+ async execute() { return [{ type: 'text', text: 'collision' }] },
+ }))
+
+ await expect(ctx.plugin(toolTeam)).rejects.toThrow(/already registered/u)
+ const assembled = await assembly(ctx, lead)
+ expect(teamTools(assembled)).toEqual(['team_task_create'])
+ expect(assembled.contexts.some(context => context.name === 'team:identity')).toBe(false)
+ })
+
+ it('applies directly without configuration and rejects removed configuration keys', async () => {
+ const { ctx, lead, fiber } = await setup([])
+ await fiber.dispose()
+ for (const key of ['interrupt', 'freshProvider', 'forkProvider']) {
+ expect(() => { toolTeam.apply(ctx, { [key]: 'x' }) }).toThrow(`${key} is no longer supported`)
+ }
+ toolTeam.apply(ctx)
+ expect(teamTools(await assembly(ctx, lead))).toEqual(TEAM_TOOLS)
+ })
+
+ it('switches tools and guidance for one tree while preserving tasks and ordinary subagents', async () => {
+ const { ctx, lead } = await setup(['hang'], false)
+ const other = await ctx.agents.create({ sessionId: SessionId('other-root'), agentOptions: { provider: 'mock', model: 'mock' } })
+ const child = await waitRunning(ctx, await spawn(ctx, lead, 'ordinary-child', 'work'))
+ for (const agent of [lead, child, other.agent]) expect(teamTools(await assembly(ctx, agent))).toEqual([])
+ await ctx.agentTeams.setEnabled(lead, true)
+ for (const agent of [lead, child]) expect(teamTools(await assembly(ctx, agent))).toEqual(TEAM_TOOLS)
+ expect(teamTools(await assembly(ctx, other.agent))).toEqual([])
+ const task = await ctx.agentTeams.createTask(child, { subject: 'shared', description: 'retained' })
+ await ctx.agentTeams.setEnabled(lead, false)
+ for (const agent of [lead, child]) {
+ const built = await assembly(ctx, agent)
+ expect(teamTools(built)).toEqual([])
+ expect(renderPrompt(built)).not.toContain('A shared task board is available')
+ }
+ expect(ctx.agents.get(child.id)).toBe(child)
+ expect(() => ctx.agentTeams.listTasks(child)).toThrow('enable Agent Teams')
+ await ctx.agentTeams.setEnabled(lead, true)
+ expect(ctx.agentTeams.listTasks(lead)).toEqual([task])
+ await interrupt(ctx, lead, child.id)
+ await waitNoAgent(ctx, child.id)
+ await other.dispose()
+ })
+
+ it('keeps tools consistent with an appended selection if flushing fails, and permits retry', async () => {
+ const { ctx, lead } = await setup([], false)
+ const failure = new Error('storage unavailable')
+ vi.spyOn(ctx.sessions, 'flush').mockRejectedValueOnce(failure)
+ await expect(ctx.agentTeams.setEnabled(lead, true)).rejects.toBe(failure)
+ expect(teamTools(await assembly(ctx, lead))).toEqual(TEAM_TOOLS)
+ await ctx.agentTeams.setEnabled(lead, true)
+ expect(lead.session.ownEvents().filter(event => event.type === 'team/mode')).toHaveLength(1)
+ })
+
+ it('installs Team scope before a cold-resumed teammate request', async () => {
+ const { ctx, lead, adapter } = await setup([textResponse('first'), textResponse('lead received settlement'), 'hang'])
+ const childId = await spawn(ctx, lead, 'cold-worker', 'finish once')
+ await waitNoAgent(ctx, childId)
+ await vi.waitFor(() => {
+ expect(adapter.requests.filter(request => request.sessionId === lead.id)).toHaveLength(1)
+ })
+ await lead.whenIdle()
+
+ await ctx.subagents.sendMessage(lead, childId, [{ type: 'text', text: 'resume with Team scope' }], { signal: SIGNAL })
+ const resumed = await waitRunning(ctx, childId)
+ expect(teamTools(await assembly(ctx, resumed))).toEqual(TEAM_TOOLS)
+ expect(renderContextSnapshot(await assembly(ctx, resumed))).toContain(teammateIdentity(lead))
+ const childRequests = () => adapter.requests.filter(request => request.sessionId === childId)
+ await vi.waitFor(() => { expect(childRequests()).toHaveLength(2) })
+ const firstMessages = childRequests()[0]!.messages
+ expect(childRequests()[1]!.messages.slice(0, firstMessages.length)).toEqual(firstMessages)
+ await interrupt(ctx, lead, childId)
+ await waitNoAgent(ctx, childId)
+ })
+
+ it('keeps Team tools absent while an orphaned subagent continues ordinary work', async () => {
+ const { ctx, adapter } = await setup([
+ textResponse('child done'), textResponse('parent received settlement'), textResponse('independent work done'),
+ ])
+ const parent = await ctx.agents.create({
+ sessionId: SessionId('temporary-parent'),
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ const childId = await spawn(ctx, parent.agent, 'orphan', 'finish')
+ await waitNoAgent(ctx, childId)
+ await vi.waitFor(() => { expect(adapter.requests.filter(request => request.sessionId === parent.agent.id)).toHaveLength(1) })
+ await parent.agent.whenIdle()
+ await parent.dispose()
+ const orphan = await ctx.agents.resume({
+ resumeSessionId: childId,
+ agentOptions: { provider: 'mock', model: 'mock' },
+ })
+ const result = await execute(ctx, orphan.agent, 'team_task_list', {})
+ expect(result.isError).toBe(true)
+ expect(text(result)).toContain('unknown tool')
+ await runTurn(orphan.agent, 'continue ordinary work')
+ const request = adapter.requests.findLast(request => request.sessionId === childId)!
+ expect(teamTools(await assembly(ctx, orphan.agent))).toEqual([])
+ expect(runtimeContextText(request)).not.toContain('You are the Team Lead.')
+ expect(orphan.agent.session.ownEvents().some(event => event.type === 'assistant/message'
+ && event.data.message.content.some(block => block.type === 'text' && block.text === 'independent work done'))).toBe(true)
+ await orphan.dispose()
+ })
+
+ it.each([
+ new Error('root lookup failed'),
+ new SubagentError('root lookup failed', 'INTERNAL_FAILURE'),
+ ])('propagates unexpected identity lookup failures: %s', async (failure) => {
+ const { ctx, lead } = await setup([])
+ vi.spyOn(ctx.subagents, 'rootOf').mockImplementation(() => { throw failure })
+ await expect(assembly(ctx, lead)).rejects.toBe(failure)
+ await expect(ctx.agents.create({ sessionId: SessionId('lookup-failure'), agentOptions: { provider: 'mock', model: 'mock' } })).rejects.toBe(failure)
+ })
+
+ it('reports unavailable identity without inventing a parent id', async () => {
+ const { ctx, lead } = await setup([])
+ vi.spyOn(ctx.subagents, 'rootOf').mockImplementation(() => {
+ throw new SubagentError('Team root is unavailable', 'UNAUTHORIZED')
+ })
+ const context = renderContextSnapshot(await assembly(ctx, lead))
+ expect(context).toContain('Your Team root agent is unavailable. Continue independent work;')
+ expect(context).not.toContain('Your parent agent id')
+ })
+
+ it('fails safely without a calling Agent and has the function-plugin export shape', async () => {
+ const { ctx } = await setup([])
+ const result = await execute(ctx, undefined, 'team_task_list', {})
+ expect(result.isError).toBe(true)
+ expect(text(result)).toContain('unknown tool "team_task_list"')
+ expect('default' in toolTeam).toBe(false)
+ expect(toolTeam.name).toBe('tool-agent-team')
+ expect(toolTeam.inject).toEqual(['agents', 'agentTeams', 'subagents', 'tools', 'systemPrompt'])
+ })
+})
diff --git a/packages/subagent/tool-agent-team/tsconfig.json b/packages/subagent/tool-agent-team/tsconfig.json
new file mode 100644
index 0000000000..b2ed0b879e
--- /dev/null
+++ b/packages/subagent/tool-agent-team/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "rootDir": "src",
+ "outDir": "lib/types"
+ },
+ "include": ["src"],
+ "references": [
+ { "path": "../../../vendor/cosmokit" },
+ { "path": "../../../vendor/schemastery" },
+ { "path": "../../../vendor/cordis" },
+ { "path": "../../core/agent" },
+ { "path": "../../core/scope" },
+ { "path": "../../core/session" },
+ { "path": "../../core/system-prompt" },
+ { "path": "../../core/tools" },
+ { "path": "../subagent" },
+ { "path": "../agent-team" }
+ ]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 651fd058c5..c5bfbd18f2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -309,9 +309,6 @@ importers:
'@deepseek-ai/dsh-cordis-client-runner':
specifier: workspace:*
version: link:../../packages/extensions/cordis-client-runner
- '@deepseek-ai/dsh-experimental-agent-team-profile':
- specifier: workspace:*
- version: link:../../packages/experimental/agent-team-profile
'@deepseek-ai/dsh-experimental-auto-review':
specifier: workspace:*
version: link:../../packages/experimental/auto-review
@@ -526,6 +523,9 @@ importers:
'@deepseek-ai/dsh-agent-loop-testkit':
specifier: workspace:*
version: link:../../packages/test-support/agent-loop-testkit
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../../packages/subagent/agent-team
'@deepseek-ai/dsh-attachment-local':
specifier: workspace:*
version: link:../../packages/attachment/attachment-local
@@ -538,15 +538,9 @@ importers:
'@deepseek-ai/dsh-deepseek-llm-api-extensions':
specifier: workspace:*
version: link:../../packages/llm/deepseek-llm-api-extensions
- '@deepseek-ai/dsh-experimental-agent-team':
- specifier: workspace:*
- version: link:../../packages/experimental/agent-team
'@deepseek-ai/dsh-experimental-ptc-runtime-python':
specifier: workspace:*
version: link:../../packages/experimental/ptc-runtime-python
- '@deepseek-ai/dsh-experimental-tool-agent-team':
- specifier: workspace:*
- version: link:../../packages/experimental/tool-agent-team
'@deepseek-ai/dsh-fs-observation-policy':
specifier: workspace:*
version: link:../../packages/fs/fs-observation-policy
@@ -640,6 +634,9 @@ importers:
'@deepseek-ai/dsh-system-prompt':
specifier: workspace:*
version: link:../../packages/core/system-prompt
+ '@deepseek-ai/dsh-tool-agent-team':
+ specifier: workspace:*
+ version: link:../../packages/subagent/tool-agent-team
'@deepseek-ai/dsh-tool-ralph':
specifier: workspace:*
version: link:../../packages/experimental/tool-ralph
@@ -880,6 +877,9 @@ importers:
'@deepseek-ai/cordis-plugin-group':
specifier: workspace:~
version: link:../../vendor/group
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../../packages/subagent/agent-team
'@deepseek-ai/dsh-client-modules':
specifier: workspace:*
version: link:../../packages/client/modules
@@ -910,9 +910,6 @@ importers:
'@deepseek-ai/dsh-cmdline':
specifier: workspace:*
version: link:../../packages/boot/cmdline
- '@deepseek-ai/dsh-experimental-agent-team':
- specifier: workspace:*
- version: link:../../packages/experimental/agent-team
'@deepseek-ai/dsh-experimental-auto-review':
specifier: workspace:*
version: link:../../packages/experimental/auto-review
@@ -2232,6 +2229,9 @@ importers:
'@deepseek-ai/dsh-agent-loop':
specifier: workspace:*
version: link:../../core/agent-loop
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../../subagent/agent-team
'@deepseek-ai/dsh-api-gateway':
specifier: workspace:*
version: link:../../api/gateway
@@ -2424,6 +2424,9 @@ importers:
'@deepseek-ai/dsh-token-meter':
specifier: workspace:*
version: link:../../llm/token-meter
+ '@deepseek-ai/dsh-tool-agent-team':
+ specifier: workspace:*
+ version: link:../../subagent/tool-agent-team
'@deepseek-ai/dsh-tool-bash':
specifier: workspace:*
version: link:../../shell/tool-bash
@@ -2776,6 +2779,9 @@ importers:
'@deepseek-ai/dsh-client-ui-agent-preset':
specifier: workspace:*
version: link:../../client/ui-agent-preset
+ '@deepseek-ai/dsh-client-ui-agent-team':
+ specifier: workspace:*
+ version: link:../../client/ui-agent-team
'@deepseek-ai/dsh-client-ui-approval':
specifier: workspace:*
version: link:../../client/ui-approval
@@ -3486,6 +3492,63 @@ importers:
specifier: ^18.2.0
version: 18.3.1
+ packages/client/ui-agent-team:
+ devDependencies:
+ '@deepseek-ai/cordis':
+ specifier: workspace:~
+ version: link:../../../vendor/cordis
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../../subagent/agent-team
+ '@deepseek-ai/dsh-api-remotes':
+ specifier: workspace:*
+ version: link:../../api/remotes
+ '@deepseek-ai/dsh-api-session-controller':
+ specifier: workspace:*
+ version: link:../../api/session-controller
+ '@deepseek-ai/dsh-client-locale':
+ specifier: workspace:*
+ version: link:../locale
+ '@deepseek-ai/dsh-client-store':
+ specifier: workspace:*
+ version: link:../store
+ '@deepseek-ai/dsh-client-test-runtime':
+ specifier: workspace:*
+ version: link:../../test-support/client-runtime
+ '@deepseek-ai/dsh-client-ui-conversation':
+ specifier: workspace:*
+ version: link:../ui-conversation
+ '@deepseek-ai/dsh-client-ui-model-selection':
+ specifier: workspace:*
+ version: link:../ui-model-selection
+ '@deepseek-ai/dsh-client-ui-primitives':
+ specifier: workspace:*
+ version: link:../ui-primitives
+ '@deepseek-ai/dsh-client-ui-renderer':
+ specifier: workspace:*
+ version: link:../ui-renderer
+ '@deepseek-ai/dsh-client-ui-slots':
+ specifier: workspace:*
+ version: link:../ui-slots
+ '@deepseek-ai/dsh-client-ui-subagent':
+ specifier: workspace:*
+ version: link:../ui-subagent
+ '@deepseek-ai/dsh-commands':
+ specifier: workspace:*
+ version: link:../../interaction/commands
+ '@deepseek-ai/dsh-session':
+ specifier: workspace:*
+ version: link:../../core/session
+ '@testing-library/react':
+ specifier: ^16.3.3
+ version: 16.3.3(@testing-library/dom@10.4.2)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+ react:
+ specifier: ^18.2.0
+ version: 18.3.1
+ react-dom:
+ specifier: ^18.2.0
+ version: 18.3.1(react@18.3.1)
+
packages/client/ui-approval:
devDependencies:
'@deepseek-ai/cordis':
@@ -6089,6 +6152,9 @@ importers:
'@deepseek-ai/cordis':
specifier: workspace:~
version: link:../../../vendor/cordis
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../../subagent/agent-team
'@deepseek-ai/dsh-api-session-controller':
specifier: workspace:*
version: link:../../api/session-controller
@@ -7601,80 +7667,6 @@ importers:
specifier: workspace:*
version: link:../../core/session
- packages/experimental/agent-team:
- dependencies:
- '@deepseek-ai/dsh-brand':
- specifier: workspace:*
- version: link:../../util/brand
- '@deepseek-ai/schemastery':
- specifier: link:../../../vendor/schemastery
- version: link:../../../vendor/schemastery
- zod:
- specifier: 4.4.3
- version: 4.4.3
- devDependencies:
- '@deepseek-ai/cordis':
- specifier: workspace:~
- version: link:../../../vendor/cordis
- '@deepseek-ai/dsh-agent':
- specifier: workspace:*
- version: link:../../core/agent
- '@deepseek-ai/dsh-agent-loop':
- specifier: workspace:*
- version: link:../../core/agent-loop
- '@deepseek-ai/dsh-agent-loop-testkit':
- specifier: workspace:*
- version: link:../../test-support/agent-loop-testkit
- '@deepseek-ai/dsh-commands':
- specifier: workspace:*
- version: link:../../interaction/commands
- '@deepseek-ai/dsh-llm':
- specifier: workspace:*
- version: link:../../llm/llm
- '@deepseek-ai/dsh-session':
- specifier: workspace:*
- version: link:../../core/session
- '@deepseek-ai/dsh-session-persistence-jsonl':
- specifier: workspace:*
- version: link:../../session/session-persistence-jsonl
- '@deepseek-ai/dsh-session-projection':
- specifier: workspace:*
- version: link:../../session/session-projection
- '@deepseek-ai/dsh-session-query':
- specifier: workspace:*
- version: link:../../session-query/session-query
- '@deepseek-ai/dsh-subagent':
- specifier: workspace:*
- version: link:../../subagent/subagent
- '@deepseek-ai/dsh-subagent-fork-in-process':
- specifier: workspace:*
- version: link:../../subagent/subagent-fork-in-process
- '@deepseek-ai/dsh-subagent-spawn-in-process':
- specifier: workspace:*
- version: link:../../subagent/subagent-spawn-in-process
-
- packages/experimental/agent-team-profile:
- dependencies:
- '@deepseek-ai/dsh-experimental-agent-team':
- specifier: workspace:*
- version: link:../agent-team
- '@deepseek-ai/dsh-experimental-client-ui-agent-team':
- specifier: workspace:*
- version: link:../client-ui-agent-team
- '@deepseek-ai/dsh-experimental-tool-agent-team':
- specifier: workspace:*
- version: link:../tool-agent-team
- devDependencies:
- '@deepseek-ai/cordis':
- specifier: workspace:~
- version: link:../../../vendor/cordis
- '@deepseek-ai/cordis-plugin-include':
- specifier: workspace:~
- version: link:../../../vendor/include
- js-yaml:
- specifier: ^4.3.2
- version: 4.3.2
-
packages/experimental/api-speech-to-text:
dependencies:
'@deepseek-ai/schemastery':
@@ -8127,60 +8119,6 @@ importers:
specifier: workspace:*
version: link:../../session/working-directory
- packages/experimental/client-ui-agent-team:
- devDependencies:
- '@deepseek-ai/cordis':
- specifier: workspace:~
- version: link:../../../vendor/cordis
- '@deepseek-ai/dsh-api-remotes':
- specifier: workspace:*
- version: link:../../api/remotes
- '@deepseek-ai/dsh-api-session-controller':
- specifier: workspace:*
- version: link:../../api/session-controller
- '@deepseek-ai/dsh-client-locale':
- specifier: workspace:*
- version: link:../../client/locale
- '@deepseek-ai/dsh-client-store':
- specifier: workspace:*
- version: link:../../client/store
- '@deepseek-ai/dsh-client-test-runtime':
- specifier: workspace:*
- version: link:../../test-support/client-runtime
- '@deepseek-ai/dsh-client-ui-conversation':
- specifier: workspace:*
- version: link:../../client/ui-conversation
- '@deepseek-ai/dsh-client-ui-model-selection':
- specifier: workspace:*
- version: link:../../client/ui-model-selection
- '@deepseek-ai/dsh-client-ui-primitives':
- specifier: workspace:*
- version: link:../../client/ui-primitives
- '@deepseek-ai/dsh-client-ui-renderer':
- specifier: workspace:*
- version: link:../../client/ui-renderer
- '@deepseek-ai/dsh-client-ui-slots':
- specifier: workspace:*
- version: link:../../client/ui-slots
- '@deepseek-ai/dsh-commands':
- specifier: workspace:*
- version: link:../../interaction/commands
- '@deepseek-ai/dsh-experimental-agent-team':
- specifier: workspace:*
- version: link:../agent-team
- '@deepseek-ai/dsh-session':
- specifier: workspace:*
- version: link:../../core/session
- '@testing-library/react':
- specifier: ^16.3.3
- version: 16.3.3(@testing-library/dom@10.4.2)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
- react:
- specifier: ^18.2.0
- version: 18.3.1
- react-dom:
- specifier: ^18.2.0
- version: 18.3.1(react@18.3.1)
-
packages/experimental/client-ui-claude-code-mods:
devDependencies:
'@deepseek-ai/cordis':
@@ -9275,67 +9213,6 @@ importers:
specifier: workspace:~
version: link:../../../vendor/cordis
- packages/experimental/tool-agent-team:
- dependencies:
- '@deepseek-ai/schemastery':
- specifier: link:../../../vendor/schemastery
- version: link:../../../vendor/schemastery
- devDependencies:
- '@deepseek-ai/cordis':
- specifier: workspace:~
- version: link:../../../vendor/cordis
- '@deepseek-ai/dsh-agent':
- specifier: workspace:*
- version: link:../../core/agent
- '@deepseek-ai/dsh-agent-loop':
- specifier: workspace:*
- version: link:../../core/agent-loop
- '@deepseek-ai/dsh-agent-loop-testkit':
- specifier: workspace:*
- version: link:../../test-support/agent-loop-testkit
- '@deepseek-ai/dsh-experimental-agent-team':
- specifier: workspace:*
- version: link:../agent-team
- '@deepseek-ai/dsh-llm':
- specifier: workspace:*
- version: link:../../llm/llm
- '@deepseek-ai/dsh-llm-deepseek':
- specifier: workspace:*
- version: link:../../llm/llm-deepseek
- '@deepseek-ai/dsh-scope':
- specifier: workspace:*
- version: link:../../core/scope
- '@deepseek-ai/dsh-session':
- specifier: workspace:*
- version: link:../../core/session
- '@deepseek-ai/dsh-session-persistence-jsonl':
- specifier: workspace:*
- version: link:../../session/session-persistence-jsonl
- '@deepseek-ai/dsh-session-projection':
- specifier: workspace:*
- version: link:../../session/session-projection
- '@deepseek-ai/dsh-session-query':
- specifier: workspace:*
- version: link:../../session-query/session-query
- '@deepseek-ai/dsh-subagent':
- specifier: workspace:*
- version: link:../../subagent/subagent
- '@deepseek-ai/dsh-subagent-fork-in-process':
- specifier: workspace:*
- version: link:../../subagent/subagent-fork-in-process
- '@deepseek-ai/dsh-subagent-spawn-in-process':
- specifier: workspace:*
- version: link:../../subagent/subagent-spawn-in-process
- '@deepseek-ai/dsh-system-prompt':
- specifier: workspace:*
- version: link:../../core/system-prompt
- '@deepseek-ai/dsh-tool-subagent-control':
- specifier: workspace:*
- version: link:../../subagent/tool-subagent-control
- '@deepseek-ai/dsh-tools':
- specifier: workspace:*
- version: link:../../core/tools
-
packages/experimental/tool-ralph:
dependencies:
'@deepseek-ai/schemastery':
@@ -13986,6 +13863,58 @@ importers:
specifier: workspace:*
version: link:../storage
+ packages/subagent/agent-team:
+ dependencies:
+ '@deepseek-ai/dsh-brand':
+ specifier: workspace:*
+ version: link:../../util/brand
+ '@deepseek-ai/schemastery':
+ specifier: link:../../../vendor/schemastery
+ version: link:../../../vendor/schemastery
+ zod:
+ specifier: 4.4.3
+ version: 4.4.3
+ devDependencies:
+ '@deepseek-ai/cordis':
+ specifier: workspace:~
+ version: link:../../../vendor/cordis
+ '@deepseek-ai/dsh-agent':
+ specifier: workspace:*
+ version: link:../../core/agent
+ '@deepseek-ai/dsh-agent-loop':
+ specifier: workspace:*
+ version: link:../../core/agent-loop
+ '@deepseek-ai/dsh-agent-loop-testkit':
+ specifier: workspace:*
+ version: link:../../test-support/agent-loop-testkit
+ '@deepseek-ai/dsh-commands':
+ specifier: workspace:*
+ version: link:../../interaction/commands
+ '@deepseek-ai/dsh-llm':
+ specifier: workspace:*
+ version: link:../../llm/llm
+ '@deepseek-ai/dsh-session':
+ specifier: workspace:*
+ version: link:../../core/session
+ '@deepseek-ai/dsh-session-persistence-jsonl':
+ specifier: workspace:*
+ version: link:../../session/session-persistence-jsonl
+ '@deepseek-ai/dsh-session-projection':
+ specifier: workspace:*
+ version: link:../../session/session-projection
+ '@deepseek-ai/dsh-session-query':
+ specifier: workspace:*
+ version: link:../../session-query/session-query
+ '@deepseek-ai/dsh-subagent':
+ specifier: workspace:*
+ version: link:../subagent
+ '@deepseek-ai/dsh-subagent-fork-in-process':
+ specifier: workspace:*
+ version: link:../subagent-fork-in-process
+ '@deepseek-ai/dsh-subagent-spawn-in-process':
+ specifier: workspace:*
+ version: link:../subagent-spawn-in-process
+
packages/subagent/subagent:
dependencies:
'@deepseek-ai/dsh-brand':
@@ -14449,6 +14378,67 @@ importers:
specifier: workspace:*
version: link:../tool-subagent
+ packages/subagent/tool-agent-team:
+ dependencies:
+ '@deepseek-ai/schemastery':
+ specifier: link:../../../vendor/schemastery
+ version: link:../../../vendor/schemastery
+ devDependencies:
+ '@deepseek-ai/cordis':
+ specifier: workspace:~
+ version: link:../../../vendor/cordis
+ '@deepseek-ai/dsh-agent':
+ specifier: workspace:*
+ version: link:../../core/agent
+ '@deepseek-ai/dsh-agent-loop':
+ specifier: workspace:*
+ version: link:../../core/agent-loop
+ '@deepseek-ai/dsh-agent-loop-testkit':
+ specifier: workspace:*
+ version: link:../../test-support/agent-loop-testkit
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../agent-team
+ '@deepseek-ai/dsh-llm':
+ specifier: workspace:*
+ version: link:../../llm/llm
+ '@deepseek-ai/dsh-llm-deepseek':
+ specifier: workspace:*
+ version: link:../../llm/llm-deepseek
+ '@deepseek-ai/dsh-scope':
+ specifier: workspace:*
+ version: link:../../core/scope
+ '@deepseek-ai/dsh-session':
+ specifier: workspace:*
+ version: link:../../core/session
+ '@deepseek-ai/dsh-session-persistence-jsonl':
+ specifier: workspace:*
+ version: link:../../session/session-persistence-jsonl
+ '@deepseek-ai/dsh-session-projection':
+ specifier: workspace:*
+ version: link:../../session/session-projection
+ '@deepseek-ai/dsh-session-query':
+ specifier: workspace:*
+ version: link:../../session-query/session-query
+ '@deepseek-ai/dsh-subagent':
+ specifier: workspace:*
+ version: link:../subagent
+ '@deepseek-ai/dsh-subagent-fork-in-process':
+ specifier: workspace:*
+ version: link:../subagent-fork-in-process
+ '@deepseek-ai/dsh-subagent-spawn-in-process':
+ specifier: workspace:*
+ version: link:../subagent-spawn-in-process
+ '@deepseek-ai/dsh-system-prompt':
+ specifier: workspace:*
+ version: link:../../core/system-prompt
+ '@deepseek-ai/dsh-tool-subagent-control':
+ specifier: workspace:*
+ version: link:../tool-subagent-control
+ '@deepseek-ai/dsh-tools':
+ specifier: workspace:*
+ version: link:../../core/tools
+
packages/subagent/tool-subagent:
dependencies:
'@deepseek-ai/schemastery':
@@ -15696,6 +15686,9 @@ importers:
'@deepseek-ai/dsh-agent-preset-registry':
specifier: workspace:*
version: link:../../packages/preset/agent-preset-registry
+ '@deepseek-ai/dsh-agent-team':
+ specifier: workspace:*
+ version: link:../../packages/subagent/agent-team
'@deepseek-ai/dsh-agent-tool-presentation':
specifier: workspace:*
version: link:../../packages/core/agent-tool-presentation
@@ -16002,6 +15995,9 @@ importers:
'@deepseek-ai/dsh-token-meter':
specifier: workspace:*
version: link:../../packages/llm/token-meter
+ '@deepseek-ai/dsh-tool-agent-team':
+ specifier: workspace:*
+ version: link:../../packages/subagent/tool-agent-team
'@deepseek-ai/dsh-tool-ask-user':
specifier: workspace:*
version: link:../../packages/interaction/tool-ask-user
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index 19f2de7e0c..6cfbbc5039 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -18,6 +18,7 @@
"@deepseek-ai/dsh-agent-instructions": "workspace:*",
"@deepseek-ai/dsh-agent-loop": "workspace:*",
"@deepseek-ai/dsh-agent-preset-registry": "workspace:*",
+ "@deepseek-ai/dsh-agent-team": "workspace:*",
"@deepseek-ai/dsh-agent-tool-presentation": "workspace:*",
"@deepseek-ai/dsh-anonymous-user-id": "workspace:*",
"@deepseek-ai/dsh-api-gateway": "workspace:*",
@@ -32,13 +33,8 @@
"@deepseek-ai/dsh-client-connection": "workspace:*",
"@deepseek-ai/dsh-client-file-upload": "workspace:*",
"@deepseek-ai/dsh-cmdline": "workspace:*",
- "@deepseek-ai/dsh-command-feedback": "workspace:*",
- "@deepseek-ai/dsh-file-reference": "workspace:*",
- "@deepseek-ai/dsh-message-feedback": "workspace:*",
- "@deepseek-ai/dsh-native-command": "workspace:*",
- "@deepseek-ai/dsh-ptc-runtime": "workspace:*",
- "@deepseek-ai/dsh-ptc-runtime-node": "workspace:*",
"@deepseek-ai/dsh-command-compact": "workspace:*",
+ "@deepseek-ai/dsh-command-feedback": "workspace:*",
"@deepseek-ai/dsh-command-goal": "workspace:*",
"@deepseek-ai/dsh-commands": "workspace:*",
"@deepseek-ai/dsh-compaction": "workspace:*",
@@ -50,6 +46,7 @@
"@deepseek-ai/dsh-credentials": "workspace:*",
"@deepseek-ai/dsh-deepseek-account": "workspace:*",
"@deepseek-ai/dsh-deepseek-llm-api-extensions": "workspace:*",
+ "@deepseek-ai/dsh-file-reference": "workspace:*",
"@deepseek-ai/dsh-fs": "workspace:*",
"@deepseek-ai/dsh-fs-local": "workspace:*",
"@deepseek-ai/dsh-fs-observation-policy": "workspace:*",
@@ -65,11 +62,14 @@
"@deepseek-ai/dsh-launch-environment": "workspace:*",
"@deepseek-ai/dsh-llm": "workspace:*",
"@deepseek-ai/dsh-llm-deepseek": "workspace:*",
- "@deepseek-ai/dsh-llm-deepseek-api-key": "workspace:*",
"@deepseek-ai/dsh-llm-deepseek-account": "workspace:*",
+ "@deepseek-ai/dsh-llm-deepseek-api-key": "workspace:*",
"@deepseek-ai/dsh-llm-pi-ai": "workspace:*",
"@deepseek-ai/dsh-llm-retry": "workspace:*",
"@deepseek-ai/dsh-mcp-client": "workspace:*",
+ "@deepseek-ai/dsh-message-feedback": "workspace:*",
+ "@deepseek-ai/dsh-native-command": "workspace:*",
+ "@deepseek-ai/dsh-otel": "workspace:*",
"@deepseek-ai/dsh-output-retention": "workspace:*",
"@deepseek-ai/dsh-permission-presets": "workspace:*",
"@deepseek-ai/dsh-persona": "workspace:*",
@@ -77,6 +77,8 @@
"@deepseek-ai/dsh-plugin-manager": "workspace:*",
"@deepseek-ai/dsh-plugin-market": "workspace:*",
"@deepseek-ai/dsh-plugin-package-inventory-deepseek": "workspace:*",
+ "@deepseek-ai/dsh-ptc-runtime": "workspace:*",
+ "@deepseek-ai/dsh-ptc-runtime-node": "workspace:*",
"@deepseek-ai/dsh-pwsh-local": "workspace:*",
"@deepseek-ai/dsh-repeat-tool-reminder": "workspace:*",
"@deepseek-ai/dsh-sandbox": "workspace:*",
@@ -104,11 +106,9 @@
"@deepseek-ai/dsh-skill": "workspace:*",
"@deepseek-ai/dsh-skill-filesystem": "workspace:*",
"@deepseek-ai/dsh-skill-office": "workspace:*",
+ "@deepseek-ai/dsh-spill": "workspace:*",
"@deepseek-ai/dsh-storage": "workspace:*",
"@deepseek-ai/dsh-storage-domain": "workspace:*",
- "@deepseek-ai/dsh-tool-schedule": "workspace:*",
- "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:*",
- "@deepseek-ai/dsh-spill": "workspace:*",
"@deepseek-ai/dsh-subagent": "workspace:*",
"@deepseek-ai/dsh-subagent-acp": "workspace:*",
"@deepseek-ai/dsh-subagent-fork-in-process": "workspace:*",
@@ -121,6 +121,7 @@
"@deepseek-ai/dsh-time-context": "workspace:*",
"@deepseek-ai/dsh-timeout": "workspace:*",
"@deepseek-ai/dsh-token-meter": "workspace:*",
+ "@deepseek-ai/dsh-tool-agent-team": "workspace:*",
"@deepseek-ai/dsh-tool-ask-user": "workspace:*",
"@deepseek-ai/dsh-tool-bash": "workspace:*",
"@deepseek-ai/dsh-tool-bash-persistent": "workspace:*",
@@ -133,6 +134,7 @@
"@deepseek-ai/dsh-tool-present": "workspace:*",
"@deepseek-ai/dsh-tool-pwsh": "workspace:*",
"@deepseek-ai/dsh-tool-pwsh-persistent": "workspace:*",
+ "@deepseek-ai/dsh-tool-schedule": "workspace:*",
"@deepseek-ai/dsh-tool-skill": "workspace:*",
"@deepseek-ai/dsh-tool-str-replace-editor": "workspace:*",
"@deepseek-ai/dsh-tool-subagent": "workspace:*",
@@ -140,6 +142,8 @@
"@deepseek-ai/dsh-tool-todo": "workspace:*",
"@deepseek-ai/dsh-tool-web": "workspace:*",
"@deepseek-ai/dsh-tool-workflow": "workspace:*",
+ "@deepseek-ai/dsh-tool-working-directory": "workspace:*",
+ "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:*",
"@deepseek-ai/dsh-tools": "workspace:*",
"@deepseek-ai/dsh-typert-protocol": "workspace:*",
"@deepseek-ai/dsh-typert-registry": "workspace:*",
@@ -155,10 +159,8 @@
"@deepseek-ai/dsh-web-search-perplexity": "workspace:*",
"@deepseek-ai/dsh-workflow": "workspace:*",
"@deepseek-ai/dsh-workflow-ptc": "workspace:*",
- "@deepseek-ai/dsh-otel": "workspace:*",
+ "@deepseek-ai/dsh-working-directory": "workspace:*",
"@deepseek-ai/dsh-workspace": "workspace:*",
- "@deepseek-ai/schemastery": "workspace:~",
- "@deepseek-ai/dsh-tool-working-directory": "workspace:*",
- "@deepseek-ai/dsh-working-directory": "workspace:*"
+ "@deepseek-ai/schemastery": "workspace:~"
}
}
diff --git a/scripts/check-workspace-constraints.spec.ts b/scripts/check-workspace-constraints.spec.ts
index 87a04010ba..4086b5c57a 100644
--- a/scripts/check-workspace-constraints.spec.ts
+++ b/scripts/check-workspace-constraints.spec.ts
@@ -306,8 +306,8 @@ describe('package payload constraints', () => {
])
})
- it('accepts the Agent Team icon payload and rejects its omission', () => {
- const dir = 'packages/experimental/agent-team-profile'
+ it('accepts the Voice Input icon payload and rejects its omission', () => {
+ const dir = 'packages/experimental/voice-input-bundle'
const manifest = JSON.parse(readFileSync(new URL(`../${dir}/package.json`, import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
expect(checkWorkspaceManifest({ dir, manifest })).toEqual([])
expect(checkWorkspaceManifest({ dir, manifest: { ...manifest, files: manifest.files!.filter(file => file !== 'icon.svg') } }))
@@ -339,9 +339,9 @@ describe('package payload constraints', () => {
})).toEqual(['lib/index.js', 'lib/types/**/*.d.ts'])
})
- it.each(['agent-team', 'agent-team-profile', 'auto-review', 'client-ui-agent-team', 'tool-agent-team'])(
+ it.each(['subagent/agent-team', 'experimental/voice-input-bundle', 'experimental/auto-review', 'client/ui-agent-team', 'subagent/tool-agent-team'])(
'accepts the published locale files for %s and rejects their omission', (name) => {
- const dir = `packages/experimental/${name}`
+ const dir = `packages/${name}`
const manifest = JSON.parse(readFileSync(new URL(`../${dir}/package.json`, import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
expect(checkWorkspaceManifest({ dir, manifest })).toEqual([])
expect(checkWorkspaceManifest({ dir, manifest: {
diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts
index 5a36e9fc83..603fd0c38b 100644
--- a/scripts/client-bundle-purity.spec.ts
+++ b/scripts/client-bundle-purity.spec.ts
@@ -285,8 +285,8 @@ describe('client bundle purity gate', () => {
})
describe('client bundle experimental input isolation', () => {
- const experimental = '@deepseek-ai/dsh-experimental-client-ui-agent-team'
- const experimentalDir = packageDir('experimental/client-ui-agent-team')
+ const experimental = '@deepseek-ai/dsh-experimental-client-ui-voice-input'
+ const experimentalDir = packageDir('experimental/client-ui-voice-input')
function fixture() {
const root = mkdtempSync(join(tmpdir(), 'dsh-client-inputs-'))
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index bdaed476cb..99f7f6e9b0 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -792,10 +792,10 @@ const SERVICE_ROLES: ServiceRole[] = [
},
{
key: 'agentTeams',
- pkg: 'experimental-agent-team',
+ pkg: 'agent-team',
title: 'Agent Teams coordination domain',
mode: 'core',
- consumers: ['experimental-tool-agent-team'],
+ consumers: ['tool-agent-team'],
note: 'Owns the shared task DAG and wait signals for a subagent tree; tool-agent-team contributes task controls.',
},
{
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 78f730d29a..a4e80fffc2 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -64,8 +64,8 @@ import * as ToolSessionQuery from '@deepseek-ai/dsh-tool-session-query'
import * as ToolJobs from '@deepseek-ai/dsh-tool-jobs'
import BrowserUseRegistry from '@deepseek-ai/dsh-browser-use'
import * as StagehandBrowserTools from '@deepseek-ai/dsh-experimental-browser-use-stagehand-native'
-import TeamService from '@deepseek-ai/dsh-experimental-agent-team'
-import * as ToolTeam from '@deepseek-ai/dsh-experimental-tool-agent-team'
+import TeamService from '@deepseek-ai/dsh-agent-team'
+import * as ToolTeam from '@deepseek-ai/dsh-tool-agent-team'
import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
import type PluginManager from '@deepseek-ai/dsh-plugin-manager'
import * as PluginManagerTools from '@deepseek-ai/dsh-plugin-manager/tools'
@@ -588,9 +588,9 @@ const TOOL_PACKAGES: ToolPackage[] = [
'The kind-agnostic background-job controller: background bash commands and PTY sends are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers\' `ctx.jobs.start()`.',
},
{
- pkg: '@deepseek-ai/dsh-experimental-tool-agent-team',
+ pkg: '@deepseek-ai/dsh-tool-agent-team',
dir: 'tool-agent-team',
- source: 'packages/experimental/tool-agent-team/src/index.ts',
+ source: 'packages/subagent/tool-agent-team/src/index.ts',
requires: ['ctx.tools', 'ctx.systemPrompt', 'ctx.agentTeams', 'ctx.subagents', 'an exact live Team member Agent'],
writes: ['tool/call', 'team/task', 'tool/result'],
async mount(ctx) {
diff --git a/scripts/no-unknown-casts.baseline.json b/scripts/no-unknown-casts.baseline.json
index 838047b182..1849b78bed 100644
--- a/scripts/no-unknown-casts.baseline.json
+++ b/scripts/no-unknown-casts.baseline.json
@@ -1013,7 +1013,7 @@
"packages/document/office-to-pdf/tests/queue.spec.ts": {
"bbe31b89b81048bb47c7158e78670deec5f2973286f9abc591290a8fdd851cf1": 1
},
- "packages/experimental/agent-team/tests/projection-events.spec.ts": {
+ "packages/subagent/agent-team/tests/projection-events.spec.ts": {
"71ffbcca0bb71d3b595143632491d4c5d580aaf6ac384c22116e038995b2f2b5": 1,
"a66c8967969859328890e6049a0bd9e90403861eb19ed5d6937da5505aa79c05": 1,
"bd3a42d7bc38a7deb366d7ad1364f2ab01be2af077aae04e49b9c8a61b9e1c7d": 1,
diff --git a/scripts/npm-baseline-packages.spec.ts b/scripts/npm-baseline-packages.spec.ts
index c79595e8d9..ed6cd4f368 100644
--- a/scripts/npm-baseline-packages.spec.ts
+++ b/scripts/npm-baseline-packages.spec.ts
@@ -23,8 +23,8 @@ describe('npm baseline package discovery', () => {
const expected = [
'apps/cli/package.json',
'packages/core/session/package.json',
- 'packages/experimental/agent-team/package.json',
'packages/experimental/new-prototype/package.json',
+ 'packages/subagent/agent-team/package.json',
'vendor/cordis/package.json',
]
const root = fixture([
diff --git a/scripts/release/families.spec.ts b/scripts/release/families.spec.ts
index 4a6a12c0a0..f4c09d60c7 100644
--- a/scripts/release/families.spec.ts
+++ b/scripts/release/families.spec.ts
@@ -49,8 +49,6 @@ describe('release families', () => {
expect(members
.filter(member => member.directory.startsWith('packages/experimental/'))
.map(member => member.name)).toEqual([
- '@deepseek-ai/dsh-experimental-agent-team-profile',
- '@deepseek-ai/dsh-experimental-agent-team',
'@deepseek-ai/dsh-experimental-api-speech-to-text',
'@deepseek-ai/dsh-experimental-auto-review',
'@deepseek-ai/dsh-experimental-badge-skill-bundle',
@@ -59,7 +57,6 @@ describe('release families', () => {
'@deepseek-ai/dsh-experimental-browser-use-runtime',
'@deepseek-ai/dsh-experimental-browser-use-stagehand-native',
'@deepseek-ai/dsh-experimental-claude-code-mods',
- '@deepseek-ai/dsh-experimental-client-ui-agent-team',
'@deepseek-ai/dsh-experimental-client-ui-claude-code-mods',
'@deepseek-ai/dsh-experimental-client-ui-cot-translation',
'@deepseek-ai/dsh-experimental-client-ui-voice-input',
@@ -85,7 +82,6 @@ describe('release families', () => {
'@deepseek-ai/dsh-experimental-speech-to-text',
'@deepseek-ai/dsh-experimental-subagent-oar',
'@deepseek-ai/dsh-experimental-terminal-bundle',
- '@deepseek-ai/dsh-experimental-tool-agent-team',
'@deepseek-ai/dsh-tool-ralph',
'@deepseek-ai/dsh-tool-session-query',
'@deepseek-ai/dsh-experimental-tool-subagent-oar',
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index 0f4b4d4a47..1a1043777c 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -985,7 +985,7 @@ describe('Node 24 lane ownership', () => {
'packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts',
'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
- 'packages/experimental/agent-team/tests/built-lib.e2e.ts',
+ 'packages/subagent/agent-team/tests/built-lib.e2e.ts',
]),
)
expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 3474561272..17c3f32f63 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -894,7 +894,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
'packages/api/remotes/tests/built-lib.e2e.ts',
- 'packages/experimental/agent-team/tests/built-lib.e2e.ts',
+ 'packages/subagent/agent-team/tests/built-lib.e2e.ts',
// Built execution consumers: the only automated proof that package-name
// imports reach their lib/ entrypoints under plain Node. The e2e lane runs
// unbuilt, so these files self-skip there.
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b91d3d0951..bf88642371 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -435,32 +435,32 @@
{
"doc": "docs/subsystems/agent-team.md",
"symbol": "TeamTaskView",
- "source": "packages/experimental/agent-team/src/types.ts"
+ "source": "packages/subagent/agent-team/src/types.ts"
},
{
"doc": "docs/subsystems/agent-team.md",
"symbol": "TeamProjection",
- "source": "packages/experimental/agent-team/src/types.ts"
+ "source": "packages/subagent/agent-team/src/types.ts"
},
{
"doc": "docs/subsystems/agent-team.md",
"symbol": "TeamMemberSnapshot",
- "source": "packages/experimental/agent-team/src/types.ts"
+ "source": "packages/subagent/agent-team/src/types.ts"
},
{
"doc": "docs/subsystems/agent-team.md",
"symbol": "TeamMessageSnapshot",
- "source": "packages/experimental/agent-team/src/types.ts"
+ "source": "packages/subagent/agent-team/src/types.ts"
},
{
"doc": "docs/subsystems/agent-team.md",
"symbol": "TeamMessageSource",
- "source": "packages/experimental/agent-team/src/types.ts"
+ "source": "packages/subagent/agent-team/src/types.ts"
},
{
"doc": "docs/subsystems/agent-team.md",
"symbol": "TeamTaskSnapshot",
- "source": "packages/experimental/agent-team/src/types.ts"
+ "source": "packages/subagent/agent-team/src/types.ts"
},
{
"doc": "docs/subsystems/commands.md",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 2c313a3dea..bae53c233e 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -118,7 +118,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = {
'packages/client/file-upload': { kind: 'none', reason: 'Browser-side request-body transport; registers nothing model-facing.' },
'packages/api/remotes': { kind: 'none', reason: 'The Remote BFF selects business methods and forwarded events; selected services own any model-visible effect.' },
'packages/api/remote-access': { kind: 'none', reason: 'Remote access decisions for Client callers; registers nothing model-facing.' },
- 'packages/experimental/client-ui-agent-team': { kind: 'none', reason: 'The browser projection and task controls register no model-facing input.' },
+ 'packages/client/ui-agent-team': { kind: 'none', reason: 'The browser projection and task controls register no model-facing input.' },
'packages/experimental/client-ui-claude-code-mods': { kind: 'none', reason: 'The browser draws Host-held mod trees and relays clicks; the mods\' own hooks own any model-visible effect.' },
'packages/client/shortcuts': { kind: 'none', reason: 'Browser keyboard routing; registers nothing model-facing.' },
'packages/client/ui-shortcuts': { kind: 'none', reason: 'Read-only browser reference; registers nothing model-facing.' },
diff --git a/snapshots/sdk/team-session-mode/cordis.yml b/snapshots/sdk/team-session-mode/cordis.yml
index d4e2b2607c..b2a0da8c21 100644
--- a/snapshots/sdk/team-session-mode/cordis.yml
+++ b/snapshots/sdk/team-session-mode/cordis.yml
@@ -28,8 +28,8 @@
- insert:
- id: agent-team
- name: '@deepseek-ai/dsh-experimental-agent-team'
+ name: '@deepseek-ai/dsh-agent-team'
- id: tool-agent-team
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
+ name: '@deepseek-ai/dsh-tool-agent-team'
- id: team-session-mode-fixture
- name: ../../../packages/experimental/agent-team/tests/session-mode-fixture.ts
+ name: ../../../packages/subagent/agent-team/tests/session-mode-fixture.ts
diff --git a/snapshots/session/team-session-mode/cordis.snapshot.yml b/snapshots/session/team-session-mode/cordis.snapshot.yml
index df29b067aa..254cbbbf31 100644
--- a/snapshots/session/team-session-mode/cordis.snapshot.yml
+++ b/snapshots/session/team-session-mode/cordis.snapshot.yml
@@ -44,12 +44,6 @@
- id: deepseek-v4-flash
- id: deepseek-v4-pro
-- insert:
- - id: agent-team
- name: '@deepseek-ai/dsh-experimental-agent-team'
- - id: tool-agent-team
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
-
- insert:
- id: team-session-mode-fixture
- name: ../../../packages/experimental/agent-team/tests/session-mode-fixture.ts
+ name: ../../../packages/subagent/agent-team/tests/session-mode-fixture.ts
diff --git a/snapshots/session/team-session-mode/cordis.yml b/snapshots/session/team-session-mode/cordis.yml
index f67ec290bc..b806493779 100644
--- a/snapshots/session/team-session-mode/cordis.yml
+++ b/snapshots/session/team-session-mode/cordis.yml
@@ -1,9 +1,3 @@
-- insert:
- - id: agent-team
- name: '@deepseek-ai/dsh-experimental-agent-team'
- - id: tool-agent-team
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
-
- insert:
- id: team-session-mode-fixture
- name: ../../../packages/experimental/agent-team/tests/session-mode-fixture.ts
+ name: ../../../packages/subagent/agent-team/tests/session-mode-fixture.ts
diff --git a/snapshots/session/team-targets/cordis.snapshot.yml b/snapshots/session/team-targets/cordis.snapshot.yml
index 931c4b5a90..bafd1e4544 100644
--- a/snapshots/session/team-targets/cordis.snapshot.yml
+++ b/snapshots/session/team-targets/cordis.snapshot.yml
@@ -44,10 +44,6 @@
- id: deepseek-v4-flash
- id: deepseek-v4-pro
-- insert:
- - id: agent-team
- name: '@deepseek-ai/dsh-experimental-agent-team'
- config:
- enabledByDefault: true
- - id: tool-agent-team
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
+- id: agent-team
+ config:
+ enabledByDefault: true
diff --git a/snapshots/session/team-targets/cordis.yml b/snapshots/session/team-targets/cordis.yml
index e5811361e0..7b58703ffa 100644
--- a/snapshots/session/team-targets/cordis.yml
+++ b/snapshots/session/team-targets/cordis.yml
@@ -1,7 +1,3 @@
-- insert:
- - id: agent-team
- name: '@deepseek-ai/dsh-experimental-agent-team'
- config:
- enabledByDefault: true
- - id: tool-agent-team
- name: '@deepseek-ai/dsh-experimental-tool-agent-team'
+- id: agent-team
+ config:
+ enabledByDefault: true
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 2a92208c57..768c08a71c 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -298,8 +298,8 @@
"@deepseek-ai/dsh-client-ui-permission-presets": ["./packages/client/ui-permission-presets/src"],
"@deepseek-ai/dsh-client-ui-skill": ["./packages/client/ui-skill/src"],
"@deepseek-ai/dsh-client-ui-subagent": ["./packages/client/ui-subagent/src"],
- "@deepseek-ai/dsh-experimental-client-ui-agent-team": ["./packages/experimental/client-ui-agent-team/src"],
- "@deepseek-ai/dsh-experimental-client-ui-agent-team/client": ["./packages/experimental/client-ui-agent-team/src/client/index.ts"],
+ "@deepseek-ai/dsh-client-ui-agent-team": ["./packages/client/ui-agent-team/src"],
+ "@deepseek-ai/dsh-client-ui-agent-team/client": ["./packages/client/ui-agent-team/src/client/index.ts"],
"@deepseek-ai/dsh-client-ui-settings-plugins": ["./packages/client/ui-settings-plugins/src"],
"@deepseek-ai/dsh-client-ui-settings-shell": ["./packages/client/ui-settings-shell/src"],
"@deepseek-ai/dsh-client-ui-settings-agent-loop": ["./packages/client/ui-settings-agent-loop/src"],
@@ -337,11 +337,10 @@
"@deepseek-ai/dsh-sdk-client": ["./packages/sdk/client/src"],
"@deepseek-ai/dsh-sdk-protocol": ["./packages/sdk/protocol/src"],
"@deepseek-ai/dsh-sdk-jsonrpc-server": ["./packages/sdk/server/src"],
- "@deepseek-ai/dsh-experimental-agent-team": ["./packages/experimental/agent-team/src"],
+ "@deepseek-ai/dsh-agent-team": ["./packages/subagent/agent-team/src"],
"@deepseek-ai/dsh-experimental-auto-review": ["./packages/experimental/auto-review/src"],
"@deepseek-ai/dsh-experimental-claude-code-mods": ["./packages/experimental/claude-code-mods/src"],
- "@deepseek-ai/dsh-experimental-agent-team-profile": ["./packages/experimental/agent-team-profile/src"],
- "@deepseek-ai/dsh-experimental-tool-agent-team": ["./packages/experimental/tool-agent-team/src"],
+ "@deepseek-ai/dsh-tool-agent-team": ["./packages/subagent/tool-agent-team/src"],
"@deepseek-ai/dsh-experimental-worktree": ["./packages/experimental/worktree/src"],
"@deepseek-ai/dsh-experimental-tool-worktree": ["./packages/experimental/tool-worktree/src"],
"@deepseek-ai/dsh-experimental-webworker-runtime": ["./packages/experimental/webworker-runtime/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index b2f0423c7c..76f3fff46e 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -111,7 +111,7 @@
{ "path": "./packages/client/ui-reference" },
{ "path": "./packages/client/ui-secret-mask" },
{ "path": "./packages/client/ui-subagent" },
- { "path": "./packages/experimental/client-ui-agent-team" },
+ { "path": "./packages/client/ui-agent-team" },
{ "path": "./packages/client/ui-dockkit" },
{ "path": "./packages/client/ui-sidebar-right" },
{ "path": "./packages/client/ui-sidebar-documentpreview/tsconfig.client.json" },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index deca327660..9e577d3b99 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -494,10 +494,9 @@
{ "path": "./packages/jobs/jobs" },
{ "path": "./packages/jobs/jobs-local" },
{ "path": "./packages/jobs/tool-jobs" },
- { "path": "./packages/experimental/agent-team" },
- { "path": "./packages/experimental/agent-team-profile" },
+ { "path": "./packages/subagent/agent-team" },
{ "path": "./packages/experimental/inspector-profile" },
- { "path": "./packages/experimental/tool-agent-team" },
+ { "path": "./packages/subagent/tool-agent-team" },
{ "path": "./packages/workflow/workflow" },
{ "path": "./packages/workflow/workflow-ptc" },
{ "path": "./packages/workflow/tool-workflow" },
diff --git a/vitest.config.ts b/vitest.config.ts
index 9c717c0ced..f3761f3809 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -327,7 +327,7 @@ export default defineConfig({
'packages/api/remotes/src/client/index.ts',
// The Team browser entry binds its source-covered mount lifecycle to
// the generated Team Remote contribution, which likewise exists only in lib.
- 'packages/experimental/client-ui-agent-team/src/client/index.ts',
+ 'packages/client/ui-agent-team/src/client/index.ts',
// The speech entry also imports generated Remote definitions; voice-input.e2e.ts
// exercises the built entry, while source tests cover mountVoiceInput.
'packages/experimental/client-ui-voice-input/src/client/index.ts',