@roll-agent/relay-protocol 0.4.2 → 0.5.0

package/fixtures/v1.3/manifest.json

@@ -0,0 +1,489 @@
+{
+  "protocolVersion": "1.3",
+  "frames": [
+    {
+      "id": "device-connect-v11",
+      "fixture": "valid-device-connect.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-request-v11",
+      "fixture": "valid-runtime-request.json",
+      "valid": true
+    },
+    {
+      "id": "interaction-candidate-user-input",
+      "fixture": "valid-interaction-candidate-user-input.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-response-v11",
+      "fixture": "valid-runtime-response.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-event-v11",
+      "fixture": "valid-runtime-event.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-event-runtime-n-minus-one",
+      "fixture": "valid-runtime-event-runtime-n-minus-one.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-ack-v11",
+      "fixture": "valid-runtime-ack.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-gap-v11",
+      "fixture": "valid-runtime-gap.json",
+      "valid": true
+    },
+    {
+      "id": "runtime-encrypted-interaction-v11",
+      "fixture": "valid-runtime-encrypted-interaction.json",
+      "valid": true
+    },
+    {
+      "id": "interaction-request-approval",
+      "fixture": "valid-interaction-request-approval.json",
+      "valid": true
+    },
+    {
+      "id": "interaction-request-user-input",
+      "fixture": "valid-interaction-request-user-input.json",
+      "valid": true
+    },
+    {
+      "id": "interaction-resolved",
+      "fixture": "valid-interaction-resolved.json",
+      "valid": true
+    },
+    {
+      "id": "interaction-cancelled",
+      "fixture": "valid-interaction-cancelled.json",
+      "valid": true
+    },
+    {
+      "id": "n-minus-one-device-connect-rejected",
+      "fixture": "invalid-n-minus-one-device-connect.json",
+      "valid": false
+    },
+    {
+      "id": "legacy-approval-respond-rejected",
+      "fixture": "invalid-legacy-approval-respond.json",
+      "valid": false
+    },
+    {
+      "id": "legacy-approval-candidate-rejected",
+      "fixture": "invalid-legacy-approval-candidate.json",
+      "valid": false
+    },
+    {
+      "id": "approval-projection-raw-input-leak",
+      "fixture": "invalid-approval-projection-raw-input-leak.json",
+      "valid": false
+    },
+    {
+      "id": "user-input-projection-secret-leak",
+      "fixture": "invalid-user-input-projection-secret-leak.json",
+      "valid": false
+    },
+    {
+      "id": "non-normal-sensitivity-rejected",
+      "fixture": "invalid-non-normal-sensitivity.json",
+      "valid": false
+    },
+    {
+      "id": "authentication-local-only",
+      "fixture": "invalid-authentication-local-only.json",
+      "valid": false
+    },
+    {
+      "id": "file-picker-local-only",
+      "fixture": "invalid-file-picker-local-only.json",
+      "valid": false
+    },
+    {
+      "id": "interaction-resolved-result-leak",
+      "fixture": "invalid-interaction-resolved-result-leak.json",
+      "valid": false
+    },
+    {
+      "id": "interaction-cancelled-reason-leak",
+      "fixture": "invalid-interaction-cancelled-reason-leak.json",
+      "valid": false
+    },
+    {
+      "id": "runtime-event-tool-input-leak",
+      "fixture": "invalid-runtime-event-tool-input-leak.json",
+      "valid": false
+    },
+    {
+      "id": "runtime-event-tool-output-leak",
+      "fixture": "invalid-runtime-event-tool-output-leak.json",
+      "valid": false
+    },
+    {
+      "id": "context-recovery",
+      "fixture": "valid-context-recovery.json",
+      "valid": true
+    },
+    {
+      "id": "context-recovery-private-notes",
+      "fixture": "invalid-context-recovery-notes.json",
+      "valid": false
+    }
+  ],
+  "negotiation": [],
+  "methodRegistry": [],
+  "methods": [],
+  "replay": [
+    {
+      "id": "interaction-candidate-duplicate",
+      "existing": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "candidate": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "candidate": {
+            "values": [
+              {
+                "value": "north",
+                "id": "region"
+              },
+              {
+                "value": "target-workspace",
+                "id": "workspace"
+              }
+            ],
+            "status": "submitted"
+          },
+          "method": "userInput.request",
+          "threadId": "00000000-0000-4000-8000-000000000502"
+        }
+      },
+      "expected": {
+        "disposition": "replay"
+      }
+    },
+    {
+      "id": "interaction-candidate-conflict",
+      "existing": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "candidate": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000512",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "expected": {
+        "disposition": "conflict",
+        "errorCode": "RELAY_REQUEST_ID_CONFLICT"
+      }
+    },
+    {
+      "id": "interaction-candidate-different-request-id",
+      "existing": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "candidate": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000505",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "expected": {
+        "disposition": "new"
+      }
+    },
+    {
+      "id": "interaction-candidate-different-workspace",
+      "existing": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000507",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "candidate": {
+        "type": "runtime.request",
+        "requestId": "00000000-0000-4000-8000-000000000509",
+        "workspaceId": "00000000-0000-4000-8000-000000000510",
+        "method": "interaction.candidate",
+        "params": {
+          "interactionId": "00000000-0000-4000-8000-000000000511",
+          "threadId": "00000000-0000-4000-8000-000000000502",
+          "turnId": "00000000-0000-4000-8000-000000000503",
+          "method": "userInput.request",
+          "candidate": {
+            "status": "submitted",
+            "values": [
+              {
+                "id": "region",
+                "value": "north"
+              },
+              {
+                "id": "workspace",
+                "value": "target-workspace"
+              }
+            ]
+          }
+        }
+      },
+      "expected": {
+        "disposition": "new"
+      }
+    }
+  ],
+  "ack": [
+    {
+      "id": "initial-advance",
+      "acknowledgedThrough": -1,
+      "advertisedThrough": 0,
+      "incomingThrough": 0,
+      "expected": "advance"
+    },
+    {
+      "id": "advance-contiguous-prefix",
+      "acknowledgedThrough": 0,
+      "advertisedThrough": 2,
+      "incomingThrough": 2,
+      "expected": "advance"
+    },
+    {
+      "id": "equal-duplicate-ack",
+      "acknowledgedThrough": 2,
+      "advertisedThrough": 2,
+      "incomingThrough": 2,
+      "expected": "duplicate"
+    },
+    {
+      "id": "stale-duplicate-ack",
+      "acknowledgedThrough": 2,
+      "advertisedThrough": 2,
+      "incomingThrough": 1,
+      "expected": "duplicate"
+    },
+    {
+      "id": "ack-beyond-advertised",
+      "acknowledgedThrough": 0,
+      "advertisedThrough": 1,
+      "incomingThrough": 2,
+      "expected": "invalid"
+    },
+    {
+      "id": "fractional-ack",
+      "acknowledgedThrough": 0,
+      "advertisedThrough": 1,
+      "incomingThrough": 0.5,
+      "expected": "invalid"
+    },
+    {
+      "id": "ack-below-sentinel",
+      "acknowledgedThrough": -2,
+      "advertisedThrough": 0,
+      "incomingThrough": 0,
+      "expected": "invalid"
+    }
+  ],
+  "errors": [
+    {
+      "id": "error-retryability-RELAY_PROTOCOL_VERSION_UNSUPPORTED",
+      "code": "RELAY_PROTOCOL_VERSION_UNSUPPORTED",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-RELAY_INVALID_FRAME",
+      "code": "RELAY_INVALID_FRAME",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-INVALID_PARAMS",
+      "code": "INVALID_PARAMS",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-RELAY_REQUEST_ID_CONFLICT",
+      "code": "RELAY_REQUEST_ID_CONFLICT",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-WORKSPACE_NOT_FOUND",
+      "code": "WORKSPACE_NOT_FOUND",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-RELAY_ENCRYPTION_REQUIRED",
+      "code": "RELAY_ENCRYPTION_REQUIRED",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-ENCRYPTED_PAYLOAD_INVALID",
+      "code": "ENCRYPTED_PAYLOAD_INVALID",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-LocalApprovalDeniedError",
+      "code": "LocalApprovalDeniedError",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-LocalConfirmationRequiredError",
+      "code": "LocalConfirmationRequiredError",
+      "retryable": false
+    },
+    {
+      "id": "error-retryability-COMPANION_ERROR",
+      "code": "COMPANION_ERROR",
+      "retryable": false
+    }
+  ],
+  "encryptedVisibleMetadataFields": [
+    "type",
+    "workspaceId",
+    "envelopeId",
+    "payloadKind",
+    "requestId",
+    "relaySequence",
+    "algorithm",
+    "nonce",
+    "ciphertext"
+  ],
+  "deferredBreakingRules": [
+    "runtime.response-result-xor-error",
+    "encrypted-payload-kind-required-metadata",
+    "gap-from-not-after-through"
+  ]
+}

package/fixtures/v1.3/valid-context-recovery.json

@@ -0,0 +1,21 @@
+{
+  "type": "runtime.event",
+  "workspaceId": "00000000-0000-4000-8000-000000000002",
+  "relaySequence": 0,
+  "event": {
+    "protocolVersion": "1.1",
+    "runtimeInstanceId": "00000000-0000-4000-8000-000000000001",
+    "sequence": 0,
+    "timestamp": "2026-10-13T00:00:00.000Z",
+    "threadId": "00000000-0000-4000-8000-000000000002",
+    "event": {
+      "type": "context.recovery.changed",
+      "contextRecovery": {
+        "checkpointId": "00000000-0000-4000-8000-000000000003",
+        "required": true,
+        "unextracted": true,
+        "requiredItemCount": 24
+      }
+    }
+  }
+}

package/fixtures/v1.3/valid-device-connect.json

@@ -0,0 +1,6 @@
+{
+  "type": "device.connect",
+  "protocolVersion": "1.3",
+  "deviceId": "00000000-0000-4000-8000-000000000506",
+  "pairingToken": "pairing-token-with-sufficient-length"
+}

package/fixtures/v1.3/valid-interaction-cancelled.json

@@ -0,0 +1,9 @@
+{
+  "type": "interaction.cancelled",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "relaySequence": 6,
+  "interactionId": "00000000-0000-4000-8000-000000000511",
+  "threadId": "00000000-0000-4000-8000-000000000502",
+  "turnId": "00000000-0000-4000-8000-000000000503",
+  "method": "approval.request"
+}

package/fixtures/v1.3/valid-interaction-candidate-user-input.json

@@ -0,0 +1,25 @@
+{
+  "type": "runtime.request",
+  "requestId": "00000000-0000-4000-8000-000000000509",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "method": "interaction.candidate",
+  "params": {
+    "interactionId": "00000000-0000-4000-8000-000000000511",
+    "threadId": "00000000-0000-4000-8000-000000000502",
+    "turnId": "00000000-0000-4000-8000-000000000503",
+    "method": "userInput.request",
+    "candidate": {
+      "status": "submitted",
+      "values": [
+        {
+          "id": "region",
+          "value": "north"
+        },
+        {
+          "id": "workspace",
+          "value": "target-workspace"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "type": "interaction.request",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "relaySequence": 3,
+  "interactionId": "00000000-0000-4000-8000-000000000511",
+  "threadId": "00000000-0000-4000-8000-000000000502",
+  "turnId": "00000000-0000-4000-8000-000000000503",
+  "expiresAt": "2026-08-04T00:05:00.000Z",
+  "sensitivity": "normal",
+  "method": "approval.request",
+  "projection": {
+    "approvalId": "00000000-0000-4000-8000-000000000504",
+    "agentName": "workspace-agent",
+    "toolName": "deploy",
+    "explanation": "部署前需要确认。"
+  }
+}

package/fixtures/v1.3/valid-interaction-request-user-input.json

@@ -0,0 +1,40 @@
+{
+  "type": "interaction.request",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "relaySequence": 4,
+  "interactionId": "00000000-0000-4000-8000-000000000511",
+  "threadId": "00000000-0000-4000-8000-000000000502",
+  "turnId": "00000000-0000-4000-8000-000000000503",
+  "expiresAt": "2026-08-04T00:05:00.000Z",
+  "sensitivity": "normal",
+  "method": "userInput.request",
+  "projection": {
+    "title": "部署配置",
+    "controls": [
+      {
+        "id": "region",
+        "type": "choice",
+        "label": "部署区域",
+        "required": true,
+        "multiple": false,
+        "options": [
+          {
+            "id": "north",
+            "label": "北区"
+          },
+          {
+            "id": "south",
+            "label": "南区"
+          }
+        ]
+      },
+      {
+        "id": "workspace",
+        "type": "text",
+        "label": "目标 Workspace",
+        "required": true,
+        "maxLength": 100
+      }
+    ]
+  }
+}

package/fixtures/v1.3/valid-interaction-resolved.json

@@ -0,0 +1,9 @@
+{
+  "type": "interaction.resolved",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "relaySequence": 5,
+  "interactionId": "00000000-0000-4000-8000-000000000511",
+  "threadId": "00000000-0000-4000-8000-000000000502",
+  "turnId": "00000000-0000-4000-8000-000000000503",
+  "method": "userInput.request"
+}

package/fixtures/v1.3/valid-runtime-ack.json

@@ -0,0 +1,5 @@
+{
+  "type": "runtime.ack",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "throughRelaySequence": 1
+}

package/fixtures/v1.3/valid-runtime-encrypted-interaction.json

@@ -0,0 +1,10 @@
+{
+  "type": "runtime.encrypted",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "envelopeId": "00000000-0000-4000-8000-000000000508",
+  "payloadKind": "interaction",
+  "relaySequence": 2,
+  "algorithm": "example-aead",
+  "nonce": "opaque-nonce",
+  "ciphertext": "opaque-ciphertext"
+}

package/fixtures/v1.3/valid-runtime-event-runtime-n-minus-one.json

@@ -0,0 +1,16 @@
+{
+  "type": "runtime.event",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "relaySequence": 1,
+  "event": {
+    "protocolVersion": "1.0",
+    "runtimeInstanceId": "00000000-0000-4000-8000-000000000501",
+    "sequence": 1,
+    "timestamp": "2026-08-04T00:00:01.000Z",
+    "threadId": "00000000-0000-4000-8000-000000000502",
+    "turnId": "00000000-0000-4000-8000-000000000503",
+    "event": {
+      "type": "turn.completed"
+    }
+  }
+}

package/fixtures/v1.3/valid-runtime-event.json

@@ -0,0 +1,16 @@
+{
+  "type": "runtime.event",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "relaySequence": 0,
+  "event": {
+    "protocolVersion": "1.1",
+    "runtimeInstanceId": "00000000-0000-4000-8000-000000000501",
+    "sequence": 0,
+    "timestamp": "2026-08-04T00:00:00.000Z",
+    "threadId": "00000000-0000-4000-8000-000000000502",
+    "turnId": "00000000-0000-4000-8000-000000000503",
+    "event": {
+      "type": "turn.completed"
+    }
+  }
+}

package/fixtures/v1.3/valid-runtime-gap.json

@@ -0,0 +1,7 @@
+{
+  "type": "runtime.gap",
+  "workspaceId": "00000000-0000-4000-8000-000000000507",
+  "fromRelaySequence": 0,
+  "throughRelaySequence": 2,
+  "recovery": "thread.snapshot"
+}