@coda-console/protocol 1.8.0 → 1.9.0

package/README.md

@@ -5,7 +5,7 @@ Coda 与插件之间的约定，Coda 和插件都引用它，独立演进：
 - **插件清单的类型**（`schemas/plugin/`）：插件目录 `package.json` 里 `contributes` 的每个键是一种类型，各有一份 JSON Schema（draft 2020-12，`$id` 为 `https://coda.pub/schemas/plugin/v1/<文件>`）。`plugin.json` 是整份清单，`setting.json` 是一项设置的声明。插件写的合乎它用到的类型就对；写给别的插件扩展点的键由那个插件声明，扩展点可以带自己的 schema（`extensionPoints.<名>.schema`，声明它的插件目录里的一个文件），写给它的东西合乎那份 schema 才对。
 - **通用校验器**（`validate.mjs`）：用 Ajv 对清单做 schema 校验。JSON Schema 说不了的只用五个通用关键字（`x-unique-by`、`x-max-contains`、`x-ref`、`x-placeholders`、`x-file`，照 Kubernetes 的 `x-kubernetes-*`），每个在哪里写都是同一个意思，写法见文件开头。校验器不随功能变长：类型加字段就是改 schema。
 - **流程方言**（`workflow/`）：项目和插件的流程（`.coda/workflows/*.bpmn`，BPMN 2.0）在 Coda 的命名空间 `https://coda.pub/schema/bpmn/1.0` 里能写什么。`moddle.json` 是 `coda:` 属性与元素（bpmn-moddle 的描述格式），`values.json` 是每个值能写什么（每个 `coda:` 类型的属性组成的对象的 JSON Schema，一个元素里同种 `coda:` 元素成组的 schema），`actions.json` 是 `coda:action` 的各个动作和它们接受的参数，`dialect.json` 是流程种类、Coda 自己发的事件、步骤失败的错误码、表达式能读的运行变量和运行的输入能是哪些类型。`workflow.mjs` 用它们读一份流程：方言里没有的、值不合 schema 的都拒绝，说法是「位置：schema 对那里的说明」。值的 schema 用清单的那几个关键字，另加三个：`x-feel`（是 FEEL：「=」开头是表达式，否则文字里的 `{{ … }}` 是，按这份流程里的名字读得通）、`x-duration`（ISO 8601 时长，不为负）、`x-number`（文字换算成数字是个有限的数）。`structure.json` 声明流程结构规则，`structure.mjs` 负责跨节点检查。
-- **Agent 接入协议**（`docs/agent-protocol.md`）：Coda 怎样用 ACP 接 Agent，以及 Coda 加的扩展（会话指令、插话、`_coda/wait`、执行失败、工具调用的审核）。
+- **Agent 接入扩展**（`schemas/agent/`、`agent.mjs`、`docs/agent-protocol.md`）：Coda 怎样用 ACP 接 Agent，以及 Coda 加的扩展（会话指令、插话、`_coda/wait`、执行失败、工具调用的审核）。
 
 流程方言的 **结构规则**从 1.8.0 起也由 `readWorkflow` / `workflowProblem` 检查。`workflow/structure.json` 声明支持的顶层元素与不支持的流程元素、各位置的事件定义、`coda:` 属性的位置限制、任务与多实例的局部写法、脚本数量、定时间隔和生命周期等待类型。`rules` 使用 JSON Schema 检查节点的无环投影（原始标量属性与父级、事件种类等固定事实），复用 `newAjv()` 和已有关键字；`moddle.json` 的 `extends` 仍声明属性可附着的基础类型。`CODA_STRUCTURE` 导出同一份表。新增局部规则改数据，不增加校验器分支。
 
@@ -63,6 +63,31 @@ fieldsProblem(JSON.parse(fieldsJSON), 'ask');
 
 设置的 `items.anyOf` 选项可附带 `workflowKind`（`check`、`premerge`、`deploy`、`preview`、`release`）。全局设置显示全部选项；项目设置只显示该项目有的流程类别，未写此字段的选项始终显示。宿主负责按项目提供可选项，流程执行时仍需按运行的提交判断可用操作。
 
+## Agent 接入扩展
+
+从 1.9.0 起，[Agent 协议正文](docs/agent-protocol.md#可执行的形状定义)引用 `schemas/agent/` 的可执行定义：
+活动报告与停止、上下文压缩、远端入口、双方能力声明、插话的 Coda 约定、执行失败、工具审核、用量数据和默认选项标记。
+`messages.json` 是方向与参数／答复 schema 的索引；ACP 本身仍由 ACP SDK 校验。
+
+```js
+import {
+  agentMessageProblem, agentResultProblem,
+  agentCapabilitiesProblem, agentValueProblem,
+  AGENT_METHODS, AGENT_SCHEMAS,
+} from '@coda-console/protocol/agent';
+
+agentMessageProblem('_coda/wait', {
+  sessionId: 's1', waitId: 'build', state: 'waiting',
+}); // null, or "location: schema description"
+agentResultProblem('_coda/session/compact', { compacted: true });
+agentCapabilitiesProblem({ coda: { waits: {}, compact: {} } }, 'agent');
+agentValueProblem('review.json', review, '工具的审核');
+```
+
+校验不修改输入。未知扩展键保留；活动文本长度沿用 UTF-16，日期沿用 `Date.parse`，用量数据按 JSON 的 UTF-8 字节数限制。
+深层／大型 JSON 用显式栈检查，非有限数字与循环引用不会通过。会话归属、活动状态迁移、调用起因、协商、超时、重试和授权仍由宿主判断；
+丢弃未知风险值、压缩答复的裁剪与兜底等整理也留在 Coda。详见正文的兼容性与接入说明。
+
 ## 谁在用
 
 - **Coda**：读插件时用它校验清单，再整理成自己的结构；只另看插件身份（ID、设置名在 ID 之下），以及装到一台机器上才知道的（来源、已装插件的冲突）。读流程时用 `readWorkflow` 同时校验方言、值与结构，再编译成引擎需要的数据。

package/agent.mjs

@@ -0,0 +1,84 @@
+// Coda's extensions beside ACP: methods select schemas from a table; metadata selects a schema by reference.
+// ACP itself stays with its SDK. These checks neither normalize values nor decide anything about a live session.
+import { readFileSync, readdirSync } from 'node:fs';
+import { newAjv, described } from './validate.mjs';
+import { jsonFits, valueKeywords } from './workflow/keywords.mjs';
+
+const dir = new URL('./schemas/agent/', import.meta.url), base = 'https://coda.pub/schemas/agent/v1/';
+const read = file => JSON.parse(readFileSync(new URL(file, dir), 'utf8'));
+export const AGENT_METHODS = read('messages.json').methods;
+export const AGENT_SCHEMAS = Object.fromEntries(readdirSync(dir).filter(file => file.endsWith('.json') && file !== 'messages.json')
+  .sort().map(file => [file, read(file)]));
+const schemas = Object.values(AGENT_SCHEMAS), ajv = newAjv();
+// Wire objects have own keys, including names also found on Object.prototype.
+ajv.opts.ownProperties = true;
+valueKeywords(ajv, {});
+ajv.addFormat('date-parse', value => Number.isFinite(Date.parse(value)));
+for (const schema of schemas) ajv.addSchema(schema);
+
+const unescape = step => step.replaceAll('~1', '/').replaceAll('~0', '~');
+const escape = step => step.replaceAll('~', '~0').replaceAll('/', '~1');
+const place = (path, where) => path.split('/').slice(1).map(unescape).reduce((at, step) =>
+  /^\d+$/.test(step) ? `${at}[${step}]` : /^[A-Za-z_$][\w$]*$/.test(step) ? `${at}.${step}` : `${at}「${step}」`, where);
+function schemaAt(ref) {
+  if (typeof ref !== 'string') return undefined;
+  const [file, fragment = '', extra] = ref.split('#');
+  if (extra !== undefined || !Object.hasOwn(AGENT_SCHEMAS, file)) return undefined;
+  let pointer;
+  try { pointer = decodeURIComponent(fragment); } catch { return undefined; }
+  if (pointer && !pointer.startsWith('/')) return undefined;
+  let node = AGENT_SCHEMAS[file];
+  for (const token of pointer.split('/').slice(1)) {
+    if (/~(?:[^01]|$)/.test(token)) return undefined;
+    const key = unescape(token);
+    node = node && typeof node === 'object' && Object.hasOwn(node, key) ? node[key] : undefined;
+  }
+  return typeof node === 'boolean' || node && typeof node === 'object' && !Array.isArray(node) ? node : undefined;
+}
+// Resolve only schema references, never pointers through incoming data or prototype properties.
+function resolve(schema) {
+  while (schema?.$ref) {
+    const url = new URL(schema.$ref, base), file = url.pathname.split('/').at(-1);
+    schema = schemaAt(`${file}${url.hash}`);
+  }
+  return schema;
+}
+function description(schema) {
+  const stack = [schema];
+  while (stack.length) {
+    const node = resolve(stack.pop());
+    if (node?.description) return node.description;
+    if (node?.allOf) for (let i = node.allOf.length - 1; i >= 0; i--) stack.push(node.allOf[i]);
+  }
+}
+function problem(error, where) {
+  let path = error.instancePath, said;
+  if (error.keyword === 'required') {
+    const key = error.params.missingProperty, properties = error.parentSchema.properties;
+    path += `/${escape(key)}`;
+    said = properties && Object.hasOwn(properties, key) ? description(properties[key]) : undefined;
+  }
+  return `${place(path, where)}：${said ?? described(error, { schemas }) ?? error.message}`;
+}
+
+// A reference is relative to schemas/agent/, optionally with a JSON Pointer fragment.
+export function agentValueProblem(ref, value, where = ref) {
+  const validate = schemaAt(ref) !== undefined ? ajv.getSchema(`${base}${ref}`) : null;
+  if (!validate) return `${where}：没有这个 Agent schema`;
+  if (!validate(value)) return problem(validate.errors[0], where);
+  // Opaque remote payloads and future metadata are JSON too. An explicit stack handles deep/wide values and cycles.
+  return jsonFits(value, Infinity) ? null : `${where}：${AGENT_SCHEMAS['json.json'].description}`;
+}
+function messageProblem(method, part, value, where) {
+  const entry = typeof method === 'string' && Object.hasOwn(AGENT_METHODS, method) ? AGENT_METHODS[method] : null;
+  if (!entry) return `${where}：没有这个 Coda 扩展方法`;
+  if (!Object.hasOwn(entry, part)) return `${where}：通知没有答复`;
+  return agentValueProblem(entry[part], value, where);
+}
+export const agentMessageProblem = (method, params, where = `${method} params`) => messageProblem(method, 'params', params, where);
+export const agentResultProblem = (method, result, where = `${method} result`) => messageProblem(method, 'result', result, where);
+// Pass the capabilities' _meta object, not initialize itself. An absent _meta means no Coda capabilities declared.
+export function agentCapabilitiesProblem(meta, party = 'agent', where = `${party}Capabilities._meta`) {
+  if (party !== 'agent' && party !== 'client') return `${where}：能力声明方只能是 agent 或 client`;
+  return meta === undefined ? null : agentValueProblem(`${party}-capabilities.json`, meta, where);
+}

package/docs/agent-protocol.md

@@ -7,6 +7,47 @@ Coda 就知道这个 Agent 在一轮之外还在做什么，如实显示、不
 
 **改协议**：本文在 `coda-console/coda-protocol`，与插件清单的类型（`schemas/`）同一个仓库、同一个版本（npm 包 `@coda-console/protocol`）。Coda 与公开仓库 `coda-console/coda-plugins` 的契约检查包都依赖这个包：改协议就在这里开 PR，发布新版本后两边各自升依赖。检查要换判定方式时（新的请求怎么发、怎样算合格），另给 coda-plugins 开 PR 改检查本身。文中提到的 Coda 文档与源码在 Coda 的仓库里。
 
+## 可执行的形状定义
+
+扩展的字段、必填项和取值以 [`schemas/agent/`](../schemas/agent/) 为准（JSON Schema draft 2020-12，
+`$id` 为 `https://coda.pub/schemas/agent/v1/<文件>`）。本文解释方向、生命周期与处理方式；
+[`messages.json`](../schemas/agent/messages.json) 是方法到 schema 的数据索引，标明请求／通知与方向。
+ACP 的消息、内容块、会话指令和能力由 ACP SDK 校验，这里只补 Coda 的部分，不代替 ACP 校验。
+
+| 扩展或位置 | schema |
+| --- | --- |
+| `_coda/wait` 通知参数 | [wait.json](../schemas/agent/wait.json) |
+| `_coda/wait/stop` 参数、答复 | [wait-stop.json](../schemas/agent/wait-stop.json) 的 `$defs/params`、`$defs/result` |
+| `_coda/session/compact` 参数、答复 | [compact.json](../schemas/agent/compact.json) 的 `$defs/params`、`$defs/result` |
+| `_coda/remote/code` 参数、答复 | [remote-code.json](../schemas/agent/remote-code.json) 的 `$defs/params`、`$defs/result` |
+| `_coda/remote` 参数、答复 | [remote.json](../schemas/agent/remote.json) 的 `$defs/params`、`$defs/result` |
+| `clientCapabilities._meta`、`agentCapabilities._meta` 的 Coda 声明 | [client-capabilities.json](../schemas/agent/client-capabilities.json)、[agent-capabilities.json](../schemas/agent/agent-capabilities.json) |
+| `_session/steering` 的 Coda 约定 | [steering.json](../schemas/agent/steering.json) 的 `$defs/params`、`$defs/result`、`$defs/capabilities`（initialize 顶层 `_meta`）；`prompt` 内容仍由 ACP SDK 校验 |
+| `error.data._meta.coda.failure` | [failure.json](../schemas/agent/failure.json) |
+| 工具更新的 `_meta.coda.review` | [review.json](../schemas/agent/review.json)；已知风险值见 `$defs/risk` |
+| 用量更新的 `_meta.coda` | [usage.json](../schemas/agent/usage.json) |
+| 配置选项的 `_meta.coda.default` | [default.json](../schemas/agent/default.json)（传入 `_meta.coda` 对象） |
+
+`@coda-console/protocol/agent` 导出 `agentMessageProblem(method, params)`、`agentResultProblem(method, result)`、
+`agentCapabilitiesProblem(meta, party = 'agent')` 和 `agentValueProblem(ref, value, where)`，合法返回 `null`，
+不合则返回「位置：schema 的 description」。前两个函数也接受第三个 `where`；能力校验接受第三个 `where`，
+`meta` 是能力声明的整个 `_meta`（缺省合法），`party` 是 `agent` 或 `client`；`ref` 是上述文件名，可带 `#/$defs/…`。
+不认识的方法返回问题，调用方须先按 `AGENT_METHODS` 区分 ACP、Coda 扩展和其他扩展；通知没有答复 schema。
+`AGENT_SCHEMAS` 导出按文件名索引的同一份 schema。
+
+保留现有接收规则：未知键允许并且不改写；活动的 `kind` 不限于本文列出的词，文本上限用 `x-length` 按 UTF-16 长度计算；
+`date-parse` format 沿用 `Date.parse`，发送端仍应使用 ISO 8601。`x-json` 复用流程的 JSON 字节预算检查。
+API 接受 [json.json](../schemas/agent/json.json) 所述的 JSON 值，额外以显式栈检查不在 JSON 中的值（非有限数字、循环引用等），不设不必要的嵌套层数或数组长度上限。
+Coda 过去静默丢弃的值，契约检查现在可得到具体位置；过去没有独立报错的字段补了 description，已有报错沿用原句，
+不把原始输入拼入错误（避免巨大值或深层对象导致报错本身失败）。
+
+**校验不是整理或运行状态判断**：审核未知 `risk` 不影响整条审核有效，宿主仍只保存 `$defs/risk` 接受的值；
+额度不足只按 `kind` 判断，不校验也不采用它附带的 `input`／`retryAfterMs`；压缩答复的未知字段照样允许，
+宿主仍只保存已知字段、裁剪原因，畸形答复仍按原有兜底处理，不应把整个答复的校验失败改成执行失败。
+压缩的 `before`／`after` 沿用有限数要求，不新增整数或非负限制。能力声明 schema 描述对象声明，
+不代替能力探测：未声明、不合法的声明仍按宿主原有方式处理（旧 `supportsRemote` 还把数组视为声明，不能直接用 schema 替换该谓词）。
+会话归属、能力是否协商、活动是否存在／终结、调用起因、轮次、顺序、重试、超时、绑定码有效期和授权仍由 Coda 处理。
+
 ## 生命周期归属
 
 插件在 `contributes.agents[]` 声明 `lifecycle`，默认 `managed`；外部自主运行的 Bot 声明 `external`。
@@ -58,7 +99,7 @@ ACP 只允许在一轮（`session/prompt`）进行时交互。Agent 在两轮之
   之后 `config_option_update` 与 `session/set_config_option`、`session/set_model` 的结果改了它，以改后的为准。Coda 每轮开始前把会话设置设给 Agent，
   再读当前模型记作这一轮的实际模型；读不到就拒绝这一轮（「适配器未报告实际模型」），不发 `session/prompt`。
 - **设置**：会话设置里选了的模型、推理强度与模式，每轮开始前设给 Agent；没选的保持会话现状。当前模式是空字符串表示还没有选模式（Agent 按它自己的配置），按没有设置显示。模型或推理强度的选择型配置项里，
-  可以有一项带 `_meta.coda.default: true`，表示交给 Agent 自己的默认：会话设置里没选时，Coda 把配置项切回这一项。这一项不进模型或强度的列表，
+  可以有一项带 `_meta.coda.default: true`（[default.json](../schemas/agent/default.json)），表示交给 Agent 自己的默认：会话设置里没选时，Coda 把配置项切回这一项。这一项不进模型或强度的列表，
   当前值是它时按没有设置显示。
 - **其他配置项**：模型、推理强度与模式之外的配置项，Coda 原样列给用户：选择型是一组选项，开关型（`type: boolean`）是一个开关；Coda 在 `initialize` 的
   `clientCapabilities.session.configOptions.boolean` 里声明接受开关型。会话设置里按配置项 ID 给的值，每轮开始前设给 Agent；当前模型没有这一项就不设。
@@ -73,6 +114,8 @@ ACP 只允许在一轮（`session/prompt`）进行时交互。Agent 在两轮之
 
 ## 会话指令
 
+本节形状由 ACP SDK 的 `systemPrompt` schema 定义，不在 Coda schema 中重复。
+
 Coda 给每个会话一份指令：回复怎样在 Mac 与 iPhone 上显示、默认回复语言，再接目录启用的插件说明（插件（Coda 的 docs/plugins.md）的 `contributes.instructions`），
 正文在 `backend/src/components/session-config/client-instructions.mjs`。它走 ACP 的 [`systemPrompt`](https://agentclientprotocol.com/protocol/draft/session-setup#system-prompt-unstable)（unstable），
 **接入 Coda 的 Agent 必须支持**：
@@ -94,6 +137,8 @@ Coda 的 MCP 服务器只提供工具，不带 `instructions`。
 
 ## 插话
 
+Coda 使用的形状见 [steering.json](../schemas/agent/steering.json)；`prompt` 内容块仍使用 ACP schema。
+
 用户在一轮进行中「立即插话」时，支持插话的 Agent 把这条消息加进正在进行的一轮，不打断它；不支持的，Coda 停止这一轮，
 在它结束后把消息作为下一轮送出（会话行为契约（Coda 的 docs/session-contracts.md「发送行为」））。父会话给正为它跑一轮的子会话发消息（`send`）时同样插话；
 不支持的 Agent，这条消息只排到这一轮结束，Coda 不为它停止（工具面（Coda 的 docs/subagent-design.md「工具面」））。插话用生态里已有的 `_session/steering` 扩展：
@@ -114,6 +159,8 @@ Coda 的 MCP 服务器只提供工具，不带 `instructions`。
 
 ## 执行失败
 
+扩展值的形状见 [failure.json](../schemas/agent/failure.json)。
+
 插件负责将上游错误归为通用类别，Coda 负责显示与重试策略；Coda 不依赖 Agent 名字、错误文字或私有上游错误码。
 `session/prompt` 的 JSON-RPC 错误通过 `error.data._meta.coda.failure` 报告类别。标准 `error.message` 保留可读的失败原因；
 其他 ACP 客户端可以忽略扩展。未标记、未知或不合格式的类别按普通错误处理，不自动重试。
@@ -166,6 +213,8 @@ Coda 统一按 15、30、60 秒退避，每次执行最多重试三次，沿用
 
 ## 用量里的数据
 
+扩展对象及大小限制见 [usage.json](../schemas/agent/usage.json)。
+
 Agent 在 `session/update` 的 `usage_update` 里可以带 `_meta.coda`：一个 JSON 对象，放生命周期流程用得着的数据。Coda 不解释里面的字段，
 原样作为会话事实 `usage` 交给生命周期流程（Coda 的 docs/workflows.md「生命周期流程」），由流程（通常是同一个插件带的）读、判断。
 
@@ -182,6 +231,8 @@ Agent 在 `session/update` 的 `usage_update` 里可以带 `_meta.coda`：一个
 
 ## 工具调用的审核
 
+审核的形状与已知风险值见 [review.json](../schemas/agent/review.json)。
+
 Agent 运行一个工具调用之前自己做的检查（如 Codex 的自动审核：按风险决定放不放行），是这个调用的一部分：
 在这个调用的 `tool_call` 或 `tool_call_update` 里带 `_meta.coda.review`，不另报一个工具调用。它不是[审批](#acp-部分)：审批由用户回答，审核由 Agent 自己判断。
 
@@ -201,6 +252,8 @@ Agent 运行一个工具调用之前自己做的检查（如 Codex 的自动审
 
 ## 压缩上下文
 
+参数和答复见 [compact.json](../schemas/agent/compact.json)，声明见 [agent-capabilities.json](../schemas/agent/agent-capabilities.json)。
+
 Coda 可以请 Agent 压缩会话的上下文（同 Claude Code 的 `/compact`），由生命周期流程的 `compact-session`（Coda 的 docs/workflows.md「coda-的动作」） 发起；
 什么时候压、值不值得压由流程按[用量里的数据](#用量里的数据)判断，Agent 只执行。
 
@@ -237,6 +290,8 @@ Coda 存的就是这段文字，两端客户端显示时按看的那台设备的
 
 ### 能力协商
 
+声明形状见 [client-capabilities.json](../schemas/agent/client-capabilities.json) 与 [agent-capabilities.json](../schemas/agent/agent-capabilities.json)。
+
 - Coda 在 `initialize` 的 `clientCapabilities` 里总是带 `_meta.coda.waits: {}`。没看到它的客户端不认识这条扩展，Agent 不应对它发 `_coda/wait`。
 - Agent 在 `initialize` 结果的 `agentCapabilities` 里带 `_meta.coda.waits: {}`，表示它会登记。这只是声明：Coda 把它记在托管握手里，
   健康检查（`GET /v1/health` 的会话项 `waits`）报出来；不声明的 Agent 发来的 `_coda/wait` 也照收。
@@ -247,6 +302,8 @@ Coda 存的就是这段文字，两端客户端显示时按看的那台设备的
 
 ### `_coda/wait`
 
+通知参数及所有字段上限见 [wait.json](../schemas/agent/wait.json)。
+
 Agent 发给 Coda 的通知（没有 `id`，不回复），和 `session/update` 走同一个顺序：说在前面的先处理。
 
 | 字段 | 必填 | 说明 |
@@ -291,6 +348,8 @@ Agent 发给 Coda 的通知（没有 `id`，不回复），和 `session/update`
 
 ### `_coda/wait/stop`
 
+请求参数和答复见 [wait-stop.json](../schemas/agent/wait-stop.json)。
+
 Coda 发给 Agent 的请求，参数 `{ "sessionId": …, "waitId": … }`，Agent 回 `{}`。只对声明了 `stoppable` 的活动发：
 用户点了任务或子 Agent 的停止、父会话取消这次调用（含已经交回、还在为补交跟进的）时它树下的项。
 回复只表示收到；Coda 不当它已经停了，直到 Agent 随后用 `_coda/wait` 报它结束（通常是 `cancelled`）。
@@ -324,6 +383,8 @@ Coda 发给 Agent 的请求，参数 `{ "sessionId": …, "waitId": … }`，Age
 
 ## 远端入口
 
+绑定码与转交请求的形状分别见 [remote-code.json](../schemas/agent/remote-code.json)、[remote.json](../schemas/agent/remote.json)。
+
 有的 Agent 不在这台机器上干活：它是别处的一个 Bot（比如 Grok Bot，在它自己的云电脑上），会话里的适配器只是它的代言。
 Bot 需要随时进到自己的会话里来：说话、调 Coda 的工具、开一轮。远端入口给它一条只通往这个会话的路。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Coda 的协议：插件清单的类型（JSON Schema）、通用校验器、流程方言与 Agent 接入协议",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,7 @@
   "files": [
     "schemas",
     "validate.mjs",
+    "agent.mjs",
     "workflow",
     "workflow.mjs",
     "docs"
@@ -24,7 +25,8 @@
     "./schemas/*": "./schemas/*",
     "./workflow/*": "./workflow/*",
     "./docs/*": "./docs/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./agent": "./agent.mjs"
   },
   "engines": {
     "node": ">=24"

package/schemas/agent/agent-capabilities.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/agent-capabilities.json",
+  "type": "object",
+  "description": "_meta 须为对象",
+  "properties": {
+    "coda": {
+      "type": "object",
+      "description": "_meta.coda 须为对象",
+      "properties": {
+        "waits": {
+          "type": "object",
+          "description": "waits 能力用对象声明（通常为 {}）",
+          "properties": {}
+        },
+        "compact": {
+          "type": "object",
+          "description": "compact 能力用对象声明（通常为 {}）",
+          "properties": {}
+        },
+        "remote": {
+          "type": "object",
+          "description": "remote 能力用对象声明（通常为 {}）",
+          "properties": {}
+        }
+      }
+    }
+  }
+}

package/schemas/agent/client-capabilities.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/client-capabilities.json",
+  "type": "object",
+  "description": "_meta 须为对象",
+  "properties": {
+    "coda": {
+      "type": "object",
+      "description": "_meta.coda 须为对象",
+      "properties": {
+        "waits": {
+          "type": "object",
+          "description": "waits 能力用对象声明（通常为 {}）",
+          "properties": {}
+        },
+        "remote": {
+          "type": "object",
+          "description": "remote 能力用对象声明（通常为 {}）",
+          "properties": {}
+        }
+      }
+    }
+  }
+}

package/schemas/agent/compact.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/compact.json",
+  "description": "压缩上下文的一来一回，不是一轮；额外答复字段由宿主忽略。",
+  "$defs": {
+    "params": {
+      "type": "object",
+      "description": "params 须为对象",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "缺 sessionId",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "sessionId"
+      ]
+    },
+    "result": {
+      "type": "object",
+      "description": "压缩答复须为对象",
+      "properties": {
+        "compacted": {
+          "type": "boolean",
+          "description": "compacted 须为 true 或 false"
+        },
+        "reason": {
+          "type": "string",
+          "description": "没压的原因，给人看"
+        },
+        "before": {
+          "type": "number",
+          "description": "before 须为有限数"
+        },
+        "after": {
+          "type": "number",
+          "description": "after 须为有限数"
+        }
+      },
+      "required": [
+        "compacted"
+      ]
+    }
+  }
+}

package/schemas/agent/default.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/default.json",
+  "type": "object",
+  "description": "_meta.coda 须为对象",
+  "properties": {
+    "default": {
+      "type": "boolean",
+      "description": "default 须为 true 或 false；true 表示交给 Agent 自己的默认"
+    }
+  }
+}

package/schemas/agent/failure.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/failure.json",
+  "type": "object",
+  "description": "执行失败须为对象",
+  "properties": {
+    "kind": {
+      "enum": [
+        "quota_exhausted",
+        "service_unavailable"
+      ],
+      "description": "kind 只能是 quota_exhausted 或 service_unavailable"
+    }
+  },
+  "required": [
+    "kind"
+  ],
+  "if": {
+    "properties": {
+      "kind": {
+        "const": "service_unavailable"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  "then": {
+    "type": "object",
+    "description": "服务暂不可用须说明输入是否已接收",
+    "properties": {
+      "input": {
+        "enum": [
+          "accepted",
+          "not_accepted"
+        ],
+        "description": "input 只能是 accepted 或 not_accepted"
+      },
+      "retryAfterMs": {
+        "type": "number",
+        "minimum": 0,
+        "description": "retryAfterMs 须为非负有限数"
+      }
+    },
+    "required": [
+      "input"
+    ]
+  },
+  "$comment": "quota_exhausted 不检查 input 或 retryAfterMs；原 agentFailure 对额度不足只检查 kind。"
+}

package/schemas/agent/json.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/json.json",
+  "description": "须为 JSON 值（数字须有限，不能循环引用）",
+  "$comment": "所有接口的输入域。JSON 本身不容纳非有限数或循环；直接调用 JavaScript API 时，校验器用显式栈检查整个值，不用递归 schema 遍历不透明载荷。",
+  "type": ["null", "boolean", "number", "string", "array", "object"]
+}

package/schemas/agent/messages.json

@@ -0,0 +1,40 @@
+{
+  "description": "Coda 使用的扩展方法与参数、答复 schema 的索引；本文件是数据表，不是 JSON Schema。",
+  "methods": {
+    "_coda/wait": {
+      "kind": "notification",
+      "direction": "agent-to-client",
+      "params": "wait.json"
+    },
+    "_coda/wait/stop": {
+      "kind": "request",
+      "direction": "client-to-agent",
+      "params": "wait-stop.json#/$defs/params",
+      "result": "wait-stop.json#/$defs/result"
+    },
+    "_coda/session/compact": {
+      "kind": "request",
+      "direction": "client-to-agent",
+      "params": "compact.json#/$defs/params",
+      "result": "compact.json#/$defs/result"
+    },
+    "_coda/remote/code": {
+      "kind": "request",
+      "direction": "agent-to-client",
+      "params": "remote-code.json#/$defs/params",
+      "result": "remote-code.json#/$defs/result"
+    },
+    "_coda/remote": {
+      "kind": "request",
+      "direction": "client-to-agent",
+      "params": "remote.json#/$defs/params",
+      "result": "remote.json#/$defs/result"
+    },
+    "_session/steering": {
+      "kind": "request",
+      "direction": "client-to-agent",
+      "params": "steering.json#/$defs/params",
+      "result": "steering.json#/$defs/result"
+    }
+  }
+}

package/schemas/agent/remote-code.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/remote-code.json",
+  "description": "Agent 请求本会话的绑定码；归属、有效期和一次性使用由 Coda 检查。",
+  "$defs": {
+    "params": {
+      "type": "object",
+      "description": "params 须为对象",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "缺 sessionId",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "sessionId"
+      ]
+    },
+    "result": {
+      "type": "object",
+      "description": "绑定码答复须为对象",
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "一次性的绑定码",
+          "minLength": 1
+        },
+        "expiresAt": {
+          "type": "string",
+          "description": "expiresAt 读不出时间",
+          "format": "date-parse"
+        },
+        "addresses": {
+          "type": "array",
+          "description": "addresses 须为入口地址的数组；不在 tailnet 时为空",
+          "items": {
+            "type": "string",
+            "description": "入口地址须为文本"
+          }
+        }
+      },
+      "required": [
+        "code",
+        "expiresAt",
+        "addresses"
+      ]
+    }
+  }
+}

package/schemas/agent/remote.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/remote.json",
+  "description": "转交远端请求，method、params 与答复的业务含义由 Agent 定义；HTTP 入口的 256 KiB 限制不施加到 ACP 答复。",
+  "$defs": {
+    "params": {
+      "type": "object",
+      "description": "请求须为 {method, params}",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "缺 sessionId",
+          "minLength": 1
+        },
+        "method": {
+          "type": "string",
+          "description": "请求须为 {method, params}",
+          "minLength": 1,
+          "x-length": 200
+        },
+        "params": {
+          "type": "object",
+          "description": "请求须为 {method, params}",
+          "properties": {}
+        }
+      },
+      "required": [
+        "sessionId",
+        "method",
+        "params"
+      ]
+    },
+    "result": {
+      "description": "Agent 的回答原样作为 { result } 回给 Bot；可以是任意 JSON 值"
+    }
+  }
+}

package/schemas/agent/review.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/review.json",
+  "type": "object",
+  "description": "审核须为对象",
+  "properties": {
+    "state": {
+      "enum": [
+        "reviewing",
+        "approved",
+        "denied"
+      ],
+      "description": "state 只能是 reviewing、approved、denied"
+    },
+    "reason": {
+      "type": "string",
+      "description": "reason 须为不超过 4000 字的文本",
+      "x-length": 4000
+    },
+    "risk": {
+      "description": "不认识的 risk 不记；不因此丢弃审核。已知值见 $defs/risk。"
+    }
+  },
+  "required": [
+    "state"
+  ],
+  "$defs": {
+    "risk": {
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "critical"
+      ],
+      "description": "risk 只能是 low、medium、high 或 critical"
+    }
+  }
+}

package/schemas/agent/steering.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/steering.json",
+  "description": "生态的 _session/steering 扩展中 Coda 使用的部分；prompt 的内容块仍交 ACP SDK 校验。",
+  "$defs": {
+    "capabilities": {
+      "type": "object",
+      "description": "initialize 的 _meta 须为对象",
+      "properties": {
+        "steering": {
+          "type": "object",
+          "description": "steering 须为对象",
+          "properties": {
+            "supported": {
+              "type": "boolean",
+              "description": "supported 须为 true 或 false"
+            }
+          }
+        }
+      }
+    },
+    "params": {
+      "type": "object",
+      "description": "插话参数须为对象",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "缺 sessionId",
+          "minLength": 1
+        },
+        "prompt": {
+          "description": "与 session/prompt 相同，由 ACP SDK 校验；Coda 发一个文本块"
+        },
+        "_meta": {
+          "type": "object",
+          "description": "_meta 须为对象",
+          "properties": {
+            "steering": {
+              "type": "object",
+              "description": "steering 须为对象",
+              "properties": {
+                "idleBehavior": {
+                  "const": "promptRequired",
+                  "description": "idleBehavior 须为 promptRequired"
+                }
+              },
+              "required": [
+                "idleBehavior"
+              ]
+            }
+          },
+          "required": [
+            "steering"
+          ]
+        }
+      },
+      "required": [
+        "sessionId",
+        "prompt",
+        "_meta"
+      ]
+    },
+    "result": {
+      "type": "object",
+      "description": "插话答复须为对象",
+      "properties": {
+        "outcome": {
+          "enum": [
+            "injected",
+            "promptRequired"
+          ],
+          "description": "插话须回答 injected 或 promptRequired；其他结果的投递状态未知"
+        },
+        "reason": {
+          "description": "原因由 Agent 给出，Coda 只按 outcome 判断投递结果"
+        }
+      },
+      "required": [
+        "outcome"
+      ]
+    }
+  }
+}

package/schemas/agent/usage.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/usage.json",
+  "type": "object",
+  "description": "须为不超过 4096 字节的 JSON 对象",
+  "x-json": {
+    "schema": {
+      "type": "object",
+      "description": "须为不超过 4096 字节的 JSON 对象"
+    },
+    "maxBytes": 4096
+  }
+}

package/schemas/agent/wait-stop.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/wait-stop.json",
+  "description": "停止一项活动；答复只表示收到，是否已停止由之后的活动报告确认。",
+  "$defs": {
+    "params": {
+      "type": "object",
+      "description": "params 须为对象",
+      "properties": {
+        "sessionId": {
+          "$ref": "wait.json#/properties/sessionId"
+        },
+        "waitId": {
+          "$ref": "wait.json#/properties/waitId"
+        }
+      },
+      "required": [
+        "sessionId",
+        "waitId"
+      ]
+    },
+    "result": {
+      "type": "object",
+      "description": "Agent 回 {}；回复只表示收到",
+      "properties": {}
+    }
+  }
+}

package/schemas/agent/wait.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/agent/v1/wait.json",
+  "type": "object",
+  "description": "params 须为对象",
+  "properties": {
+    "sessionId": {
+      "allOf": [
+        {
+          "type": "string",
+          "description": "缺 sessionId",
+          "minLength": 1
+        },
+        {
+          "type": "string",
+          "description": "sessionId 须为不超过 200 字的文本",
+          "x-length": 200
+        }
+      ]
+    },
+    "waitId": {
+      "allOf": [
+        {
+          "type": "string",
+          "description": "缺 waitId",
+          "minLength": 1
+        },
+        {
+          "type": "string",
+          "description": "waitId 须为不超过 200 字的文本",
+          "x-length": 200
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "handling",
+        "done",
+        "failed",
+        "cancelled"
+      ],
+      "description": "state 只能是 waiting、handling、done、failed、cancelled"
+    },
+    "kind": {
+      "type": "string",
+      "description": "kind 须为不超过 50 字的文本",
+      "x-length": 50
+    },
+    "title": {
+      "type": "string",
+      "description": "title 须为不超过 500 字的文本",
+      "x-length": 500
+    },
+    "detail": {
+      "type": "string",
+      "description": "detail 须为不超过 4000 字的文本",
+      "x-length": 4000
+    },
+    "childSessionId": {
+      "type": "string",
+      "description": "childSessionId 须为不超过 200 字的文本",
+      "x-length": 200
+    },
+    "model": {
+      "type": "string",
+      "description": "model 须为不超过 200 字的文本",
+      "x-length": 200
+    },
+    "outputFile": {
+      "type": "string",
+      "description": "outputFile 须为不超过 4096 字的文本",
+      "x-length": 4096
+    },
+    "toolCallId": {
+      "type": "string",
+      "description": "toolCallId 须为不超过 200 字的文本",
+      "x-length": 200
+    },
+    "stoppable": {
+      "type": "boolean",
+      "description": "stoppable 须为 true 或 false"
+    },
+    "recurring": {
+      "type": "boolean",
+      "description": "recurring 须为 true 或 false"
+    },
+    "at": {
+      "type": "string",
+      "description": "at 读不出时间",
+      "format": "date-parse"
+    }
+  },
+  "required": [
+    "sessionId",
+    "waitId",
+    "state"
+  ]
+}

package/workflow/keywords.mjs

@@ -5,7 +5,7 @@ import { isAbsolute } from 'node:path';
 
 // The byte length of a JSON value, without recursion or serializing the whole object. Stop as soon as the budget is
 // exceeded. Only JSON values count: cycles, non-finite numbers and non-JSON objects cannot turn into a different value.
-function jsonFits(value, max) {
+export function jsonFits(value, max) {
   let bytes = 0;
   const active = new Set(), stack = [{ value }];
   while (stack.length && bytes <= max) {