@coda-console/protocol 2.6.0 → 3.1.0

package/schemas/protocol/v1/agent.json

@@ -0,0 +1,69 @@
+{
+  "name": "coda/agent@1",
+  "title": "Agent",
+  "description": "一台机器上装着的 Agent 程序及其模型与审批模式，照 Coda 的 Agent 资源 spec。插件不再写在 spec 里，由记录的 provider 表达；本版本不定义操作。",
+  "spec": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "$defs": {
+      "level": {
+        "type": "object",
+        "properties": {
+          "id": {"type": "string", "minLength": 1, "maxLength": 200},
+          "name": {"type": "string", "maxLength": 200},
+          "shortName": {"type": "string", "maxLength": 40}
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "option": {
+        "type": "object",
+        "properties": {
+          "id": {"type": "string", "minLength": 1, "maxLength": 200},
+          "name": {"type": "string", "maxLength": 200},
+          "shortName": {"type": "string", "maxLength": 40},
+          "type": {"enum": ["boolean", "select"], "description": "开关，或几个选项里选一个"},
+          "choices": {"type": "array", "items": {"$ref": "#/$defs/level"}, "description": "能选的选项"}
+        },
+        "required": ["id", "type"],
+        "additionalProperties": false,
+        "if": {"properties": {"type": {"const": "select"}}, "required": ["type"]},
+        "then": {"required": ["choices"]},
+        "else": {"not": {"required": ["choices"]}}
+      }
+    },
+    "properties": {
+      "agent": {"type": "string", "minLength": 1, "maxLength": 200, "description": "Agent 的 ID：spawn 的 agent 写它"},
+      "title": {"type": "string", "maxLength": 200, "description": "给人看的名字"},
+      "defaultModel": {"type": "string", "maxLength": 200, "description": "不指定模型时用的模型 ID；读到目录前为空"},
+      "models": {
+        "type": "array",
+        "description": "它在那台能用的模型，最近读到的目录",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {"type": "string", "minLength": 1, "maxLength": 200},
+            "name": {"type": "string", "maxLength": 200},
+            "shortName": {"type": "string", "maxLength": 40},
+            "group": {"type": "string", "maxLength": 200, "description": "来源：Agent 自带的没有，模型服务的是服务的标题"},
+            "efforts": {"type": "array", "items": {"$ref": "#/$defs/level"}},
+            "options": {"type": "array", "items": {"$ref": "#/$defs/option"}}
+          },
+          "required": ["id", "efforts", "options"],
+          "additionalProperties": false
+        }
+      },
+      "modes": {"type": "array", "description": "它的审批模式", "items": {"$ref": "#/$defs/level"}}
+    },
+    "required": ["agent", "title", "defaultModel", "models", "modes"],
+    "additionalProperties": false
+  },
+  "status": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "maxProperties": 0,
+    "additionalProperties": false,
+    "description": "Agent 记录没有 status 字段"
+  },
+  "operations": {}
+}

package/schemas/protocol/v1/definition.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/protocol/v1/definition.json",
+  "title": "协议定义",
+  "description": "一个协议的名字、记录格式与操作。名字是「命名空间/名字@大版本」；spec、status 与每个操作的输入、结果都是 JSON Schema（draft 2020-12），只引用定义自身的 $defs。操作要么立刻返回结果（result），要么返回运行引用（run: true）；只读的立即结果可标 safe: true。",
+  "type": "object",
+  "properties": {
+    "name": {"$ref": "#/$defs/name"},
+    "title": {"$ref": "#/$defs/title"},
+    "description": {"$ref": "#/$defs/description"},
+    "spec": {"$ref": "#/$defs/schema"},
+    "status": {"$ref": "#/$defs/schema"},
+    "operations": {
+      "description": "操作名 → 输入与输出；不定义操作的协议写空对象",
+      "type": "object",
+      "maxProperties": 50,
+      "propertyNames": {"$ref": "#/$defs/operationName"},
+      "additionalProperties": {"$ref": "#/$defs/operation"}
+    }
+  },
+  "required": ["name", "spec", "status", "operations"],
+  "additionalProperties": false,
+  "$defs": {
+    "name": {
+      "description": "命名空间以小写字母开头，名字以小写字母或数字开头，两者只用小写字母、数字和「-」，各不超过 40 个字符；大版本是正整数。短名（见文档）至多 63 个字符；每个「-」在短名里占两个字符，所以协议名本身至多 61 个字符，parseProtocolName 还会按实际短名再核一次。命名空间为 coda 的由 Coda 保留。",
+      "type": "string",
+      "maxLength": 61,
+      "pattern": "^[a-z][a-z0-9-]{0,39}/[a-z0-9][a-z0-9-]{0,39}@[1-9][0-9]*$"
+    },
+    "operationName": {
+      "description": "操作名：小写字母开头，只用小写字母、数字和「-」，不超过 64 个字符",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "schema": {
+      "description": "JSON Schema（draft 2020-12）",
+      "type": ["object", "boolean"]
+    },
+    "title": {"description": "给人看的名字", "type": "string", "maxLength": 100, "pattern": "^(?=.*\\S)[^\\u0000\\r\\n]*$"},
+    "description": {"description": "一句话说明", "type": "string", "maxLength": 1000, "pattern": "^(?=.*\\S)[^\\u0000\\r\\n]*$"},
+    "operation": {
+      "description": "操作：input 必有；result 是立即结果的 schema，或写 run: true 表示返回运行引用。两者恰写一个。safe: true 只能与 result 一起写。",
+      "type": "object",
+      "properties": {
+        "description": {"$ref": "#/$defs/description"},
+        "input": {"$ref": "#/$defs/schema"},
+        "result": {"$ref": "#/$defs/schema"},
+        "run": {"const": true, "description": "返回运行引用，而不是立即结果"},
+        "safe": {"const": true, "description": "只读、没有副作用：调用双方都不按 requestId 留请求和回答，重发就再做一次"}
+      },
+      "required": ["input"],
+      "additionalProperties": false,
+      "oneOf": [{"required": ["result"]}, {"required": ["run"]}],
+      "dependentRequired": {"safe": ["result"]}
+    }
+  }
+}

package/schemas/protocol/v1/environment.json

@@ -0,0 +1,105 @@
+{
+  "name": "coda/environment@1",
+  "title": "环境",
+  "description": "插件提供的外部环境，例如别家 Agent 自带的云主机。本版本只读：list 列目录，read 读文件；路径是 Provider 自己的命名空间。",
+  "spec": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "title": {"type": "string", "maxLength": 200, "description": "给人看的名字"},
+      "container": {
+        "type": "object",
+        "description": "Provider 给的容器",
+        "properties": {
+          "id": {"type": "string", "minLength": 1, "maxLength": 2048},
+          "title": {"type": "string", "maxLength": 200}
+        },
+        "required": ["id", "title"],
+        "additionalProperties": false
+      },
+      "actions": {
+        "type": "array",
+        "uniqueItems": true,
+        "items": {"enum": ["read", "checkout", "delete", "exec"]},
+        "description": "能做什么；本版本只认 read"
+      }
+    },
+    "required": ["title", "actions"],
+    "additionalProperties": false
+  },
+  "status": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "state": {"enum": ["available", "unreachable"]},
+      "reason": {"type": "string", "maxLength": 4096, "description": "状态说明，可选"}
+    },
+    "required": ["state"],
+    "additionalProperties": false
+  },
+  "operations": {
+    "list": {
+      "description": "列目录：path 为空字符串表示根，after 是上一页的 next；立即结果。",
+      "safe": true,
+      "input": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "path": {"type": "string", "maxLength": 4096},
+          "after": {"type": "string", "minLength": 1, "maxLength": 2048}
+        },
+        "required": ["path"],
+        "additionalProperties": false
+      },
+      "result": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "entries": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {"type": "string", "minLength": 1, "maxLength": 1024},
+                "type": {"enum": ["file", "dir", "link"]},
+                "size": {"type": "integer", "minimum": 0}
+              },
+              "required": ["name", "type"],
+              "additionalProperties": false
+            }
+          },
+          "next": {"oneOf": [{"type": "string", "minLength": 1, "maxLength": 2048}, {"type": "null"}], "description": "下一页从哪里接着列；没有了为 null"}
+        },
+        "required": ["entries", "next"],
+        "additionalProperties": false
+      }
+    },
+    "read": {
+      "description": "读文件的一段：offset 默认 0，length 至多 1 MiB；立即结果。",
+      "safe": true,
+      "input": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "path": {"type": "string", "minLength": 1, "maxLength": 4096},
+          "offset": {"type": "integer", "minimum": 0},
+          "length": {"type": "integer", "minimum": 0, "maximum": 1048576}
+        },
+        "required": ["path"],
+        "additionalProperties": false
+      },
+      "result": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "path": {"type": "string", "minLength": 1, "maxLength": 4096},
+          "size": {"type": "integer", "minimum": 0, "description": "文件总字节数"},
+          "base64": {"type": "string", "pattern": "^[A-Za-z0-9+/]*={0,2}$", "description": "这一段的内容"},
+          "more": {"type": "boolean", "description": "这一段之后还有没有"}
+        },
+        "required": ["path", "size", "base64", "more"],
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/schemas/protocol/v1/executor.json

@@ -0,0 +1,279 @@
+{
+  "name": "coda/executor@1",
+  "title": "执行器",
+  "description": "一台机器上执行脚本步骤的环境。execute 接下一份工作，返回执行器自己开出的 coda/run@1 运行引用；执行器不写调用方的记录，也没有 target 绑定。",
+  "spec": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "$defs": {
+      "resourceName": {
+        "type": "string",
+        "pattern": "^(?:slots|group:(?!host$(?![\\s\\S]))[^\\s\\u0000-\\u001f\\u007f]{1,100})$(?![\\s\\S])",
+        "description": "slots 对应 host；其他本机命名组用 group:<原名>，不将不同组折叠为 slots"
+      },
+      "resourceAmounts": {
+        "type": "object",
+        "propertyNames": {"$ref": "#/$defs/resourceName"},
+        "maxProperties": 128,
+        "additionalProperties": {"type": "integer", "minimum": 0, "maximum": 9007199254740991},
+        "description": "可报告多个独立资源的容量"
+      },
+      "userLabels": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40,
+          "pattern": "^[a-z0-9][a-z0-9._-]*$(?![\\s\\S])",
+          "not": {
+            "pattern": "^(darwin|linux|win32|aix|android|freebsd|openbsd|sunos|cygwin|netbsd|haiku|arm|arm64|ia32|x64|loong64|mips|mipsel|ppc|ppc64|riscv64|s390|s390x|gui)$|^(xcode|ios|node)-"
+          }
+        },
+        "maxItems": 64,
+        "uniqueItems": true,
+        "description": "用户自定义标签，不占用 OS、架构、gui 与 xcode-/ios-/node- 探测命名空间"
+      }
+    },
+    "properties": {
+      "enabled": {"type": "boolean"},
+      "capacity": {"$ref": "#/$defs/resourceAmounts"},
+      "labels": {"$ref": "#/$defs/userLabels"},
+      "title": {"type": "string", "minLength": 1, "maxLength": 200}
+    },
+    "required": ["enabled", "capacity", "labels"],
+    "additionalProperties": false,
+    "description": "执行器配置意图，由持有端维护"
+  },
+  "status": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "$defs": {
+      "resourceName": {
+        "type": "string",
+        "pattern": "^(?:slots|group:(?!host$(?![\\s\\S]))[^\\s\\u0000-\\u001f\\u007f]{1,100})$(?![\\s\\S])"
+      },
+      "resourceAmounts": {
+        "type": "object",
+        "propertyNames": {"$ref": "#/$defs/resourceName"},
+        "maxProperties": 128,
+        "additionalProperties": {"type": "integer", "minimum": 0, "maximum": 9007199254740991}
+      },
+      "labels": {
+        "type": "array",
+        "items": {"type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9][a-z0-9._-]*$(?![\\s\\S])"},
+        "maxItems": 64,
+        "uniqueItems": true
+      },
+      "reason": {
+        "type": "object",
+        "properties": {
+          "code": {"type": "string", "minLength": 1, "maxLength": 128},
+          "message": {"type": "string", "minLength": 1, "maxLength": 4096}
+        },
+        "required": ["code", "message"],
+        "additionalProperties": false
+      },
+      "timestamp": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 40,
+        "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d{1,9})?Z$(?![\\s\\S])"
+      }
+    },
+    "properties": {
+      "detectedLabels": {"$ref": "#/$defs/labels"},
+      "capabilities": {
+        "type": "object",
+        "properties": {
+          "os": {"type": "string", "minLength": 1, "maxLength": 40},
+          "arch": {"type": "string", "minLength": 1, "maxLength": 40},
+          "nodeVersion": {"type": "string", "minLength": 1, "maxLength": 128},
+          "xcode": {
+            "type": "object",
+            "properties": {"version": {"type": "string", "minLength": 1, "maxLength": 128}, "build": {"type": "string", "minLength": 1, "maxLength": 128}},
+            "required": ["version", "build"],
+            "additionalProperties": false
+          },
+          "simulatorRuntimes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {"id": {"type": "string", "minLength": 1, "maxLength": 256}, "version": {"type": "string", "minLength": 1, "maxLength": 128}, "available": {"type": "boolean"}},
+              "required": ["id", "version", "available"],
+              "additionalProperties": false
+            },
+            "maxItems": 256
+          },
+          "graphicalSession": {"type": ["boolean", "null"]}
+        },
+        "required": ["os", "arch", "nodeVersion", "graphicalSession"],
+        "additionalProperties": false
+      },
+      "capacity": {"$ref": "#/$defs/resourceAmounts"},
+      "occupied": {"$ref": "#/$defs/resourceAmounts"},
+      "available": {"$ref": "#/$defs/resourceAmounts"},
+      "accepting": {"type": "boolean"},
+      "reason": {"$ref": "#/$defs/reason"},
+      "observedAt": {"$ref": "#/$defs/timestamp"},
+      "observedRevision": {"type": "string", "minLength": 1, "maxLength": 2048},
+      "executionFeatures": {
+        "type": "object",
+        "properties": {
+          "multiResource": {"const": false},
+          "multiUnit": {"const": false},
+          "exclusive": {"type": "boolean"},
+          "noResources": {"type": "boolean"},
+          "namedResources": {"type": "boolean"},
+          "context": {"type": "boolean"}
+        },
+        "required": ["multiResource", "multiUnit", "exclusive"],
+        "additionalProperties": false
+      }
+    },
+    "required": [],
+    "additionalProperties": false,
+    "anyOf": [
+      {"maxProperties": 0},
+      {
+        "required": ["detectedLabels", "capabilities", "capacity", "occupied", "available", "accepting", "observedAt", "observedRevision", "executionFeatures"]
+      }
+    ],
+    "description": "空对象表示未知；非空为持有端最近观察到的事实，不是在线或预留保证"
+  },
+  "operations": {
+    "execute": {
+      "description": "接下一份执行工作，返回执行器自己开出的运行引用。",
+      "input": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "$defs": {
+          "opaqueId": {"type": "string", "minLength": 1, "maxLength": 2048},
+          "resourceRef": {
+            "type": "object",
+            "properties": {"kind": {"type": "string", "minLength": 1, "maxLength": 128}, "id": {"$ref": "#/$defs/opaqueId"}},
+            "required": ["kind", "id"],
+            "additionalProperties": false
+          },
+          "snapshotRef": {
+            "type": "object",
+            "properties": {"kind": {"const": "git/snapshot@1"}, "id": {"$ref": "#/$defs/opaqueId"}},
+            "required": ["kind", "id"],
+            "additionalProperties": false
+          },
+          "repositoryRef": {
+            "type": "object",
+            "properties": {"kind": {"const": "git/source@1"}, "id": {"$ref": "#/$defs/opaqueId"}},
+            "required": ["kind", "id"],
+            "additionalProperties": false
+          },
+          "labels": {
+            "type": "array",
+            "items": {"type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9][a-z0-9._-]*$(?![\\s\\S])"},
+            "maxItems": 64,
+            "uniqueItems": true
+          },
+          "resourceName": {
+            "type": "string",
+            "pattern": "^(?:slots|group:(?!host$(?![\\s\\S]))[^\\s\\u0000-\\u001f\\u007f]{1,100})$(?![\\s\\S])"
+          },
+          "workingDirectory": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096,
+            "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f])(?!.*(?:^|/)\\.\\.(?:/|$)).+$",
+            "description": "工作根下的相对路径；拒绝绝对路径、反斜线和 .. 段，真实落点与符号链接仍须执行方检查"
+          }
+        },
+        "properties": {
+          "source": {
+            "oneOf": [
+              {"type": "null"},
+              {"type": "object", "properties": {"snapshot": {"$ref": "#/$defs/snapshotRef"}}, "required": ["snapshot"], "additionalProperties": false},
+              {
+                "type": "object",
+                "properties": {
+                  "repository": {"$ref": "#/$defs/repositoryRef"},
+                  "commit": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$(?![\\s\\S])"}
+                },
+                "required": ["repository", "commit"],
+                "additionalProperties": false
+              }
+            ]
+          },
+          "requirements": {
+            "type": "object",
+            "properties": {"labels": {"$ref": "#/$defs/labels"}},
+            "required": ["labels"],
+            "additionalProperties": false
+          },
+          "resources": {
+            "type": "object",
+            "propertyNames": {"$ref": "#/$defs/resourceName"},
+            "maxProperties": 1,
+            "additionalProperties": {"const": 1},
+            "description": "空对象表示不占资源；否则只申请一个资源的一单位"
+          },
+          "exclusiveResources": {
+            "type": "array",
+            "items": {"$ref": "#/$defs/resourceName"},
+            "maxItems": 1,
+            "uniqueItems": true,
+            "default": [],
+            "description": "空数组或独占申请的那一个资源，须与 resources 的键一致"
+          },
+          "context": {
+            "type": "object",
+            "properties": {
+              "workflow": {
+                "type": "object",
+                "properties": {
+                  "name": {"type": "string", "minLength": 1, "maxLength": 256},
+                  "job": {"type": "string", "minLength": 1, "maxLength": 256},
+                  "runId": {"$ref": "#/$defs/opaqueId"},
+                  "runAttempt": {"type": "integer", "minimum": 1, "maximum": 9007199254740991},
+                  "sha": {"type": "string", "pattern": "^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})?$(?![\\s\\S])"},
+                  "ref": {"type": "string", "maxLength": 1024},
+                  "repository": {"type": "string", "maxLength": 2048}
+                },
+                "required": ["name", "job", "runId", "runAttempt", "sha", "ref", "repository"],
+                "additionalProperties": false
+              },
+              "plugin": {
+                "type": "object",
+                "properties": {"id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$(?![\\s\\S])"}, "version": {"type": "string", "minLength": 1, "maxLength": 128}},
+                "required": ["id", "version"],
+                "additionalProperties": false
+              },
+              "audience": {"const": "user"},
+              "outputNames": {"type": "array", "maxItems": 64, "uniqueItems": true, "items": {"type": "string", "minLength": 1, "maxLength": 128}}
+            },
+            "additionalProperties": false,
+            "description": "可信生产者给出的运行上下文与输出声明；不是环境快照或授权凭证"
+          },
+          "task": {
+            "oneOf": [
+              {"type": "object", "properties": {"script": {"type": "string", "minLength": 1, "maxLength": 65536}, "shell": {"type": "string", "minLength": 1, "maxLength": 4096}}, "required": ["script", "shell"], "additionalProperties": false},
+              {"type": "object", "properties": {"command": {"type": "string", "minLength": 1, "maxLength": 4096}, "args": {"type": "array", "items": {"type": "string", "minLength": 0, "maxLength": 16384}, "maxItems": 256}}, "required": ["command", "args"], "additionalProperties": false}
+            ]
+          },
+          "workingDirectory": {"$ref": "#/$defs/workingDirectory", "default": "."},
+          "env": {
+            "type": "object",
+            "propertyNames": {"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$(?![\\s\\S])"},
+            "maxProperties": 128,
+            "additionalProperties": {"type": "string", "minLength": 0, "maxLength": 16384}
+          },
+          "timeoutMs": {"type": "integer", "minimum": 1, "maximum": 9007199254740991},
+          "cancelGraceMs": {"type": "integer", "minimum": 0, "maximum": 9007199254740991}
+        },
+        "required": ["source", "requirements", "resources", "task", "env"],
+        "additionalProperties": false,
+        "allOf": [
+          {"if": {"properties": {"resources": {"maxProperties": 0}}}, "then": {"properties": {"exclusiveResources": {"maxItems": 0}}}}
+        ],
+        "description": "一次执行工作的输入；取消走 coda/run@1 的 cancel 操作，不写在输入里"
+      },
+      "run": true
+    }
+  }
+}

package/schemas/protocol/v1/request.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/protocol/v1/request.json",
+  "title": "统一调用请求",
+  "description": "对一条记录的一次操作：记录引用、操作名、输入、请求 ID、发起方引用和是否被等待。同一个请求 ID 重发只做一次；被调用方建运行时照抄 parent 与 awaited。",
+  "type": "object",
+  "$defs": {
+    "reference": {
+      "description": "记录引用：协议名（尚未定义成协议的资源暂用资源种类名）与不透明 ID",
+      "type": "object",
+      "properties": {
+        "kind": {"type": "string", "minLength": 1, "maxLength": 128},
+        "id": {"type": "string", "minLength": 1, "maxLength": 2048}
+      },
+      "required": ["kind", "id"],
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "record": {"$ref": "#/$defs/reference"},
+    "operation": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9-]{0,63}$"},
+    "input": true,
+    "requestId": {"type": "string", "minLength": 1, "maxLength": 2048},
+    "parent": {"$ref": "#/$defs/reference", "description": "发起这次调用的一方：调用方的运行、会话或其他记录"},
+    "awaited": {"type": "boolean", "description": "调用方是否在等它"}
+  },
+  "required": ["record", "operation", "input", "requestId", "parent", "awaited"],
+  "additionalProperties": false
+}

package/schemas/protocol/v1/response.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schemas/protocol/v1/response.json",
+  "title": "统一调用回答",
+  "description": "一次调用要么立刻返回结果，要么返回一个运行引用；两者恰有一个。运行引用指向被调用方自己的 coda/run@1 记录，调用方 watch 它取结果。",
+  "type": "object",
+  "$defs": {
+    "reference": {
+      "description": "运行记录引用：类型名与不透明 ID",
+      "type": "object",
+      "properties": {
+        "kind": {"type": "string", "minLength": 1, "maxLength": 128},
+        "id": {"type": "string", "minLength": 1, "maxLength": 2048}
+      },
+      "required": ["kind", "id"],
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "result": true,
+    "run": {"$ref": "#/$defs/reference"}
+  },
+  "additionalProperties": false,
+  "oneOf": [{"required": ["result"]}, {"required": ["run"]}]
+}

package/schemas/protocol/v1/run.json

@@ -0,0 +1,75 @@
+{
+  "name": "coda/run@1",
+  "title": "运行",
+  "description": "被调用方为一次调用开出的运行记录，由被调用方持有和写入。调用方 watch 这条记录取结果；状态到 completed、failed、canceled 后不再改变。",
+  "spec": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "$defs": {
+      "reference": {
+        "type": "object",
+        "properties": {
+          "kind": {"type": "string", "minLength": 1, "maxLength": 128},
+          "id": {"type": "string", "minLength": 1, "maxLength": 2048}
+        },
+        "required": ["kind", "id"],
+        "additionalProperties": false
+      }
+    },
+    "properties": {
+      "record": {"$ref": "#/$defs/reference", "description": "调用的是哪条记录"},
+      "operation": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "调用的操作名"},
+      "input": {"description": "原样保存的调用输入"},
+      "requestId": {"type": "string", "minLength": 1, "maxLength": 2048, "description": "调用方的请求 ID；重发只对应这条运行"},
+      "parent": {"$ref": "#/$defs/reference", "description": "谁让它存在：发起它的记录引用，必填"},
+      "awaited": {"type": "boolean", "description": "父是否在等它；不等时完成只追加消息，不叫醒父"}
+    },
+    "required": ["record", "operation", "input", "requestId", "parent", "awaited"],
+    "additionalProperties": false
+  },
+  "status": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "$defs": {
+      "reference": {
+        "type": "object",
+        "properties": {
+          "kind": {"type": "string", "minLength": 1, "maxLength": 128},
+          "id": {"type": "string", "minLength": 1, "maxLength": 2048}
+        },
+        "required": ["kind", "id"],
+        "additionalProperties": false
+      }
+    },
+    "properties": {
+      "state": {"enum": ["working", "input-required", "completed", "failed", "canceled"], "description": "后三个是终态"},
+      "result": {"description": "完成、失败或取消时的结果；失败时约定为 { code, message }，code 为 unknown 表示结局不明"},
+      "progress": {"type": "string", "maxLength": 4096, "description": "进展说明，可选"},
+      "awaiting": {"$ref": "#/$defs/reference", "description": "等输入时那张卡片的引用"}
+    },
+    "required": ["state"],
+    "additionalProperties": false,
+    "allOf": [
+      {
+        "if": {"properties": {"state": {"enum": ["completed", "failed"]}}, "required": ["state"]},
+        "then": {"required": ["result"]}
+      },
+      {
+        "if": {"properties": {"state": {"enum": ["working", "input-required"]}}, "required": ["state"]},
+        "then": {"not": {"required": ["result"]}}
+      },
+      {
+        "if": {"properties": {"state": {"const": "input-required"}}, "required": ["state"]},
+        "then": {"required": ["awaiting"]},
+        "else": {"not": {"required": ["awaiting"]}}
+      }
+    ]
+  },
+  "operations": {
+    "cancel": {
+      "description": "请求取消；立即回答空结果，实际是否停止看状态。",
+      "input": {"$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "maxProperties": 0, "additionalProperties": false},
+      "result": {"$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "maxProperties": 0, "additionalProperties": false}
+    }
+  }
+}