dsh-plugin-agent-tree 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 未发布
+
+- **「等你拍板」的会话不再消失**：读实时状态里的 `pendingInteraction`（`question` / `approval` / `plan-review`），这类会话即使没在跑也会列出，琥珀色圆点 + `待答 / 待批 / 待审` 徽标，排在在跑的前面；标题栏变成「N 个等你处理 · M 个在跑 · K 个定时」。
+- **定时任务显示修复**：`remote.schedule` 是别的客户端插件挂上来的命名空间服务，只读 `ctx.remote.schedule` 在它还没挂上时会拿到 undefined，导致定时任务整段消失；现在用 `ctx.get('remote.schedule')` 兜底并继续轮询。
+- **codex 行名改成会话标题**：从 rollout 里取第一条真实用户消息（跳过 `environment_context` / `AGENTS.md` 注入）当行名，取不到才回落目录名；右侧加灰色目录小标签；同 cwd 的多个 codex 进程按时间各认领一条会话，避免多行同名。
+- **codex 的子对话**：读 `~/.codex/sessions/**/rollout-*.jsonl` 的 `session_meta`，按 `parent_thread_id` 还原 subagent 线程树，挂在 codex 行下面（昵称 + agent 路径 + 最后活动时间 / `running`）；按 cwd、cwd 前缀、桌面端 originator 三级匹配主线程。
+- 顶层改成「本机 agent 列表」：`dsh` 与 `claude` / `codex` 同级，各自展开自己的子树；行规格统一。
+
+## 0.1.0 — 2026-10-28
+
+首个公开版本。从「一个会话里翻着看 subagent 太累」长出来的一张小卡片。
+
+### 功能
+
+- **迷你 agent 树**：288px 浮动卡（`shell.overlay` 座位），根节点 `dsh` → `workspace` → `对话` → `subagent` → `孙代理`，`├─ └─ │` 连接线，只保留通往活跃分支的路径，`▾/▸` 逐级折叠。
+- **常驻入口**：空闲时自动收成一条窄条（`● Agent 树 ▸`），永不消失；有活儿自动展开。
+- **颜色编码**：顶层对话绿点、第 2 层 subagent 蓝点、第 3 层及更深紫点、已结束灰点。
+- **模型标签**：每行右侧显示该会话实际在用的模型（`projectionValues.modelSelection`，`next` → `lastUsed`），subagent 未记录时继承上级。
+- **定时任务**：读 `schedule.catalog() + schedule/changed`，间歇式工作的会话即使当前没在跑也列出，带 `⏱8m` 倒计时与「N 个定时」计数。
+- **外部 agent 进程（带子树）**：宿主半部只读接口 `GET /local/dsh-agent-tree/processes`，用 `ps` + `lsof` 发现本机正在跑的 `claude` / `codex` CLI，并按 `ppid` 把它们的子进程挂成子树（同类子进程归组成 `computer use ×4` / `MCP ×3` 这样的行）。它们和 `dsh` 是**同级的顶层 agent 节点**（本机 agent 列表），用同一套行规格，可折叠。
+- **点击跳转**：点任意一行 → `subagentAddress` + `uiWorkspace.openSession` 跳到对应会话（含 subagent）。
+- **拖动与记忆**：拖标题栏移动，位置存 `localStorage`。
+
+### 健壮性
+
+- 宿主路由：`webServer` 缺失则 warn 跳过、注册包 try/catch、只读 GET、复用 `connection.requestRejection` 鉴权（未登录 401）、`ps`/`lsof` 超时、结果缓存 3 秒、最多 8 条。
+- 客户端：没有 global props 时回落到轮询快照并自行订阅 `api-session/status`；`schedule` 服务缺失时静默跳过。
+- 客户端模块 id 与包名统一为 `dsh-plugin-agent-tree`（此前是本地 `@local/...`）。
+- 20 项本地校验（`node --test test/*.test.mjs` + `node verify/smoke.mjs`）。
+
+### 兼容
+
+- 验证于 DeepSeek Harness `0.2.1-rc.2`（Web profile）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuna (DSH Agent Tree)
+
+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.en.md

@@ -0,0 +1,118 @@
+# Agent Tree · a mini live tree of every DSH agent
+
+[简体中文](README.md) · English
+
+![Agent Tree: a 288px floating card that draws the dsh instance, workspaces, conversations and subagents as a real tree](docs/assets/screenshot.png)
+
+**Agent Tree** is a small observability plugin for the DeepSeek Harness (DSH) Web UI: a **288px wide floating card**
+in a corner that draws `dsh → workspace → conversation → subagent → grandchild` as a live tree with
+`git log --graph`-style connectors. Only branches that are **running or scheduled** are shown, so the card stays small;
+when nothing is happening it collapses to a one-line strip — and it never disappears.
+
+It solves one concrete annoyance: with many conversations open you have to click into each one to see what its
+subagents are doing. The DSH sidebar lists conversations, not agent lineage. This card shows **who is running,
+at which depth, on which model, for how long, and when its next scheduled run fires**.
+
+## Features
+
+- **The top level is an agent list** — `dsh` (this instance) and the local `claude` / `codex` processes are **siblings**, each expanding its own tree: `dsh → workspace → conversation → subagent → grandchild`, with `├─ └─ │` indentation and `▾ / ▸` collapse.
+- **Always-on entry** — idle collapses to `● Agent tree ▸`; work re-expands it; manual collapse wins.
+- **Color = depth** — green dot for top-level conversations, blue for level-2 subagents, violet for deeper ones, grey for finished rows.
+- **Per-row model chip** (right aligned) — from the session projection `modelSelection` (`next` → `lastUsed`), shortened to `v4.1-flash`; subagents without their own record inherit the parent's (tooltip says so).
+- **Scheduled-task countdown** — reads `schedule.catalog()` from Automation tasks (the `remote.schedule` service, with a `ctx.get` fallback while its namespace is not mounted yet); sessions driven by a schedule are listed even while idle, with `⏱8m / ⏱2h / ⏱3d` and a `N running · M scheduled` headline.
+- **Sessions that need your call come first** — when an agent asks a question, waits for an approval, or waits for a plan review (`pendingInteraction` = `question` / `approval` / `plan-review`), that row turns **amber**, carries a `待答 / 待批 / 待审` badge and **sorts above running rows**. Previously such a session disappeared because it was no longer running.
+- **Local external agent processes, also as a tree** — the plugin's host half exposes a read-only endpoint that finds running **claude / codex CLIs** via `ps` + `lsof` and nests their children by `ppid` (e.g. codex's `computer use ×4` / `MCP ×3` / `code mode`). They show up as **top-level agents next to `dsh`**, with exactly the same row spec. ChatGPT desktop's `Codex Framework` helpers are not mistaken for CLIs themselves.
+- **codex rows are named after their own session** — the first *real* user message from the rollout (skipping `environment_context` / `AGENTS.md` injections), e.g. `codex 推进一下能推进的任务…  devline`, falling back to the directory name; processes sharing one cwd claim distinct sessions, so rows never share a name.
+- **codex sub-conversations are visible too** — reads codex's own session records (`~/.codex/sessions/**/rollout-*.jsonl`, first `session_meta` line) and rebuilds its subagent threads by `parent_thread_id`, hanging them under the codex row: `● Hubble advance_review_logic running` / `● Carson review_nextarchive_code 16m前`. Local read-only, no network, nothing leaves the machine. (Claude's sidechain layout differs and is not parsed yet.)
+- **Click to jump** — `subagentAddress()` + `uiWorkspace.openSession()`, including subagents.
+- **Draggable, remembers its position** — stored in `localStorage`.
+
+## Install in 3 minutes
+
+Prerequisites: Node.js `^22.19 or ≥ 24` (same as the DSH runtime), pnpm 10+, DSH `≥ 0.2.1-rc.2 < 0.3` (verified on `0.2.1-rc.2`).
+
+```sh
+# 1) a dedicated profile (or reuse your existing web profile)
+dsh --profile agent-tree --from-default-profile web
+
+# 2) install from npm
+dsh plugin --profile agent-tree add dsh-plugin-agent-tree
+
+# 3) start
+dsh --profile agent-tree --port 13090
+```
+
+**Restart `dsh` once after installing** (the host half registers the process endpoint), then hard-refresh the browser (`Cmd/Ctrl + Shift + R`).
+
+```sh
+# existing profile
+dsh plugin --profile web add dsh-plugin-agent-tree
+# from GitHub source
+dsh plugin --profile web add "github:yuna78/dsh-agent-tree"
+# local development
+dsh plugin --profile web add "$PWD"
+```
+
+> Details, uninstall and troubleshooting: [docs/install.en.md](docs/install.en.md). What every element means: [docs/manual.en.md](docs/manual.en.md).
+
+## Reading the card
+
+| What you see | Meaning |
+|---|---|
+| `● 5 个 agent 在跑 · 2 个定时` | 5 sessions/subagents are running; 2 more are schedule-driven (may be idle right now) |
+| `▾ ● dsh  2 个 workspace` | one local agent — this DSH instance; workspace count on the right |
+| `├─ ▾ proj-alpha  2` | workspace group, count on the right |
+| `├─ ▾ ● Refactor billing flow  ⏱8m  v4.1-pro` | top-level conversation running (green), next scheduled run in 8 min, on v4.1-pro |
+| `│  ├─ ● Explore repo structure  v4.1-flash  1m5s` | its subagent (blue), running for 1m05s |
+| `│  │  └─ ● Run unit tests  v4.1-flash  9s` | grandchild agent (violet) |
+| `├─ ● claude  proj-alpha        12m 3%` | a local claude CLI process in `proj-alpha`, 12 min, 3% CPU |
+| `会话 6 · 子代理 3 · 运行中 5（live）` | self-check line: sessions / subagents / running; `live` = official realtime status stream |
+
+The UI strings are Chinese for now (DSH itself is Chinese-first); a locale pass is welcome — the copy lives in one
+`labels` object in `client.js`.
+
+Click a row to jump to that session; drag the header to move the card; click `▾/▸` to collapse.
+
+## Where the data comes from
+
+Only public client-side UI contracts — no host patching, no database access:
+
+| Info | Source |
+|---|---|
+| sessions + parent/child | `useSessions()` → `ids / byId` (`parentId`, `origin`) |
+| live running state | `useSessionStatus()`; falls back to polling + `$on('api-session/status')` |
+| workspace ownership | `ctx.workspaces.list.getSnapshot()` |
+| duration / model | `projectionValues.subagentTiming`, `projectionValues.modelSelection` |
+| scheduled tasks | `ctx.remote.schedule.catalog()` + `$on('schedule/changed')` |
+| jumping | `ctx.sessions.subagentAddress()` + `ctx.uiWorkspace.openSession()` |
+| external processes | host half: `GET /local/dsh-agent-tree/processes` |
+
+## External process monitoring: scope and limits
+
+- **Read-only**: `ps -axo pid=,etime=,pcpu=,command=` + `lsof -a -p <pid> -d cwd -Fn`. No signals, no output capture.
+- **Real CLIs only**: the executable basename must be exactly `claude` or `codex`; ChatGPT desktop helper processes are excluded.
+- **Endpoint guards**: same-origin, reuses DSH connection auth (401 without a session), GET only (405 otherwise), timeouts on `ps`/`lsof`, 3s cache, max 8 rows; if the `webServer` service is missing it only warns and never blocks DSH startup.
+- **Platforms**: macOS / Linux. On Windows the block stays empty (the tree itself still works).
+- Disable it by removing the plugin from the profile — the client card simply loses that section.
+
+## Compatibility
+
+| Item | Range |
+|---|---|
+| DSH | `>= 0.2.1-rc.2 < 0.3.0` (verified `0.2.1-rc.2`, Web profile) |
+| Node.js | `^22.19.0 \|\| >= 24.0.0` |
+| Platform | DSH Web (client seat `shell.overlay`); process block macOS/Linux |
+
+## Development
+
+```sh
+npm test                              # unit tests (tree / model / schedule / process parsing)
+npm run verify                        # package contract + seats + data sources + privacy + tests
+node scripts/build-public-bundle.mjs  # whitelisted public copy with a privacy scan
+```
+
+Editing `client.js` needs only a hard refresh; editing `index.js` (host half) needs a `dsh` restart.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# Agent Tree · DSH 迷你 agent 树
 
-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.
+简体中文 · [English](README.en.md)
+
+![Agent Tree：一张 288px 的常驻小卡，把 dsh、workspace、对话、subagent 画成真树](docs/assets/screenshot.png)
+
+**Agent Tree** 是 DeepSeek Harness（DSH）Web 端的可观测性小插件：右下角一张 **288px 宽的浮动卡**，
+用 `git log --graph` 那种连接线，把 `dsh → workspace → 对话 → subagent → 孙代理` 实时画出来。只显示
+**正在干活或有定时任务的分支**，所以卡永远小；没有活儿时自动收成一条窄条，但不会消失。
+
+解决的问题很具体：对话一多，就得挨个会话切进去看「这个 subagent 到底在干什么」。DSH 侧栏只列会话，
+不列 agent 谱系；Activity 面板要么太大、要么和当前 rc 版本不兼容。这张卡补上这块——**一眼看到谁在跑、
+跑在哪个层级、用哪个模型、跑了多久、下一步什么时候自动来**。
+
+## 有什么
+
+- **顶层就是 agent 列表**：`dsh`（这个实例）和本机的 `claude` / `codex` 是**同级**的顶层节点，各自往下展开自己的树：`dsh → workspace → 对话 → subagent → 孙代理`；`├─ └─ │` 逐层缩进；`▾ / ▸` 逐级折叠。
+- **常驻入口**：空闲自动收成 `● Agent 树 ▸` 一条窄条，有活儿自动展开；手动折叠优先于自动折叠。
+- **颜色即层级**：顶层对话绿点、第 2 层 subagent 蓝点、第 3 层及更深紫点、已结束灰点。
+- **每行右侧模型标签**：读会话投影 `modelSelection`（`next` → `lastUsed`），压成 `v4.1-flash` 这类短标签；
+  subagent 没有自己的记录时继承上级（悬停会标注）。
+- **定时任务倒计时**：读 Automation tasks 的 `schedule.catalog()`（服务名 `remote.schedule`，命名空间没挂上时用
+  `ctx.get` 兜底），间歇式工作的会话**即使现在没在跑也会列出**，右侧显示 `⏱8m / ⏱2h / ⏱3d`。
+- **需要你拍板的会话来最上面**：agent 提问、等你批准操作、等你审阅计划时（`pendingInteraction` = `question` /
+  `approval` / `plan-review`），那一行**换成琥珀色**、带 `待答 / 待批 / 待审` 小徽标，并且**排在在跑的之前**——
+  以前这类会话因为「没在跑」会直接消失。
+- **本机外部 agent 进程（也是树）**：插件宿主半部提供只读接口，用 `ps` + `lsof` 找到本机正在跑的 **claude / codex CLI**，
+  再按 `ppid` 把它们的子进程挂成子树（如 codex 的 `computer use ×4` / `MCP ×3` / `code mode`）。它们是**和 `dsh` 同级的顶层 agent 节点**，行规格完全一致，可折叠。
+  ChatGPT 桌面端里的 `Codex Framework` 辅助进程本身不会被误认成 CLI。
+- **codex 的行名是它自己的会话标题**：从 rollout 里取第一条**真实**用户消息（跳过 `environment_context` /
+  `AGENTS.md` 这类上下文注入）当行名，比如 `codex 推进一下能推进的任务…  devline`；取不到才回落到目录名。
+  多个 codex 进程同 cwd 时会各认领一条会话，不会三行同名。
+- **codex 的子对话也看得见**：读 codex 自己的会话记录（`~/.codex/sessions/**/rollout-*.jsonl` 的第一行
+  `session_meta`），按 `parent_thread_id` 还原它的 subagent 线程树，挂在 codex 那行下面——
+  `● Hubble advance_review_logic  running` / `● Carson review_nextarchive_code  16m前`。
+  只读本机文件、不联网、不外发。（claude 的 sidechain 结构不同，暂未解析。）
+- **点一行就跳过去**：`subagentAddress(id)` + `uiWorkspace.openSession()`，连 subagent 也能直接落到它的对话。
+- **拖动 + 位置记忆**：拖标题栏移动，位置存 `localStorage`，下次还在原处。
+
+## 3 分钟安装
+
+前置：Node.js `^22.19 或 ≥24`（与 DSH 运行时一致）、pnpm 10+、DSH `≥ 0.2.1-rc.2 < 0.3`（已验证 `0.2.1-rc.2`）。
+
+```sh
+# 1) 建一个专用 profile（也可以装到现有的 web profile）
+dsh --profile agent-tree --from-default-profile web
+
+# 2) 从 npm 安装
+dsh plugin --profile agent-tree add dsh-plugin-agent-tree
+
+# 3) 启动
+dsh --profile agent-tree --port 13090
+```
+
+**装完必须重启一次 `dsh`**（宿主半部注册了进程接口），然后浏览器硬刷新（`Cmd/Ctrl + Shift + R`）。
+
+其他安装方式：
+
+```sh
+# 装到已有 profile
+dsh plugin --profile web add dsh-plugin-agent-tree
+
+# 从 GitHub 源码装
+dsh plugin --profile web add "github:yuna78/dsh-agent-tree"
+
+# 本地开发（本仓库路径）
+dsh plugin --profile web add "$PWD"
+```
+
+> 细节、卸载、排查见 [安装与配置](docs/install.md)；每块 UI 是什么意思见 [使用手册](docs/manual.md)。
+
+## 怎么用
+
+| 你看到的 | 意思 |
+|---|---|
+| `● 1 个等你处理 · 5 个在跑 · 2 个定时` | 有 1 个会话在等你拍板（提问/审批/计划审阅），5 个在跑，2 个由定时任务驱动 |
+| `├─ ● 智力研发团队 1  待答  v4.1-pro` | 这一行**要你决定**：琥珀色圆点 + `待答` 徽标，排在在跑的会话之前 |
+| `▾ ● dsh  2 个 workspace` | 本机上的一个 agent：当前这个 DSH 实例，右上是它的 workspace 数 |
+| `├─ ▾ proj-alpha  2` | workspace 分组，右上是它下面列出的分支数 |
+| `├─ ▾ ● Refactor billing flow  ⏱8m  v4.1-pro` | 顶层对话在跑（绿点），8 分钟后有下一次定时，用 v4.1-pro |
+| `│  ├─ ● Explore repo structure  v4.1-flash  1m5s` | 它的 subagent（蓝点），已跑 1 分 05 秒 |
+| `│  │  └─ ● Run unit tests  v4.1-flash  9s` | 孙代理（紫点） |
+| `▾ ● codex 推进一下能推进的任务…  devline` | codex 的**会话标题**（首条真实用户消息）+ 目录名；不是目录名兜底 |
+| `▾ ● claude proj-alpha         12m 3%` | 本机另一个 agent（和 `dsh` 同级）：claude CLI，工作目录 `proj-alpha`，跑了 12 分钟、3% CPU |
+| `│  └─ computer use ×2            41m` | 它的子进程，自动按种类归组（`×N` + 最长的那个时长） |
+| `│  ├─ ● Hubble advance_review_logic  running` | codex 的子对话（subagent 线程）：昵称 + agent 路径，右边是「正在工作 / 最后活动多久前」 |
+| `会话 6 · 子代理 3 · 运行中 5（live）` | 自检：快照里的会话数 / 子代理数 / 运行中数量；`live` 表示官方实时状态流 |
+
+- 点任意一行 → 跳到对应会话（subagent 会跳到它自己的对话）。
+- 拖标题栏 → 换位置；点 `▾/▸` → 折叠；`localStorage` 里的 `dsh-agent-tree:pos` 存位置。
+- 卡宽度固定 288px，高度随内容自适应，最多 48 行。
+
+## 数据从哪来
+
+全部走 DSH 客户端公开的 UI 契约，不 patch 宿主、不读数据库：
+
+| 信息 | 来源 |
+|---|---|
+| 会话、父子关系 | `useSessions()` → `ids / byId`，行上的 `parentId`、`origin` |
+| 实时 running | `useSessionStatus()`；拿不到全局 props 时回落到轮询快照 + `$on('api-session/status')` |
+| workspace 归属 | `ctx.workspaces.list.getSnapshot()` |
+| 耗时 / 模型 | `projectionValues.subagentTiming`、`projectionValues.modelSelection` |
+| 定时任务 | `ctx.remote.schedule.catalog()` + `$on('schedule/changed')` |
+| 跳转 | `ctx.sessions.subagentAddress()` + `ctx.uiWorkspace.openSession()` |
+| 外部进程 | 宿主半部 `GET /local/dsh-agent-tree/processes` |
+
+## 外部进程监控：范围与边界
+
+- **只读**：`ps -axo pid=,etime=,pcpu=,command=` + `lsof -a -p <pid> -d cwd -Fn`，不碰进程、不发信号、不读它输出。
+- **只认真 CLI**：可执行文件 basename 必须精确是 `claude` 或 `codex`；ChatGPT.app 里的 `Codex Framework`
+  助手 / crashpad 进程被排除（它们会误报成 8 条一样的记录）。
+- **接口护栏**：同源、复用 DSH 连接层鉴权（未登录 401）、只读 GET（其它方法 405）、`ps`/`lsof` 都有超时、
+  结果缓存 3 秒、最多返回 8 条；`webServer` 服务缺失时只 warn 跳过，不会阻断 DSH 启动。
+- **平台**：macOS / Linux 可用；Windows 没有 `ps -axo` 语义，这段自然为空（树本身照常工作）。
+- 想关掉：删掉 profile 里 `dsh-plugin-agent-tree` 这一项即可，客户端不受影响（进程段自动消失）。
+
+## 兼容
+
+| 项目 | 范围 |
+|---|---|
+| DSH | `>= 0.2.1-rc.2 < 0.3.0`（已验证 `0.2.1-rc.2`，Web profile） |
+| Node.js | `^22.19.0 \|\| >= 24.0.0` |
+| 平台 | DSH Web（客户端座位 `shell.overlay`）；外部进程段 macOS/Linux |
+
+## 开发
+
+```sh
+npm test                              # 单测（树构建 / 模型 / 定时 / 进程解析）
+npm run verify                        # 契约 + 座位 + 数据源 + 隐私 + 单测，全绿才算过
+node scripts/build-public-bundle.mjs  # 生成公开仓内容（白名单 + 隐私扫描，0 命中才放行）
+```
+
+改 `client.js` 只需浏览器硬刷新；改 `index.js`（宿主半部）需要重启 `dsh`。
+
+## License
+
+[MIT](LICENSE)