@roll-agent/protocol 0.6.0 → 0.6.1

package/README.md

@@ -86,22 +86,23 @@ function handleEvent(event: RuntimeEventEnvelopeV13): void {
 
 - `@roll-agent/protocol/schema` 与 `@roll-agent/protocol/schema/latest`：最新版本
   JSON Schema Draft 2020-12 根 Schema；
-- `@roll-agent/protocol/schema/1.3`、`/1.2`、`/1.1`、`/1.0`：严格按协商版本隔离的 Schema；
+- `@roll-agent/protocol/schema/1.4`、`/1.3`、`/1.2`、`/1.1`、`/1.0`：严格按协商版本隔离的 Schema；
+- `@roll-agent/protocol/fixtures/v1.4/*`：Protocol 1.4 attachment / turn.start / snapshot fixtures；
 - `@roll-agent/protocol/fixtures/v1.3/*`：Protocol 1.3 durable event/replay fixtures；
 - `@roll-agent/protocol/fixtures/v1/*`：冻结的 1.1/1.0 跨语言有效/无效消息 fixtures。
 - `@roll-agent/protocol/fixtures/v1.2/*`：Protocol 1.2 capability/interaction fixtures。
 
 协议版本与 npm 包版本相互独立。`RUNTIME_PROTOCOL_VERSION` 表示这个包提供的最新 wire
 schema，并不代表调用方已实现对应 Client 能力。当前支持顺序为
-`["1.3", "1.2", "1.1", "1.0"]`。`initialize` 请求保持旧 strict 形状；协商到 `"1.2"`
-或 `"1.3"` 后，
+`["1.4", "1.3", "1.2", "1.1", "1.0"]`。`initialize` 请求保持旧 strict 形状；协商到 `"1.2"`、
+`"1.3"` 或 `"1.4"` 后，
 Client 必须用 `client.capabilities.set` 提交单调 `revision` 与当前 Handler methods，Runtime
 返回 registry 交集后才进入 interaction-ready。ACK 可以为空或为请求集的任意子集，顺序按
 Runtime registry；Client 必须按集合语义处理。未知的未来 method 名可安全发送但不会被接受。
 
-广告 `"1.3"` 同时声明 Client 能接收至少 `17 MiB` 的单个 Runtime→Client NDJSON 帧：
+广告 `"1.4"` 或 `"1.3"` 同时声明 Client 能接收至少 `17 MiB` 的单个 Runtime→Client NDJSON 帧：
 durable record 的绝对上限为 `16 MiB`，额外 1 MiB 留给 envelope 与 JSON-RPC 元数据。本地
-入站预算低于 17 MiB 的 Client 必须省略 `"1.3"`。这不会扩大 Client→Runtime 出站额度；
+入站预算低于 17 MiB 的 Client 必须同时省略 `"1.4"` 与 `"1.3"`。这不会扩大 Client→Runtime 出站额度；
 初始化后的出站上限仍取本地预算与 Runtime 返回的 `limits.maxFrameBytes` 的较小值。
 官方 Node 恢复管理器的默认 replay 暂存窗口为 10,000 条 / 32 MiB。
 

package/dist/index.js

@@ -129,6 +129,19 @@ export const REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION = {
 export function getRuntimeProtocolCapabilities(version) {
     return RUNTIME_PROTOCOL_CAPABILITIES[version];
 }
+const RUNTIME_SERVER_REQUEST_WIRE_SHAPES = {
+    interaction: "interaction",
+    legacy: "legacy",
+};
+function resolveRuntimeServerRequestWireShape(version) {
+    const capabilities = getRuntimeProtocolCapabilities(version);
+    if (!capabilities.serverRequests) {
+        return null;
+    }
+    return capabilities.serverRequestCapabilityNegotiation
+        ? RUNTIME_SERVER_REQUEST_WIRE_SHAPES.interaction
+        : RUNTIME_SERVER_REQUEST_WIRE_SHAPES.legacy;
+}
 export function isRuntimeServerRequestMethodRequired(version, method) {
     return getRuntimeProtocolCapabilities(version).requiredServerRequestMethods.some((requiredMethod) => requiredMethod === method);
 }
@@ -2121,10 +2134,12 @@ export function parseRuntimeProtocolErrorDataForVersion(version, value) {
 }
 export function projectRuntimeServerRequestParams(version, method, value) {
     const latest = parseRuntimeServerRequestParamsForVersion("1.3", method, value);
-    if (version === "1.3" || version === "1.2") {
+    const shape = resolveRuntimeServerRequestWireShape(version);
+    if (shape === RUNTIME_SERVER_REQUEST_WIRE_SHAPES.interaction) {
         return latest;
     }
-    if (version === "1.1" && method === RUNTIME_SERVER_REQUEST_METHODS.approvalRequest) {
+    if (shape === RUNTIME_SERVER_REQUEST_WIRE_SHAPES.legacy &&
+        method === RUNTIME_SERVER_REQUEST_METHODS.approvalRequest) {
         const approval = approvalRequestParamsV12Schema.parse(latest);
         return approvalRequestParamsV11Schema.parse({
             threadId: approval.threadId,
@@ -2136,13 +2151,14 @@ export function projectRuntimeServerRequestParams(version, method, value) {
 }
 export function projectRuntimeServerRequestCancelParams(version, value) {
     const input = runtimeServerRequestCancelProjectionInputSchema.parse(value);
-    if (version === "1.3" || version === "1.2") {
+    const shape = resolveRuntimeServerRequestWireShape(version);
+    if (shape === RUNTIME_SERVER_REQUEST_WIRE_SHAPES.interaction) {
         return runtimeServerRequestCancelParamsV12Schema.parse({
             interactionId: input.interactionId,
             reason: input.reason,
         });
     }
-    if (version === "1.1") {
+    if (shape === RUNTIME_SERVER_REQUEST_WIRE_SHAPES.legacy) {
         return runtimeServerRequestCancelParamsV11Schema.parse({
             serverRequestId: input.serverRequestId,
             ...(input.approvalId === undefined ? {} : { approvalId: input.approvalId }),

package/fixtures/v1.4/invalid-attachment-stage-sha256-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 26,
+  "method": "attachment.stage",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b1",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "fileName": "diagram.png",
+    "mediaType": "image/png",
+    "bytes": 2048,
+    "sha256": "not-a-sha256",
+    "source": "chunks"
+  }
+}

package/fixtures/v1.4/invalid-turn-start-too-many-attachments-request.json

@@ -0,0 +1,24 @@
+{
+  "jsonrpc": "2.0",
+  "id": 25,
+  "method": "turn.start",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b5",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "turnId": "00000000-0000-4000-8000-000000000003",
+    "input": {
+      "text": "too many",
+      "attachments": [
+        "00000000-0000-4000-8000-0000000000a1",
+        "00000000-0000-4000-8000-0000000000a2",
+        "00000000-0000-4000-8000-0000000000a3",
+        "00000000-0000-4000-8000-0000000000a4",
+        "00000000-0000-4000-8000-0000000000a5",
+        "00000000-0000-4000-8000-0000000000a6",
+        "00000000-0000-4000-8000-0000000000a7",
+        "00000000-0000-4000-8000-0000000000a8",
+        "00000000-0000-4000-8000-0000000000a9"
+      ]
+    }
+  }
+}

package/fixtures/v1.4/valid-attachment-chunk-request.json

@@ -0,0 +1,12 @@
+{
+  "jsonrpc": "2.0",
+  "id": 21,
+  "method": "attachment.chunk",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b2",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "attachmentId": "00000000-0000-4000-8000-0000000000a1",
+    "sequence": 0,
+    "dataBase64": "iVBORw0KGgo="
+  }
+}

package/fixtures/v1.4/valid-attachment-commit-request.json

@@ -0,0 +1,10 @@
+{
+  "jsonrpc": "2.0",
+  "id": 22,
+  "method": "attachment.commit",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b3",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "attachmentId": "00000000-0000-4000-8000-0000000000a1"
+  }
+}

package/fixtures/v1.4/valid-attachment-commit-response.json

@@ -0,0 +1,16 @@
+{
+  "jsonrpc": "2.0",
+  "id": 22,
+  "result": {
+    "descriptor": {
+      "attachmentId": "00000000-0000-4000-8000-0000000000a1",
+      "fileName": "diagram.png",
+      "displayName": "diagram.png",
+      "mediaType": "image/png",
+      "bytes": 2048,
+      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "source": "chunks",
+      "createdAt": "2026-08-21T12:00:00.000Z"
+    }
+  }
+}

package/fixtures/v1.4/valid-attachment-release-request.json

@@ -0,0 +1,10 @@
+{
+  "jsonrpc": "2.0",
+  "id": 23,
+  "method": "attachment.release",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b4",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "attachmentId": "00000000-0000-4000-8000-0000000000a1"
+  }
+}

package/fixtures/v1.4/valid-attachment-stage-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 20,
+  "method": "attachment.stage",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b1",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "fileName": "diagram.png",
+    "mediaType": "image/png",
+    "bytes": 2048,
+    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "source": "chunks"
+  }
+}

package/fixtures/v1.4/valid-attachment-stage-response.json

@@ -0,0 +1,8 @@
+{
+  "jsonrpc": "2.0",
+  "id": 20,
+  "result": {
+    "attachmentId": "00000000-0000-4000-8000-0000000000a1",
+    "state": "staged"
+  }
+}

package/fixtures/v1.4/valid-initialize-response.json

@@ -0,0 +1,34 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "1.4",
+    "runtimeInstanceId": "00000000-0000-4000-8000-000000000001",
+    "server": {
+      "name": "roll-runtime",
+      "version": "0.18.0",
+      "runtimeVersion": "0.18.0"
+    },
+    "features": [
+      "thread-management",
+      "snapshots",
+      "turns",
+      "approvals",
+      "tool-streaming",
+      "reasoning-summary",
+      "operation-projection",
+      "process-local-sequence",
+      "attachments"
+    ],
+    "limits": {
+      "maxFrameBytes": 4194304,
+      "maxPageSize": 500,
+      "eventReplay": true,
+      "idempotencyCacheEntries": 10000,
+      "maxAttachmentBytes": 16777216,
+      "maxAttachmentChunkBytes": 2097152,
+      "maxTurnAttachments": 8,
+      "maxStagedAttachments": 16
+    }
+  }
+}

package/fixtures/v1.4/valid-runtime-durable-event-notification.json

@@ -0,0 +1,20 @@
+{
+  "jsonrpc": "2.0",
+  "method": "runtime.event",
+  "params": {
+    "protocolVersion": "1.4",
+    "runtimeInstanceId": "00000000-0000-4000-8000-000000000001",
+    "sequence": 8,
+    "timestamp": "2026-07-30T12:00:00.000Z",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "turnId": "00000000-0000-4000-8000-000000000003",
+    "durability": "durable",
+    "eventId": "00000000-0000-4000-8000-000000000007",
+    "cursor": "rte1:00000000-0000-4000-8000-000000000008:0:00000000-0000-4000-8000-000000000007",
+    "event": {
+      "type": "message.completed",
+      "streamId": "00000000-0000-4000-8000-000000000004",
+      "text": "hello"
+    }
+  }
+}

package/fixtures/v1.4/valid-thread-snapshot-attachment-part-response.json

@@ -0,0 +1,44 @@
+{
+  "jsonrpc": "2.0",
+  "id": 27,
+  "result": {
+    "thread": {
+      "id": "00000000-0000-4000-8000-000000000002",
+      "title": "Attachment transcript",
+      "model": "fixture-model",
+      "createdAt": "2026-08-21T12:00:00.000Z",
+      "updatedAt": "2026-08-21T12:00:00.000Z",
+      "messageCount": 1
+    },
+    "messages": {
+      "items": [
+        {
+          "sequence": 0,
+          "role": "user",
+          "createdAt": "2026-08-21T12:00:00.000Z",
+          "parts": [
+            {
+              "type": "text",
+              "text": "看看这张图"
+            },
+            {
+              "type": "attachment",
+              "mediaType": "image/png",
+              "bytes": 2048,
+              "displayName": "diagram.png"
+            }
+          ]
+        }
+      ],
+      "nextBeforeSequence": null
+    },
+    "operations": {
+      "items": [],
+      "nextBeforeSequence": null
+    },
+    "pendingApprovals": [],
+    "pendingInteractions": [],
+    "transcriptCompleteness": "complete",
+    "eventCursor": null
+  }
+}

package/fixtures/v1.4/valid-turn-start-with-attachments-request.json

@@ -0,0 +1,14 @@
+{
+  "jsonrpc": "2.0",
+  "id": 24,
+  "method": "turn.start",
+  "params": {
+    "requestId": "00000000-0000-4000-8000-0000000000b5",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "turnId": "00000000-0000-4000-8000-000000000003",
+    "input": {
+      "text": "",
+      "attachments": ["00000000-0000-4000-8000-0000000000a1"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/protocol",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
     },
     "./schema": "./dist/schema/roll-runtime-protocol-v1.schema.json",
     "./schema/latest": "./dist/schema/roll-runtime-protocol-v1.schema.json",
+    "./schema/1.4": "./dist/schema/roll-runtime-protocol-v1.4.schema.json",
     "./schema/1.3": "./dist/schema/roll-runtime-protocol-v1.3.schema.json",
     "./schema/1.2": "./dist/schema/roll-runtime-protocol-v1.2.schema.json",
     "./schema/1.1": "./dist/schema/roll-runtime-protocol-v1.1.schema.json",