@roll-agent/protocol 0.1.0 → 0.3.0

package/README.md

@@ -18,7 +18,10 @@ pnpm add @roll-agent/protocol
 import {
   RUNTIME_METHODS,
   RUNTIME_PROTOCOL_VERSION,
+  RUNTIME_SERVER_REQUEST_METHODS,
+  getApprovalExplanation,
   parseRuntimeMethodParams,
+  parseRuntimeServerRequestResult,
   type RuntimeEventEnvelope,
 } from "@roll-agent/protocol";
 
@@ -29,18 +32,32 @@ const params = parseRuntimeMethodParams(RUNTIME_METHODS.threadSnapshot, {
 
 console.log(RUNTIME_PROTOCOL_VERSION, params);
 
+const approval = parseRuntimeServerRequestResult(
+  RUNTIME_SERVER_REQUEST_METHODS.approvalRequest,
+  { decision: "approve" },
+);
+
 function handleEvent(event: RuntimeEventEnvelope): void {
-  console.log(event.event.type);
+  if (event.event.type === "approval.required") {
+    console.log(getApprovalExplanation(event.event.approval));
+  }
+  console.log(event.event.type, approval.decision);
 }
 ```
 
 主要导出包括：
 
-- 协议常量：`RUNTIME_PROTOCOL_VERSION`、`RUNTIME_METHODS`、`RUNTIME_FEATURES`、
-  `RUNTIME_ERROR_CODES`；
+- 协议常量：`SUPPORTED_RUNTIME_PROTOCOL_VERSIONS`、`RUNTIME_PROTOCOL_VERSION`、
+  `RUNTIME_METHODS`、`RUNTIME_SERVER_REQUEST_METHODS`、
+  `RUNTIME_PROTOCOL_CAPABILITIES`、`REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION`、
+  `RUNTIME_FEATURES`、`RUNTIME_ERROR_CODES`；
+- 能力查询：`getRuntimeProtocolCapabilities()`、
+  `isRuntimeServerRequestMethodRequired()`、`getApprovalExplanation()`；
 - 全部 Zod Schema 与派生类型；
 - `runtimeMethodSchemas`、`parseRuntimeMethodParams()`、
   `parseRuntimeMethodResult()`；
+- `runtimeServerRequestSchemas`、`parseRuntimeServerRequestParams()`、
+  `parseRuntimeServerRequestResult()`；
 - JSON-RPC 与 Runtime Event Envelope 类型。
 
 ## JSON Schema 与 fixtures
@@ -48,7 +65,23 @@ function handleEvent(event: RuntimeEventEnvelope): void {
 - `@roll-agent/protocol/schema`：JSON Schema Draft 2020-12 根 Schema；
 - `@roll-agent/protocol/fixtures/v1/*`：跨语言有效/无效消息 fixtures。
 
-协议版本与 npm 包版本相互独立；Runtime Protocol v1 的 wire version 是 `"1.0"`。
+协议版本与 npm 包版本相互独立。`RUNTIME_PROTOCOL_VERSION` 表示这个包提供的最新 wire
+schema，并不代表调用方已实现对应 Client 能力。当前最新版本是 `"1.1"`；只有覆盖该版本
+全部必需 Server Request handler 的 Client 才应广告它，否则应协商回退到 `"1.0"`。
+
+`"1.1"` 首个 Server Request 是 `approval.request`。Runtime 可用
+`runtime.serverRequest.cancel.params.serverRequestId` 引用该请求的 JSON-RPC `id`，
+终止尚未完成的交互，并用只读
+`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` 缺失时应使用中性提示或直接省略。
 
 ## 文档
 

package/dist/index.d.ts

@@ -1,6 +1,41 @@
 import { z } from "zod/v4";
-export declare const RUNTIME_PROTOCOL_VERSION: "1.0";
+export declare const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS: readonly ["1.1", "1.0"];
+export type RuntimeProtocolVersion = (typeof SUPPORTED_RUNTIME_PROTOCOL_VERSIONS)[number];
+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";
+};
+export type RuntimeServerRequestMethod = (typeof RUNTIME_SERVER_REQUEST_METHODS)[keyof typeof RUNTIME_SERVER_REQUEST_METHODS];
+export interface RuntimeProtocolCapabilities {
+    readonly serverRequests: boolean;
+    readonly approvalResolvedEvents: boolean;
+    readonly clientApprovalResponses: boolean;
+    readonly requiredServerRequestMethods: readonly RuntimeServerRequestMethod[];
+}
+export declare const RUNTIME_PROTOCOL_CAPABILITIES: {
+    readonly "1.1": {
+        readonly serverRequests: true;
+        readonly approvalResolvedEvents: true;
+        readonly clientApprovalResponses: false;
+        readonly requiredServerRequestMethods: readonly ["approval.request"];
+    };
+    readonly "1.0": {
+        readonly serverRequests: false;
+        readonly approvalResolvedEvents: false;
+        readonly clientApprovalResponses: true;
+        readonly requiredServerRequestMethods: readonly [];
+    };
+};
+export declare const REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION: {
+    readonly "1.1": readonly ["approval.request"];
+    readonly "1.0": readonly [];
+};
+export declare function getRuntimeProtocolCapabilities(version: RuntimeProtocolVersion): RuntimeProtocolCapabilities;
+export declare function isRuntimeServerRequestMethodRequired(version: RuntimeProtocolVersion, method: RuntimeServerRequestMethod): boolean;
 export declare const RUNTIME_METHODS: {
     readonly initialize: "initialize";
     readonly threadList: "thread.list";
@@ -41,6 +76,12 @@ export declare const streamIdSchema: z.core.$ZodBranded<z.ZodString, "StreamId">
 export declare const operationIdSchema: z.core.$ZodBranded<z.ZodString, "OperationId">;
 export declare const timestampSchema: z.ZodString;
 export declare const jsonValueSchema: z.ZodJSONSchema;
+export declare const jsonRpcIdSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+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>;
@@ -49,6 +90,7 @@ export type RequestId = z.infer<typeof requestIdSchema>;
 export type StreamId = z.infer<typeof streamIdSchema>;
 export type OperationId = z.infer<typeof operationIdSchema>;
 export type JsonValue = z.infer<typeof jsonValueSchema>;
+export type JsonRpcId = z.infer<typeof jsonRpcIdSchema>;
 export declare const runtimeClientInfoSchema: z.ZodReadonly<z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
@@ -72,7 +114,10 @@ export declare const initializeParamsSchema: z.ZodReadonly<z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>>;
 export declare const initializeResultSchema: z.ZodReadonly<z.ZodObject<{
-    protocolVersion: z.ZodLiteral<"1.0">;
+    protocolVersion: z.ZodEnum<{
+        1.1: "1.1";
+        "1.0": "1.0";
+    }>;
     runtimeInstanceId: z.core.$ZodBranded<z.ZodString, "RuntimeInstanceId">;
     server: z.ZodReadonly<z.ZodObject<{
         runtimeVersion: z.ZodString;
@@ -516,6 +561,29 @@ export declare const approvalRespondParamsSchema: z.ZodReadonly<z.ZodObject<{
 export declare const approvalRespondResultSchema: z.ZodReadonly<z.ZodObject<{
     resolved: z.ZodLiteral<true>;
 }, z.core.$strict>>;
+export declare const approvalRequestParamsSchema: z.ZodReadonly<z.ZodObject<{
+    threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
+    approval: z.ZodReadonly<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+        turnId: z.core.$ZodBranded<z.ZodString, "TurnId">;
+        agentName: z.ZodString;
+        toolName: z.ZodString;
+        preview: z.ZodJSONSchema;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const approvalRequestResultSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    decision: z.ZodLiteral<"approve">;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    decision: z.ZodLiteral<"reject">;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>]>;
+export declare const runtimeServerRequestCancelParamsSchema: z.ZodReadonly<z.ZodObject<{
+    serverRequestId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    approvalId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "ApprovalId">>;
+    reason: z.ZodString;
+}, z.core.$strict>>;
 export declare const operationGetParamsSchema: z.ZodReadonly<z.ZodObject<{
     operationId: z.core.$ZodBranded<z.ZodString, "OperationId">;
     threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
@@ -542,6 +610,20 @@ export declare const operationGetResultSchema: z.ZodReadonly<z.ZodObject<{
         display: z.ZodJSONSchema;
     }, z.core.$strict>>>;
 }, z.core.$strict>>;
+export declare const approvalResolutionSchema: z.ZodUnion<readonly [z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"resolved">;
+    decision: z.ZodLiteral<"approve">;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"resolved">;
+    decision: z.ZodLiteral<"reject">;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"cancelled">;
+    reason: z.ZodString;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"expired">;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>]>;
 export declare const runtimeEventSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
     type: z.ZodLiteral<"turn.started">;
 }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
@@ -603,6 +685,23 @@ export declare const runtimeEventSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<
         preview: z.ZodJSONSchema;
         reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"approval.resolved">;
+    approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+    resolution: z.ZodUnion<readonly [z.ZodReadonly<z.ZodObject<{
+        status: z.ZodLiteral<"resolved">;
+        decision: z.ZodLiteral<"approve">;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        status: z.ZodLiteral<"resolved">;
+        decision: z.ZodLiteral<"reject">;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        status: z.ZodLiteral<"cancelled">;
+        reason: z.ZodString;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        status: z.ZodLiteral<"expired">;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>]>;
 }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
     type: z.ZodLiteral<"turn.completed">;
 }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
@@ -621,7 +720,10 @@ export declare const runtimeEventSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<
     type: z.ZodLiteral<"capabilities.changed">;
 }, z.core.$strict>>]>;
 export declare const runtimeEventEnvelopeSchema: z.ZodReadonly<z.ZodObject<{
-    protocolVersion: z.ZodLiteral<"1.0">;
+    protocolVersion: z.ZodEnum<{
+        1.1: "1.1";
+        "1.0": "1.0";
+    }>;
     runtimeInstanceId: z.core.$ZodBranded<z.ZodString, "RuntimeInstanceId">;
     sequence: z.ZodNumber;
     timestamp: z.ZodString;
@@ -688,6 +790,23 @@ export declare const runtimeEventEnvelopeSchema: z.ZodReadonly<z.ZodObject<{
             preview: z.ZodJSONSchema;
             reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        type: z.ZodLiteral<"approval.resolved">;
+        approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+        resolution: z.ZodUnion<readonly [z.ZodReadonly<z.ZodObject<{
+            status: z.ZodLiteral<"resolved">;
+            decision: z.ZodLiteral<"approve">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            status: z.ZodLiteral<"resolved">;
+            decision: z.ZodLiteral<"reject">;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            status: z.ZodLiteral<"cancelled">;
+            reason: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            status: z.ZodLiteral<"expired">;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>]>;
     }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
         type: z.ZodLiteral<"turn.completed">;
     }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
@@ -734,7 +853,10 @@ export declare const runtimeMethodSchemas: {
             }, z.core.$strict>>;
         }, z.core.$strict>>;
         readonly result: z.ZodReadonly<z.ZodObject<{
-            protocolVersion: z.ZodLiteral<"1.0">;
+            protocolVersion: z.ZodEnum<{
+                1.1: "1.1";
+                "1.0": "1.0";
+            }>;
             runtimeInstanceId: z.core.$ZodBranded<z.ZodString, "RuntimeInstanceId">;
             server: z.ZodReadonly<z.ZodObject<{
                 runtimeVersion: z.ZodString;
@@ -1053,10 +1175,39 @@ export declare const runtimeMethodSchemas: {
         }, z.core.$strict>>;
     };
 };
+export declare const runtimeServerRequestSchemas: {
+    readonly "approval.request": {
+        readonly params: z.ZodReadonly<z.ZodObject<{
+            threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
+            approval: z.ZodReadonly<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+                turnId: z.core.$ZodBranded<z.ZodString, "TurnId">;
+                agentName: z.ZodString;
+                toolName: z.ZodString;
+                preview: z.ZodJSONSchema;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            expiresAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        readonly result: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+            decision: z.ZodLiteral<"approve">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            decision: z.ZodLiteral<"reject">;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>]>;
+    };
+};
 export type RuntimeMethod = keyof typeof runtimeMethodSchemas;
 export type RuntimeMethodInput<TMethod extends RuntimeMethod> = z.input<(typeof runtimeMethodSchemas)[TMethod]["params"]>;
 export type RuntimeMethodParams<TMethod extends RuntimeMethod> = z.output<(typeof runtimeMethodSchemas)[TMethod]["params"]>;
 export type RuntimeMethodResult<TMethod extends RuntimeMethod> = z.output<(typeof runtimeMethodSchemas)[TMethod]["result"]>;
+export type RuntimeServerRequestInput<TMethod extends RuntimeServerRequestMethod> = z.input<(typeof runtimeServerRequestSchemas)[TMethod]["params"]>;
+export type RuntimeServerRequestParams<TMethod extends RuntimeServerRequestMethod> = z.output<(typeof runtimeServerRequestSchemas)[TMethod]["params"]>;
+export type RuntimeServerRequestResult<TMethod extends RuntimeServerRequestMethod> = z.output<(typeof runtimeServerRequestSchemas)[TMethod]["result"]>;
+export type RuntimeServerRequestHandler<TMethod extends RuntimeServerRequestMethod> = (params: RuntimeServerRequestParams<TMethod>) => RuntimeServerRequestResult<TMethod> | Promise<RuntimeServerRequestResult<TMethod>>;
+export type RuntimeServerRequestHandlers = {
+    readonly [TMethod in RuntimeServerRequestMethod]?: RuntimeServerRequestHandler<TMethod>;
+};
 export type InitializeParams = z.output<typeof initializeParamsSchema>;
 export type InitializeResult = z.output<typeof initializeResultSchema>;
 export type RuntimeEvent = z.infer<typeof runtimeEventSchema>;
@@ -1067,8 +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 JsonRpcId = number | string;
+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;
@@ -1098,3 +1254,6 @@ export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcSucce
 export declare function isRuntimeMethod(value: string): value is RuntimeMethod;
 export declare function parseRuntimeMethodParams<TMethod extends RuntimeMethod>(method: TMethod, value: unknown): RuntimeMethodParams<TMethod>;
 export declare function parseRuntimeMethodResult<TMethod extends RuntimeMethod>(method: TMethod, value: unknown): RuntimeMethodResult<TMethod>;
+export declare function isRuntimeServerRequestMethod(value: string): value is RuntimeServerRequestMethod;
+export declare function parseRuntimeServerRequestParams<TMethod extends RuntimeServerRequestMethod>(method: TMethod, value: unknown): RuntimeServerRequestParams<TMethod>;
+export declare function parseRuntimeServerRequestResult<TMethod extends RuntimeServerRequestMethod>(method: TMethod, value: unknown): RuntimeServerRequestResult<TMethod>;

package/dist/index.js

@@ -1,6 +1,37 @@
 import { z } from "zod/v4";
-export const RUNTIME_PROTOCOL_VERSION = "1.0";
+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",
+};
+export const RUNTIME_PROTOCOL_CAPABILITIES = {
+    "1.1": {
+        serverRequests: true,
+        approvalResolvedEvents: true,
+        clientApprovalResponses: false,
+        requiredServerRequestMethods: [RUNTIME_SERVER_REQUEST_METHODS.approvalRequest],
+    },
+    "1.0": {
+        serverRequests: false,
+        approvalResolvedEvents: false,
+        clientApprovalResponses: true,
+        requiredServerRequestMethods: [],
+    },
+};
+export const REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION = {
+    "1.1": RUNTIME_PROTOCOL_CAPABILITIES["1.1"].requiredServerRequestMethods,
+    "1.0": RUNTIME_PROTOCOL_CAPABILITIES["1.0"].requiredServerRequestMethods,
+};
+export function getRuntimeProtocolCapabilities(version) {
+    return RUNTIME_PROTOCOL_CAPABILITIES[version];
+}
+export function isRuntimeServerRequestMethodRequired(version, method) {
+    return getRuntimeProtocolCapabilities(version).requiredServerRequestMethods.some((requiredMethod) => requiredMethod === method);
+}
 export const RUNTIME_METHODS = {
     initialize: "initialize",
     threadList: "thread.list",
@@ -57,6 +88,13 @@ export const streamIdSchema = z.string().uuid().brand();
 export const operationIdSchema = z.string().uuid().brand();
 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),
@@ -87,7 +125,7 @@ export const initializeParamsSchema = z
     .readonly();
 export const initializeResultSchema = z
     .object({
-    protocolVersion: z.literal(RUNTIME_PROTOCOL_VERSION),
+    protocolVersion: runtimeProtocolVersionSchema,
     runtimeInstanceId: runtimeInstanceIdSchema,
     server: runtimeServerInfoSchema,
     features: z.array(z.enum(RUNTIME_FEATURES)),
@@ -292,6 +330,7 @@ export const turnCancelParamsSchema = z
     .strict()
     .readonly();
 export const turnCancelResultSchema = z.object({ cancelling: z.boolean() }).strict().readonly();
+const approvalRejectReasonSchema = z.string().min(1);
 export const approvalRespondParamsSchema = z
     .object({
     ...requestFields,
@@ -299,7 +338,7 @@ export const approvalRespondParamsSchema = z
     turnId: turnIdSchema,
     approvalId: approvalIdSchema,
     decision: z.enum(["approve", "reject"]),
-    reason: z.string().optional(),
+    reason: approvalRejectReasonSchema.optional(),
 })
     .strict()
     .readonly();
@@ -307,6 +346,37 @@ export const approvalRespondResultSchema = z
     .object({ resolved: z.literal(true) })
     .strict()
     .readonly();
+export const approvalRequestParamsSchema = z
+    .object({
+    threadId: threadIdSchema,
+    approval: pendingApprovalSchema,
+    expiresAt: timestampSchema.optional(),
+})
+    .strict()
+    .readonly();
+export const approvalRequestResultSchema = z.discriminatedUnion("decision", [
+    z
+        .object({
+        decision: z.literal("approve"),
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        decision: z.literal("reject"),
+        reason: approvalRejectReasonSchema.optional(),
+    })
+        .strict()
+        .readonly(),
+]);
+export const runtimeServerRequestCancelParamsSchema = z
+    .object({
+    serverRequestId: jsonRpcIdSchema,
+    approvalId: approvalIdSchema.optional(),
+    reason: z.string().min(1),
+})
+    .strict()
+    .readonly();
 export const operationGetParamsSchema = z
     .object({
     ...threadRequestFields,
@@ -320,6 +390,37 @@ export const operationGetResultSchema = z
 })
     .strict()
     .readonly();
+export const approvalResolutionSchema = z.union([
+    z
+        .object({
+        status: z.literal("resolved"),
+        decision: z.literal("approve"),
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        status: z.literal("resolved"),
+        decision: z.literal("reject"),
+        reason: approvalRejectReasonSchema.optional(),
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        status: z.literal("cancelled"),
+        reason: z.string().min(1),
+    })
+        .strict()
+        .readonly(),
+    z
+        .object({
+        status: z.literal("expired"),
+        reason: z.string().min(1).optional(),
+    })
+        .strict()
+        .readonly(),
+]);
 export const runtimeEventSchema = z.discriminatedUnion("type", [
     z
         .object({ type: z.literal("turn.started") })
@@ -396,6 +497,14 @@ export const runtimeEventSchema = z.discriminatedUnion("type", [
     })
         .strict()
         .readonly(),
+    z
+        .object({
+        type: z.literal("approval.resolved"),
+        approvalId: approvalIdSchema,
+        resolution: approvalResolutionSchema,
+    })
+        .strict()
+        .readonly(),
     z
         .object({ type: z.literal("turn.completed") })
         .strict()
@@ -423,7 +532,7 @@ export const runtimeEventSchema = z.discriminatedUnion("type", [
 ]);
 export const runtimeEventEnvelopeSchema = z
     .object({
-    protocolVersion: z.literal(RUNTIME_PROTOCOL_VERSION),
+    protocolVersion: runtimeProtocolVersionSchema,
     runtimeInstanceId: runtimeInstanceIdSchema,
     sequence: z.number().int().nonnegative(),
     timestamp: timestampSchema,
@@ -432,6 +541,16 @@ export const runtimeEventEnvelopeSchema = z
     event: runtimeEventSchema,
 })
     .strict()
+    .superRefine((value, context) => {
+    if (!getRuntimeProtocolCapabilities(value.protocolVersion).approvalResolvedEvents &&
+        value.event.type === "approval.resolved") {
+        context.addIssue({
+            code: "custom",
+            message: "approval.resolved requires the negotiated approval-resolved event capability",
+            path: ["event", "type"],
+        });
+    }
+})
     .readonly();
 export const runtimeProtocolErrorDataSchema = z
     .object({
@@ -495,6 +614,20 @@ export const runtimeMethodSchemas = {
         result: operationGetResultSchema,
     },
 };
+export const runtimeServerRequestSchemas = {
+    [RUNTIME_SERVER_REQUEST_METHODS.approvalRequest]: {
+        params: approvalRequestParamsSchema,
+        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);
 }
@@ -504,3 +637,12 @@ export function parseRuntimeMethodParams(method, value) {
 export function parseRuntimeMethodResult(method, value) {
     return runtimeMethodSchemas[method].result.parse(value);
 }
+export function isRuntimeServerRequestMethod(value) {
+    return Object.hasOwn(runtimeServerRequestSchemas, value);
+}
+export function parseRuntimeServerRequestParams(method, value) {
+    return runtimeServerRequestSchemas[method].params.parse(value);
+}
+export function parseRuntimeServerRequestResult(method, value) {
+    return runtimeServerRequestSchemas[method].result.parse(value);
+}