@roll-agent/protocol 0.5.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。
 
@@ -162,6 +163,15 @@ Protocol `"1.0"` / `"1.1"` 的 strict 顶层结构不变，旧 GUI 可以继续
 时才向用户展示风险 `reason`；仅因无法证明安全而复用 `destructiveHint` 的 `unknown`
 命令不会显示“破坏性操作”。GUI 在 `reason` 缺失时应使用中性提示或直接省略。
 
+文件编辑类审批（`edit_file` / `write_file`）的变更预览位于 `approval.preview.diff`，形状为
+`fileChangeDiffSchema`（`path`、`change: "create" | "modify"`、`added`、`removed`、`hunks`、可选的
+`unified` 文本、`truncated`）；`getApprovalDiffPreview()` 完成校验。写入成功后的
+`tool.completed.display` 为 `{ text, diff }` 对象（`fileChangeDisplaySchema`），`getFileChangeDisplay()`
+读取；`text` 是与旧版本一致的人类可读摘要。`operationView.display`（`thread.snapshot` /
+`operation.get`）沿用台账信封 `{ version, encoding, value }`，`value` 才是同一 `{ text, diff }` 对象，
+读取时传 `display.value`。两者同样刻意放在既有 JSON 槽位内：strict 顶层结构不变，旧客户端把它们当
+普通 JSON 忽略；`unified` 缺席表示只有统计（超大文件），`truncated: true` 表示正文按上限截断。
+
 ## 文档
 
 - [Runtime Protocol v1 参考](https://github.com/steveoon/roll-agent/blob/main/docs/runtime-protocol-v1-reference.md)

package/dist/index.d.ts

@@ -22,6 +22,10 @@ export declare const RUNTIME_V13_RECOVERY_SNAPSHOT_METADATA_MAX_CHARS = 1024;
 export declare const RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS = 64;
 export declare const APPROVAL_EXPLANATION_PREVIEW_KEY: "explanation";
 export declare const APPROVAL_EXPLANATION_MAX_CHARS = 100;
+export declare const APPROVAL_DIFF_PREVIEW_KEY: "diff";
+export declare const FILE_CHANGE_DIFF_PATH_MAX_CHARS = 4096;
+export declare const FILE_CHANGE_DIFF_UNIFIED_MAX_CHARS = 20000;
+export declare const FILE_CHANGE_KINDS: readonly ["create", "modify"];
 export declare const CLIENT_CAPABILITY_METHOD_MAX_COUNT = 64;
 export declare const CLIENT_CAPABILITY_METHOD_MAX_CHARS = 100;
 export declare const USER_INPUT_CONTROL_MAX_COUNT = 16;
@@ -277,6 +281,33 @@ export declare const runtimeInteractionMetadataSchema: z.ZodReadonly<z.ZodObject
     }>;
 }, z.core.$strict>>;
 export declare const approvalExplanationSchema: z.ZodString;
+export declare const fileChangeDiffSchema: z.ZodReadonly<z.ZodObject<{
+    path: z.ZodString;
+    change: z.ZodEnum<{
+        create: "create";
+        modify: "modify";
+    }>;
+    added: z.ZodNumber;
+    removed: z.ZodNumber;
+    hunks: z.ZodNumber;
+    unified: z.ZodOptional<z.ZodString>;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>>;
+export declare const fileChangeDisplaySchema: z.ZodReadonly<z.ZodObject<{
+    text: z.ZodString;
+    diff: z.ZodReadonly<z.ZodObject<{
+        path: z.ZodString;
+        change: z.ZodEnum<{
+            create: "create";
+            modify: "modify";
+        }>;
+        added: z.ZodNumber;
+        removed: z.ZodNumber;
+        hunks: z.ZodNumber;
+        unified: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
 export type ThreadId = z.infer<typeof threadIdSchema>;
 export type TurnId = z.infer<typeof turnIdSchema>;
 export type ApprovalId = z.infer<typeof approvalIdSchema>;
@@ -13294,6 +13325,9 @@ export type UserInputResult = z.infer<typeof userInputResultSchema>;
 /** A submitted result whose values were correlated and ordered against the original form. */
 export type NormalizedUserInputResult = UserInputResult;
 export type ApprovalExplanation = z.infer<typeof approvalExplanationSchema>;
+export type FileChangeKind = (typeof FILE_CHANGE_KINDS)[number];
+export type FileChangeDiff = z.infer<typeof fileChangeDiffSchema>;
+export type FileChangeDisplay = z.infer<typeof fileChangeDisplaySchema>;
 export type ActiveTurn = z.infer<typeof activeTurnSchema>;
 export type ActiveTurnV11 = z.infer<typeof activeTurnV11Schema>;
 export type ActiveTurnV12 = z.infer<typeof activeTurnV12Schema>;
@@ -13317,6 +13351,8 @@ export declare function isRuntimeMethodAvailable<TVersion extends RuntimeProtoco
 export declare function isRuntimeServerRequestMethodAvailable<TVersion extends RuntimeProtocolVersion>(version: TVersion, method: string): method is RuntimeServerRequestMethodForVersion<TVersion>;
 export declare function projectClientCapabilitiesSetResult(value: unknown): ClientCapabilitiesSetResult;
 export declare function getApprovalExplanation(approval: Pick<PendingApproval, "preview">): ApprovalExplanation | undefined;
+export declare function getApprovalDiffPreview(approval: Pick<PendingApproval, "preview">): FileChangeDiff | undefined;
+export declare function getFileChangeDisplay(display: unknown): FileChangeDisplay | undefined;
 /**
  * Correlates a structurally valid Client result with the original form and returns values in
  * form definition order. Unknown, duplicate, missing or type-incompatible values are rejected.

package/dist/index.js

@@ -30,6 +30,10 @@ export const RUNTIME_V13_RECOVERY_SNAPSHOT_METADATA_MAX_CHARS = 1_024;
 export const RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS = 64;
 export const APPROVAL_EXPLANATION_PREVIEW_KEY = "explanation";
 export const APPROVAL_EXPLANATION_MAX_CHARS = 100;
+export const APPROVAL_DIFF_PREVIEW_KEY = "diff";
+export const FILE_CHANGE_DIFF_PATH_MAX_CHARS = 4_096;
+export const FILE_CHANGE_DIFF_UNIFIED_MAX_CHARS = 20_000;
+export const FILE_CHANGE_KINDS = ["create", "modify"];
 export const CLIENT_CAPABILITY_METHOD_MAX_COUNT = 64;
 export const CLIENT_CAPABILITY_METHOD_MAX_CHARS = 100;
 export const USER_INPUT_CONTROL_MAX_COUNT = 16;
@@ -125,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);
 }
@@ -243,6 +260,23 @@ export const approvalExplanationSchema = z
     .trim()
     .min(1)
     .max(APPROVAL_EXPLANATION_MAX_CHARS);
+export const fileChangeDiffSchema = z
+    .object({
+    path: z.string().min(1).max(FILE_CHANGE_DIFF_PATH_MAX_CHARS),
+    change: z.enum(FILE_CHANGE_KINDS),
+    added: z.number().int().nonnegative(),
+    removed: z.number().int().nonnegative(),
+    hunks: z.number().int().nonnegative(),
+    unified: z.string().max(FILE_CHANGE_DIFF_UNIFIED_MAX_CHARS).optional(),
+    truncated: z.boolean(),
+})
+    .readonly();
+export const fileChangeDisplaySchema = z
+    .object({
+    text: z.string(),
+    diff: fileChangeDiffSchema,
+})
+    .readonly();
 function runtimeEventCursorParts(cursor) {
     const parsed = runtimeEventCursorSchema.parse(cursor);
     const [, eventLogId, threadSequence, eventId] = parsed.split(":");
@@ -1780,6 +1814,18 @@ export function getApprovalExplanation(approval) {
     const parsed = approvalExplanationSchema.safeParse(preview[APPROVAL_EXPLANATION_PREVIEW_KEY]);
     return parsed.success ? parsed.data : undefined;
 }
+export function getApprovalDiffPreview(approval) {
+    const preview = approval.preview;
+    if (typeof preview !== "object" || preview === null || Array.isArray(preview)) {
+        return undefined;
+    }
+    const parsed = fileChangeDiffSchema.safeParse(preview[APPROVAL_DIFF_PREVIEW_KEY]);
+    return parsed.success ? parsed.data : undefined;
+}
+export function getFileChangeDisplay(display) {
+    const parsed = fileChangeDisplaySchema.safeParse(display);
+    return parsed.success ? parsed.data : undefined;
+}
 function validateUserInputTextValue(control, value, path, addIssue) {
     if (typeof value !== "string") {
         addIssue(path, `${control.type} control requires a string value`);
@@ -2088,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,
@@ -2103,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.5.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",