@coda-console/protocol 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 按 semver。协议自己的大版本写在协议名里（如 `coda/run@1`），与 npm 包版本、插件清单的 v2 独立；更早的版本见 git 历史。
 
+## 3.5.0 — 2026-11-09
+
+- 流程参数的 `agent` 类型：值是一组 Agent 选择，与插件设置的 Agent 组合（`format: coda-agent`）相同：`agent`，以及可选的 `model`、`effort`、`mode`、`options`。不写 `default`；`defaultFrom="session.agent"` 是从会话发起、没给值时取那个会话的 Agent 选择，只用于这种参数（Coda #2303 第 4 步）。
+
+## 3.4.0 — 2026-11-09
+
+- `coda/session@1` 的 `read`：都不带游标时读最新的 `limit` 条；写清 `before` 是这个游标之前最新的 `limit` 条、`more` 表示更早还有没有；消息总按先后排；`after` 与 `before` 不能同时带（Coda #2311）。
+- `coda/session@1` 的消息加可选的 `senderName`：发送者当时的显示名，大群不必把每个发送者都写进 `status.participants`。
+
 ## 3.3.0 — 2026-11-09
 
 - `coda:choice` 的 `note`：`required` 时选它必须附言（写说明或附上文件），默认 `optional`（Coda #2303 第 3 步：卡片在输入框里填写）。

package/docs/protocol.md

@@ -293,12 +293,17 @@ status：
 
 观察方 watch 这条记录，`head` 变了就用 `read` 读游标之后的消息。两个操作都是立即结果，不开运行；`read` 是 `safe` 的：
 
-- `read`：输入 `{ after?, before?, limit? }`，`after`、`before` 是游标，`limit` 为 1 到 100；结果 `{ messages, cursor, more }`，没有消息时 `cursor` 为 `null`。
+- `read`：输入 `{ after?, before?, limit? }`，`after`、`before` 是游标，`limit` 为 1 到 100；结果 `{ messages, cursor, more }`，没有消息时 `cursor` 为 `null`。`messages` 总按先后排，旧的在前：
+  - 都不带游标：最新的 `limit` 条，`more` 表示更早还有没有；客户端打开会话时先读这一页；
+  - 只带 `after`：这个游标之后的，`more` 表示之后还有没有；
+  - 只带 `before`：这个游标之前最新的 `limit` 条，`more` 表示更早还有没有；往前翻页就拿这一页第一条的 `cursor` 作下一次的 `before`；
+  - `after` 与 `before` 不能同时带。
 - `post`：输入 `{ text, parts?, replyTo?, mentions? }`；结果 `{ message: { id, cursor } }`。发送者固定是 `self`；Provider 按调用的 `requestId` 只发一次，发送失败就报错。
 
-消息是 `{ id, cursor, sender, text, parts?, replyTo?, mentions?, about?, createdAt? }`：
+消息是 `{ id, cursor, sender, senderName?, text, parts?, replyTo?, mentions?, about?, createdAt? }`：
 
 - `sender` 与 `mentions` 写参与者 ID，`replyTo` 写消息 ID；
+- `senderName` 是发送者当时的显示名，可选：大群不必把每个发送者都写进 `status.participants`；
 - 回复一条消息就算 @ 了它的发送者，Provider 把被回复消息的发送者也写进 `mentions`：只有 Provider 知道被回复的那条是谁发的，观察方不用记住 Bot 发过哪些消息；
 - `text` 是纯文本兜底，看不懂 `parts` 的一方只看它；
 - 撤回、编辑、表情回应都是一条新消息，`about: { message, change: "edit"|"recall"|"reaction", value? }` 指向旧消息；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Coda 的协议：插件清单的类型（JSON Schema）、通用校验器、协议定义与调用信封、流程方言与 Agent 接入协议",
   "type": "module",
   "license": "MIT",

package/schemas/protocol/v1/session.json

@@ -58,7 +58,7 @@
   },
   "operations": {
     "read": {
-      "description": "读消息：after、before 是游标，limit 为 1 到 100；立即结果。",
+      "description": "读消息，limit 为 1 到 100，消息总按先后排（旧在前）；立即结果。都不带游标时读最新的 limit 条，more 表示更早还有没有；带 after 读这个游标之后的，more 表示之后还有没有；带 before 读这个游标之前最新的 limit 条，more 表示更早还有没有。after 与 before 不能同时带。",
       "safe": true,
       "input": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -68,6 +68,7 @@
           "before": {"type": "string", "minLength": 1, "maxLength": 2048},
           "limit": {"type": "integer", "minimum": 1, "maximum": 100}
         },
+        "not": {"required": ["after", "before"]},
         "additionalProperties": false
       },
       "result": {
@@ -109,6 +110,7 @@
               "id": {"$ref": "#/$defs/id"},
               "cursor": {"$ref": "#/$defs/id"},
               "sender": {"$ref": "#/$defs/id", "description": "参与者 ID"},
+              "senderName": {"type": "string", "maxLength": 200, "description": "发送者当时的显示名，可选；大群不必把每个发送者都写进 status.participants"},
               "text": {"type": "string", "description": "纯文本兜底"},
               "parts": {"type": "array", "items": {"$ref": "#/$defs/part"}},
               "replyTo": {"$ref": "#/$defs/id", "description": "回复的消息 ID"},

package/workflow/dialect.json

@@ -20,7 +20,7 @@
   "stepFailed": "STEP_FAILED",
   "variables": ["inputs", "run", "github", "vars"],
   "inputs": {
-    "types": ["string", "boolean", "number", "branch"],
-    "sources": {"session.branch": ["branch", "string"]}
+    "types": ["string", "boolean", "number", "branch", "agent"],
+    "sources": {"session.branch": ["branch", "string"], "session.agent": ["agent"]}
   }
 }

package/workflow/moddle.json

@@ -120,7 +120,7 @@
     {
       "name": "Input",
       "superClass": ["Element"],
-      "description": "运行的一个输入：label 是表单上的名字，defaultFrom 是从会话发起、没给值时从哪里取（在 default 之前）",
+      "description": "运行的一个输入：label 是表单上的名字，defaultFrom 是从会话发起、没给值时从哪里取（在 default 之前）；type 为 agent 的值是一组 Agent 选择（agent，以及可选的 model、effort、mode、options）",
       "properties": [
         {"name": "name", "isAttr": true, "type": "String"},
         {"name": "type", "isAttr": true, "type": "String"},

package/workflow/values.json

@@ -92,13 +92,15 @@
           "not": {"enum": ["__defineGetter__", "__defineSetter__", "__lookupGetter__", "__lookupSetter__", "__proto__", "constructor", "hasOwnProperty", "isPrototypeOf",
             "propertyIsEnumerable", "toLocaleString", "toString", "valueOf"]},
           "description": "name 不合法：须为字母开头的字母、数字、「_」，且不是 JavaScript 对象自带的名字（如 constructor、toString、__proto__）：运行按名字记和取输入"},
-        "type": {"enum": ["string", "boolean", "number", "branch"], "description": "type 只能是 string、boolean、number、branch"},
+        "type": {"enum": ["string", "boolean", "number", "branch", "agent"], "description": "type 只能是 string、boolean、number、branch、agent"},
         "label": {"type": "string", "pattern": "\\S", "maxLength": 40, "description": "label 须为 1–40 个字"},
-        "defaultFrom": {"enum": ["session.branch"], "description": "defaultFrom 只能是 session.branch"}
+        "defaultFrom": {"enum": ["session.branch", "session.agent"], "description": "defaultFrom 只能是 session.branch 或 session.agent"}
       },
       "required": ["name"],
       "allOf": [
-        {"if": {"required": ["defaultFrom"]}, "then": {"properties": {"type": {"enum": ["branch", "string"], "description": "defaultFrom=\"session.branch\" 只用于 type 为 branch、string 的参数"}}}},
+        {"if": {"required": ["defaultFrom"], "properties": {"defaultFrom": {"const": "session.branch"}}}, "then": {"properties": {"type": {"enum": ["branch", "string"], "description": "defaultFrom=\"session.branch\" 只用于 type 为 branch、string 的参数"}}}},
+        {"if": {"required": ["defaultFrom"], "properties": {"defaultFrom": {"const": "session.agent"}}}, "then": {"required": ["type"], "description": "defaultFrom=\"session.agent\" 只用于 type 为 agent 的参数", "properties": {"type": {"enum": ["agent"], "description": "defaultFrom=\"session.agent\" 只用于 type 为 agent 的参数"}}}},
+        {"if": {"required": ["type"], "properties": {"type": {"const": "agent"}}}, "then": {"not": {"required": ["default"]}, "description": "type 为 agent 的参数不写 default：值是一组 Agent 选择，从会话取用 defaultFrom=\"session.agent\""}},
         {"if": {"required": ["type"], "properties": {"type": {"const": "number"}}},
           "then": {"properties": {"default": {"pattern": "^\\s*[-+]?(?:\\d+\\.?\\d*|\\.\\d+)(?:[eE][-+]?\\d+)?\\s*$", "x-number": true, "description": "default 须为数字"}}}}
       ]