dsh-agent-crew-agents-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tushar
+
+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.i18n.yaml

@@ -0,0 +1,55 @@
+# 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/crew-agents-ui/README.md
+/:
+  en: ca93de121087ffd9
+  zh: 7431cbe5f89d64c6
+/deepseek-ai-dsh-crew-agents-ui:
+  en: c54dfe8c6a384a6c
+  zh: 1a86c86aecfee1ee
+/deepseek-ai-dsh-crew-agents-ui/summary:
+  en: ff748aaa597909c6
+  zh: 8495b25f541a455b
+/deepseek-ai-dsh-crew-agents-ui/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: b00dddf4c88f0a45
+/deepseek-ai-dsh-crew-agents-ui/use-this-package:
+  en: c8d334c9bb184861
+  zh: 9b8e9a62cdfad213
+/deepseek-ai-dsh-crew-agents-ui/use-this-package/faces:
+  en: 311415406e0bf546
+  zh: 61db2a342548d5a3
+/deepseek-ai-dsh-crew-agents-ui/use-this-package/crew-section-and-chat-header:
+  en: faeabf6dcacff32f
+  zh: 437055b7e14c14bd
+/deepseek-ai-dsh-crew-agents-ui/use-this-package/connections:
+  en: 8b15d590e29c95f3
+  zh: 4e4b99c406cf987b
+/deepseek-ai-dsh-crew-agents-ui/use-this-package/crew-tab:
+  en: 9a343abd9a741aac
+  zh: b940c7289e2440da
+/deepseek-ai-dsh-crew-agents-ui/use-this-package/slack:
+  en: 2805935f7dbefe46
+  zh: e47abe359a48c372
+/deepseek-ai-dsh-crew-agents-ui/use-this-package/learning:
+  en: f3a1d3fd0fc577d2
+  zh: c37ed03066b73fbe
+/deepseek-ai-dsh-crew-agents-ui/understand-the-implementation:
+  en: 11ee4af1c13e00c2
+  zh: 413f0c51621e2fbe
+/deepseek-ai-dsh-crew-agents-ui/further-exploration:
+  en: bd596b904b00e26f
+  zh: e287ad7c80c62e5a
+/deepseek-ai-dsh-crew-agents-ui/model-experience:
+  en: e61e7f70df03f64a
+  zh: 8c5e7126756baab7
+/deepseek-ai-dsh-crew-agents-ui/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: 477b768cc9dcda1a
+/deepseek-ai-dsh-crew-agents-ui/known-limitations-and-deferred-work:
+  en: dff772cd83c6a131
+  zh: 1b06a5826e376632
+/deepseek-ai-dsh-crew-agents-ui/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: bd8a8936229e035e

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+---
+description: "Browser roster of the crew: each member's name, face and live status, a Session start, and adding, editing and removing members, shared with other crew plugins."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-agent-crew-agents-ui
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This client plugin provides `ctx.crew`: the crew members stored by [crew-roster](../crew-roster/README.md), with their faces, names and live status (working, needs you or idle) folded from the Session list and Session status, plus a way to start a Session with a member. It draws a **Crew** section above the workspaces, a badge in the chat header of crew Sessions, and a **Crew** tab in the right panel where you add, edit and remove members.
+
+## 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)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The [crew-agents](../crew-agents/README.md) bundle mounts this row. A browser plugin injects `crew` and reads:
+
+| Member | Meaning |
+|---|---|
+| `members` | Observable roster: `{ id, name, face, status, sessions, open, home, focus }` per member, in roster order |
+| `name(id)` | Member name, translated for a shipped member until it is renamed |
+| `design(id)` | Member face, or undefined for an id not on the roster |
+| `statusLabel(state)` | Localized `Working`, `Needs you` or `Idle` |
+| `openChat(id)` | Open the member's focus Session, creating its own chat outside any workspace when it has none |
+| `startInWorkspace(id, workspaceId)` | Start a new chat with the member in a workspace |
+| `roster`, `refresh()` | The stored member records and connection choices from [crew-roster](../crew-roster/README.md), and a re-read |
+| `save(member)`, `remove(id)` | Add (empty id), update or remove a member; each resolves the outcome or the message to show |
+| `requestEdit(id)` | Ask the Crew tab to open the editor for a member, or for a new one with `''` |
+
+Draw a member with `ctx.crewFaces.Face` from [crew-faces](../crew-faces/README.md), passing the member id as `agentId`, its `face` as `design`, and `mood="working"` while its status is `working`.
+
+### Faces
+
+| Member | Body | Colour |
+|---|---|---|
+| Chief of staff | orb | `#0B0B0C`, with white eyes |
+| Mail | block | `#E8B4A0` |
+| Chat | bean | `#C9B6E4` |
+| Code | drop | `#4D6BFE` |
+| Research | orb | `#A8C7A1` |
+| Life | bean | `#F2D16B` |
+
+Each member's face is part of its record and can be changed in the editor; the table lists the shipped faces. A member's eyes move up and right while it works.
+
+### Crew section and chat header
+
+The section uses the `sidebar.sections` slot and lists every member, idle ones included, with a status chip while it works or needs you. Each member has its own chat: a Session outside any workspace, running in the member's folder that [crew-connections](../crew-connections/README.md) provides, and created the first time it is opened. A row opens the Session waiting on you, else one running, else the member's own chat. The **⋯** menu opens the own chat, starts a new chat with the member in any workspace, or opens **Edit member**; the **+** beside the heading adds a member. Both open the editor in the Crew tab. The collapsed rail shows the faces alone, each still named for assistive technology and in its tooltip.
+
+The badge uses `conversation.session.header.actions`. It shows the member a Session runs, then the faces of the crew members the Session handed work to, read from its subagent catalog: those that need you first, then those working, whose eyes move, then those done, dimmed. More than four collapse into a count. It appears when a Session runs a crew member or has handed work to one.
+
+### Connections
+
+Below the roster, the Crew tab lists the crew's MCP connections, who uses each and its state in words. Google takes an OAuth client id and secret, then **Sign in with Google** opens Google's consent page; GitHub takes a token. Secrets go to the Host credential store and are never shown back: a stored one reads as stored and can be replaced or removed. Keyless servers read **No account needed**, and servers waiting for your approval read **Off until you approve it**.
+
+### Crew tab
+
+Open **Crew** from the right panel's guide in any Session. Each row shows the member's face, name, status in words (Working, Needs you or Idle), its Session count and a **New session** button that starts a Session with that member's preset.
+
+**Edit** on a row and **Add crew member** below the list open the editor: name, what the member does (the Chief of staff reads it when choosing whom to ask), instructions, tool calls per message (0 for no limit), face shape and colour, file access, commands, web pages, scheduled tasks and connections. Connections whose account you have not approved are shown switched off. The Chief of staff can be renamed and re-instructed but not removed, and its tools are fixed. **Remove** asks once more; past chats stay. Saving takes effect for new chats; running chats keep the setup they started with.
+
+### Slack
+
+Below the connections, the **Slack** card stores the Slack app's tokens and your member id for [crew-slack](../crew-slack/README.md), shows whether it is connected, and lists replies waiting for you. Each reply can be edited, then posted with **Post reply** or dropped with **Discard**; the list re-reads every 5 seconds while open.
+
+### Learning
+
+Between the roster and the connections, the **Learning** list shows lessons crew members propose through [crew-improve](../crew-improve/README.md). Each proposal names its member, the lesson, the quoted evidence, whether it came from a rating or a chat and when, and the lesson it would replace; **Approve** and **Reject** decide it. Approved lessons are listed with their approval time and a **Remove** button. The list re-reads every 30 seconds while open; nothing changes without a click.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+A Session belongs to a member when its listed `agentPreset` projection value equals the member's preset id. A member is `needs-you` while any of its Sessions has a pending interaction, such as an unanswered question or approval, else `working` while any runs, else `idle`. Live running state from `uiSession.sessionStatus` takes precedence over the list's running flag. The roster snapshot keeps its identity until a member's status or Session list changes, so React selectors re-render only on real changes.
+
+| Source | Contents |
+|---|---|
+| [`src/roster.ts`](src/roster.ts) | The status fold |
+| [`src/client/index.ts`](src/client/index.ts) | Registrations |
+| [`src/client/crew-roster.ts`](src/client/crew-roster.ts) | `ctx.crew` service and chat opening |
+| [`src/client/CrewPanel.tsx`](src/client/CrewPanel.tsx), [`src/client/MemberEditor.tsx`](src/client/MemberEditor.tsx) | Crew tab and member editor |
+| [`src/client/CrewSection.tsx`](src/client/CrewSection.tsx) | Sidebar section |
+| [`src/client/CrewLearning.tsx`](src/client/CrewLearning.tsx), [`src/client/learning.ts`](src/client/learning.ts) | Learning list and its store |
+| [`src/client/CrewHeader.tsx`](src/client/CrewHeader.tsx) | Chat header badge |
+| [`src/client/locales.ts`](src/client/locales.ts) | Names, status labels and tab copy |
+| [`tests/`](tests/) | Fold and service tests |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [crew-roster](../crew-roster/README.md) — stored members and their presets.
+- [crew-agents](../crew-agents/README.md) — the bundle.
+- [crew-faces](../crew-faces/README.md) — member faces.
+- [ui-session](../../client/ui-session/README.md) — the Session status source.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the package is a browser-side roster that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Only Sessions in the browser's Session list count; a delegated child the list does not retain does not change its member's status.
+- The roster is read again when the window regains focus, so a change made in another window or on another device shows once you switch back.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,139 @@
+---
+description: "Crew 的浏览器端名册：每位成员的名称、头像和实时状态、Session 启动，以及添加、编辑和移除成员，供其他 crew 插件共用。"
+kind: "package-reference"
+---
+
+# dsh-agent-crew-agents-ui
+
+[English](README.md) | 中文
+
+## 概述
+
+本客户端插件提供 `ctx.crew`：由 [crew-roster](../crew-roster/README.zh.md) 存储的 crew 成员，及其头像、名称和由 Session 列表与 Session 状态汇总的实时状态（工作中、需要你或空闲），并提供与成员新建 Session 的方法。它在 Workspace 上方绘制 **Crew** 区块，在 crew Session 的聊天标题中显示徽标，并在右侧面板提供 **Crew** 标签页，可在其中添加、编辑和移除成员。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [实现原理](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+[crew-agents](../crew-agents/README.zh.md) bundle 挂载此行。浏览器插件注入 `crew` 并读取：
+
+| 成员 | 含义 |
+|---|---|
+| `members` | 可观察的名册：每位成员的 `{ id, name, face, status, sessions, open, home, focus }`，按名册顺序 |
+| `name(id)` | 成员名称；随附成员在改名前显示翻译后的名称 |
+| `design(id)` | 成员头像；不在名册中的 ID 返回 undefined |
+| `statusLabel(state)` | 本地化的“工作中”“需要你”或“空闲” |
+| `openChat(id)` | 打开该成员的焦点 Session，若没有则创建其不属于任何 Workspace 的对话 |
+| `startInWorkspace(id, workspaceId)` | 在某个 Workspace 中与该成员新建对话 |
+| `roster`、`refresh()` | 来自 [crew-roster](../crew-roster/README.zh.md) 的成员记录与可选连接，以及重新读取 |
+| `save(member)`、`remove(id)` | 添加（空 ID）、更新或移除成员；各自返回结果或要显示的消息 |
+| `requestEdit(id)` | 请求 Crew 标签页打开某位成员的编辑器，传入 `''` 则新建成员 |
+
+使用 [crew-faces](../crew-faces/README.zh.md) 的 `ctx.crewFaces.Face` 绘制成员，把成员 ID 作为 `agentId`、其 `face` 作为 `design` 传入，状态为 `working` 时传入 `mood="working"`。
+
+### 头像
+
+| 成员 | 身体 | 颜色 |
+|---|---|---|
+| 幕僚长 | orb | `#0B0B0C`，白色眼睛 |
+| 邮件 | block | `#E8B4A0` |
+| 聊天 | bean | `#C9B6E4` |
+| 代码 | drop | `#4D6BFE` |
+| 研究 | orb | `#A8C7A1` |
+| 生活 | bean | `#F2D16B` |
+
+每位成员的头像是其记录的一部分，可在编辑器中修改；下表列出随附的头像。成员工作时眼睛向右上方移动。
+
+### Crew 区块与聊天标题
+
+区块使用 `sidebar.sections` 插槽，列出所有成员（包括空闲成员），成员工作中或需要你时显示状态标签。每位成员都有自己的对话：一个不属于任何 Workspace 的 Session，运行在 [crew-connections](../crew-connections/README.zh.md) 提供的成员文件夹中，首次打开时创建。点击一行会打开等待你的 Session，其次是正在运行的，否则是该成员自己的对话。**⋯** 菜单可打开其自己的对话、在任意 Workspace 中与该成员新建对话，或打开 **编辑成员**；标题旁的 **+** 用于添加成员。两者都会在 Crew 标签页中打开编辑器。折叠的轨道只显示头像，但仍为辅助技术和提示提供名称。
+
+徽标使用 `conversation.session.header.actions`。它显示 Session 运行的成员，以及从其子智能体目录读取的、该 Session 交付了工作的 crew 成员头像：先显示需要你处理的，再显示工作中的（眼睛会移动），最后显示已完成的（变暗）。超过四位时折叠为计数。当 Session 运行某位 crew 成员或已把工作交给某位成员时显示。
+
+### 连接
+
+在名册下方，Crew 标签页列出 crew 的 MCP 连接、各自的使用者以及文字状态。Google 需要 OAuth 客户端 ID 和密钥，然后 **使用 Google 登录** 打开 Google 的同意页面；GitHub 需要一个令牌。机密发送到 Host 凭据存储，从不回显：已保存的显示为已保存，可以替换或移除。无需密钥的服务器显示 **无需账户**，等待你批准的服务器显示 **在你批准前保持关闭**。
+
+### Crew 标签页
+
+在任意 Session 中从右侧面板的引导页打开 **Crew**。每行显示成员的头像、名称、文字状态（工作中、需要你或空闲）、Session 数量和一个 **新建会话** 按钮，用该成员的预设新建 Session。
+
+行上的 **编辑** 和列表下方的 **添加 crew 成员** 会打开编辑器：名称、负责的工作（幕僚长据此决定把工作交给谁）、说明、每条消息的工具调用次数（0 表示不限）、头像形状和颜色、文件访问、运行命令、获取网页、定时任务和连接。尚未批准账号的连接显示为关闭。幕僚长可以改名和修改说明，但不能移除，其工具也固定不变。**移除** 会再确认一次，过往对话会保留。保存后对新对话生效；正在运行的对话保持其启动时的设置。
+
+### Slack
+
+在连接下方，**Slack** 卡片为 [crew-slack](../crew-slack/README.zh.md) 保存 Slack 应用的令牌和你的成员 id，显示是否已连接，并列出等待你处理的回复。每条回复可以先编辑，再用 **发布回复** 发布或用 **舍弃** 丢弃；卡片打开时每 5 秒重新读取一次。
+
+### 学习
+
+在名册和连接之间，**学习** 列表显示 crew 成员通过 [crew-improve](../crew-improve/README.zh.md) 提出的经验。每条提议显示其成员、经验内容、引用的依据、来自评分还是对话及时间，以及将被替换的经验；用 **批准** 和 **拒绝** 处理。已批准的经验列出批准时间和 **移除** 按钮。列表打开时每 30 秒重新读取一次；不点击就不会有任何更改。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 实现原理
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+当 Session 列表中的 `agentPreset` 投影值等于成员的预设 ID 时，该 Session 属于此成员。只要成员的任一 Session 有待处理交互（如未回答的问题或审批），成员即为 `needs-you`；否则只要任一 Session 在运行即为 `working`；否则为 `idle`。`uiSession.sessionStatus` 的实时运行状态优先于列表的运行标记。名册快照在成员状态或 Session 列表变化前保持同一引用，因此 React 选择器只在真正变化时重新渲染。
+
+| 源文件 | 内容 |
+|---|---|
+| [`src/roster.ts`](src/roster.ts) | 状态汇总 |
+| [`src/client/index.ts`](src/client/index.ts) | 注册 |
+| [`src/client/crew-roster.ts`](src/client/crew-roster.ts) | `ctx.crew` 服务与打开对话 |
+| [`src/client/CrewPanel.tsx`](src/client/CrewPanel.tsx)、[`src/client/MemberEditor.tsx`](src/client/MemberEditor.tsx) | Crew 标签页与成员编辑器 |
+| [`src/client/CrewSection.tsx`](src/client/CrewSection.tsx) | 侧边栏区块 |
+| [`src/client/CrewLearning.tsx`](src/client/CrewLearning.tsx)、[`src/client/learning.ts`](src/client/learning.ts) | 学习列表及其存储 |
+| [`src/client/CrewHeader.tsx`](src/client/CrewHeader.tsx) | 聊天标题徽标 |
+| [`src/client/locales.ts`](src/client/locales.ts) | 名称、状态标签与标签页文案 |
+| [`tests/`](tests/) | 汇总与服务测试 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [crew-roster](../crew-roster/README.zh.md) — 存储的成员及其预设。
+- [crew-agents](../crew-agents/README.zh.md) — bundle。
+- [crew-faces](../crew-faces/README.zh.md) — 成员头像。
+- [ui-session](../../client/ui-session/README.zh.md) — Session 状态来源。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，本包是浏览器端名册，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送模型提供方请求。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 只计入浏览器 Session 列表中的 Session；列表未保留的委派子智能体不会改变其成员的状态。
+- 窗口重新获得焦点时会重新读取名册，因此在其他窗口或设备上的修改会在切回后显示。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作背景——点击展开</summary>
+
+无。
+
+</details>