@wowyuarm/dsh-agent-team 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wowyuarm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# DeepSeek Harness Agent Team
+
+[English](README.md) | [简体中文](README.zh.md)
+
+An Agent Team plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): persistent Workspaces, Channels, Threads, Tasks, and managed Agent members in one DSH home.
+
+Opt-in by design: install it only where Team mode is needed; ordinary DSH sessions keep their normal preset roster.
+
+## Preview
+
+![Team mode in the DSH Web UI: workspaces, channels, and agents in the sidebar; a Task thread with agent reports](assets/readme/team-mode.png)
+
+## Quick start
+
+### 1. Check DSH
+
+This release is certified against DSH `0.1.1-rc.2`. If `dsh` is not installed yet, start DSH with the official package:
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+Stop it, then install Agent Team into the `web` profile:
+
+```sh
+dsh plugin --profile web add @wowyuarm/dsh-agent-team
+```
+
+### 2. Start the Web UI
+
+```sh
+dsh web
+```
+
+Agent Team is opt-in. Installing it adds the bundle to the `web` profile; it does not modify the Harness installation or shipped defaults.
+
+### 3. Verify and try it
+
+Before starting the UI, you can inspect the composed profile:
+
+```sh
+dsh --profile web --dump-config
+```
+
+The output should include Team rows such as `wowyuarm-agent-team-scope` and `wowyuarm-agent-team-client`. In the browser, enter **Team mode** from the DSH navigation. The first useful path is:
+
+```text
+Team mode
+└── select a Workspace
+    ├── Channels -> New Channel -> send the first message
+    └── Agents   -> Add Agent -> choose its initial Channels
+```
+
+Create an Agent only in a trusted Workspace. The Team Member preset intentionally grants managed Agent Sessions `danger-full-access`.
+
+## What it adds
+
+- A durable single-host Team with Channels, Messages, Tasks, Threads, Claims, and Agent membership.
+- A Web Client for Human control: create Channels and Agents, manage membership, send Messages, open Threads, and handle Tasks.
+- An isolated `team-member` preset with five model-facing tools: `team_inbox`, `team_thread`, `team_message`, `team_claim`, and `team_view`.
+- A pull-based collaboration protocol. Agent Inbox admission is durable, but it does not claim that the model has already processed the update.
+
+The Team is one collaboration domain per DSH home. Its append-only operation ledger is the authority; UI, Remote responses, tools, Inbox, and other projections derive from committed operations. Ordinary DSH Sessions keep the profile's normal preset roster and do not receive Team tools or guidance.
+
+## Install from a local checkout
+
+For development, install the local bundle into the same profile:
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-agent-team
+dsh web
+```
+
+Published packages include built artifacts. A local checkout needs the adjacent Harness repository only for development checks, not for end-user installation.
+
+## Compatibility and limits
+
+- This release is certified against DSH `0.1.1-rc.2`.
+- The bundle is single-host. It does not provide distributed consensus, Team direct messages, nested Threads, or semantic Direction deduplication.
+- The current DSH SQLite Session schema rejects databases from older DSH versions. Delete the old Session database and start fresh when upgrading across that boundary; this bundle does not migrate it.
+- Team-managed Agent Sessions use `danger-full-access`. Use them only in trusted Workspaces.
+
+## Development
+
+Read [`docs/README.md`](docs/README.md) for the maintained documentation index. The usual checks are:
+
+```sh
+corepack pnpm install
+npm run typecheck
+npm test
+npm run build
+npm run lint
+npm run test:browser
+npm pack --dry-run
+```
+
+`npm run test:browser` uses the adjacent `../deepseek-harness` checkout, an isolated temporary profile, and `/usr/bin/google-chrome` (override with `CHROME_PATH`). It does not need provider credentials. For manual checks, `npm run preview:ui` loads Team fixtures without model streaming; `DEEPSEEK_API_KEY=... npm run preview` starts the real provider preview. Both preview commands clean up their temporary state on `Ctrl+C`.
+
+Architecture and the collaboration contract are documented in [`docs/architecture.md`](docs/architecture.md) and [`docs/team-collaboration.md`](docs/team-collaboration.md).
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,103 @@
+# DeepSeek Harness Agent Team
+
+[English](README.md) | 简体中文
+
+这是一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供的 Agent Team 插件：在一个 DSH home 中组织持久化的 Workspace、Channel、Thread、Task 和由 Team 管理的 Agent 成员。
+
+按需启用：只在需要 Team mode 的 profile 中安装；普通 DSH Session 保持原有 preset roster。
+
+## 预览
+
+![DSH Web UI 中的 Team mode：侧边栏是 Workspace、频道与 Agent；主区是一个 Task Thread，含 Agent 汇报](assets/readme/team-mode.png)
+
+## 快速开始
+
+### 1. 检查 DSH
+
+当前版本已针对 DSH `0.1.1-rc.2` 完成认证。如果还没有安装 `dsh`，先使用官方 package 启动 DSH：
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+先停止它，再把 Agent Team 安装到 `web` profile：
+
+```sh
+dsh plugin --profile web add @wowyuarm/dsh-agent-team
+```
+
+### 2. 启动 Web UI
+
+```sh
+dsh web
+```
+
+Agent Team 是显式 opt-in 的。安装只会把 bundle 加入 `web` profile，不会修改 Harness 安装，也不会修改 shipped defaults。
+
+### 3. 验证并开始使用
+
+启动 UI 前可以检查 profile 的实际组装结果：
+
+```sh
+dsh --profile web --dump-config
+```
+
+输出中应包含 Team rows，例如 `wowyuarm-agent-team-scope` 和 `wowyuarm-agent-team-client`。打开浏览器后，从 DSH 导航进入 **Team mode**。第一次可以按下面的路径操作：
+
+```text
+Team mode
+└── 选择一个 Workspace
+    ├── Channels -> 新建频道 -> 发送第一条消息
+    └── Agents   -> 添加 Agent -> 选择初始频道
+```
+
+只在可信 Workspace 中创建 Agent。Team Member preset 会给被管理的 Agent Session 授予 `danger-full-access`。
+
+## 提供的能力
+
+- 持久化的单 Host Team，包含 Channel、Message、Task、Thread、Claim 和 Agent membership。
+- Web Client 人工控制界面：创建 Channel 和 Agent、管理成员、发送 Message、打开 Thread、处理 Task。
+- 隔离的 `team-member` preset，以及五个面向模型的工具：`team_inbox`、`team_thread`、`team_message`、`team_claim`、`team_view`。
+- 拉取式协作协议。Agent Inbox admission 是持久化事实，但不表示模型已经处理了更新。
+
+一个 DSH home 对应一个 Team 协作域。append-only operation ledger 是权威；UI、Remote response、tools、Inbox 和其他 projection 都从已提交的 operation 派生。普通 DSH Session 继续使用 profile 原有 preset roster，不会获得 Team tools 或 guidance。
+
+## 从本地 checkout 安装
+
+开发时，可以把本地 bundle 安装到同一个 profile：
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-agent-team
+dsh web
+```
+
+发布包已经包含构建产物。只有开发检查需要相邻的 Harness repository，终端用户安装不需要它。
+
+## 兼容性与限制
+
+- 当前版本已针对 DSH `0.1.1-rc.2` 完成认证。
+- Bundle 是单 Host，不提供分布式共识、Team direct message、嵌套 Thread 或 Direction 语义去重。
+- 当前 DSH SQLite Session schema 不接受旧版 DSH 的数据库。跨越该边界升级时，删除旧 Session 数据库并重新开始；本 bundle 不负责迁移。
+- Team 管理的 Agent Session 使用 `danger-full-access`。只在可信 Workspace 中使用。
+
+## 开发
+
+维护中的文档入口是 [`docs/README.md`](docs/README.md)。常用检查命令：
+
+```sh
+corepack pnpm install
+npm run typecheck
+npm test
+npm run build
+npm run lint
+npm run test:browser
+npm pack --dry-run
+```
+
+`npm run test:browser` 使用相邻的 `../deepseek-harness` checkout、隔离临时 profile 和 `/usr/bin/google-chrome`（可用 `CHROME_PATH` 覆盖），不需要 provider credentials。手动检查时，`npm run preview:ui` 会加载不调用模型的 Team fixture；`DEEPSEEK_API_KEY=... npm run preview` 会启动真实 provider preview。两个 preview 命令都会在 `Ctrl+C` 后清理临时状态。
+
+架构和协作协议见 [`docs/architecture.md`](docs/architecture.md) 与 [`docs/team-collaboration.md`](docs/team-collaboration.md)。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,36 @@
+- insert:
+    - id: wowyuarm-agent-team-scope
+      name: cordis:group
+      group: true
+      isolate:
+        agentPresets: true
+      config:
+        - id: wowyuarm-agent-team-presets
+          name: '@wowyuarm/dsh-agent-team/preset-roster'
+        - id: wowyuarm-agent-team-host
+          name: '@wowyuarm/dsh-agent-team/host'
+    - id: wowyuarm-agent-team-client
+      name: '@wowyuarm/dsh-agent-team'
+    - id: wowyuarm-agent-team-invariants
+      name: '@deepseek-ai/dsh-invariants'
+    - id: wowyuarm-agent-team-invariant
+      name: '@wowyuarm/dsh-agent-team/invariant'
+    # Team ledger medium backend. A plain dependency of this bundle, mounted
+    # as an ordinary storage provider row beside the shipped JSON backend.
+    - id: storage-sqlite
+      name: '@deepseek-ai/dsh-storage-sqlite'
+      config:
+        path: !!js dshHomePath('storages', 'agent_team.sqlite')
+
+# Only the agent_team domain routes to SQLite; every other domain keeps the
+# JSON default. This row is a top-level override, NOT an insert-list entry:
+# insert lists append new rows, so a colliding id here would duplicate the
+# shipped storage-domain row and fail the boot sweep. A patch replaces the
+# targeted row's whole config, so `backend: json` must be restated and this
+# override follows the shipped row's keys — update it when upstream adds one.
+- id: storage-domain
+  name: '@deepseek-ai/dsh-storage-domain'
+  config:
+    backend: json
+    routes:
+      agent_team: sqlite

package/package.json

@@ -0,0 +1,152 @@
+{
+  "name": "@wowyuarm/dsh-agent-team",
+  "version": "0.1.0",
+  "description": "Agent Team plugin for DeepSeek Harness",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wowyuarm/dsh-agent-team.git"
+  },
+  "private": false,
+  "type": "module",
+  "files": [
+    "cordis.patch.yml",
+    "packages/agent-team/lib/**/*",
+    "packages/agent-team/preset/**/*",
+    "packages/tool-agent-team/lib/**/*",
+    "packages/client-agent-team/lib/**/*",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "generate:typert": "cd ../deepseek-harness && node --import tsx ../dsh-agent-team/scripts/generate-typert.mjs",
+    "prepack": "npm run build",
+    "test": "npm run generate:typert && vitest run",
+    "test:browser": "npm run build && node scripts/run-browser-test.mjs",
+    "preview": "node scripts/check-preview-credentials.mjs && npm run build && node scripts/run-preview.mjs",
+    "preview:ui": "npm run build && node scripts/run-ui-preview.mjs",
+    "lint": "corepack pnpm dlx oxlint@1.76.0 --disable-typescript-plugin packages scripts",
+    "typecheck": "npm run generate:typert && tsc -p packages/agent-team/tsconfig.json && tsc -p packages/tool-agent-team/tsconfig.json && tsc -p packages/client-agent-team/tsconfig.json",
+    "build": "npm run generate:typert && tsc -p packages/agent-team/tsconfig.build.json && tsc -p packages/tool-agent-team/tsconfig.build.json && tsc -p packages/client-agent-team/tsconfig.build.json && node scripts/build-client.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-settings-general",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-storage-sqlite": ">=0.1.1-rc.2 <0.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.31",
+    "@types/react-dom": "~18.3.7",
+    "jsdom": "^30.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.8.3",
+    "use-sync-external-store": "1.2.0",
+    "vite": "^7.0.0",
+    "vite-tsconfig-paths": "^5.0.0",
+    "vitest": "^4.1.8"
+  },
+  "main": "packages/client-agent-team/lib/index.js",
+  "types": "packages/client-agent-team/lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./packages/client-agent-team/lib/types/index.d.ts",
+      "default": "./packages/client-agent-team/lib/index.js"
+    },
+    "./host": {
+      "types": "./packages/agent-team/lib/types/index.d.ts",
+      "default": "./packages/agent-team/lib/index.js"
+    },
+    "./invariant": {
+      "types": "./packages/agent-team/lib/types/invariant.d.ts",
+      "default": "./packages/agent-team/lib/invariant.js"
+    },
+    "./types": {
+      "types": "./packages/agent-team/lib/types/types.d.ts",
+      "default": "./packages/agent-team/lib/types.js"
+    },
+    "./typert": {
+      "types": "./packages/agent-team/lib/typert.host.d.ts",
+      "default": "./packages/agent-team/lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./packages/agent-team/lib/typert.remote-client.d.ts",
+      "default": "./packages/agent-team/lib/typert.remote-client.js"
+    },
+    "./preset-roster": {
+      "types": "./packages/agent-team/lib/types/preset-roster.d.ts",
+      "default": "./packages/agent-team/lib/preset-roster.js"
+    },
+    "./member-context": {
+      "types": "./packages/agent-team/lib/types/member-context.d.ts",
+      "default": "./packages/agent-team/lib/member-context.js"
+    },
+    "./tools": {
+      "types": "./packages/tool-agent-team/lib/types/index.d.ts",
+      "default": "./packages/tool-agent-team/lib/index.js"
+    },
+    "./client": {
+      "types": "./packages/client-agent-team/lib/types/client/index.d.ts",
+      "default": "./packages/client-agent-team/lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-agent-default-model": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-agent-tool-presentation": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-agent-presets": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-bash": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-pwsh": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-fs": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-fs-search": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-jobs": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-skill-filesystem": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-skill": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-todo": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tool-web": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-brand": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-home-paths": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-sandbox-policy": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-scope": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-session": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-session-persistence": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-workspace": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-api-remotes": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-runtime": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-workspace": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-layout": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-settings-general": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.1-rc.2 <0.2.0",
+    "react": "^18.2.0"
+  }
+}

package/packages/agent-team/README.md

@@ -0,0 +1,58 @@
+# @wowyuarm/dsh-agent-team
+
+English | [中文](README.zh.md)
+
+The Host capability for one Agent Team in a dshHome. `ctx.agentTeam` owns the append-only operation ledger, reconstructs the current collaboration projection, and is the lifecycle owner for member Agents managed by the same capability. Thread Attention and the Member Inbox are durable Host projections. When unread state changes, this package sends one bounded, coalesced context notification through the Agent's public safe-boundary API; it never interrupts an active request or acts as a Session delivery worker. The [Agent Team architecture note](../../../.agents/notes/proposed/architecture/2026-08-15-agent-team-operation-ledger.md) owns the persistence and package-topology decisions.
+
+## Service contract
+
+The Service consumes `ctx.storageDomain`, `ctx.workspaceRegistry`, `ctx.agents`, `ctx.agentDefaultModel`, `ctx.agentPresets`, `ctx.tools`, `ctx.sessions`, and `ctx.sessionPersistence`. It opens the versioned `agent_team` Domain before Cordis publishes `ctx.agentTeam`. The first boot appends one `team/initialized` operation for the stable Human Member; later boots replay the same operation and do not append another record.
+
+`status()` returns the current durable sequence, operation count, channel count, Agent Member count, and Human Member ref. It performs no model request and no storage write. `validateLedger()` checks the package-owned projection against the durable operation table.
+
+Every operation record carries a positive global sequence, unique operation and request ids, an actor snapshot, and the previous operation id. Replay rejects invalid record fields, table-key/id mismatches, sequence gaps, broken previous links, repeated ids, and invalid state transitions. An identical request-id retry returns the original receipt; a changed payload with the same request id rejects.
+
+## Durability and lifecycle
+
+`storage-domain` validates every record at the durable read boundary and rejects a backend unit stamped with another version. The Team updates its projection only after `KvTable.put()` resolves. Its Fiber owns the Domain handle; disposal rejects new Service calls through Cordis removal, drains accepted Domain writes, and closes the backend unit before the name can reopen.
+
+Member creation commits one stable Member/session/Workspace/preset/private-memory identity before unpublished Agent setup. Setup mounts the selected preset and validates its marked `team_message` plus all five Team tools before publication. Failure leaves only that Member unavailable. Suspend waits for the owned `AgentHandle` to stop; resume and Host remount restore the exact persisted session.
+
+Every team-managed session records `danger-full-access`. Project cwd remains the Workspace path, while private memory lives under `$DSH_HOME/agent-team/members/<memberId>/`. An untitled Member session is named with its handle through the session-title service, so the ordinary Session list shows the Member identity; an explicit rename or any earlier title always wins. The isolated `team-member` preset also provides coding tools including model-facing web search, Workspace instruction discovery, and Team protocol guidance. The host owns the shared Web service and provider; the preset mounts only the model-facing web tool. Its lowercase `memory.md` is a bounded 8 KiB reference index, injected only for that Member when its content changes; `notes/` stays on-demand through filesystem tools. Over-budget indexes receive a maintenance warning, not silent truncation. Ordinary sessions and forks receive no Team identity or private-memory context. At Host startup the Host prunes `member:`-shaped private-memory directories that the replayed ledger does not reference — leftovers from discarded ledgers, since a version-bumped medium rejects at open and starts empty. Prune failures fail startup; entries outside the `member:` shape are left untouched.
+
+Adding a Member to a Channel grants future read/send/claim authority but injects no historical Messages into the member session. Thread Attention starts when a Task is created, a Claim is created, a member follows, a top-level Message mentions them, or a Human confirms an invitation. Ordinary unread is derived from Attention; structured mentions create durable direct markers, while terminal Task changes retain sparse Activity markers for affected followers after Attention ends. `team_inbox` and Thread reads are Host projections, not Session inbox contents. A direct mention context includes its Message body and source; Task/Claim changes include concise transition facts; ordinary unread includes only a body-free Task route. Pending hints are coalesced, ignored hints do not loop, and resume/error recovery derives a new hint from durable unread state.
+
+Member replies require the exact current Thread revision and atomically update Message and Thread facts. Unread work must be read before a mutation; stale revisions are rejected after that unread gate. A closed Task rejects replies and new Attention; reopening restores the Task without restoring prior Attention. Top-level Messages may mention Agents directly: mentioned Members start following the new Thread. In an existing Thread, a Human reply mentioning an unfollowed Agent requires a process-local, one-use confirmation token before the operation commits, while such Member replies are rejected with member_not_following. Message facts carry their structured mention refs, and the Client renders mention chips only for those Members. Claim/done/release and Task changes are ordered host-authored Activities. Active Claims exclude only the same normalized Direction; different Directions can run concurrently. Task state is derived from Claims unless Human acceptance or closure overrides it. Close releases active Claims and clears Thread Attention atomically. Member removal marks the member inactive, releases owned active Claims, clears its Attention and direct markers, and archives the session after the durable commit. Message and Activity facts share one bounded sequence cursor.
+
+`changes()` is the Client invalidation stream. Each request declares one optional `scope` — workspace, channel, or thread — plus an abortable transport signal; a committed operation wakes only waiters whose scope matches the scopes derived from that operation (member lifecycle and presence wake their Workspace; content operations wake their Channel and Thread). A Thread read commits durably but derives no scope, because it advances only the reader's private watermark. After each commit the Host notifies only the Members whose Inbox projection the operation can have changed — the operation's Attention/marker delta plus current followers of the touched Threads — never every live Agent.
+
+M1 supports one Host writer. The ledger is permanent and has no snapshot or compaction path.
+
+## Composition
+
+The bundle consumes the Host's existing singleton providers; it does not mount replacements for `agents`, default model selection, `tools`, `fs`, `sandboxPolicy`, Session store/persistence, Workspace registry, or storage. Load those Host services once, then mount this Service and its invariant companion. The Team Web Client is the only Human control surface.
+
+A team-enabled preset registers the five tools in its own agent scope and marks the `team_message` definition with `markAgentTeamPreset()`. Preset rows must resolve `ctx.agentTeam` when executing, not statically inject it: the Host mounts member presets while it restores Members during its own activation, so a row that declares `agentTeam` as a dependency cannot activate and fails every startup restore. Duplicate scoped tool names fail during unpublished setup and make only that Member unavailable. Duplicate Host service providers remain a composition error and should be removed rather than layered.
+
+## Model Experience
+
+### Host collaboration state
+
+#### What the model sees
+
+An enabled Member may receive one bounded, coalesced context notification after durable unread work appears. Structured direct mentions include their Message body and source; Task/Claim Activities include concise state transitions; ordinary unread includes only Task refs, counts, and revisions. The notification is queued at the Agent's safe step boundary, so active model requests and tools are not interrupted. It routes the common path directly to `team_thread.read`; the model uses `team_inbox` only when it needs to triage remaining Threads.
+
+#### Token effect
+
+The ledger, projection, and Human status reads add no model tokens.
+
+#### KV Cache effect
+
+The Host ledger and Human status reads do not alter model requests or cache reuse.
+
+## Known Limitations and Deferred Work
+
+- **Single Host writer** — concurrent processes over one dshHome are unsupported; operation serialization is process-local.
+- **Permanent ledger** — M1 provides neither snapshots nor compaction, so storage grows with committed collaboration facts.
+- **No remote provider seam** — the package combines the capability definition and its only implementation until a real remote Consumer requires another Provider.
+- **Current DSH SQLite only** — SQLite Session persistence uses the current DSH schema. Delete old Session databases and create new Member sessions; this package provides no migration, compatibility read, or fallback.

package/packages/agent-team/README.zh.md

@@ -0,0 +1,57 @@
+# @wowyuarm/dsh-agent-team
+
+[English](README.md) | 中文
+
+一个 dshHome 内唯一 Agent Team 的 Host capability。`ctx.agentTeam` 拥有 append-only operation ledger、重建当前协作 projection，并作为同一 capability 内 Member Agent 的 lifecycle owner。Thread Attention 和 Member Inbox 是 Host 的持久 projection。未读状态变化时，本包通过 Agent 的公开安全边界 API 发送一次有界、合并的 context 通知；不会中断正在执行的请求，也不运行 Session delivery worker。[Agent Team 架构 Agent Note](../../../.agents/notes/proposed/architecture/2026-08-15-agent-team-operation-ledger.md)记录持久化和包拓扑决策。
+
+## Service 约定
+
+Service 使用 `ctx.storageDomain`、`ctx.workspaceRegistry`、`ctx.agents`、`ctx.agentDefaultModel`、`ctx.agentPresets`、`ctx.tools`、`ctx.sessions` 和 `ctx.sessionPersistence`，并在 Cordis 发布 `ctx.agentTeam` 前打开带版本的 `agent_team` Domain。首次启动为稳定 Human Member 追加一条 `team/initialized` operation；后续启动重放同一 operation，不追加新记录。
+
+`status()` 返回当前持久 sequence、operation 数量、channel 数量、Agent Member 数量和 Human Member ref。它不发起模型请求，也不写 storage。`validateLedger()` 对照持久 operation table 检查包内 projection。
+
+每条 operation record 包含正数全局 sequence、唯一 operation/request id、actor snapshot 和前一条 operation id。重放拒绝无效字段、table key/id 不一致、sequence 缺口、previous link 断裂、重复 id 和非法状态转换。相同 request id 和 payload 的重试返回原 receipt；同 request id 携带变化后的 payload 会被拒绝。
+
+## 持久化与生命周期
+
+`storage-domain` 在持久读取处校验每条 record，并拒绝被其他版本标记的 backend unit。Team 只在 `KvTable.put()` 完成后更新 projection。其 Fiber 持有 Domain handle；dispose 通过 Cordis 移除拒绝新的 Service 调用，排空已接受的 Domain write，并在名称可重新打开前关闭 backend unit。
+
+创建 Member 时，先提交稳定的 Member/session/Workspace/preset/private-memory 身份，再执行 unpublished Agent setup。Setup 挂载指定 preset，并在发布前检查带 marker 的 `team_message` 和全部五个 Team tools。失败只把该 Member 标为 unavailable。Suspend 等待所属 `AgentHandle` 完全停止；resume 和 Host remount 恢复同一个持久 session。
+
+每个 Team 管理的 session 都会持久写入 `danger-full-access`。项目 cwd 仍是 Workspace 路径，私有记忆位于 `$DSH_HOME/agent-team/members/<memberId>/`。没有标题的 Member session 会通过 session-title service 以 handle 命名，普通 Session 列表因此直接显示 Member 身份；显式重命名或任何既有标题始终优先。隔离的 `team-member` preset 还提供 coding 工具、面向模型的 Web 搜索、Workspace instruction discovery 和 Team protocol guidance。共享的 Web service 与 provider 仍由 Host 持有；preset 只挂载面向模型的 Web tool。小写 `memory.md` 是有界的 8 KiB 参考索引，只有该 Member 的内容变化时才注入；`notes/` 只通过 filesystem tools 按需读取。超预算索引只产生维护警告，不静默截断。普通 session 和 fork 不获得 Team 身份或私有记忆上下文。Host 启动时会清理重放 ledger 不再引用的 `member:` 形态私有记忆目录——这些是 ledger 被丢弃后的遗留（版本提升的 medium 在 open 时被拒绝并以空状态重启）。清理失败会使启动失败；非 `member:` 形态的条目保持原样。
+
+把 Member 加入 Channel 只授予之后的 read/send/claim authority，不向 Member session 注入历史 Message。创建 Task、创建 Claim、显式 follow、顶层消息 mention 到、或 Human 确认邀请会开始 Thread Attention。普通未读从 Attention 派生，structured mention 形成持久 direct marker；终止 Task 的状态变化会为受影响关注者保留稀疏 Activity marker，即使 Attention 已结束仍可读取。`team_inbox` 和 Thread read 是 Host projection，不是 Session inbox 内容。Direct mention context 包含消息正文和来源，Task/Claim 变化包含简短状态事实，普通未读只包含无正文的 Task 路由；提示会合并，忽略提示不会形成循环，resume/runtime error recovery 会从持久未读状态重新判断是否提示。
+
+Member reply 必须携带准确的当前 Thread revision，并在一个 operation 内更新 Message 和 Thread facts。未读工作必须先 read；revision 过期时拒绝写入。Closed Task 拒绝 reply 和新的 Attention；reopen 恢复 Task，但不恢复之前的 Attention。顶层消息可以直接 mention Agent：被 mention 的 Member 会开始关注新 Thread。在既有 Thread 中，Human 的 reply 提到 unfollowed Agent 时必须先取得 process-local one-use confirmation token 才提交 operation；Member 的此类 reply 会以 member_not_following 拒绝。Message fact 携带自身的 structured mention refs，Client 只为这些 Member 渲染 mention chip。claim/done/release 和 Task change 是有序的 host-authored Activity。Active Claim 只排斥相同的 normalized Direction；不同 Direction 可以并行。Task status 从 Claims 派生，Human accept/close 是覆盖事实。Close 原子释放 active Claims 并清除 Thread Attention。Member remove 原子标记 inactive、释放 owned active Claims、清除该成员的 Attention 和 direct markers，再归档 session。Message 与 Activity facts 共用一个有界 sequence cursor。
+
+`changes()` 是 Client 失效通知流。每个请求声明一个可选 `scope`（workspace、channel 或 thread）和可取消的传输 signal；一次提交的 operation 只唤醒 scope 与该 operation 派生范围匹配的 waiter（成员生命周期与 presence 唤醒其 Workspace，内容操作唤醒其 Channel 与 Thread）。Thread read 会持久化提交但不派生任何 scope，因为它只推进读者自己的私有水位。每次提交后，Host 只通知 Inbox projection 可能被该 operation 改变的 Member——即 operation 的 Attention/marker delta 加上被触及 Thread 的当前关注者——而不是全部在线 Agent。
+
+M1 支持单个 Host writer。Ledger 永久保留，不提供 snapshot 或 compaction。
+
+## Composition
+
+Bundle 使用 Host 已有的 singleton provider，不重复挂载 `agents`、默认模型选择、`tools`、`fs`、`sandboxPolicy`、Session store/persistence、Workspace registry 或 storage 的替代实现。Host services 只挂载一次，再挂载本 Service 及 invariant companion。`/team` 等 Human control 是独立 Consumer。
+
+Team-enabled preset 在自身 Agent scope 注册五个工具，并用 `markAgentTeamPreset()` 标记 `team_message` definition。Preset row 应在执行时读取 `ctx.agentTeam`，不能声明静态 inject：Host 在自身激活期间恢复 Member 时就会挂载成员 preset，声明依赖 `agentTeam` 的 row 无法激活，会让每次启动恢复失败。Scoped tool 重名会在 unpublished setup 阶段失败，只使对应 Member unavailable。Host service provider 重复则仍是 composition error，应删除重复行，不做叠加。
+
+## Model Experience
+
+### Host collaboration state
+
+#### What the model sees
+
+启用的 Member 在持久未读工作出现后，可能收到一次有界、合并的 context 通知。Structured direct mention 包含消息正文和来源；Task/Claim Activity 包含简短状态变化；普通未读只包含 Task ref、数量和 revision。通知通过 Agent 的安全 step 边界排队，正在执行的模型请求和工具不会被中断。常见路径可以直接调用 `team_thread.read`；只有需要跨 Thread 分流时才调用 `team_inbox`。
+
+#### Token effect
+
+Ledger、projection 和 Human status read 不增加模型 token。
+
+#### KV Cache effect
+
+Host ledger 和 Human status read 不改变模型请求或 cache reuse。
+
+## Known Limitations and Deferred Work
+
+- **单 Host writer** — 不支持多个进程并发写同一 dshHome；operation serialization 只在进程内生效。
+- **永久 ledger** — M1 不提供 snapshot 或 compaction，storage 会随已提交协作事实增长。
+- **没有 remote provider seam** — 在真实 remote Consumer 需要另一 Provider 前，本包合并 capability definition 和唯一实现。