dsh-as-mcp 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -6,6 +6,52 @@ plugin is pre-1.0, so a minor bump is a feature and a patch is a fix or docs.
 A Chinese summary of every release lives in [CHANGELOG.zh.md](./CHANGELOG.zh.md);
 this file stays the authoritative record.
 
+## 0.55.0
+
+- Three new tools in the `session` group — `session_command_list`, `session_command` and
+  `session_goal` — bring the surface from 35 to 38 (the group from 18 to 21). A slash command
+  executes **without a model turn** (the registry parses the line and invokes the handler directly),
+  so `session_command` is the cheap half of "do what a human typing into the DSH composer would
+  do": compact a long session, export its log, enter plan mode or set a goal. `session_command_list`
+  reports every command the session's agent can see, with its description and input hint, and marks
+  each `permitted` instead of hiding the refused ones; `session_command` takes the line with or
+  without its leading slash and with arguments in the same string (`"compact"`, `"/export"`,
+  `"/goal <objective>"`, `"/plan off"`), and the run goes through the harness's own command
+  registry, so it is the same execution a human typing the line produces (the reply carries the
+  harness's `commandId`, `ok`, the handler's `text` and the `sourceEventSeq` it recorded). The
+  admitted set is explicit — `/compact`, `/plan`, `/goal`, `/export` — not "anything the registry
+  lists": `/permission` would change the session's permission preset (a remote caller must not
+  escalate its own session) and `/feedback` writes the user's own review records, so both are
+  refused **before** any handler runs — a refused call writes nothing to the session log — and an
+  unknown name is refused with the admitted set listed. A handler that reports an error comes back
+  as `ok: false` with its text, while a name/argument the registry did not admit is an error saying
+  nothing was logged.
+- `session_goal` reads and mutates the session's **durable goal** — the long-running objective the
+  harness's round driver keeps advancing across turns, which is how a caller delegates multi-hour
+  work instead of holding one turn open. `action` is `get` (the goal, or `null`) or
+  `create`/`edit`/`pause`/`resume`/`complete`/`clear`; `create` needs `objective`, `edit` needs
+  `objective` and/or `maxGoalRounds`, and every other action acts on the goal that exists now, so
+  its ref comes from a read rather than from the caller. `expectedRevision` (from a previous read) is
+  the lost-update guard: a mutation whose goal changed underneath — say the user edited it in the DSH
+  UI a moment ago — is refused instead of silently applied, the same spirit as the UI's conflict
+  handling. A goal reports `id`, `revision`, `objective`, `phase` (`active`/`paused`/`blocked`/
+  `complete`), `activation` (`armed`/`disarmed`), `maxGoalRounds`, `roundsStarted`, `blockedReason`
+  when blocked and its timestamps; `clear` returns `goal: null` with `cleared: true`, and `complete`
+  returns the completed goal.
+- `dsh_info.harnessServices` reports two more probes, `commands` and `goals` (29 in total, up from
+  27), and `toolAvailability` pre-flights the three tools against `sessionController` +
+  `sessionController.resolveAgent` plus the matching service, so an agent-scoped command or goal
+  service that a profile does not mount is reported unavailable instead of failing at call time.
+  `dsh_info.notes` gains one paragraph per surface: commands run without a model turn and only the
+  user-plane set is admitted, and goal mutations carry the harness's revision guard.
+- No new configuration keys: push, the two transports, the tool groups and the settings panel are
+  unchanged. Both READMEs gain the three tool rows, a "Session orchestration" flow and a
+  deployment-requirements row; `docs/CAPABILITY-GAPS.md` is re-counted to 38 tools and 29 probes and
+  marks slash commands and durable goals as shipped, with `resolveAgent` named as the bridging layer.
+  `tests/orchestration.test.ts` pins the new driver surface (allow-list before the handler, slash
+  normalization, the revision guard, projection of the goal view) and `tests/mcp-endpoint.test.ts`
+  the argument passthrough; `tests/availability.test.ts` covers the new pre-flight rules.
+
 ## 0.54.0
 
 - Server push now covers the whole run instead of one turn-ending signal. The existing

package/CHANGELOG.zh.md

@@ -6,6 +6,13 @@
 - 两份文件的**版本标题必须完全一致**（集合与顺序），由 `tools/check-docs.mjs` 强制检查——发布时漏写中文条目会让检查失败，中文读者不会悄悄落后一个版本。
 - 版本号遵循 SemVer；项目仍是 pre-1.0，所以 minor 是功能，patch 是修复或文档。
 
+## 0.55.0
+
+- 新增 3 个工具（`session_command_list`、`session_command`、`session_goal`），工具面从 35 增至 38，仍全在 session 组（该组从 18 增至 21）。斜杠命令**不消耗模型轮次**（注册表解析命令行后直接调用 handler），所以 `session_command` 就是「替人在 DSH 输入框里敲命令」的便宜一半：压缩长会话、导出日志、进入 plan 模式、设置目标。`session_command_list` 报出该会话 agent 能看到的全部命令（描述与输入提示），并用 `permitted` 标出本端点会执行哪些，而不是把被拒绝的隐藏掉；`session_command` 接受带或不带前导斜杠的命令行、参数写在同一字符串里（`"compact"`、`"/export"`、`"/goal <objective>"`、`"/plan off"`），执行走 harness 自己的命令注册表，与真人敲同一行的执行完全一致（回复带 harness 的 `commandId`、`ok`、handler 的 `text`，以及它记录的 `sourceEventSeq`）。放行集是显式的 `/compact`、`/plan`、`/goal`、`/export`，而不是「注册表里有什么就运行什么」：`/permission` 会改变会话的权限 preset（远程调用方不能给自己提权），`/feedback` 会写入用户自己的评审记录，两者在**任何 handler 运行之前**就被拒绝——被拒调用不向会话日志写任何东西；未注册的名字会被拒绝并列出放行集。handler 报错时返回 `ok: false` 与文本，注册表未接收的名字/参数返回「什么都没写进日志」的错误。
+- `session_goal` 读取和修改会话的**持久目标**——harness 的轮次驱动会在多轮之间持续推进的长期目标，调用方因此可以委派多小时的任务，而不必一直挂着一轮。`action` 取 `get`（返回目标或 `null`）或 `create`/`edit`/`pause`/`resume`/`complete`/`clear`；`create` 需要 `objective`，`edit` 需要 `objective` 和/或 `maxGoalRounds`，其余动作作用于当前存在的目标，其 ref 来自一次读取而不是调用方。`expectedRevision`（来自上一次读取）是丢失更新保护：目标在脚下被改过（比如用户刚在 DSH 界面里编辑过）就拒绝，而不是悄悄覆盖——与界面冲突处理同一思路。目标报出 `id`、`revision`、`objective`、`phase`（`active`/`paused`/`blocked`/`complete`）、`activation`（`armed`/`disarmed`）、`maxGoalRounds`、`roundsStarted`、被阻塞时的 `blockedReason` 与时间戳；`clear` 返回 `goal: null`（`cleared: true`），`complete` 返回已完成的目标。
+- `dsh_info.harnessServices` 新增 `commands` 与 `goals` 两个探针（共 29 个，原为 27 个）；`dsh_info.toolAvailability` 对三个新工具做预检，要求 `sessionController` + `sessionController.resolveAgent` 以及对应的 commands/goals 服务，缺能力的 profile 会把它们报成不可用，而不是等到调用时才失败；`dsh_info.notes` 各增一段（命令不消耗轮次且只放行用户面集合；目标修改带 harness 的 revision 保护）。
+- 无新增配置键：推送、两种传输、工具组与设置面板均不变。两份 README 增加三行工具表、「会话编排 / Session orchestration」流程与部署要求行；`docs/CAPABILITY-GAPS.md` 的工具数/探针数更新为 38/29，并把斜杠命令与持久目标两条差距标记为已交付、点名 `resolveAgent` 是打通它们的桥。`tests/orchestration.test.ts` 钉住新驱动面（handler 之前的 allow-list、斜杠归一化、revision 保护、目标投影），`tests/mcp-endpoint.test.ts` 钉住参数透传，`tests/availability.test.ts` 覆盖新的预检规则。
+
 ## 0.54.0
 
 - 服务端推送从「只报一轮结束」扩展到整场运行，仍走现有的 `subscriptions/listen` 流，且不新增任何工具（工具面仍是 35 个）：`dsh://sessions`（会话增删、活动/状态、subagent 起止）、`dsh://session/<id>/events`（最新持久事件投影为 `{seq, type, at, turn, step, summary, error}`，每次追加都发布，单次读取至多 64 条）、`dsh://session/<id>/assistant`（实时 `start`/`text`/`reasoning`/`tool`/`finish`/`end` 帧，`seq` 每会话单调递增）、`dsh://session/<id>/status`（与 `session_status` 同负载）、`dsh://session/<id>/projections`（白名单内的 `workingDirectory`/`worktree`/`goal`/`plan`/`todos`/`agentPreset`/`title`）、`dsh://jobs` 与 `dsh://jobs/<id>`（后台 shell 任务；任务尾部读取不消费，不会抢走 `shell_output` 的字节）。0.52.86 的 `dsh://session/<id>/turn` 结算资源保留，成为整个 feed 集合中的一项。`resources/list`/`resources/templates/list` 会公布这些 feed，`dsh_info.notes` 也会点名它们。

package/README.md

@@ -252,6 +252,9 @@ schema-aware client can read the object directly instead of parsing JSON out of
 | `session_unarchive` | Return an archived session to its recorded position in the DSH UI. Idempotent: an id that is not archived is not an error, and the log was never touched, so the session is visible and promptable again. |
 | `session_pin` | Pin a session to the top of the DSH UI's session list (the same pin set the sidebar writes). The session must exist and must not be archived; pinning is idempotent. |
 | `session_unpin` | Remove a session from the DSH UI's pin set. Idempotent: an id that is not pinned is not an error. |
+| `session_command_list` | The slash commands this session's agent can run — each with a one-line description, an optional `input` hint and a `permitted` flag — so a caller can see that a command exists while this endpoint deliberately will not run it (the admitted set is `/compact`, `/plan`, `/goal`, `/export`; `/permission` and `/feedback` are refused on purpose). A command executes without a model turn — the handler is invoked directly — which makes this the cheap way to compact a long session, export its log, enter plan mode or set a goal, exactly as a human typing into the DSH composer would. Read-only; run one with `session_command`. |
+| `session_command` | Execute one slash command against a session's agent without spending a model turn, as if the human had typed it into the DSH composer: give the `command` with or without its leading slash, with its arguments in the same string (`"compact"`, `"/export"`, `"/goal <objective>"`, `"/plan off"`). The run goes through the harness's own command registry, so it is the same execution a human typing the line produces and the session log records it; the reply carries the harness's `commandId`, `ok` (`false` when the handler itself reported an error result), the handler's `text` and the `sourceEventSeq` it recorded when it reported one. Only the user-plane commands are admitted (`/compact`, `/plan`, `/goal`, `/export`); `/permission` (which would change the session permission preset) and `/feedback` (which would write the user's own review records) are refused before any handler runs, so a refused call writes nothing to the session log, and a name that is not registered on this profile is refused with the admitted set listed. A name or argument the registry did not admit is an error saying nothing was logged. Call `session_command_list` first to see the exact names and the input hint this agent accepts. |
+| `session_goal` | Read or mutate the session's durable goal — the long-running objective the harness's round driver keeps advancing across turns, which is how a caller delegates multi-hour work instead of holding one turn open. `action` is `get` (which returns the `goal` or `null`), or one of `create` (needs `objective`), `edit` (needs `objective` and/or `maxGoalRounds`), `pause`, `resume`, `complete`, `clear`; every action except `create` acts on the goal that exists now, so its ref comes from a read rather than from the caller. Pass `expectedRevision` (from a previous read) to refuse a mutation whose goal changed underneath you — the equivalent of the DSH UI's conflict handling. A goal reports `id`, `revision`, `objective`, `phase` (`active`/`paused`/`blocked`/`complete`), `activation` (`armed`/`disarmed`), `maxGoalRounds`, `roundsStarted`, `blockedReason` when blocked, and `createdAt`/`updatedAt`; `clear` returns `goal: null` (and `cleared: true`), while `complete` returns the completed goal. |
 | `session_usage` | Token usage per session (its subagents included by default): exact bucket counts, a per-model breakdown, optional per-turn detail, and money when a price plugin is installed. Pass `sessionIds` to tally several known sessions in one receipt, or `cwd` to total every session that ran in one workspace directory. |
 | `file_read` | Read a UTF-8 file through DSH's filesystem service. Bounded by a byte limit; `offset`/`nextOffset` page through a larger file (both are **byte** offsets, so an offset at or past EOF is an empty complete read), `maxBytes` asks for a smaller window so reading a slice costs less, and `sha256: true` returns the whole file's hash as the compare-and-swap value for a later write/edit. |
 | `file_read_image` | Read an image (png/jpeg/gif/webp/bmp, detected from the bytes) and return it as an MCP image block, preceded by a metadata block (path, mimeType, bytes), so you can look at a screenshot or chart instead of guessing. Capped at 8 MiB. |
@@ -311,6 +314,33 @@ refused *and* hidden from `dsh_tool_list`. The omissions that matter:
 An operator can widen this deliberately with the `agentTools.allow` setting, or subtract from
 the default with `agentTools.deny`.
 
+### Session orchestration
+
+Some work is not a single prompt. Compacting a long session, exporting its log, entering plan mode or
+setting a goal are user-plane actions a human performs by typing a slash command into the DSH
+composer; a durable goal also turns a one-turn request into an objective the harness's round driver
+keeps advancing across turns. Neither path costs a model turn of its own. The intended flow:
+
+```
+session_command_list { sessionId }                                    # what this agent accepts; permitted marks the admitted set
+  -> session_command { sessionId, command: "/compact" }               # run one; no model turn
+  -> session_goal { sessionId, action: "create", objective: "Finish the migration", maxGoalRounds: 20 }
+  -> session_goal { sessionId, action: "get" }                        # poll phase/revision...
+     or subscribe to dsh://session/<id>/projections                   # ...or be told when the goal changes
+  -> session_goal { sessionId, action: "pause", expectedRevision: 3 } # then resume / complete / clear
+```
+
+`session_command_list` reports each entry's `permitted` flag instead of hiding the refused commands, so
+a caller can see that `/permission` and `/feedback` exist on the profile and that this endpoint
+deliberately will not run them: `/permission` would change the session's permission preset and
+`/feedback` would write the user's own review records, and neither reaches a handler or writes anything
+to the session log. `session_status` reports the session's turn and log state, not the goal itself; the
+goal's phase and revision come from `session_goal { action: "get" }`, and the
+`dsh://session/<id>/projections` feed (which includes `goal`) publishes when it changes, so following a
+goal is a poll or a subscription rather than a prompt per turn. A mutation without `expectedRevision`
+acts on the goal that exists at that moment; pass the revision a read returned when two supervisors
+could race.
+
 ## Worktrees
 
 A session can work in its own Git checkout of the same repository. The operation is the one the
@@ -361,7 +391,7 @@ An MCP server cannot call a client on its own, so every "something changed" trav
 resource notification. This endpoint publishes one change-feed surface over both standard push
 channels, and each notification is **payload-less**: it names a synthetic resource, and the
 client reads that resource for the JSON. No tools were added for this — the surface is still the
-35 in the table above — and push has no configuration key: it is always on and costs nothing
+38 in the table above — and push has no configuration key: it is always on and costs nothing
 while nobody subscribes.
 
 | Client era | Handshake | Server→client channel | How push is requested |
@@ -1007,6 +1037,7 @@ but a deployment can switch the capability off.
 | `worktree_create` / `worktree_restore` / `session_create { worktree }` | `worktrees` **and** `sessionController.resolveAgent` | the forge bundle in DSH Desktop/Web provides the service (`@deepseek-ai/dsh-experimental-forge-bundle`); a bare profile has none, `dsh_info.toolAvailability` reports the tools unavailable, and `session_create { worktree }` is refused before the session exists. Git and Node must exist in the session's execution world |
 | `session_status.workingDirectory` / `session_status.worktree` / `session_list { includeWorktree }` | readable session projections (`sessionController.projections` or `sessionQuery.observeSession`) | optional: without them both replies omit those two fields and the rest is unchanged |
 | `session_archive` / `session_unarchive` / `session_pin` / `session_unpin` | `workspaceRegistry.archiveSession` / `pinSession` | the same registry sets the DSH sidebar's actions write; if the methods are missing the tools are reported unavailable |
+| `session_command_list` / `session_command` / `session_goal` | `sessionController.resolveAgent` **and** `commands` / `goals` | both services are agent-scoped, so the session's live agent is the bridge; a profile without them reports the three tools unavailable in `dsh_info.toolAvailability`, and each call names the missing service and the bundle that provides it |
 | `workspace_*` | `workspaceRegistry` | provided by the base bundle in normal profiles |
 | `file_*` | `fs` | the deployment's sandbox policy still applies; `file_read_image` additionally needs a supported image format |
 | `shell_*` | `shell` | `shell_run` uses `run()` when present and `execute()` otherwise; background jobs need `start()` or `execute()` |
@@ -1180,14 +1211,14 @@ build:
 
 | Tool groups enabled | Tools advertised | Last result |
 | --- | --- | --- |
-| all six | 35 | live-checks 195/195 with `--with-model --with-subagent` and acceptance 166/166 — one boot, search index open |
-| `session`, `usage` only | 20 | live-checks 95/95 with `--with-model` (file/shell/workspace sections skip) |
-| `workspace`, `session`, `agentTools`, `usage` | 25 | live-checks 64/64 (a disabled group's reason names its `tools.<group>` switch) |
+| all six | 38 | live-checks 195/195 with `--with-model --with-subagent` and acceptance 166/166 — one boot, search index open |
+| `session`, `usage` only | 23 | live-checks 95/95 with `--with-model` (file/shell/workspace sections skip) |
+| `workspace`, `session`, `agentTools`, `usage` | 28 | live-checks 64/64 (a disabled group's reason names its `tools.<group>` switch) |
 | `files`, `shell` only | 11 | live-checks 68/68 (session/usage/queue/search sections skip) |
 
-The advertised counts are the current surface (0.53.0: 18 session-group tools and 35 overall); the
-last-result column records runs made against 0.52.86, before the six new tools, and has not been
-re-measured for this release.
+The advertised counts are the current surface (0.55.0: 21 session-group tools and 38 overall); the
+last-result column records runs made against 0.52.86, before the 0.53.0 additions, and has not been
+re-measured since.
 
 A fifth shape, `mountonly`, boots with `http.enabled: false` and `mountOnWebServer: true` and
 checks the endpoint over DSH's own web server: 109/109, all cheap, including the assertions that

package/README.zh.md

@@ -237,6 +237,9 @@ scheme 可以省略：`127.0.0.1:8790/mcp` 也能识别。
 | `session_unarchive` | 把归档的会话放回它在 DSH 界面里记录的位置。幂等：对未归档的 id 不算错误；日志从未被动过，因此会话重新可见、可继续 prompt。 |
 | `session_pin` | 把会话置顶到 DSH 界面的会话列表（与侧边栏置顶写入同一个 pin 集合）。会话必须存在且未归档；置顶幂等。 |
 | `session_unpin` | 把会话从 DSH 界面的 pin 集合里移除。幂等：对未置顶的 id 不算错误。 |
+| `session_command_list` | 列出该会话 agent 能运行的斜杠命令——每条带一句描述、可选的 `input` 提示与 `permitted` 标记——因此调用方能看到某个命令存在、而本端点故意不运行它（放行集是 `/compact`、`/plan`、`/goal`、`/export`；`/permission` 与 `/feedback` 刻意拒绝）。命令**不消耗模型轮次**（直接调用 handler），所以这是压缩长会话、导出日志、进入 plan 模式或设置目标最便宜的办法——与人在 DSH 输入框里敲命令完全一致。只读；用 `session_command` 运行其中一条。 |
+| `session_command` | 对会话的 agent 执行一条斜杠命令，不花模型轮次，就像人真的在 DSH 输入框里敲了它：`command` 可带可不带前导斜杠，参数写在同一字符串里（`"compact"`、`"/export"`、`"/goal <objective>"`、`"/plan off"`）。执行走 harness 自己的命令注册表，因此与真人敲同一行的执行完全一致，会话日志也会记录；回复带 harness 的 `commandId`、`ok`（handler 自己报告错误结果时为 `false`）、handler 的 `text`，以及它报告时记录的 `sourceEventSeq`。只放行用户面命令（`/compact`、`/plan`、`/goal`、`/export`）；`/permission`（会改变会话的 permission preset）与 `/feedback`（会写入你自己的评审记录）在任何 handler 运行之前就被拒绝，因此被拒调用**不会向会话日志写入任何东西**；本 profile 未注册的命令名会被拒绝并列出放行集。注册表没有接收的名字或参数返回错误并说明什么都没写进日志。先调 `session_command_list` 看该 agent 接受的确切名字与输入提示。 |
+| `session_goal` | 读取或修改会话的持久目标（durable goal）——即 harness 的轮次驱动会在多轮之间持续推进的长期目标，调用方因此可以委派多小时的任务，而不必一直挂着一轮。`action` 取 `get`（返回 `goal` 或 `null`），或 `create`（需要 `objective`）、`edit`（需要 `objective` 和/或 `maxGoalRounds`）、`pause`、`resume`、`complete`、`clear` 之一；除 `create` 外的动作都作用于当前存在的目标，其 ref 来自一次读取而不是调用方。传 `expectedRevision`（来自之前的读取）可拒绝"目标已在脚下被改过"的修改——相当于 DSH 界面的冲突处理。目标报出 `id`、`revision`、`objective`、`phase`（`active`/`paused`/`blocked`/`complete`）、`activation`（`armed`/`disarmed`）、`maxGoalRounds`、`roundsStarted`、被阻塞时的 `blockedReason` 与 `createdAt`/`updatedAt`；`clear` 返回 `goal: null`（并带 `cleared: true`），`complete` 返回已完成的目标。 |
 | `session_usage` | 按会话统计 token 用量（默认含其 subagent）：精确的四桶计数、按模型拆分、可选的按轮拆分，装了价格插件时还有钱。传 `sessionIds` 可一次结算多个已知会话，传 `cwd` 可汇总某个工作目录里跑过的所有会话。 |
 | `file_read` | 经 DSH 文件系统服务读 UTF-8 文件。受字节上限约束；`offset`/`nextOffset` 可翻页读取更大的文件（两者都是**字节**偏移，因此 EOF 处或之后的偏移是空的完整读取），`maxBytes` 用更小的窗口降低单次开销；`sha256: true` 返回整个文件的哈希，作为后续写入/编辑的比较并交换值。 |
 | `file_read_image` | 读取图片（png/jpeg/gif/webp/bmp，按字节嗅探）并以 MCP image block 返回，让你直接看截图或图表而不是靠猜。上限 8 MiB。 |
@@ -288,6 +291,29 @@ workspace_create { path: "/Users/me/project" }
 
 运维方可以通过 `agentTools.allow` 有意放宽，或用 `agentTools.deny` 从默认集合里减去。
 
+### 会话编排
+
+有些活不是一次 prompt 能装下的。压缩长会话、导出日志、进入 plan 模式、设置目标，都是人在 DSH 输入框里
+敲一条斜杠命令就能完成的用户面动作；持久目标还会把"一次请求"变成 harness 的轮次驱动会跨轮持续推进的
+目标。这两条路本身都不消耗模型轮次。预期流程：
+
+```
+session_command_list { sessionId }                                    # 该 agent 接受什么；permitted 标出放行集
+  -> session_command { sessionId, command: "/compact" }               # 运行一条；不花模型轮次
+  -> session_goal { sessionId, action: "create", objective: "完成迁移", maxGoalRounds: 20 }
+  -> session_goal { sessionId, action: "get" }                        # 轮询 phase/revision……
+     或订阅 dsh://session/<id>/projections                               # ……或等它在变化时通知你
+  -> session_goal { sessionId, action: "pause", expectedRevision: 3 } # 之后 resume / complete / clear
+```
+
+`session_command_list` 报出每条命令的 `permitted` 标记而不是把被拒命令藏起来，调用方因此能看到该 profile
+上确实有 `/permission` 与 `/feedback`、而本端点故意不运行它们：`/permission` 会改变会话的权限 preset，
+`/feedback` 会写入用户自己的评审记录；两者都到不了 handler，也不会向会话日志写入任何东西。
+`session_status` 报的是会话的轮次与日志状态，不含目标本身；目标的 phase 与 revision 来自
+`session_goal { action: "get" }`，而 `dsh://session/<id>/projections` feed（其中含 `goal`）会在目标变化时
+发布，因此跟进一个目标是轮询或订阅，而不是每轮都发 prompt。不带 `expectedRevision` 的修改作用于当时存在
+的目标；若可能有两个监督者竞争，请传回读取时拿到的 revision。
+
 ## 工作树
 
 一个会话可以在一份自己的、来自同一仓库的 Git 检出里工作。这正是 DSH 界面「New worktree」选项做的事：
@@ -328,7 +354,7 @@ profile 能读 session projection 时，`session_status` 会报 `workingDirector
 
 MCP 服务无法主动调用客户端，所以「有什么变了」只能以资源通知的形式送出去。本端点把同一套变更 feed 发布到
 两种标准的推送通道上，而且每条通知都**不携带负载**：它只点名一个合成资源，客户端再去读那个资源拿 JSON。
-这件事没有新增任何工具——工具面仍是上面表格里的 35 个——推送也没有配置键：它始终开启，且在无人订阅时
+这件事没有新增任何工具——工具面仍是上面表格里的 38 个——推送也没有配置键：它始终开启，且在无人订阅时
 零成本。
 
 | 客户端时代 | 握手 | 服务端→客户端通道 | 如何请求推送 |
@@ -880,6 +906,7 @@ profile 推导同一份映射；不过配置 profile 的人应当能在一处读
 | `worktree_create` / `worktree_restore` / `session_create { worktree }` | `worktrees` **且** `sessionController.resolveAgent` | 服务由 DSH Desktop/Web 的 forge bundle（`@deepseek-ai/dsh-experimental-forge-bundle`）提供；裸 profile 没有它，`dsh_info.toolAvailability` 会把这些工具报成不可用，`session_create { worktree }` 在创建会话之前就被拒绝。会话的执行环境里还需要 Git 与 Node |
 | `session_status.workingDirectory` / `session_status.worktree` / `session_list { includeWorktree }` | 可读的 session projection（`sessionController.projections` 或 `sessionQuery.observeSession`） | 可选：没有它时两个回复都省略这两个字段，其余内容不变 |
 | `session_archive` / `session_unarchive` / `session_pin` / `session_unpin` | `workspaceRegistry.archiveSession` / `pinSession` | 与 DSH 侧边栏动作写入同一组 registry 集合；方法缺失时这些工具被报成不可用 |
+| `session_command_list` / `session_command` / `session_goal` | `sessionController.resolveAgent` **且** `commands` / `goals` | 两个服务都是 agent 作用域的，会话的实时 agent 就是桥；profile 没有它们时 `dsh_info.toolAvailability` 会把这三个工具报成不可用，每次调用也会点名缺少的服务与提供它的 bundle |
 | `workspace_*` | `workspaceRegistry` | 常规 profile 由 base bundle 提供 |
 | `file_*` | `fs` | 部署的沙箱策略照样生效；`file_read_image` 还需要受支持的图片格式 |
 | `shell_*` | `shell` | `shell_run` 有 `run()` 用 `run()`、否则 `execute()`；后台任务需要 `start()` 或 `execute()` |
@@ -1011,13 +1038,13 @@ node scripts/exercise.mjs    # 约 60 项断言：建工作区、开会话、让
 
 | 启用的工具组 | 公布工具数 | 最近结果 |
 | --- | --- | --- |
-| 全部六组 | 35 | `--with-model --with-subagent` 下 live-checks 195/195；验收 166/166，同一轮启动、搜索索引开启 |
-| 仅 `session`、`usage` | 20 | `--with-model` 下 live-checks 95/95（文件/shell/工作区段落跳过） |
-| `workspace`、`session`、`agentTools`、`usage` | 25 | live-checks 64/64（被关闭的组会在原因里点名 `tools.<group>` 开关） |
+| 全部六组 | 38 | `--with-model --with-subagent` 下 live-checks 195/195；验收 166/166，同一轮启动、搜索索引开启 |
+| 仅 `session`、`usage` | 23 | `--with-model` 下 live-checks 95/95（文件/shell/工作区段落跳过） |
+| `workspace`、`session`、`agentTools`、`usage` | 28 | live-checks 64/64（被关闭的组会在原因里点名 `tools.<group>` 开关） |
 | 仅 `files`、`shell` | 11 | live-checks 68/68（会话/用量/队列/搜索段落跳过） |
 
-"公布工具数"一列是当前工具面（0.53.0：session 组 18 个、总计 35 个）；"最近结果"一列记录的是
-针对 0.52.86（尚无这六个新工具）的实测，本次发布没有重测。
+"公布工具数"一列是当前工具面（0.55.0：session 组 21 个、总计 38 个）；"最近结果"一列记录的是
+针对 0.52.86（尚无 0.53.0 新增工具）的实测，此后未重测。
 
 第五个形态 `mountonly` 以 `http.enabled: false` + `mountOnWebServer: true` 启动，经 DSH 自己的
 web 服务器验证端点：109/109，全部廉价，其中包含 `dsh_info` 必须报 `listening: false`、

package/cordis.patch.yml

@@ -50,13 +50,14 @@
           # stream) and cost nothing while no client subscribes. The session-group
           # feeds need `session`; the job feeds need `shell`.
           #
-          # The session group: 18 tools — create/list/search/status/prompt/
+          # The session group: 21 tools — create/list/search/status/prompt/
           # transcript/tool-result/queue/cancel/fork/rename/set_model, the
-          # worktree pair, and archive/unarchive + pin/unpin. The worktree tools
+          # worktree pair, archive/unarchive + pin/unpin, and the orchestration
+          # trio (slash commands + durable goal). The worktree tools
           # also need the worktrees service (the forge bundle in Desktop/Web,
           # probed as `dsh_info.harnessServices.worktrees`); archive/pin write the
           # same registry sets the DSH sidebar's actions write. Disabling the
-          # group removes all 18 at once; `dsh_info.toolAvailability` names the
+          # group removes all 21 at once; `dsh_info.toolAvailability` names the
           # ones a profile cannot serve.
           session: true
           files: true

package/lib/index.d.ts

@@ -1482,6 +1482,19 @@ interface DshSessionEvent {
   readonly time: number;
   readonly data: unknown;
 }
+/** One slash command a session's agent can run — `CommandDescriptor` in the 0.2.2 catalog. */
+interface DshCommandDescriptor {
+  readonly name: string;
+  readonly description: string;
+  readonly input?: {
+    readonly hint: string;
+    readonly acceptsAttachments?: boolean;
+  };
+}
+/** Durable goal phase — `GoalPhase` in the 0.2.2 catalog. */
+type DshGoalPhase = 'active' | 'paused' | 'blocked' | 'complete';
+/** Whether the round driver is currently advancing the goal (`GoalActivation`). */
+type DshGoalActivation = 'armed' | 'disarmed';
 /**
  * One created worktree — `CreatedWorktree` in
  * `packages/tool/worktree/src/index.ts` (harness 0.2.2-rc.1).
@@ -2063,6 +2076,35 @@ interface SessionEventFeed {
   readonly asOfSeq: number;
   readonly events: readonly SessionEventFeedEvent[];
 }
+/** The reply of one slash-command execution. */
+interface SessionCommandResult {
+  readonly sessionId: string;
+  /** The harness's own command id for this execution; usable in the log/transcript. */
+  readonly commandId: string;
+  /** False when the handler itself reported an error result (`result.kind: 'error'`). */
+  readonly ok: boolean;
+  /** Text the handler returned, when it returned any. */
+  readonly text?: string;
+  /** The durable event the handler wrote, when it reported one. */
+  readonly sourceEventSeq?: number;
+}
+/** One durable goal, as this endpoint projects it from the harness's `GoalView`. */
+interface SessionGoalView {
+  readonly id: string;
+  readonly revision: number;
+  readonly objective: string;
+  readonly phase: DshGoalPhase;
+  /** Whether the round driver is currently advancing it. */
+  readonly activation: DshGoalActivation;
+  readonly maxGoalRounds: number;
+  readonly roundsStarted: number;
+  readonly blockedReason?: {
+    readonly code: string;
+    readonly message: string;
+  };
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
 /**
  * One background shell job as a non-consuming feed snapshot.
  *
@@ -2388,6 +2430,24 @@ export declare class DshDriver {
   private workspaceRegistry;
   private sessionController;
   private sessionQuery;
+  /**
+   * `ctx.commands`, when the profile mounts the command registry.
+   *
+   * Every shipped DSH composition does (`dsh-base` mounts `@deepseek-ai/dsh-commands`
+   * together with the built-in command packages), so a missing service means a
+   * stripped-down profile rather than a version difference.
+   */
+  private commandService;
+  /**
+   * `ctx.goals`, when the profile mounts the goal store.
+   *
+   * Shipped compositions mount it with `@deepseek-ai/dsh-tool-goal`; a profile that
+   * drops the goal bundle has no goal surface at all, which is why the probe is
+   * separate from `commands`.
+   */
+  private goalService;
+  private requireCommandService;
+  private requireGoalService;
   /**
    * `ctx.worktrees`, when the profile mounts one.
    *
@@ -2493,6 +2553,71 @@ export declare class DshDriver {
     sessionId: string;
     pinned: false;
   }>;
+  /**
+   * The slash commands this session's agent can run, with the ones this endpoint
+   * will actually execute marked.
+   *
+   * A command runs **without a model turn** (the handler is invoked directly), so
+   * this is the cheap half of "do the thing a human would type into the composer".
+   * `permitted` is reported rather than filtered out: a caller should be able to
+   * see that `/permission` exists and that this endpoint deliberately will not run
+   * it, instead of guessing why a name is missing.
+   */
+  listSessionCommands(request: {
+    sessionId: string;
+  }): Promise<{
+    sessionId: string;
+    commands: readonly (DshCommandDescriptor & {
+      readonly permitted: boolean;
+    })[];
+  }>;
+  /**
+   * Run one slash command against a session's agent.
+   *
+   * The allow-list is explicit and lives in {@link PERMITTED_COMMANDS}: the set of
+   * commands a profile registers is not this endpoint's decision, and two of the
+   * shipped ones are deliberately excluded (`/permission` escalates the session's
+   * permission preset; `/feedback` writes the user's own review records). A
+   * command not on the list is refused **before** the handler runs, so nothing is
+   * logged into the session’s history for a refused call.
+   */
+  runSessionCommand(request: {
+    sessionId: string;
+    command: string;
+    signal?: AbortSignal;
+  }): Promise<SessionCommandResult>;
+  /**
+   * The durable goal this session carries, if any.
+   *
+   * Goal state lives in the harness's own store and the round driver advances it
+   * across turns, so reading it is how a supervising caller answers "what is this
+   * session supposed to be doing, and is it paused".
+   */
+  sessionGoal(request: {
+    sessionId: string;
+  }): Promise<{
+    sessionId: string;
+    goal: SessionGoalView | null;
+  }>;
+  /**
+   * Create, edit, pause, resume, complete or clear a session's durable goal.
+   *
+   * `expectedRevision` is the lost-update guard: the harness's own `GoalRef`
+   * carries a revision, and a mutation whose revision no longer matches is refused
+   * rather than silently rewriting a goal the user edited in the UI a moment ago.
+   */
+  mutateSessionGoal(request: {
+    sessionId: string;
+    action: 'create' | 'edit' | 'pause' | 'resume' | 'complete' | 'clear';
+    objective?: string;
+    maxGoalRounds?: number;
+    expectedRevision?: number;
+  }): Promise<{
+    sessionId: string;
+    action: string;
+    goal: SessionGoalView | null;
+    cleared?: true;
+  }>;
   private toWorkspaceInfo;
   /**
    * Explain a model-selection failure in terms the caller can act on.