@epoch-agent/protocol 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -1478,11 +1478,17 @@ type ComplianceAction = (typeof COMPLIANCE_ACTIONS)[number];
  * 侧栏最下面那一行「用户」（2026-09-07）—— 宿主可以换掉的名字和头像。
  *
  * 这是「宿主装配期按下的事实」那条路上的**第五个键**（`brand` → `sidebarMenu`
- * → `blankCards` → `blankGreeting` → 这一个）：只读、`GET /api/config` 原样下发、
- * 界面上没有写端点。为什么是配置项而不是 `createWebServer()` 的装配参数，全文在
+ * → `blankCards` → `blankGreeting` → 这一个 → 同一天还多了个 `userMenu`）：
+ * 只读、`GET /api/config` 原样下发、界面上没有写端点。为什么是配置项而不是
+ * `createWebServer()` 的装配参数，全文在
  * [`EpochConfig.brand`](./config.ts) 上（一句话：走 `epoch web --json` 起子进程的
  * 宿主没有构造函数可传）。
  *
+ * ⚠️ **它和 `userMenu` 是同一天落的两个键，但管的不是同一件事**：这一个只管那一行
+ * 上的**名字和头像**，那张菜单里有什么归 `userMenu`（判据在
+ * [sidebar-menu.ts](./sidebar-menu.ts) 文件头第一节）。只配这一个的宿主得到
+ * 「一行改了名字的触发器 + 一张只有『设置』的菜单」—— 那是一句说得通的话。
+ *
  * ## ⚠️ 它和前四个键**默认档不同**：不配也有东西，而且照旧点得开
  *
  * 那一行是**设置的唯一入口**（点开是一张菜单，「设置」在最下面 —— 屏幕上那一格在
@@ -1490,7 +1496,7 @@ type ComplianceAction = (typeof COMPLIANCE_ACTIONS)[number];
  *
  * | 键                    | 没配 = 屏幕上 |
  * | --------------------- | ------------------------------------- |
- * | `brand` / `sidebarMenu` / `blankCards` | 什么都没有 |
+ * | `brand` / `sidebarMenu` / `userMenu` / `blankCards` | 什么都没有 |
  * | `blankGreeting`       | **我们那句**招呼（跟着界面语言翻） |
  * | 这一个                | **我们那句**「用户」+ 一枚 `user-round` |
  *
@@ -1540,15 +1546,42 @@ interface HostUser {
 }
 
 /**
- * 宿主自定义的那几行侧栏菜单（2026-09-02）。
+ * 宿主自定义的侧栏菜单项（2026-09-02）—— **一个形状，两个键**（2026-09-07 拆开）。
+ *
+ * 这个文件里的 {@link SidebarMenuItem} 是**两个配置键共用的那一个 item 形状**：
+ *
+ * | 键 | 画在哪 | 不配 = |
+ * | -- | ------ | ------ |
+ * | `EpochConfig.sidebarMenu` | 侧栏底部「用户」那一行**上面**的几行常驻按钮 | 那几行整个没有 |
+ * | `EpochConfig.userMenu`    | 「用户」点开的那张菜单里的宿主项（排在「设置」上面） | 菜单里只有「设置」，**连分隔线都没有** |
+ *
+ * ⚠️ **两个键互不兜底**，这是拆开那一笔的全部内容（老板原话：「不行，需要是两个
+ * 配置」）：只配 `sidebarMenu` 的宿主得到几行常驻按钮、菜单里**一项宿主项都没有**；
+ * 只配 `userMenu` 的反过来。谁都不去拿另一个顶上 —— 那种兜底的表现是宿主配了一个键
+ * 却在**两处**都看见东西，而它想改掉多出来的那一处时会发现没有对应的键可关。
+ * 判据在 web 的 `shell/sidebar.tsx` 上（两个常量各判一次「键在且非空数组」）。
  *
- * 形状和口径逐字照 `EpochConfig.brand`（决定 19）：**宿主装配期预置的一个配置项，
- * 界面上没有写端点**，`GET /api/config` 原样下发、没配就不带这个键。
+ * ⚠️ **类型名照旧是 `SidebarMenuItem`，没有跟着拆成两个**。它是**同一个形状**
+ * （`id` / `label` / `icon` 三个字段，一个字都不差），为「这一份是给哪个键的」造第二个
+ * 名字只会多一处要同步的地方 —— 而两个键的 item 真要长得不一样的那天，那时才拆。
+ *
+ * 2026-09-02 到 09-07 之间它只有一个键（`sidebarMenu`），中途还有过**同一份 items
+ * 画在两处**的一版（当天定稿就被否了，见上面那条 ⚠️）。宿主那侧接的那句 `message`
+ * 监听**从头到尾一个字没改** —— 见下面「点下去发生什么」。
+ *
+ * 形状和口径逐字照 `EpochConfig.brand`（决定 19）：**宿主装配期预置的配置项，
+ * 界面上没有写端点**，`GET /api/config` 原样下发、没配就不带那个键。
  * 为什么是配置项而不是 `createWebServer()` 的参数，全文在那个字段上
  * （一句话：走 `epoch web --json` 起子进程的宿主没有构造函数可传）。
  *
  * ## 点下去发生什么：往父窗口发一条 `postMessage`，**不跳页**
  *
+ * ⚠️ **两个键共用这一条消息，而且不带「来源」** —— 点侧栏那几行和点菜单里那几项发出去
+ * 的东西**逐字节一样**（`{ type, id }`）。刻意的：宿主已经拿 `id` 认出了是哪一项，
+ * 而那个 `id` 出自它自己那份配置 —— 它当然知道自己把那一项配在了哪个键上。
+ * 多带一个 `from: 'sidebar' | 'menu'` 的代价是**宿主那句监听得跟着改**，
+ * 换来的是一个它本来就答得出的答案。
+ *
  * 这是这一格和 `brand` 唯一的形状差别 —— 品牌是一个字符串，菜单是一个**动作**，
  * 而动作要有个落点。三条路里选了这一条：
  *
@@ -1588,7 +1621,9 @@ interface HostUser {
  * `message`**，所以宿主发什么进来都改不动这张页的任何状态。
  */
 /**
- * 侧栏菜单里的一项。
+ * 侧栏菜单里的一项。**`sidebarMenu` 和 `userMenu` 两个键共用这一个形状**
+ * （见文件头第一节那张表）—— 名字里的 `Sidebar` 是它 2026-09-02 出生时的位置，
+ * 不是「只给 `sidebarMenu` 用」的意思。
  *
  * ⚠️ 三个字段都是**宿主的话**，一个都不过 i18n catalog —— 同侧栏底下那几条启动
  * 诊断的 `detail`：它们的内容随宿主而变，没有有限的码可以枚举。用户把界面切成
@@ -1598,8 +1633,13 @@ interface SidebarMenuItem {
     /**
      * 宿主自己认的那个码 —— 点下去原样回给它（{@link SidebarMenuMessage.id}）。
      *
-     * ⚠️ **一份菜单里不许重复**（core 的 schema 拦这一条）：重了的话宿主收到消息
-     * 也分不出用户按的是哪一行，而屏幕上那两行长得完全不一样。
+     * ⚠️ **一个键里不许重复**（core 的 schema 拦这一条，两个键各拦自己那一份）：
+     * 重了的话宿主收到消息也分不出用户按的是哪一行，而屏幕上那两行长得完全不一样。
+     *
+     * ⚠️ **跨键重复反过来不拦，而且它是一句说得通的话**：同一个 `id` 同时配进
+     * `sidebarMenu` 和 `userMenu`，意思是「这个去处两处都摆一份」—— 那时两处点下去
+     * 发的是同一条消息，宿主那侧本来就该做同一件事（判据在文件头「两个键共用这一条
+     * 消息」那一段）。要拦的话得让 schema 跨字段看，而它拦掉的是一个正当写法。
      *
      * 它**不是**给人看的，所以不必好读；给人看的是 {@link label}。
      */
@@ -2131,12 +2171,29 @@ interface EpochConfig {
      */
     brand?: string;
     /**
-     * 宿主自定义的那几行侧栏菜单（2026-09-02）。**缺省 = 那张菜单里只有「设置」一行**。
+     * 宿主自定义的**侧栏那几行常驻按钮**（2026-09-02；2026-09-07 语义收窄成只管
+     * 这一处）。**缺省 = 侧栏上那几行整个没有**，那一格里只剩「用户」那一行。
      *
-     * ⚠️ **2026-09-07 起它画在侧栏最下面那一行「用户」点开的那张菜单里**，不再是
-     * 贴在「设置」上面的几行常驻按钮 —— 那一格的形态换了，**这个键一个字都没改**
-     * （`id` / `label` / `icon` 三个字段、点下去那条 `postMessage`、顺序原样、
-     * 空数组算配错，全部照旧）。宿主已经接好的那句 `message` 监听不用动。
+     * 画的位置是侧栏底部「用户」那一行**上面**，一行一个宿主入口。
+     *
+     * ## ⚠️ 2026-09-07：这个键**不再管那张菜单**，菜单归 {@link userMenu}
+     *
+     * 中间有过一版「同一份 items 画在两处」（侧栏那几行 + 用户菜单里那几项），
+     * 当天就被否了（老板原话：「不行，需要是两个配置」）。今天是**两个键各管各的面**：
+     *
+     * | 键 | 画在哪 |
+     * | -- | ------ |
+     * | 这一个 | 只画侧栏底部那几行常驻按钮 |
+     * | {@link userMenu} | 只画「用户」点开的那张菜单里的宿主项 |
+     *
+     * ⚠️ **两个键互不兜底**：配了这一个、菜单里**一项宿主项都没有**（只剩「设置」，
+     * 连分隔线都没有）；配了 `userMenu`、侧栏上**一行都不多**。判据（以及那种兜底
+     * 为什么是坏的）在 [sidebar-menu.ts](./sidebar-menu.ts) 文件头第一节。
+     *
+     * ⚠️ **这个键自己的形状一个字都没改** —— `id` / `label` / `icon` 三个字段、
+     * 点下去那条 `postMessage`、顺序原样、空数组算配错，全部照旧。宿主已经接好的
+     * 那句 `message` 监听不用动；要动的只是「原来那一份也在菜单里」的宿主，
+     * 它把想留在菜单里的那几项抄进 `userMenu` 就行。
      *
      * 形状、口径、以及「点下去往父窗口发一条 `postMessage`」那条判据，全文在
      * [sidebar-menu.ts](./sidebar-menu.ts) 的文件头 —— 这儿只记它和 {@link brand}
@@ -2144,7 +2201,7 @@ interface EpochConfig {
      * 原样下发、没配就不带那个键），所以它们并排放在顶层，而不是塞进 `display`
      * （那一段收的是**用户**的显示偏好）。
      *
-     * ⚠️ **空数组是配错了，不是「不要菜单」** —— 不要就别写这个键，同 `brand`
+     * ⚠️ **空数组是配错了，不是「不要那几行」** —— 不要就别写这个键，同 `brand`
      * 那条「空串是配错了」。core 的 schema 会为它产出一条带字段路径的 warn 诊断。
      *
      * ⚠️ **不设条数上限**，判据同 `brand` 的「不设长度上限」：为「菜单有点长」判一次
@@ -2152,6 +2209,41 @@ interface EpochConfig {
      * 兜（web 那一格滚动），不由校验兜。
      */
     sidebarMenu?: readonly SidebarMenuItem[];
+    /**
+     * 宿主自定义的**「用户」菜单里那几项**（2026-09-07）。**缺省 = 那张菜单里只有
+     * 内置的「设置」一项，连那道分隔线都没有**。
+     *
+     * 「用户」是侧栏最底下那一行（名字和头像归 {@link user}），点开是一张菜单：
+     * 这个键那几项在最上面 → 一道分隔线 → 内置的「设置」（带 `⌘,` 芯片，
+     * **永远最下面、不可配**）。
+     *
+     * ## ⚠️ 它和 {@link sidebarMenu} 是**两个配置，互相不兜底**
+     *
+     * 这个键 2026-09-07 从 `sidebarMenu` 里**拆出来**的 —— 那天中途有一版是「同一份
+     * items 两处都画」，当天被否（老板原话：「不行，需要是两个配置」）。所以：
+     *
+     * - 只配 `sidebarMenu` → 有那几行，**菜单里一项宿主项都没有**；
+     * - 只配这一个 → **侧栏上一行都不多**，菜单里有那几项；
+     * - 两个都配 → 两处各画各的（内容可以完全不一样，那正是拆开的用处）。
+     *
+     * **不许拿另一个顶上。** 那种兜底的表现是宿主配了一个键却在两处都看见东西，
+     * 而它想关掉多出来的那一处时会发现没有对应的键可关。
+     *
+     * ## 形状：和 {@link sidebarMenu} **逐字同一个**
+     *
+     * 同一个 {@link SidebarMenuItem}（`id` / `label` / `icon`）、同一条
+     * `postMessage`（`{ type: 'epoch:sidebar-menu', id }`，**不带来源**）、
+     * 同一张图标白名单、同一枚兜底图标。全文在
+     * [sidebar-menu.ts](./sidebar-menu.ts) 的文件头 —— 那个文件现在是**两个键共用**的
+     * 一份说明，`SidebarMenuItem` 这个名字里的 `Sidebar` 是它出生时的位置，
+     * 不是「只给 `sidebarMenu` 用」。
+     *
+     * ⚠️ 三条边界也逐字照那一个：**空数组是配错了**（不要就别写这个键，core 的 schema
+     * 为这个键产出一条带自己字段路径的 warn 诊断）、**`id` 不许重复**（在这个键内部；
+     * 跨键重复不拦，那是「两处都摆一份」）、**不设条数上限**（装不下由那张菜单
+     * 自己滚，判据在 web 的 `menu/index.tsx` 的 `placeMenu` 上）。
+     */
+    userMenu?: readonly SidebarMenuItem[];
     /**
      * 宿主自定义的那几张开场卡片（2026-09-04）。**缺省 = 新会话空屏上一张都没有**，
      * 那一屏仍然只有一行招呼。
@@ -2191,6 +2283,11 @@ interface EpochConfig {
      * 侧栏最下面那一行「用户」的名字和头像（2026-09-07）。**缺省 = 我们那句「用户」
      * + 一枚 `user-round`**，那一行**永远在** —— 它是设置的唯一入口。
      *
+     * ⚠️ **它只管那一行上的名字和头像，不管那张菜单里有什么** —— 菜单里的宿主项归
+     * {@link userMenu}（那是拆出来的第二个键）。两个键并排、各管一格：
+     * 只配这一个的宿主得到「一行改了名字的触发器 + 一张只有『设置』的菜单」，
+     * 而那是一句说得通的话。
+     *
      * 形状、以及「为什么这一格的默认档和上面四个键相反」，全文在
      * [host-user.ts](./host-user.ts) 的文件头 —— 这儿只记它和它们的**关系**：
      * 同一类东西（宿主装配期按下的事实、只读、`GET /api/config` 原样下发、
@@ -3710,8 +3807,10 @@ declare const SCHEDULE_RUN_STATUSES: readonly ScheduleRunStatus[];
  * 任务注册在哪儿。
  *
  * - `schtasks` / `launchd` —— 真的注册进了操作系统的调度器，**epoch 不用开着**
- * - `host` —— 一行都没注册进 OS，宿主自己掐点调 `fire()`（方案 45 §2.6 的路 B）。
- *   **关掉宿主应用就不跑**，这句话必须原样说给用户听，不许写成「已启用」
+ * - `host` —— **一行都没注册进 OS**（方案 45 §2.6 的路 B）。到点了唤起它的只能是
+ *   宿主自己（`setInterval` 调 `fire()`）—— 而宿主有没有真的这么做，**这一格答不出来**，
+ *   它唯一承诺的事实就是「没进 OS」。所以界面上不许把它写成「已启用」，
+ *   也**不许许诺「开着就会跑」**（判据全文在 locales 的 `notice_host` 上）
  */
 type ScheduleBackendKind = 'schtasks' | 'launchd' | 'host';
 /**
@@ -6364,11 +6463,13 @@ interface WireConfigResponse {
      */
     brand?: string;
     /**
-     * 宿主自定义的那几行侧栏菜单 —— **宿主没配就没有这个键**（2026-09-02）。
+     * 宿主自定义的**侧栏那几行常驻按钮** —— **宿主没配就没有这个键**（2026-09-02）。
      *
-     * ⚠️ **2026-09-07 起第一方 Web UI 把它画在「用户」那张菜单里**（原来是贴在
-     * 「设置」上面的几行常驻按钮）。**网线上这一格一个字都没改** —— 那是那张界面
-     * 自己的排版决定，而这条端点也服务着自己画前端的宿主（EMBEDDING §10）。
+     * ⚠️ **2026-09-07 语义收窄成只管那几行**：那天中途有一版把这一份同时画进
+     * 「用户」那张菜单里，当天定稿否了它 —— 菜单里的宿主项从此是**另一个键**
+     * （{@link userMenu}），两个键**互不兜底**。**网线上这一格的形状一个字都没改**，
+     * 加的是并排那个新键；而画在哪儿本来就是那张界面自己的排版决定，
+     * 这条端点也服务着自己画前端的宿主（EMBEDDING §10）。
      *
      * 和 {@link brand} 同一个形状、同一个理由，连搭在这条端点上的理由都一样：
      * 侧栏首屏就要画它，为一份可选的静态清单另开一个端点等于让每个客户端多一次往返。
@@ -6382,6 +6483,21 @@ interface WireConfigResponse {
      * 第一方 Web UI 自己的事，而这条端点也服务着自己画前端的宿主（EMBEDDING §10）。
      */
     sidebarMenu?: readonly SidebarMenuItem[];
+    /**
+     * 宿主自定义的**「用户」菜单里那几项** —— **宿主没配就没有这个键**（2026-09-07）。
+     *
+     * 来源是 `EpochConfig.userMenu`。**item 的形状和上面那个键逐字同一个**
+     * （同一个 {@link SidebarMenuItem}、同一条 `postMessage`），差的只是画在哪一格 ——
+     * 全文在 [sidebar-menu.ts](./sidebar-menu.ts) 的文件头第一节那张表。
+     *
+     * ⚠️ **两个键在这条网线上也互不兜底**：客户端拿不到这个键时，那张菜单里
+     * **一项宿主项都没有**（第一方 Web UI 那边只剩内置的「设置」，连分隔线都没有）
+     * —— **不许拿 `sidebarMenu` 那一份顶上**。自己画前端的宿主（EMBEDDING §10）
+     * 照同一条口径：两个键各画各的面，缺哪个就少哪一面。
+     *
+     * ⚠️ **原样转发，服务端一个字都不改**，判据逐字同上面那个 `sidebarMenu`。
+     */
+    userMenu?: readonly SidebarMenuItem[];
     /**
      * 宿主自定义的那几张开场卡片 —— **宿主没配就没有这个键**（2026-09-04）。
      *
@@ -11944,9 +12060,17 @@ declare const WIRE_SCHEDULE_CREATE_FIELDS: WireFields<WireScheduleCreateRequest>
 /**
  * `PATCH /api/schedules/:id` 的请求体 —— **没给的字段一个都不动**。
  *
- * ⚠️ 三个「清空」用 `null` 而不是空串：`workDir: null` 是「不绑工作区了」，
- * `workDir: ''` 说不清是「清空」还是「客户端把一个 undefined 序列化坏了」。
+ * ⚠️ **四个**「清空」用 `null` 而不是空串（`workDir` / `model` / `startDate` /
+ * `endDate`）：`workDir: null` 是「不绑工作区了」，而 `workDir: ''` 说不清是
+ * 「清空」还是「客户端把一个 undefined 序列化坏了」。
  * 同一条规矩在 `WireModelSetRequest.model` 上用过一次。
+ *
+ * ⚠️ **这个 `null` 一路走到 SQLite 的 `NULL`，中间没有第二个词。**
+ * 2026-09-07 之前 server 那一层把它翻成空串再往下递（`schedule/body.ts`），
+ * 而 core 压根不认空串是清空 —— 于是「两格生效区间都没填」被判成
+ * 「给了两个不合法的日期」，表单上冒出两行 `生效区间不对: ` 后面空着；
+ * 而那个空串真要是落进库，`isWithinWindow` 对它是 `false`，这条任务会
+ * **每次到点都被判在生效区间外**。判据全文在 `UpdateScheduleInput` 上。
  */
 interface WireScheduleUpdateRequest {
     name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/protocol",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "private": false,
   "description": "epoch-agent 契约层：工具 / 事件 / 权限 / 插件的类型定义，零运行时依赖",
   "repository": {