@epoch-agent/server 0.21.0 → 0.22.0

package/README.md

@@ -1694,14 +1694,21 @@ role 上。
 3. **[bind.ts](src/bind.ts) 那条「非回环不给 token 就拒绝启动」不放松**，也不为这个
    字段开例外
 
-**绑定后不给改**（决定 18）：中途换地盘会让前面那些工具调用里的 `./src/a.ts`
+**开过工之后不给改**（决定 18）：中途换地盘会让前面那些工具调用里的 `./src/a.ts`
 指向另一个目录，而记录里没有任何地方写着从哪条开始换的。
 
-⚠️ **所以「换一个工作区」的唯一形态是新建一个会话** —— 2026-08-15 多会话工厂落地
-之后，`POST /api/sessions` 带另一个目录**不再是 409 `workspace-locked`**，而是
-建一个绑在那儿的新会话（见上面那张表）。那个码没有作废：它守的仍然是同一条规矩，
-只是这条路上再也走不到它了，真正会撞到它的是 runtime 那一层
-（`SessionWorkspaces.bind`）。
+⚠️ **2026-09-30：这条锁的边界从「绑过没有」挪到了「开过工没有」。** 判据就是上面
+那句话自己 —— 还没开过工就**一条工具调用都没有**，锁在那段窗口里没有对象。
+所以「挑一个 → 想换一个」在一段还没发过消息的会话上是允许的，而开过工之后照旧
+一个字不能改。判据只有一份（`WorkspaceControl.canChange`），三处共用：runtime 里
+`bind()` 那道 `locked`、这条端点那道 409 闸、以及网线上给界面的 `changeable`。
+三处各判一次的表现是「界面画着一张 picker、按下去 409」。
+
+⚠️ **所以「换一个工作区」的唯一形态**（开过工之后）**仍然是新建一个会话**
+—— 2026-08-15 多会话工厂落地之后，`POST /api/sessions` 带另一个目录**不再是
+409 `workspace-locked`**，而是建一个绑在那儿的新会话（见上面那张表）。那个码没有
+作废：它守的仍然是同一条规矩，只是这条路上再也走不到它了，真正会撞到它的是
+runtime 那一层（`SessionWorkspaces.bind`）和这条端点那个 409 闸。
 
 ### 「这个会话绑在哪儿」是一条独立端点（2026-08-15）
 
@@ -1721,6 +1728,11 @@ role 上。
 | 建好了、**还没选**地盘         | 200 + `{binding:{state:'unbound'}}`  |
 | 这个进程手里**没有**这段会话   | 409 `not-live-session`               |
 
+⚠️ **`bound` / `none` 还各带一格 `changeable`**（2026-09-30）：这次决定还能不能改，
+判据只有一条 —— 这段会话**开过工没有**（和上面那道 409 闸、以及 runtime 里
+`bind()` 那道 `locked` 读的是同一个方法，见下面 POST 那一节）。`unbound` 不带它：
+那一档还没有决定，一直可挑。这一格是**界面画菜单还是画 diff 门**的依据。
+
 第 3 行和第 5 行是这条端点原本全部的难点。绑定活在进程内存里、**不落盘**，所以上
 一个进程留下的会话在 `workspaces.of()` 那儿也是 `null` —— 和「这个会话真的不使用
 工作区」在数据上一模一样。合成一个的表现很具体：一段昨天在某个仓库里干了一整轮活
@@ -1807,27 +1819,35 @@ body: {root: '<绝对路径>'} | {none: true}
 「宿主看得见的那一面」上，路径校验、信任闸门、`locked` 幂等三样一个字都没动 ——
 这条端点只是第二个调用点。
 
-**只有 `unbound` 收得动：**
+**只有 `unbound`，或者还没开过工的已定会话，收得动：**
+
+| 这个会话此刻                     | 结果                                                  |
+| -------------------------------- | ----------------------------------------------------- |
+| `unbound` 且 idle                | 绑 / 转 `none`，200 回**改完之后**的整份 binding      |
+| `unbound` 但在跑                 | 409 `busy` —— 等这一轮结束再挑（2026-08-20）          |
+| `bound` / `none`，**还没开过工** | 同上第一行 —— 换一个「还没被任何工具调用用上的选择」  |
+| `bound` / `none`，**开过工了**   | 409 `workspace-locked` —— 决定 18「开过工之后不给改」 |
+| 上面任一档，但这一轮在跑         | 409 `busy`                                            |
 
-| 这个会话此刻      | 结果                                                 |
-| ----------------- | ---------------------------------------------------- |
-| `unbound` 且 idle | 绑 / 转 `none`，200 回**改完之后**的整份 binding     |
-| `unbound` 但在跑  | 409 `busy` —— 等这一轮结束再挑（2026-08-20）         |
-| `bound`           | 409 `workspace-locked` —— 决定 18「绑定后不给改」    |
-| `none`            | 409 `workspace-locked` —— **「不使用」也是一次决定** |
+⚠️ 第三行 2026-09-30 才有（判据在 `WorkspaceControl.canChange` 上，读的是会话库
+——「这段会话开过工没有」）。**它不是放宽**：那条锁要护的是「前面那些工具调用里的
+相对路径」，而那段窗口里一条都没有。
 
-⚠️ 第二行和另外两行**不是同一句话**，别合并：`workspace-locked` 说的是「已经定了，
-永远不能改」（下一步是新建会话），`busy` 说的是「现在不行，等一下」（下一步还是
-同一个按钮）。合成一句的话，用户会去建一个他不需要的会话。它是迟绑那一轮
-（2026-08-20）补的：绑定这一下现在会真的改引擎脚下的目录，而一次 `run()` 底下可能有
+⚠️ `workspace-locked` 和 `busy` **不是同一句话**，别合并：前者说的是「已经定了，
+不能改」（下一步是新建会话），后者说的是「现在不行，等一下」（下一步还是
+同一个按钮）。合成一句的话，用户会去建一个他不需要的会话。`busy` 是迟绑那一轮
+（2026-08-20）补的：绑定这一下会真的改引擎脚下的目录，而一次 `run()` 底下可能有
 二十次工具调用 —— 半路换根等于同一轮里前几次按 A、后几次按 B 解析相对路径，而历史里
 那条 `[系统]` 留痕是**轮次开始时**插的，盖不住这一档。响应头带 `X-Epoch-Turn-State`，
 和 `POST /messages` 那条 409 同一对形状。
 
-⚠️ 第三行是这条端点唯一一处会被读错的地方：`none` 看着像「还空着」，但它是用户
-**明确按过**的一档（决定 18 侧栏「任务」组的成员）。让它还能被改，等于给一段说过
-「不要地盘」的会话补一个地盘 —— 而它前面那些工具调用里的相对路径已经按服务进程的
-启动目录解析过了，判据逐字同 `bound` 那一行。**不做 `PATCH`，也不做换绑。**
+⚠️ `none` 那一档是这条端点唯一一处会被读错的地方：它看着像「还空着」，但它是用户
+**明确按过**的一档（决定 18 侧栏「任务」组的成员）。**开过工之后**让它还能被改，
+等于给一段说过「不要地盘」的会话补一个地盘 —— 而它前面那些工具调用里的相对路径
+已经按服务进程的启动目录解析过了，判据逐字同 `bound` 那一行。而还没开过工时它和
+`bound` 一样放行：底栏那张菜单里「不使用工作区」和「换一个目录」本来就是同一层的
+两项，一项能改、另一项点了没反应，用户看到的是「菜单里有一项坏了」。
+**不做 `PATCH`，也不做换绑** —— 这条端点只是在那个窗口里允许「改一个还没用上的选择」。
 
 请求体**两支恰好一支**：两支都给 / 都不给一律 400 `bad-workspace`。「两支都给」
 不许挑一支执行 —— 那两支通向的是两段完全不同的会话。**这一层一次路径校验都不做**

package/dist/index.d.ts

@@ -2094,19 +2094,36 @@ declare class SessionHub {
      *
      * 为一帧发给**零个**收件人的帧去改一份三边共用的契约，换不回任何东西。
      *
-     * ## 所以产地是两条端点，各自的判据
+     * ## 所以产地是四条端点，各自的判据
      *
      * | 产地 | 什么时候发 | 为什么 |
      * | --- | --- | --- |
      * | `POST /api/sessions`（`workspace/handlers.ts`） | **只在 `outcome.created`** | 复用那一支没多出一行来，发了等于让所有标签页白重取一次 |
      * | `DELETE /api/sessions/:id`（`api.ts`） | 删成了就发 | 不发的话**别的**标签页会一直挂着一行已经没了的会话，点进去才拿 404 |
      * | `PATCH /api/sessions/:id`（`api.ts`，2026-09-16） | **只在 `archived` 真的翻了** | 列表默认不列归档的那几段，所以归档 = 少一行、取回 = 多一行。判据全文在那个调用点上 |
+     * | `POST /api/sessions/:id/workspace`（`workspace/handlers.ts`，2026-09-30） | **只在那一行真的换了组的时候**（`bind` 那一支看 `outcome.changed`、「不使用工作区」那一支看调用前是不是已经是 `none`） | 它改的是那一行上的 `workspace` 格 —— 而侧栏「空间 / 任务 / 早先的会话」三组正是读它分出来的。判据全文在那个调用点上，和下面「置顶」那一档的分界见下一节 |
      *
      * ⚠️ 第三个产地**不在「进出 Hub」这条路上**，而上一版这段话正是按那条路数的
      * （原文「那是第一版……`hub-register-sites.test.ts` 已经钉住了会话只能从那三处
      * 变活」）。钉住的是**活性**，而这一帧的宾语是**列表端点答出来的那几行** ——
      * 两者在归档这一档上分叉：一段会话被收进归档时进出 Hub 的表一个字没动，
      * 可侧栏那份列表少了一行。别再拿「经不经过 Hub」当这一帧的判据。
+     * ⚠️ 第四个产地（绑定）**同样不经过 Hub**，而且它比归档那一档更远：它在
+     * 字面上不增不减任何一行，改的只是**其中一行上的一个格子**。
+     *
+     * ## ⚠️ 绑定那一档和「置顶不发」看着像，分界是「那句话会不会骗人」
+     *
+     * 绑定和置顶一样不改成员数，但**只有它发**：
+     *
+     * - 置顶只是**顺序旧一拍** —— 那一行还在列表里、点得开、内容也对，而按下去
+     *   的那一页自己会重取。过期看得见，但**不会骗人**，所以不发（判据全文在
+     *   protocol 的 `sessions-changed` 上）；
+     * - 绑定把那一行**放进了错误的分组**：屏幕说「这段会话在 epoch-agent 里干活」，
+     *   而它其实在 `lw` 里 —— 那句话是假的，而且**不会自己修**，得用户刷新页面、
+     *   或者切到一段列表里没有的会话才把它捡回来（2026-09-30 用户报的正是这个）。
+     *
+     * 代价如实记：一次换绑 = **每个标签页**各重取一次整份列表（本机 loopback GET，
+     * 50 行封顶）。绑定是用户手动、低频的一次动作，不在一轮里反复发生，认下它。
      *
      * 另外两处刻意**不发**：
      *
@@ -3189,6 +3206,45 @@ interface PluginPreviewView {
         name: string;
         version: string;
     };
+    /** `InstallDependency`（core，经 runtime 原样透出）的镜像 —— 见 `WirePluginDependency` */
+    dependencies?: readonly DependencyView[];
+}
+/**
+ * 一个依赖。**手写一份镜像**，理由同 {@link PluginPreviewView}：这一层只依赖
+ * protocol + runtime，而 core 那个类型是经 runtime 透出来的，直接 import 会把
+ * 分层绕过去（`check-layers` 会红）。
+ *
+ * ⚠️ 镜像的代价是**加一格要两边一起加**，而漏了的表现是「core 算了、界面没有」——
+ * 所以 `toWireDependency` 是照着这个形状逐格写的，不是 spread 过去的。
+ */
+interface DependencyView {
+    name: string;
+    status: 'installed' | 'plan' | 'unresolved';
+    requiredBy: string;
+    source?: string;
+    reason?: string;
+    versionUnmet?: {
+        required: string;
+        current: string;
+        reason: string;
+    };
+    manifest?: {
+        name: string;
+        version: string;
+    };
+    inventory?: {
+        commands: readonly string[];
+        roles: readonly string[];
+        skills: readonly string[];
+        hooks: readonly {
+            type: string;
+            count: number;
+        }[];
+        denyRules: number;
+        mcpServers: readonly string[];
+        ignoredBuckets: readonly string[];
+        jsTools: boolean;
+    };
 }
 /** 七档拒绝的共同形状（runtime 的 `PluginRefusal`） */
 interface RefusalView {
@@ -3861,6 +3917,16 @@ interface WorkspaceView {
     decideNone(sessionId: string): void;
     /** 这个会话是哪一档。**不答「这个进程认不认识它」**，那一问由 Hub 答 */
     stateOf(sessionId: string): WorkspaceBindingState;
+    /**
+     * 这次决定还能不能改（2026-09-30）。
+     *
+     * **两处问它，而且必须是同一个答案**：`bindWorkspace` 那道 409 闸，
+     * 以及 GET / POST 两条路下发给界面的 `changeable`。三处各判一次的表现是
+     * 「界面上画着一张 picker、按下去 409」—— 那句话读起来像功能坏了。
+     *
+     * 判据全文在 runtime 的 `WorkspaceControl.canChange` 上。
+     */
+    canChange(sessionId: string): boolean;
     release(sessionId: string): void;
     /** 本机「已知工作区」清单，最近使用的在前 */
     known(): ReadonlyArray<{
@@ -4993,6 +5059,26 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      */
     session: (HubSession & ModelSessionFacts) | null;
     sessionId: string;
+    /**
+     * 不绑工作区时引擎**实际**跑在哪个目录（2026-09-30）。
+     * `EpochRuntime.defaultWorkDir` 结构上满足它。
+     *
+     * ⚠️ **它是可选字段**，同 `diagnosticsIn?` / `lastOpenSession?` 那一条：
+     * 自己拼 `WebRuntimeView` 的宿主可以不给 —— 那时 `GET /api/config` 整个不下发
+     * `defaultWorkDir`，界面退回「选择工作区」那个纯动作（两种形态都画得出来）。
+     * 把 `EpochRuntime` 整个传进来的宿主什么都不用做：它恒有这一格。
+     *
+     * ⚠️ **它是进程级的一份，所有会话共用**：绑定表答不出来时每个会话都回落到它
+     * （`session-factory.ts` 的 `site()` 那一行 `now?.workspace.root ?? opts.defaultWorkDir`）。
+     * 别读成「引导会话的工作目录」—— 引导会话只是**恰好**也跑在它上面。
+     *
+     * ⚠️ 在这儿**不要**用 `process.cwd()` 重算：宿主可以显式传 `workDir` 起引擎
+     * （`buildRuntime({ workDir })`），而那是**宿主进程**的 cwd，两者不是一回事。
+     *
+     * 上网线的形态、以及它为什么非下发不可，在 protocol 的
+     * `WireConfigResponse.defaultWorkDir` 上。
+     */
+    defaultWorkDir?: string;
     /**
      * 多会话工厂（方案 30 §6.3）。`EpochRuntime.sessionFactory` 结构上满足它。
      *

package/dist/index.js

@@ -370,10 +370,13 @@ var EMPTY_INVENTORY = {
   policies: 0,
   settingsFiles: []
 };
-function toWireBinding(state, bound) {
-  if (state === "bound" && bound)
-    return { state: "bound", workspace: toWireSessionWorkspace(bound) };
-  return { state: state === "bound" ? "unbound" : state };
+function toWireBinding(state, bound, changeable) {
+  if (state === "bound") {
+    if (bound) return { state: "bound", workspace: toWireSessionWorkspace(bound), changeable };
+    return { state: "unbound" };
+  }
+  if (state === "none") return { state: "none", changeable };
+  return { state: "unbound" };
 }
 function toWireWorkspaceRef(bound) {
   if (!bound) return null;
@@ -1780,6 +1783,7 @@ function config(ctx, res, lang) {
     model: runtime.config.model,
     permission: runtime.config.permission,
     workspace: bound ? toWireSessionWorkspace(bound) : null,
+    ...runtime.defaultWorkDir !== void 0 ? { defaultWorkDir: workspaceRefOf(runtime.defaultWorkDir) } : {},
     knownWorkspaces: toWireKnownWorkspaces(runtime.workspaces.known()),
     usageScope: runtime.usageScope,
     compression: runtime.compression,
@@ -2827,14 +2831,15 @@ function sessionWorkspace(ctx, res, sessionId, lang) {
     return sendUnknownSession(res, sessionId);
   }
   const state = ctx.runtime.workspaces.stateOf(sessionId);
+  const changeable = ctx.runtime.workspaces.canChange(sessionId);
   if (state !== "none") {
     return sendJson(res, 200, {
-      binding: toWireBinding(state, ctx.runtime.workspaces.of(sessionId))
+      binding: toWireBinding(state, ctx.runtime.workspaces.of(sessionId), changeable)
     });
   }
   if (ctx.hub.has(sessionId) || ctx.hub.isCooled(sessionId)) {
     return sendJson(res, 200, {
-      binding: { state: "none" }
+      binding: { state: "none", changeable }
     });
   }
   sendError(res, 409, "not-live-session", t("web.workspace_not_live", void 0, lang));
@@ -2848,7 +2853,7 @@ async function bindWorkspace(ctx, req, res, sessionId, lang) {
   const parsed = readBindWorkspaceBody(asRecord(body.value), lang);
   if (!parsed.ok) return sendError(res, 400, "bad-workspace", parsed.message);
   const state = ctx.runtime.workspaces.stateOf(sessionId);
-  if (state !== "unbound") {
+  if (state !== "unbound" && !ctx.runtime.workspaces.canChange(sessionId)) {
     return sendError(
       res,
       409,
@@ -2864,8 +2869,9 @@ async function bindWorkspace(ctx, req, res, sessionId, lang) {
   }
   if (parsed.kind === "none") {
     ctx.runtime.workspaces.decideNone(sessionId);
+    if (state !== "none") ctx.hub.notifySessionsChanged(sessionId);
     return sendJson(res, 200, {
-      binding: { state: "none" }
+      binding: { state: "none", changeable: ctx.runtime.workspaces.canChange(sessionId) }
     });
   }
   const outcome = ctx.runtime.workspaces.bind(sessionId, parsed.root, lang);
@@ -2873,8 +2879,13 @@ async function bindWorkspace(ctx, req, res, sessionId, lang) {
     const mapped = bindFailureToHttp(outcome, lang);
     return sendError(res, mapped.status, mapped.code, mapped.message);
   }
+  if (outcome.changed) ctx.hub.notifySessionsChanged(sessionId);
   sendJson(res, 200, {
-    binding: { state: "bound", workspace: toWireSessionWorkspace(outcome.bound) }
+    binding: {
+      state: "bound",
+      workspace: toWireSessionWorkspace(outcome.bound),
+      changeable: ctx.runtime.workspaces.canChange(sessionId)
+    }
   });
 }
 async function sessionDiff(ctx, res, sessionId, _lang) {
@@ -3415,7 +3426,30 @@ function toWirePreview2(preview) {
     mcpServers: [...inventory.mcpServers],
     ignoredBuckets: [...inventory.ignoredBuckets],
     hasJsTools: inventory.jsTools,
-    conflict: preview.conflict ? { name: preview.conflict.name, version: preview.conflict.version } : null
+    conflict: preview.conflict ? { name: preview.conflict.name, version: preview.conflict.version } : null,
+    dependencies: (preview.dependencies ?? []).map(toWireDependency)
+  };
+}
+function toWireDependency(dep) {
+  const inventory = dep.inventory;
+  return {
+    name: dep.name,
+    status: dep.status,
+    requiredBy: dep.requiredBy,
+    source: dep.source ?? null,
+    reason: dep.reason ?? null,
+    version: dep.manifest?.version ?? null,
+    versionUnmet: dep.versionUnmet ?? null,
+    inventory: inventory ? {
+      commands: [...inventory.commands],
+      roles: [...inventory.roles],
+      skills: [...inventory.skills],
+      hooks: inventory.hooks.map((h) => ({ type: h.type, count: h.count })),
+      denyRules: inventory.denyRules,
+      mcpServers: [...inventory.mcpServers],
+      ignoredBuckets: [...inventory.ignoredBuckets],
+      hasJsTools: inventory.jsTools
+    } : null
   };
 }
 function controlOf(ctx, res, lang) {