@roll-agent/protocol 0.5.0 → 0.6.0

package/README.md

@@ -162,6 +162,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;
@@ -243,6 +247,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 +1801,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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/protocol",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "repository": {
     "type": "git",