@roll-agent/relay-protocol 0.0.0

package/README.md

@@ -0,0 +1,72 @@
+# `@roll-agent/relay-protocol`
+
+Browser-safe 的 Roll Companion Relay Wire 契约。
+
+它不是 Cloud 服务、Browser SDK 或 Companion 进程；安装或导入本包不会建立连接、打开端口
+或启动后台任务。
+
+## 谁安装
+
+| 使用方 | 是否直接安装 | 用途 |
+|---|---:|---|
+| Browser Web App | 是 | 构造和校验 Relay frame |
+| Cloud Relay Server | 是 | 校验、路由和持久化 Relay frame |
+| Local Companion Host | 是 | 与 Cloud 使用同一 Wire 契约 |
+| Local-only Desktop GUI | 否 | 直接使用 Runtime Protocol，不经过 Relay |
+| Runtime / `roll chat` | 否 | 使用 `@roll-agent/protocol` 或进程内调用 |
+
+```bash
+pnpm add @roll-agent/relay-protocol
+```
+
+本包提供：
+
+- 显式冻结的 Relay Wire version、message/method registry；
+- `DeviceId`、`WorkspaceId`、Relay `requestId` / `envelopeId` Schema；
+- `device.connect`、request/response/event/ack/gap/encrypted frame Schema；
+- method-specific Params/Result parser；
+- 以 `(workspaceId, requestId)` 为幂等键的 `new/replay/conflict` 分类；
+- 稳定 Relay error code 与 retryability 映射；
+- JSON Schema、跨语言 fixtures 和可复用 conformance cases。
+
+```ts
+import {
+  RELAY_PROTOCOL_VERSION,
+  relayMessageSchema,
+  workspaceIdSchema,
+} from "@roll-agent/relay-protocol";
+import {
+  runRelayProtocolConformance,
+  runtimeRelayProtocolConformanceAdapter,
+} from "@roll-agent/relay-protocol/conformance";
+```
+
+`@roll-agent/relay-protocol/schema` 导出 JSON Schema Draft 2020-12，
+`@roll-agent/relay-protocol/fixtures/v1/*` 导出 golden fixtures。
+
+`runRelayProtocolConformance()` 同时检查 frame、version 选择、完整 method registry 及其
+`query` / `mutation` / `local-only` disposition、duplicate/conflict 与错误码形状、基于调用方
+已证明连续投递前缀的 ACK 边界、gap recovery、加密 metadata 和 Relay error retryability。
+Transport 必须自行保证发送失败后不会越过序号缺口；Companion Bridge 会终止失败的
+transport generation 并在重连后重放。当前只有 `"1.0"`，因此只能验证同版本与未知版本
+fail-closed；真实 `N/N-1` 矩阵必须等下一版 Relay Wire 存在后补齐，不能伪造历史版本。
+
+## 边界
+
+本包不包含 Transport、WebSocket、账号/设备数据库、本地 Policy、加密实现或 Cloud
+部署代码。运行时代码只依赖 Browser-safe 的 `@roll-agent/protocol` 与 `zod`。
+
+Browser 与 Cloud Relay 不能为了获得 Wire Schema 而安装 `@roll-agent/companion`。
+TypeScript/JavaScript 实现直接使用本包；其他语言使用本包发布的 JSON Schema、fixtures
+与 conformance cases。
+
+当前只冻结 Relay Wire `"1.0"`。其中 `approval.candidate` 是现有 Approval 专属方法；
+通用 typed interaction 与逻辑 `interactionId` 必须在后续 Relay Wire version 中定义，
+不能静默扩张 `"1.0"`。
+
+Relay version 冻结外层 envelope、message type 与 recognized method registry。
+`local-only` 方法（当前为 `initialize`）只能由 Companion 在本地处理，不得转发给 Runtime；
+`query` / `mutation` 才是远程请求分类。既有 Runtime method 的 Params/Result 继续属于按
+Workspace 协商的 Runtime Protocol 契约；`relayRequestMethodSchemas` 是当前
+`@roll-agent/protocol` 依赖版本的 typed 视图，不应被解释为 Relay `"1.0"` 单独复制的一套
+Runtime Schema。

package/dist/conformance.d.ts

@@ -0,0 +1,329 @@
+import { RELAY_PROTOCOL_VERSION, type RelayAckDisposition, type RelayAckState, type RelayErrorCode, type RelayProtocolVersion, type RelayRequestMethod, type RelayRequestMethodDisposition, type RelayRequestReplayClassification, type RelayRuntimeRequest } from "./index.ts";
+export interface RelayFrameConformanceCase {
+    readonly id: string;
+    readonly fixtureName: `${"valid" | "invalid"}-${string}.json`;
+    readonly valid: boolean;
+    readonly frame: unknown;
+}
+export declare const RELAY_FRAME_CONFORMANCE_CASES: readonly [{
+    readonly id: "device-connect";
+    readonly fixtureName: "valid-device-connect.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "device.connect";
+        readonly protocolVersion: "1.0";
+        readonly deviceId: "00000000-0000-4000-8000-000000000506";
+        readonly pairingToken: "pairing-token-with-sufficient-length";
+    };
+}, {
+    readonly id: "runtime-request";
+    readonly fixtureName: "valid-runtime-request.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "runtime.request";
+        readonly requestId: "00000000-0000-4000-8000-000000000505";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly method: "thread.snapshot";
+        readonly params: {
+            readonly threadId: "00000000-0000-4000-8000-000000000502";
+            readonly limit: 100;
+        };
+    };
+}, {
+    readonly id: "runtime-response";
+    readonly fixtureName: "valid-runtime-response.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "runtime.response";
+        readonly requestId: "00000000-0000-4000-8000-000000000505";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly result: {
+            readonly accepted: true;
+        };
+    };
+}, {
+    readonly id: "runtime-event";
+    readonly fixtureName: "valid-runtime-event.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "runtime.event";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly relaySequence: 0;
+        readonly event: {
+            readonly protocolVersion: "1.0";
+            readonly runtimeInstanceId: "00000000-0000-4000-8000-000000000501";
+            readonly sequence: 0;
+            readonly timestamp: "2026-07-30T00:00:00.000Z";
+            readonly threadId: "00000000-0000-4000-8000-000000000502";
+            readonly turnId: "00000000-0000-4000-8000-000000000503";
+            readonly event: {
+                readonly type: "turn.completed";
+            };
+        };
+    };
+}, {
+    readonly id: "runtime-ack";
+    readonly fixtureName: "valid-runtime-ack.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "runtime.ack";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly throughRelaySequence: 0;
+    };
+}, {
+    readonly id: "runtime-gap";
+    readonly fixtureName: "valid-runtime-gap.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "runtime.gap";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly fromRelaySequence: 0;
+        readonly throughRelaySequence: 2;
+        readonly recovery: "thread.snapshot";
+    };
+}, {
+    readonly id: "runtime-encrypted";
+    readonly fixtureName: "valid-runtime-encrypted.json";
+    readonly valid: true;
+    readonly frame: {
+        readonly type: "runtime.encrypted";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly envelopeId: "00000000-0000-4000-8000-000000000508";
+        readonly payloadKind: "request";
+        readonly requestId: "00000000-0000-4000-8000-000000000505";
+        readonly algorithm: "example-aead";
+        readonly nonce: "opaque-nonce";
+        readonly ciphertext: "opaque-ciphertext";
+    };
+}, {
+    readonly id: "unknown-version";
+    readonly fixtureName: "invalid-unknown-version.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "device.connect";
+        readonly protocolVersion: "9.9";
+        readonly deviceId: "00000000-0000-4000-8000-000000000506";
+        readonly pairingToken: "pairing-token-with-sufficient-length";
+    };
+}, {
+    readonly id: "unknown-message";
+    readonly fixtureName: "invalid-unknown-message.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "runtime.unknown";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+    };
+}, {
+    readonly id: "unknown-method";
+    readonly fixtureName: "invalid-unknown-method.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "runtime.request";
+        readonly requestId: "00000000-0000-4000-8000-000000000505";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly method: "runtime.futureMethod";
+        readonly params: {};
+    };
+}, {
+    readonly id: "invalid-id";
+    readonly fixtureName: "invalid-request-id.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "runtime.request";
+        readonly requestId: "not-a-uuid";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly method: "thread.list";
+        readonly params: {};
+    };
+}, {
+    readonly id: "extra-field";
+    readonly fixtureName: "invalid-extra-field.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "runtime.ack";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly throughRelaySequence: 0;
+        readonly unexpected: true;
+    };
+}, {
+    readonly id: "invalid-gap-recovery";
+    readonly fixtureName: "invalid-gap-recovery.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "runtime.gap";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly fromRelaySequence: 0;
+        readonly throughRelaySequence: 2;
+        readonly recovery: "event.replay";
+    };
+}, {
+    readonly id: "encrypted-metadata-leak";
+    readonly fixtureName: "invalid-encrypted-metadata-leak.json";
+    readonly valid: false;
+    readonly frame: {
+        readonly type: "runtime.encrypted";
+        readonly workspaceId: "00000000-0000-4000-8000-000000000507";
+        readonly envelopeId: "00000000-0000-4000-8000-000000000508";
+        readonly payloadKind: "request";
+        readonly requestId: "00000000-0000-4000-8000-000000000505";
+        readonly algorithm: "example-aead";
+        readonly nonce: "opaque-nonce";
+        readonly ciphertext: "opaque-ciphertext";
+        readonly plaintext: {
+            readonly secret: "must-not-be-visible";
+        };
+    };
+}];
+export interface RelayNegotiationConformanceCase {
+    readonly id: string;
+    readonly peerVersions: readonly string[];
+    readonly expected: RelayProtocolVersion | undefined;
+}
+export declare const RELAY_NEGOTIATION_CONFORMANCE_CASES: readonly [{
+    readonly id: "same-version";
+    readonly peerVersions: readonly ["1.0"];
+    readonly expected: "1.0";
+}, {
+    readonly id: "unknown-before-supported";
+    readonly peerVersions: readonly ["9.9", "1.0"];
+    readonly expected: "1.0";
+}, {
+    readonly id: "unknown-only";
+    readonly peerVersions: readonly ["9.9"];
+    readonly expected: undefined;
+}];
+export interface RelayMethodRegistryConformanceCase {
+    readonly id: string;
+    readonly value: string;
+    readonly expected: RelayRequestMethodDisposition | undefined;
+}
+export declare const RELAY_METHOD_REGISTRY_CONFORMANCE_CASES: readonly RelayMethodRegistryConformanceCase[];
+export interface RelayMethodConformanceCase {
+    readonly id: string;
+    readonly method: RelayRequestMethod;
+    readonly kind: "params" | "result";
+    readonly valid: boolean;
+    readonly value: unknown;
+}
+export declare const RELAY_METHOD_CONFORMANCE_CASES: readonly [{
+    readonly id: "approval-candidate-params";
+    readonly method: "approval.candidate";
+    readonly kind: "params";
+    readonly valid: true;
+    readonly value: {
+        readonly threadId: "00000000-0000-4000-8000-000000000502";
+        readonly turnId: "00000000-0000-4000-8000-000000000503";
+        readonly approvalId: "00000000-0000-4000-8000-000000000504";
+        readonly decision: "approve";
+    };
+}, {
+    readonly id: "approval-candidate-empty-reason";
+    readonly method: "approval.candidate";
+    readonly kind: "params";
+    readonly valid: false;
+    readonly value: {
+        readonly threadId: "00000000-0000-4000-8000-000000000502";
+        readonly turnId: "00000000-0000-4000-8000-000000000503";
+        readonly approvalId: "00000000-0000-4000-8000-000000000504";
+        readonly decision: "reject";
+        readonly reason: "";
+    };
+}, {
+    readonly id: "approval-candidate-result";
+    readonly method: "approval.candidate";
+    readonly kind: "result";
+    readonly valid: true;
+    readonly value: {
+        readonly accepted: true;
+    };
+}];
+export interface RelayReplayConformanceCase {
+    readonly id: string;
+    readonly existing: RelayRuntimeRequest;
+    readonly candidate: RelayRuntimeRequest;
+    readonly expected: RelayRequestReplayClassification;
+}
+export declare const RELAY_REPLAY_CONFORMANCE_CASES: readonly RelayReplayConformanceCase[];
+export interface RelayAckConformanceCase extends RelayAckState {
+    readonly id: string;
+    readonly expected: RelayAckDisposition;
+}
+export declare const RELAY_ACK_CONFORMANCE_CASES: readonly [{
+    readonly id: "initial-advance";
+    readonly acknowledgedThrough: -1;
+    readonly advertisedThrough: 0;
+    readonly incomingThrough: 0;
+    readonly expected: "advance";
+}, {
+    readonly id: "advance-contiguous-prefix";
+    readonly acknowledgedThrough: 0;
+    readonly advertisedThrough: 2;
+    readonly incomingThrough: 2;
+    readonly expected: "advance";
+}, {
+    readonly id: "equal-duplicate-ack";
+    readonly acknowledgedThrough: 2;
+    readonly advertisedThrough: 2;
+    readonly incomingThrough: 2;
+    readonly expected: "duplicate";
+}, {
+    readonly id: "stale-duplicate-ack";
+    readonly acknowledgedThrough: 2;
+    readonly advertisedThrough: 2;
+    readonly incomingThrough: 1;
+    readonly expected: "duplicate";
+}, {
+    readonly id: "ack-beyond-advertised";
+    readonly acknowledgedThrough: 0;
+    readonly advertisedThrough: 1;
+    readonly incomingThrough: 2;
+    readonly expected: "invalid";
+}, {
+    readonly id: "fractional-ack";
+    readonly acknowledgedThrough: 0;
+    readonly advertisedThrough: 1;
+    readonly incomingThrough: 0.5;
+    readonly expected: "invalid";
+}, {
+    readonly id: "ack-below-sentinel";
+    readonly acknowledgedThrough: -2;
+    readonly advertisedThrough: 0;
+    readonly incomingThrough: 0;
+    readonly expected: "invalid";
+}];
+export declare const RELAY_ENCRYPTED_VISIBLE_METADATA_FIELDS: readonly ["type", "workspaceId", "envelopeId", "payloadKind", "requestId", "relaySequence", "algorithm", "nonce", "ciphertext"];
+export interface RelayErrorConformanceCase {
+    readonly id: string;
+    readonly code: RelayErrorCode;
+    readonly retryable: boolean;
+}
+export declare const RELAY_ERROR_CONFORMANCE_CASES: {
+    id: string;
+    code: "INVALID_PARAMS" | "RELAY_PROTOCOL_VERSION_UNSUPPORTED" | "RELAY_INVALID_FRAME" | "RELAY_REQUEST_ID_CONFLICT" | "WORKSPACE_NOT_FOUND" | "RELAY_ENCRYPTION_REQUIRED" | "ENCRYPTED_PAYLOAD_INVALID" | "LocalApprovalDeniedError" | "LocalConfirmationRequiredError" | "COMPANION_ERROR";
+    retryable: false;
+}[];
+export interface RelayProtocolConformanceAdapter {
+    validateFrame(value: unknown): boolean;
+    negotiate(peerVersions: readonly string[]): RelayProtocolVersion | undefined;
+    getRequestMethodDisposition(value: string): string | undefined;
+    validateMethodValue(method: RelayRequestMethod, kind: "params" | "result", value: unknown): boolean;
+    classifyReplay(existing: RelayRuntimeRequest, candidate: RelayRuntimeRequest): RelayReplayConformanceObservation;
+    classifyAck(state: RelayAckState): RelayAckDisposition;
+    getErrorRetryability(code: RelayErrorCode): boolean;
+}
+export interface RelayReplayConformanceObservation {
+    readonly disposition: string;
+    readonly errorCode?: string;
+}
+export declare const runtimeRelayProtocolConformanceAdapter: RelayProtocolConformanceAdapter;
+export interface RelayProtocolConformanceFailure {
+    readonly caseId: string;
+    readonly expected: string;
+    readonly actual: string;
+}
+export interface RelayProtocolConformanceResult {
+    readonly protocolVersion: typeof RELAY_PROTOCOL_VERSION;
+    readonly passed: boolean;
+    readonly failures: readonly RelayProtocolConformanceFailure[];
+}
+export declare function runRelayProtocolConformance(adapter: RelayProtocolConformanceAdapter): RelayProtocolConformanceResult;