@epoch-agent/protocol 0.27.0 → 0.28.0

package/dist/index.d.ts

@@ -3328,6 +3328,21 @@ interface CustomCommandDef {
      * 而引擎侧手里只有这张表。拆成两个类型（一个给 UI、一个给引擎）迟早漂移。
      */
     prompt: string;
+    /**
+     * frontmatter 的 `displayName`：**给人看**的称呼（2026-10-10）。缺省 = 屏幕上印 {@link name}。
+     *
+     * 判据逐字同角色那一格（`AgentRole.displayName`，`agent-role.ts`）：`name` 一个字节
+     * 都不动 —— 它仍是用户敲的那个 `/xxx`、服务端认命令的那个 key、同名合并的 key；
+     * 这一格只是屏幕上的称呼。插件命令的名字**一定带 `<插件名>:` 前缀**
+     * （`aione:bailing_daily_report`），那是两个标识拼起来的，不是一个人的叫法。
+     *
+     * 键名用驼峰而不是本文件其余键的连字符（`argument-hint`）：连字符那几个是对齐
+     * 同类工具的既有写法，而这一格别家没有，没有可对齐的；同一个插件的作者在
+     * `plugin.json` 和角色 md 上写的都是 `displayName`，三处一个词。
+     *
+     * ⚠️ **缺省回落发生在消费侧**，判据同 `AgentRole.displayName` 末节。
+     */
+    displayName?: string;
     /** frontmatter 的 `description`，必填 —— `/help` 和补全面板里显示的那行 */
     description: string;
     /** frontmatter 的 `argument-hint`，例如 `[scope]`。只用于展示 */
@@ -4830,6 +4845,13 @@ type AgentEvent =
     type: 'steer';
     text: string;
     parts?: EpochContentPart[];
+    /**
+     * 发送方在 `POST /messages` 里给的编号（2026-10-10）。**引擎从不填它** —— 是
+     * Hub 往网线上扇出时按「交给引擎的先后」贴上的（`server/src/hub.ts` 的 `drive()`）。
+     * 发送方拿它认出「这句插话是我那条」，把本地乐观上屏的那份换到这一帧的位置。
+     * 判据在 `WireSendMessageRequest.clientMessageId` 上。
+     */
+    clientMessageId?: string;
 }
 /** 运行中出错（随后会有一个 finish: 'error'） */
  | {
@@ -7054,6 +7076,38 @@ type WireHubEvent =
     id: string;
     text: string;
     autoSend: boolean;
+}
+/**
+ * 这一轮的用户消息 —— **一轮开跑那一刻**广播（2026-10-10）。
+ *
+ * ## 治的是什么
+ *
+ * 同一段会话开在两处（电脑上的窗口 + 手机，或者两个标签页），在一处发的那条，
+ * 另一处在这之前**根本收不到**：`drive()` 只扇出引擎产出的事件，跑到一半插的话
+ * 有引擎发的 `steer`，而开轮那一条谁都没发。另一处于是看到模型的回答、看到标题
+ * 变了，正文里却没有那条问题。
+ *
+ * ## 时机：开跑时，不是收下时
+ *
+ * 由 `beginTurn()` 在 `session-state: running` 之后、`drive()` 之前发。排队的那几条
+ * 各在**自己开跑时**才发 —— 收下时就发的话，它会被画进上一轮的中间。
+ * 被正在跑的那一轮拉走的（插进本轮）**不走这一帧**，那一条由引擎发 `steer`；
+ * 两帧讲的是两件事，一条消息只会有其中一帧。
+ *
+ * ## 载荷照 `steer`
+ *
+ * `text` 是文本投影（`contentToText()`，同落盘那一列），`parts` 只在有图片 / 文件时
+ * 出现。内容是**斜杠命令展开之后**的那份 —— 和刷新之后历史里显示的是同一份。
+ *
+ * ⚠️ **发送方自己会再收到一遍。** 它在发出那一刻已经乐观上屏了，收到这一帧时拿
+ * `clientMessageId` 认出这是自己那条、别再画一次。
+ */
+ | {
+    type: 'user-message';
+    text: string;
+    parts?: EpochContentPart[];
+    /** 发送方在 `POST /messages` 里给的编号，原样带回；没给就缺席（判据在 `WireSendMessageRequest.clientMessageId` 上） */
+    clientMessageId?: string;
 };
 /** 信封里能装的所有东西 */
 type WireEvent = WireAgentEvent | WireHubEvent;
@@ -9394,6 +9448,49 @@ interface WireSendMessageRequest {
      * 缺席 = 这一条没有附件。**不写进下面那份必填清单**，同 `role`。
      */
     attachments?: readonly string[];
+    /**
+     * 这一条**按哪条自定义命令发**（2026-10-10）：面板上挑中、挂成 chip 的那条命令名，
+     * 不带斜杠。给了它，{@link message} 里装的就**只是参数**（可以为空、可以多行）。
+     *
+     * ## 为什么不拼成 `/name 参数` 一行字发
+     *
+     * 那一行要过服务端「这是不是一条命令」的判定（`server/src/commands.ts` 的
+     * `parseSlashInput`），而那道判定**只认单行** —— 多行输入里第一行是 `/foo`，
+     * 它按「一段以斜杠开头的文字」放行，这在用户**手打**的时候是对的（贴一段
+     * `/etc/hosts` 再接着问）。挂着 chip 时用户已经明确挑了命令，没有意图可猜：
+     * 参数里一换行，命令就悄悄不生效、而 chip 已经随着发送消失了。
+     * 名字单独走这一格，那道判定在这条路上就压根不跑。
+     *
+     * ## ⚠️ 认不出来的名字是 400 `unknown-command`，这一条不发出去
+     *
+     * 判据逐字照上面 `role`：用户显式挑了一条命令，按普通消息发出去的话模型收到的
+     * 只是一串参数，而屏幕上没有任何区别。手打的 `/xxx` 认不出来时照旧当普通文本 ——
+     * 那是另一条路、另一种意图。
+     *
+     * 不是字符串 / 空串 = 当没给，同 `role`。缺席 = 这一条不是用 chip 挑的命令
+     * （手打的 `/xxx` 仍走 `message` 那一行字的判定）。
+     */
+    command?: string;
+    /**
+     * 发送方给这一条起的编号（2026-10-10）—— **服务端不解读，原样带回**。
+     *
+     * 带回到两处：这一条自己开一轮时，贴在 Hub 事件 `user-message` 上；被正在跑的那一轮
+     * 拉走时，贴在引擎那帧 `steer` 上。发送方在发出那一刻已经乐观上屏了，拿这个编号认出
+     * 「这条回执是我那条」—— 开轮的不再画第二遍，插话的把本地那份换到事件流给的位置。
+     *
+     * ## 为什么要发送方自己起，而不是服务端起了在 202 里回
+     *
+     * 事件流那一帧可能**比 202 先到**（`hub.start()` 同步发帧，回包在它之后才写），
+     * 服务端起的号发送方那时还不认得。自己起的号在乐观上屏那一刻就在手上，没有先后问题。
+     *
+     * ## 为什么不按条数、不按文字认
+     *
+     * 条数：两处几乎同一瞬间各发一条时会认错。文字：广播的是斜杠命令**展开之后**、
+     * `@` 引用**附上之后**的内容，和发送方屏幕上那一行对不上。
+     *
+     * 不是字符串、空串、超过 128 个字符 = 当没给（这一条照常发，只是回执上不带编号）。
+     */
+    clientMessageId?: string;
 }
 declare const WIRE_SEND_MESSAGE_FIELDS: WireFields<WireSendMessageRequest>;
 /**
@@ -10317,6 +10414,14 @@ declare const WIRE_REWIND_RESPONSE_FIELDS: WireFields<WireRewindResponse>;
 interface WireCustomCommand {
     /** 命令名，不带斜杠。子目录用 `:` 连接（`commands/git/commit.md` → `git:commit`） */
     name: string;
+    /**
+     * frontmatter 的 `displayName`（`CustomCommandDef.displayName`，2026-10-10）。
+     * **没写的命令这个键缺席**，判据同下面 `argumentHint`；回落到 `name` 在界面那一侧做。
+     *
+     * ⚠️ 它**只进屏幕**：面板那一行的标题、选中之后输入框里那枚 chip。发消息时
+     * 带的仍是 `name`（`WireSendMessageRequest.command`）—— 服务端只认它。
+     */
+    displayName?: string;
     /** frontmatter 的 `description`。面板上名字后面那一行 */
     description: string;
     /**

package/dist/index.js

@@ -844,7 +844,8 @@ var HUB_EVENT_TYPES = /* @__PURE__ */ new Set([
   "sessions-changed",
   "session-title-changed",
   "plugins-changed",
-  "host-compose"
+  "host-compose",
+  "user-message"
 ]);
 function isWireHubEvent(event) {
   return HUB_EVENT_TYPES.has(event.type);

package/package.json

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