@roll-agent/protocol 0.8.0 → 0.9.0

package/dist/schema/roll-runtime-protocol-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:roll-agent:schema:runtime-protocol:1.5",
-  "title": "Roll Runtime Protocol v1.5",
+  "$id": "urn:roll-agent:schema:runtime-protocol:1.6",
+  "title": "Roll Runtime Protocol v1.6",
   "description": "Bidirectional JSON-RPC requests, responses, and notifications for Roll Runtime Protocol.",
   "oneOf": [
     {
@@ -42,7 +42,7 @@
           "properties": {
             "protocolVersion": {
               "type": "string",
-              "const": "1.5"
+              "const": "1.6"
             },
             "runtimeInstanceId": {
               "type": "string",
@@ -497,6 +497,57 @@
                     "type"
                   ],
                   "additionalProperties": false
+                },
+                {
+                  "readOnly": true,
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "context.recovery.changed"
+                    },
+                    "contextRecovery": {
+                      "anyOf": [
+                        {
+                          "readOnly": true,
+                          "type": "object",
+                          "properties": {
+                            "checkpointId": {
+                              "type": "string",
+                              "format": "uuid",
+                              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+                            },
+                            "required": {
+                              "type": "boolean"
+                            },
+                            "unextracted": {
+                              "type": "boolean"
+                            },
+                            "requiredItemCount": {
+                              "type": "integer",
+                              "minimum": 0,
+                              "maximum": 9007199254740991
+                            }
+                          },
+                          "required": [
+                            "checkpointId",
+                            "required",
+                            "unextracted",
+                            "requiredItemCount"
+                          ],
+                          "additionalProperties": false
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "contextRecovery"
+                  ],
+                  "additionalProperties": false
                 }
               ]
             }
@@ -520,7 +571,7 @@
           "properties": {
             "protocolVersion": {
               "type": "string",
-              "const": "1.5"
+              "const": "1.6"
             },
             "runtimeInstanceId": {
               "type": "string",
@@ -821,7 +872,7 @@
       "properties": {
         "protocolVersion": {
           "type": "string",
-          "const": "1.5"
+          "const": "1.6"
         },
         "runtimeInstanceId": {
           "type": "string",
@@ -869,7 +920,8 @@
               "operation-projection",
               "process-local-sequence",
               "attachments",
-              "app-output"
+              "app-output",
+              "context-recovery"
             ]
           }
         },
@@ -1896,6 +1948,42 @@
                   "type": "null"
                 }
               ]
+            },
+            "contextRecovery": {
+              "anyOf": [
+                {
+                  "readOnly": true,
+                  "type": "object",
+                  "properties": {
+                    "checkpointId": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+                    },
+                    "required": {
+                      "type": "boolean"
+                    },
+                    "unextracted": {
+                      "type": "boolean"
+                    },
+                    "requiredItemCount": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "checkpointId",
+                    "required",
+                    "unextracted",
+                    "requiredItemCount"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
             }
           },
           "required": [
@@ -1905,7 +1993,8 @@
             "pendingApprovals",
             "transcriptCompleteness",
             "pendingInteractions",
-            "eventCursor"
+            "eventCursor",
+            "contextRecovery"
           ],
           "additionalProperties": false
         },
@@ -2581,6 +2670,42 @@
             "recoveryProjection": {
               "type": "boolean",
               "const": true
+            },
+            "contextRecovery": {
+              "anyOf": [
+                {
+                  "readOnly": true,
+                  "type": "object",
+                  "properties": {
+                    "checkpointId": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+                    },
+                    "required": {
+                      "type": "boolean"
+                    },
+                    "unextracted": {
+                      "type": "boolean"
+                    },
+                    "requiredItemCount": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "checkpointId",
+                    "required",
+                    "unextracted",
+                    "requiredItemCount"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
             }
           },
           "required": [
@@ -2591,7 +2716,8 @@
             "transcriptCompleteness",
             "pendingInteractions",
             "eventCursor",
-            "recoveryProjection"
+            "recoveryProjection",
+            "contextRecovery"
           ],
           "additionalProperties": false
         }
@@ -3422,6 +3548,42 @@
                   "type": "null"
                 }
               ]
+            },
+            "contextRecovery": {
+              "anyOf": [
+                {
+                  "readOnly": true,
+                  "type": "object",
+                  "properties": {
+                    "checkpointId": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+                    },
+                    "required": {
+                      "type": "boolean"
+                    },
+                    "unextracted": {
+                      "type": "boolean"
+                    },
+                    "requiredItemCount": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "checkpointId",
+                    "required",
+                    "unextracted",
+                    "requiredItemCount"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
             }
           },
           "required": [
@@ -3431,7 +3593,8 @@
             "pendingApprovals",
             "transcriptCompleteness",
             "pendingInteractions",
-            "eventCursor"
+            "eventCursor",
+            "contextRecovery"
           ],
           "additionalProperties": false
         },
@@ -4107,6 +4270,42 @@
             "recoveryProjection": {
               "type": "boolean",
               "const": true
+            },
+            "contextRecovery": {
+              "anyOf": [
+                {
+                  "readOnly": true,
+                  "type": "object",
+                  "properties": {
+                    "checkpointId": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+                    },
+                    "required": {
+                      "type": "boolean"
+                    },
+                    "unextracted": {
+                      "type": "boolean"
+                    },
+                    "requiredItemCount": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "checkpointId",
+                    "required",
+                    "unextracted",
+                    "requiredItemCount"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
             }
           },
           "required": [
@@ -4117,7 +4316,8 @@
             "transcriptCompleteness",
             "pendingInteractions",
             "eventCursor",
-            "recoveryProjection"
+            "recoveryProjection",
+            "contextRecovery"
           ],
           "additionalProperties": false
         }
@@ -5283,6 +5483,80 @@
       ],
       "additionalProperties": false
     },
+    "approvalPreviewParams": {
+      "readOnly": true,
+      "type": "object",
+      "properties": {
+        "threadId": {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+        },
+        "turnId": {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+        },
+        "approvalId": {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+        },
+        "offset": {
+          "default": 0,
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxChars": {
+          "default": 12000,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32000
+        }
+      },
+      "required": [
+        "threadId",
+        "turnId",
+        "approvalId",
+        "offset",
+        "maxChars"
+      ],
+      "additionalProperties": false
+    },
+    "approvalPreviewResult": {
+      "readOnly": true,
+      "type": "object",
+      "properties": {
+        "text": {
+          "type": "string",
+          "maxLength": 32000
+        },
+        "totalChars": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "nextOffset": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "text",
+        "totalChars",
+        "nextOffset"
+      ],
+      "additionalProperties": false
+    },
     "approvalRequestParams": {
       "readOnly": true,
       "type": "object",
@@ -6328,6 +6602,30 @@
       ],
       "additionalProperties": false
     },
+    "approvalPreviewRequest": {
+      "type": "object",
+      "properties": {
+        "jsonrpc": {
+          "const": "2.0"
+        },
+        "id": {
+          "$ref": "#/$defs/jsonRpcId"
+        },
+        "method": {
+          "const": "approval.preview"
+        },
+        "params": {
+          "$ref": "#/$defs/approvalPreviewParams"
+        }
+      },
+      "required": [
+        "jsonrpc",
+        "id",
+        "method",
+        "params"
+      ],
+      "additionalProperties": false
+    },
     "approvalRequestServerRequest": {
       "type": "object",
       "properties": {
@@ -6437,6 +6735,9 @@
         },
         {
           "$ref": "#/$defs/operationResultGetRequest"
+        },
+        {
+          "$ref": "#/$defs/approvalPreviewRequest"
         }
       ]
     },
@@ -6561,6 +6862,9 @@
             {
               "$ref": "#/$defs/operationResultGetResult"
             },
+            {
+              "$ref": "#/$defs/approvalPreviewResult"
+            },
             {
               "$ref": "#/$defs/approvalRequestResult"
             },
@@ -6621,7 +6925,7 @@
       "additionalProperties": false
     }
   },
-  "x-roll-protocol-version": "1.5",
+  "x-roll-protocol-version": "1.6",
   "x-roll-methods": {
     "initialize": {
       "params": {
@@ -6842,6 +7146,17 @@
       "request": {
         "$ref": "#/$defs/operationResultGetRequest"
       }
+    },
+    "approval.preview": {
+      "params": {
+        "$ref": "#/$defs/approvalPreviewParams"
+      },
+      "result": {
+        "$ref": "#/$defs/approvalPreviewResult"
+      },
+      "request": {
+        "$ref": "#/$defs/approvalPreviewRequest"
+      }
     }
   },
   "x-roll-server-request-methods": {

package/fixtures/v1.6/valid-context-recovery-event.json

@@ -0,0 +1,23 @@
+{
+  "jsonrpc": "2.0",
+  "method": "runtime.event",
+  "params": {
+    "protocolVersion": "1.6",
+    "runtimeInstanceId": "00000000-0000-4000-8000-000000000001",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "sequence": 0,
+    "timestamp": "2026-10-13T00:00:00.000Z",
+    "durability": "durable",
+    "eventId": "00000000-0000-4000-8000-000000000003",
+    "cursor": "rte1:00000000-0000-4000-8000-000000000001:0:00000000-0000-4000-8000-000000000003",
+    "event": {
+      "type": "context.recovery.changed",
+      "contextRecovery": {
+        "checkpointId": "00000000-0000-4000-8000-000000000003",
+        "required": true,
+        "unextracted": true,
+        "requiredItemCount": 24
+      }
+    }
+  }
+}

package/fixtures/v1.6/valid-context-recovery-snapshot-response.json

@@ -0,0 +1,30 @@
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "thread": {
+      "id": "00000000-0000-4000-8000-000000000002",
+      "createdAt": "2026-10-13T00:00:00.000Z",
+      "updatedAt": "2026-10-13T00:00:00.000Z",
+      "messageCount": 0
+    },
+    "messages": {
+      "items": [],
+      "nextBeforeSequence": null
+    },
+    "operations": {
+      "items": [],
+      "nextBeforeSequence": null
+    },
+    "pendingApprovals": [],
+    "pendingInteractions": [],
+    "transcriptCompleteness": "complete",
+    "eventCursor": null,
+    "contextRecovery": {
+      "checkpointId": "00000000-0000-4000-8000-000000000003",
+      "required": true,
+      "unextracted": true,
+      "requiredItemCount": 24
+    }
+  }
+}

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

@@ -0,0 +1,36 @@
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "1.6",
+    "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",
+      "app-output",
+      "context-recovery"
+    ],
+    "limits": {
+      "maxFrameBytes": 4194304,
+      "maxPageSize": 500,
+      "eventReplay": true,
+      "idempotencyCacheEntries": 10000,
+      "maxAttachmentBytes": 16777216,
+      "maxAttachmentChunkBytes": 2097152,
+      "maxTurnAttachments": 8,
+      "maxStagedAttachments": 16
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/protocol",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -31,7 +31,8 @@
       "types": "./dist/observation-retention.d.ts",
       "default": "./dist/observation-retention.js"
     },
-    "./schema/1.5": "./dist/schema/roll-runtime-protocol-v1.5.schema.json"
+    "./schema/1.5": "./dist/schema/roll-runtime-protocol-v1.5.schema.json",
+    "./schema/1.6": "./dist/schema/roll-runtime-protocol-v1.6.schema.json"
   },
   "publishConfig": {
     "access": "public"