@roll-agent/protocol 0.2.0 → 0.3.0

package/README.md

@@ -19,6 +19,7 @@ import {
   RUNTIME_METHODS,
   RUNTIME_PROTOCOL_VERSION,
   RUNTIME_SERVER_REQUEST_METHODS,
+  getApprovalExplanation,
   parseRuntimeMethodParams,
   parseRuntimeServerRequestResult,
   type RuntimeEventEnvelope,
@@ -37,6 +38,9 @@ const approval = parseRuntimeServerRequestResult(
 );
 
 function handleEvent(event: RuntimeEventEnvelope): void {
+  if (event.event.type === "approval.required") {
+    console.log(getApprovalExplanation(event.event.approval));
+  }
   console.log(event.event.type, approval.decision);
 }
 ```
@@ -48,7 +52,7 @@ function handleEvent(event: RuntimeEventEnvelope): void {
   `RUNTIME_PROTOCOL_CAPABILITIES`、`REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION`、
   `RUNTIME_FEATURES`、`RUNTIME_ERROR_CODES`；
 - 能力查询：`getRuntimeProtocolCapabilities()`、
-  `isRuntimeServerRequestMethodRequired()`；
+  `isRuntimeServerRequestMethodRequired()`、`getApprovalExplanation()`；
 - 全部 Zod Schema 与派生类型；
 - `runtimeMethodSchemas`、`parseRuntimeMethodParams()`、
   `parseRuntimeMethodResult()`；
@@ -71,6 +75,14 @@ schema，并不代表调用方已实现对应 Client 能力。当前最新版本
 `approval.resolved` Event 向所有观察端同步最终状态；`"1.0"` 继续使用
 `approval.required` + `approval.respond`。
 
+Shell 审批的模型说明位于 `approval.preview.explanation`。它是一个可选的、最多 100
+字符的显示辅助字段；`getApprovalExplanation()` 会完成类型和长度校验。说明不会替代
+原始命令，也不会影响 Policy。该字段刻意保留在既有 `preview` JSON 内，因此 Runtime
+Protocol `"1.0"` / `"1.1"` 的 strict 顶层结构不变，旧 GUI 可以继续解析，新 GUI
+则可将它单独显示为“AI 说明”。内置 Shell 命令仅在分类器明确判定为 `dangerous`
+时才向用户展示风险 `reason`；仅因无法证明安全而复用 `destructiveHint` 的 `unknown`
+命令不会显示“破坏性操作”。GUI 在 `reason` 缺失时应使用中性提示或直接省略。
+
 ## 文档
 
 - [Runtime Protocol v1 参考](https://github.com/steveoon/roll-agent/blob/main/docs/runtime-protocol-v1-reference.md)

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export type RuntimeProtocolVersion = (typeof SUPPORTED_RUNTIME_PROTOCOL_VERSIONS
 export declare const RUNTIME_PROTOCOL_VERSION: "1.1";
 export declare const RUNTIME_EVENT_NOTIFICATION: "runtime.event";
 export declare const RUNTIME_SERVER_REQUEST_CANCEL_NOTIFICATION: "runtime.serverRequest.cancel";
+export declare const APPROVAL_EXPLANATION_PREVIEW_KEY: "explanation";
+export declare const APPROVAL_EXPLANATION_MAX_CHARS = 100;
 export declare const RUNTIME_SERVER_REQUEST_METHODS: {
     readonly approvalRequest: "approval.request";
 };
@@ -79,6 +81,7 @@ export declare const runtimeProtocolVersionSchema: z.ZodEnum<{
     1.1: "1.1";
     "1.0": "1.0";
 }>;
+export declare const approvalExplanationSchema: z.ZodString;
 export type ThreadId = z.infer<typeof threadIdSchema>;
 export type TurnId = z.infer<typeof turnIdSchema>;
 export type ApprovalId = z.infer<typeof approvalIdSchema>;
@@ -1215,11 +1218,13 @@ export type ThreadSnapshot = z.infer<typeof threadSnapshotSchema>;
 export type UiMessage = z.infer<typeof uiMessageSchema>;
 export type OperationView = z.infer<typeof operationViewSchema>;
 export type PendingApproval = z.infer<typeof pendingApprovalSchema>;
+export type ApprovalExplanation = z.infer<typeof approvalExplanationSchema>;
 export type ActiveTurn = z.infer<typeof activeTurnSchema>;
 export type ApprovalRequestParams = z.infer<typeof approvalRequestParamsSchema>;
 export type ApprovalRequestResult = z.infer<typeof approvalRequestResultSchema>;
 export type ApprovalResolution = z.infer<typeof approvalResolutionSchema>;
 export type RuntimeServerRequestCancelParams = z.infer<typeof runtimeServerRequestCancelParamsSchema>;
+export declare function getApprovalExplanation(approval: Pick<PendingApproval, "preview">): ApprovalExplanation | undefined;
 export interface JsonRpcRequest {
     readonly jsonrpc: "2.0";
     readonly id: JsonRpcId;

package/dist/index.js

@@ -3,6 +3,8 @@ export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = ["1.1", "1.0"];
 export const RUNTIME_PROTOCOL_VERSION = SUPPORTED_RUNTIME_PROTOCOL_VERSIONS[0];
 export const RUNTIME_EVENT_NOTIFICATION = "runtime.event";
 export const RUNTIME_SERVER_REQUEST_CANCEL_NOTIFICATION = "runtime.serverRequest.cancel";
+export const APPROVAL_EXPLANATION_PREVIEW_KEY = "explanation";
+export const APPROVAL_EXPLANATION_MAX_CHARS = 100;
 export const RUNTIME_SERVER_REQUEST_METHODS = {
     approvalRequest: "approval.request",
 };
@@ -88,6 +90,11 @@ export const timestampSchema = z.string().datetime({ offset: true });
 export const jsonValueSchema = z.json();
 export const jsonRpcIdSchema = z.union([z.string(), z.number()]);
 export const runtimeProtocolVersionSchema = z.enum(SUPPORTED_RUNTIME_PROTOCOL_VERSIONS);
+export const approvalExplanationSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(APPROVAL_EXPLANATION_MAX_CHARS);
 const runtimeClientInfoFields = {
     name: z.string().trim().min(1).max(100),
     version: z.string().trim().min(1).max(100),
@@ -613,6 +620,14 @@ export const runtimeServerRequestSchemas = {
         result: approvalRequestResultSchema,
     },
 };
+export function getApprovalExplanation(approval) {
+    const preview = approval.preview;
+    if (typeof preview !== "object" || preview === null || Array.isArray(preview)) {
+        return undefined;
+    }
+    const parsed = approvalExplanationSchema.safeParse(preview[APPROVAL_EXPLANATION_PREVIEW_KEY]);
+    return parsed.success ? parsed.data : undefined;
+}
 export function isRuntimeMethod(value) {
     return Object.hasOwn(runtimeMethodSchemas, value);
 }

package/fixtures/v1/valid-approval-request.json

@@ -10,7 +10,8 @@
       "agentName": "browser-use-agent",
       "toolName": "click",
       "preview": {
-        "selector": "#submit"
+        "selector": "#submit",
+        "explanation": "提交当前表单，以完成用户要求的操作。"
       },
       "reason": "此操作会提交表单"
     },

package/package.json

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