@roll-agent/relay-protocol 0.2.0 → 0.3.1

package/README.md

@@ -9,7 +9,8 @@ Browser-safe 的 Roll Companion Relay Wire 契约。
 
 | 使用方 | 是否直接安装 | 用途 |
 |---|---:|---|
-| Browser Web App | 是 | 构造、校验并投影 Relay frame |
+| 普通 Browser Web App | 否 | 安装 `@roll-agent/relay-client`，不直接处理 frame |
+| 自定义 Browser Transport | 是 | 实现 Relay frame、ACK/gap 与恢复 |
 | Cloud Relay Server | 是 | 校验、路由和持久化 Relay frame |
 | Local Companion Host | 是 | 与 Cloud 使用同一 Wire 契约 |
 | Local-only Desktop GUI | 否 | 直接使用 Runtime Protocol，不经过 Relay |
@@ -19,6 +20,39 @@ Browser-safe 的 Roll Companion Relay Wire 契约。
 pnpm add @roll-agent/relay-protocol
 ```
 
+普通第三方 Web App 应安装 `@roll-agent/relay-client`；本包面向 Cloud Relay、Companion 和确实
+需要自定义 Transport 的高级实现者。
+
+## Control 1.0 与方向合同
+
+Browser Session 的 HTTP 返回和 WebSocket 控制面从独立 subpath 导入，不属于
+`relayMessageSchemaV11` 数据面 union：
+
+```ts
+import {
+  RELAY_BROWSER_WSS_MESSAGE_TYPES_BY_DIRECTION,
+  RELAY_COMPANION_WSS_MESSAGE_TYPES_BY_DIRECTION,
+  parseRelayBrowserFirstControlFrame,
+  relayBrowserControlMessageSchema,
+  relaySessionDescriptorSchema,
+} from "@roll-agent/relay-protocol/control";
+
+const session = relaySessionDescriptorSchema.parse(await response.json());
+const ready = parseRelayBrowserFirstControlFrame(firstWebSocketFrame);
+relayBrowserControlMessageSchema.parse(laterControlFrame);
+```
+
+`session.ready` 必须是 Browser WebSocket 收到的第一帧，并固定声明 Control 1.0、Wire 1.1、
+Relay 绑定的 Workspace 和在线状态。Browser 不能在请求中自行指定 `workspaceId`。
+Ticket 无效、过期、重复消费或 Origin 不匹配时，Relay 必须在 HTTP upgrade 阶段拒绝连接；
+这些错误属于 `RELAY_BROWSER_HANDSHAKE_ERROR_CODES`，不能伪装成已认证连接中的
+`session.error`。后者只承载 `session.ready` 之后的会话错误。
+
+方向 allowlist 固定为：Browser→Relay 只允许 Wire 1.1 `runtime.request` 与 `runtime.ack`；
+Relay→Companion 同样只允许这两类。Relay→Browser 允许 Control 帧以及 response/event/gap/
+Interaction 帧；Companion→Relay 还包含首帧 `device.connect`。`runtime.ack` 是 Wire 数据面，
+不是 Control ACK。P0 不提供 E2EE，因此这些 P0 WSS allowlist 明确不含 `runtime.encrypted`。
+
 ## 版本
 
 支持矩阵是 `["1.1", "1.0"]`。Wire 1.1 新增 typed Interaction；Wire 1.0 的 registry、
@@ -50,8 +84,10 @@ Wire 1.1 增加 `interaction.request`、`interaction.resolved`、
 `interaction.cancelled` 三种 Companion→Browser frame。Browser 通过 mutation
 `interaction.candidate` 提交候选；`approval.candidate` 只存在于冻结的 Wire 1.0。
 
-远端候选不是 Runtime 的权威决议。Companion 仍持有 Runtime Handler、绝对 deadline 和
-本地 Policy；Approval approve candidate 必须在本机重新经过 Policy。
+远端候选不是独立授权事实源。Runtime policy 先决定 auto/confirm/deny；只有 confirm 才产生
+可响应 Interaction，deny 不会被远端越过。官方 Companion 只再验证 request policy、Workspace、
+responder 与绝对 deadline，不增加电脑端二次审批。低层自定义 Host 可以进一步收紧，但不能
+放宽 Runtime 决议。
 
 安全投影只允许：
 
@@ -64,6 +100,10 @@ Runtime JSON-RPC `id`、原始 Tool input/output、secret、完整 User Input Re
 以及 Authentication/File Picker projector 都不能进入 Companion→Browser 投影。Browser→Companion 的
 `interaction.candidate` 是 User Input Result 唯一允许的入站位置，并且必须关联原始表单重新校验。
 
+Wire 1.1 Snapshot 不能重建一个仍可响应的 `interactionId`。Browser Session 重连时，Cloud
+Relay 必须保留并重新投递尚未 resolved/cancelled 的 `interaction.request`；客户端不得从
+`approvalId` 或 Snapshot 自行合成 Interaction identity。
+
 Wire 1.1 的 pull 查询遵守同一边界：`thread.open` / `thread.snapshot` 必须把 Approval preview
 投影为可选 explanation、移除本地 reason，并把 Operation display 与 outcome reason 脱敏；
 Host 对前两种结果调用 `projectRelayThreadSnapshotV11(value)`，对 `operation.get` 调用
@@ -104,6 +144,10 @@ context 必须由宿主注入。
 
 - `@roll-agent/relay-protocol/schema` 与 `/schema/v1.0`：冻结的 Wire 1.0 JSON Schema；
 - `@roll-agent/relay-protocol/schema/v1.1`：Wire 1.1 JSON Schema；
+- `@roll-agent/relay-protocol/control`：Control 1.0、Browser Session 和 WSS 方向 Schema；
+- `@roll-agent/relay-protocol/control/schema`：Control 1.0 JSON Schema；
+- `@roll-agent/relay-protocol/control/session-schema`：Browser Session JSON Schema；
+- `@roll-agent/relay-protocol/control/fixtures/*`：Control/Session golden fixtures；
 - `@roll-agent/relay-protocol/fixtures/v1/*`：字节冻结的 Wire 1.0 golden fixtures；
 - `@roll-agent/relay-protocol/fixtures/v1.1/*`：Wire 1.1 Interaction 与安全负例；
 - `@roll-agent/relay-protocol/conformance`：可复用的 N/N-1 suite。

package/dist/control.d.ts

@@ -0,0 +1,188 @@
+import { z } from "zod/v4";
+export declare const RELAY_CONTROL_VERSION: "1.0";
+export declare const RELAY_BROWSER_PROTOCOL_VERSION: "1.1";
+/**
+ * Authentication failures happen before the Browser WebSocket is accepted. They are HTTP upgrade
+ * errors and must never be sent as an authenticated Control frame.
+ */
+export declare const RELAY_BROWSER_HANDSHAKE_ERROR_CODES: {
+    readonly sessionTicketInvalid: "SESSION_TICKET_INVALID";
+    readonly sessionTicketExpired: "SESSION_TICKET_EXPIRED";
+    readonly sessionTicketAlreadyUsed: "SESSION_TICKET_ALREADY_USED";
+    readonly originNotAllowed: "ORIGIN_NOT_ALLOWED";
+};
+export declare const RELAY_BROWSER_HANDSHAKE_ERROR_CODE_VALUES: readonly ["SESSION_TICKET_INVALID", "SESSION_TICKET_EXPIRED", "SESSION_TICKET_ALREADY_USED", "ORIGIN_NOT_ALLOWED"];
+export declare const relayBrowserHandshakeErrorCodeSchema: z.ZodEnum<{
+    SESSION_TICKET_INVALID: "SESSION_TICKET_INVALID";
+    SESSION_TICKET_EXPIRED: "SESSION_TICKET_EXPIRED";
+    SESSION_TICKET_ALREADY_USED: "SESSION_TICKET_ALREADY_USED";
+    ORIGIN_NOT_ALLOWED: "ORIGIN_NOT_ALLOWED";
+}>;
+/** Errors observable only after the authenticated `session.ready` first frame. */
+export declare const RELAY_CLIENT_ERROR_CODES: {
+    readonly workspaceNotFound: "WORKSPACE_NOT_FOUND";
+    readonly workspaceOffline: "WORKSPACE_OFFLINE";
+    readonly controllerConflict: "CONTROLLER_CONFLICT";
+    readonly protocolVersionUnsupported: "RELAY_PROTOCOL_VERSION_UNSUPPORTED";
+    readonly rateLimited: "RATE_LIMITED";
+    readonly internalError: "RELAY_INTERNAL_ERROR";
+};
+export declare const RELAY_CLIENT_ERROR_CODE_VALUES: readonly ["WORKSPACE_NOT_FOUND", "WORKSPACE_OFFLINE", "CONTROLLER_CONFLICT", "RELAY_PROTOCOL_VERSION_UNSUPPORTED", "RATE_LIMITED", "RELAY_INTERNAL_ERROR"];
+export declare const relayClientErrorCodeSchema: z.ZodEnum<{
+    RELAY_PROTOCOL_VERSION_UNSUPPORTED: "RELAY_PROTOCOL_VERSION_UNSUPPORTED";
+    WORKSPACE_NOT_FOUND: "WORKSPACE_NOT_FOUND";
+    WORKSPACE_OFFLINE: "WORKSPACE_OFFLINE";
+    CONTROLLER_CONFLICT: "CONTROLLER_CONFLICT";
+    RATE_LIMITED: "RATE_LIMITED";
+    RELAY_INTERNAL_ERROR: "RELAY_INTERNAL_ERROR";
+}>;
+export declare const relayBrowserSessionIdSchema: z.core.$ZodBranded<z.ZodString, "RelayBrowserSessionId">;
+export declare const relaySessionDescriptorSchema: z.ZodReadonly<z.ZodObject<{
+    connectUrl: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strict>>;
+export declare const RELAY_WORKSPACE_STATUSES: readonly ["online", "offline"];
+export declare const relayWorkspaceStatusSchema: z.ZodEnum<{
+    online: "online";
+    offline: "offline";
+}>;
+export declare const RELAY_BROWSER_CONTROL_MESSAGE_TYPES: {
+    readonly sessionReady: "session.ready";
+    readonly workspaceStatus: "workspace.status";
+    readonly sessionError: "session.error";
+};
+export declare const RELAY_BROWSER_CONTROL_MESSAGE_TYPE_VALUES: readonly ["session.ready", "workspace.status", "session.error"];
+export declare const relaySessionReadyControlMessageSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"session.ready">;
+    controlVersion: z.ZodLiteral<"1.0">;
+    relayProtocolVersion: z.ZodLiteral<"1.1">;
+    sessionId: z.core.$ZodBranded<z.ZodString, "RelayBrowserSessionId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    workspaceStatus: z.ZodEnum<{
+        online: "online";
+        offline: "offline";
+    }>;
+}, z.core.$strict>>;
+export declare const relayWorkspaceStatusControlMessageSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"workspace.status">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    status: z.ZodEnum<{
+        online: "online";
+        offline: "offline";
+    }>;
+}, z.core.$strict>>;
+export declare const relaySessionErrorControlMessageSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"session.error">;
+    code: z.ZodEnum<{
+        RELAY_PROTOCOL_VERSION_UNSUPPORTED: "RELAY_PROTOCOL_VERSION_UNSUPPORTED";
+        WORKSPACE_NOT_FOUND: "WORKSPACE_NOT_FOUND";
+        WORKSPACE_OFFLINE: "WORKSPACE_OFFLINE";
+        CONTROLLER_CONFLICT: "CONTROLLER_CONFLICT";
+        RATE_LIMITED: "RATE_LIMITED";
+        RELAY_INTERNAL_ERROR: "RELAY_INTERNAL_ERROR";
+    }>;
+    retryable: z.ZodBoolean;
+}, z.core.$strict>>;
+export declare const relayBrowserControlMessageSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"session.ready">;
+    controlVersion: z.ZodLiteral<"1.0">;
+    relayProtocolVersion: z.ZodLiteral<"1.1">;
+    sessionId: z.core.$ZodBranded<z.ZodString, "RelayBrowserSessionId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    workspaceStatus: z.ZodEnum<{
+        online: "online";
+        offline: "offline";
+    }>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"workspace.status">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    status: z.ZodEnum<{
+        online: "online";
+        offline: "offline";
+    }>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"session.error">;
+    code: z.ZodEnum<{
+        RELAY_PROTOCOL_VERSION_UNSUPPORTED: "RELAY_PROTOCOL_VERSION_UNSUPPORTED";
+        WORKSPACE_NOT_FOUND: "WORKSPACE_NOT_FOUND";
+        WORKSPACE_OFFLINE: "WORKSPACE_OFFLINE";
+        CONTROLLER_CONFLICT: "CONTROLLER_CONFLICT";
+        RATE_LIMITED: "RATE_LIMITED";
+        RELAY_INTERNAL_ERROR: "RELAY_INTERNAL_ERROR";
+    }>;
+    retryable: z.ZodBoolean;
+}, z.core.$strict>>]>;
+/** Browser WebSocket connections must validate their first received frame with this schema. */
+export declare const relayBrowserFirstControlFrameSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"session.ready">;
+    controlVersion: z.ZodLiteral<"1.0">;
+    relayProtocolVersion: z.ZodLiteral<"1.1">;
+    sessionId: z.core.$ZodBranded<z.ZodString, "RelayBrowserSessionId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    workspaceStatus: z.ZodEnum<{
+        online: "online";
+        offline: "offline";
+    }>;
+}, z.core.$strict>>;
+export declare function parseRelayBrowserFirstControlFrame(value: unknown): RelaySessionReadyControlMessage;
+export declare const RELAY_CONTROL_DIRECTIONS: {
+    readonly relayToBrowser: "relay-to-browser";
+    readonly browserToRelay: "browser-to-relay";
+    readonly relayToCompanion: "relay-to-companion";
+    readonly companionToRelay: "companion-to-relay";
+};
+export declare const RELAY_CONTROL_DIRECTION_VALUES: readonly ["relay-to-browser", "browser-to-relay", "relay-to-companion", "companion-to-relay"];
+export declare const relayControlDirectionSchema: z.ZodEnum<{
+    "relay-to-browser": "relay-to-browser";
+    "browser-to-relay": "browser-to-relay";
+    "relay-to-companion": "relay-to-companion";
+    "companion-to-relay": "companion-to-relay";
+}>;
+export type RelayControlDirection = z.infer<typeof relayControlDirectionSchema>;
+export type RelayBrowserControlMessageType = (typeof RELAY_BROWSER_CONTROL_MESSAGE_TYPE_VALUES)[number];
+/** Control 1.0 is Relay-to-Browser only. Data-plane frames remain governed by Relay Wire 1.1. */
+export declare const RELAY_CONTROL_MESSAGE_TYPES_BY_DIRECTION: {
+    readonly "relay-to-browser": readonly ["session.ready", "workspace.status", "session.error"];
+    readonly "browser-to-relay": readonly [];
+    readonly "relay-to-companion": readonly [];
+    readonly "companion-to-relay": readonly [];
+};
+export declare function isRelayControlMessageTypeAllowed(direction: RelayControlDirection, messageType: string): messageType is RelayBrowserControlMessageType;
+export declare const RELAY_WSS_DIRECTIONS: {
+    readonly relayToPeer: "relay-to-peer";
+    readonly peerToRelay: "peer-to-relay";
+};
+export declare const RELAY_WSS_DIRECTION_VALUES: readonly ["relay-to-peer", "peer-to-relay"];
+export declare const relayWssDirectionSchema: z.ZodEnum<{
+    "relay-to-peer": "relay-to-peer";
+    "peer-to-relay": "peer-to-relay";
+}>;
+export type RelayWssDirection = z.infer<typeof relayWssDirectionSchema>;
+/**
+ * P0 Browser WebSocket direction contract. `runtime.ack` is a Wire 1.1 data-plane frame,
+ * not a Control frame. `runtime.encrypted` is intentionally absent because P0 does not offer E2EE.
+ */
+export declare const RELAY_BROWSER_WSS_MESSAGE_TYPES_BY_DIRECTION: {
+    readonly "relay-to-peer": readonly ["session.ready", "workspace.status", "session.error", "runtime.response", "runtime.event", "runtime.gap", "interaction.request", "interaction.resolved", "interaction.cancelled"];
+    readonly "peer-to-relay": readonly ["runtime.request", "runtime.ack"];
+};
+/**
+ * P0 Companion WebSocket direction contract. A Cloud Relay must additionally require
+ * `device.connect` as the Companion connection's first frame.
+ */
+export declare const RELAY_COMPANION_WSS_MESSAGE_TYPES_BY_DIRECTION: {
+    readonly "relay-to-peer": readonly ["runtime.request", "runtime.ack"];
+    readonly "peer-to-relay": readonly ["device.connect", "runtime.response", "runtime.event", "runtime.gap", "interaction.request", "interaction.resolved", "interaction.cancelled"];
+};
+export declare function isRelayBrowserWssMessageTypeAllowed(direction: RelayWssDirection, messageType: string): boolean;
+export declare function isRelayCompanionWssMessageTypeAllowed(direction: RelayWssDirection, messageType: string): boolean;
+export type RelayClientErrorCode = z.infer<typeof relayClientErrorCodeSchema>;
+export type RelayBrowserHandshakeErrorCode = z.infer<typeof relayBrowserHandshakeErrorCodeSchema>;
+export type RelayBrowserSessionId = z.infer<typeof relayBrowserSessionIdSchema>;
+export type RelaySessionDescriptor = z.infer<typeof relaySessionDescriptorSchema>;
+export type RelayWorkspaceStatus = z.infer<typeof relayWorkspaceStatusSchema>;
+export type RelaySessionReadyControlMessage = z.infer<typeof relaySessionReadyControlMessageSchema>;
+export type RelayWorkspaceStatusControlMessage = z.infer<typeof relayWorkspaceStatusControlMessageSchema>;
+export type RelaySessionErrorControlMessage = z.infer<typeof relaySessionErrorControlMessageSchema>;
+export type RelayBrowserControlMessage = z.infer<typeof relayBrowserControlMessageSchema>;
+export type RelayBrowserFirstControlFrame = z.infer<typeof relayBrowserFirstControlFrameSchema>;

package/dist/control.js

@@ -0,0 +1,180 @@
+import { z } from "zod/v4";
+import { RELAY_MESSAGE_TYPES_V11, workspaceIdSchema } from "./index.js";
+export const RELAY_CONTROL_VERSION = "1.0";
+export const RELAY_BROWSER_PROTOCOL_VERSION = "1.1";
+/**
+ * Authentication failures happen before the Browser WebSocket is accepted. They are HTTP upgrade
+ * errors and must never be sent as an authenticated Control frame.
+ */
+export const RELAY_BROWSER_HANDSHAKE_ERROR_CODES = {
+    sessionTicketInvalid: "SESSION_TICKET_INVALID",
+    sessionTicketExpired: "SESSION_TICKET_EXPIRED",
+    sessionTicketAlreadyUsed: "SESSION_TICKET_ALREADY_USED",
+    originNotAllowed: "ORIGIN_NOT_ALLOWED",
+};
+export const RELAY_BROWSER_HANDSHAKE_ERROR_CODE_VALUES = [
+    RELAY_BROWSER_HANDSHAKE_ERROR_CODES.sessionTicketInvalid,
+    RELAY_BROWSER_HANDSHAKE_ERROR_CODES.sessionTicketExpired,
+    RELAY_BROWSER_HANDSHAKE_ERROR_CODES.sessionTicketAlreadyUsed,
+    RELAY_BROWSER_HANDSHAKE_ERROR_CODES.originNotAllowed,
+];
+export const relayBrowserHandshakeErrorCodeSchema = z.enum(RELAY_BROWSER_HANDSHAKE_ERROR_CODE_VALUES);
+/** Errors observable only after the authenticated `session.ready` first frame. */
+export const RELAY_CLIENT_ERROR_CODES = {
+    workspaceNotFound: "WORKSPACE_NOT_FOUND",
+    workspaceOffline: "WORKSPACE_OFFLINE",
+    controllerConflict: "CONTROLLER_CONFLICT",
+    protocolVersionUnsupported: "RELAY_PROTOCOL_VERSION_UNSUPPORTED",
+    rateLimited: "RATE_LIMITED",
+    internalError: "RELAY_INTERNAL_ERROR",
+};
+export const RELAY_CLIENT_ERROR_CODE_VALUES = [
+    RELAY_CLIENT_ERROR_CODES.workspaceNotFound,
+    RELAY_CLIENT_ERROR_CODES.workspaceOffline,
+    RELAY_CLIENT_ERROR_CODES.controllerConflict,
+    RELAY_CLIENT_ERROR_CODES.protocolVersionUnsupported,
+    RELAY_CLIENT_ERROR_CODES.rateLimited,
+    RELAY_CLIENT_ERROR_CODES.internalError,
+];
+export const relayClientErrorCodeSchema = z.enum(RELAY_CLIENT_ERROR_CODE_VALUES);
+export const relayBrowserSessionIdSchema = z.string().min(1).brand();
+const secureWebSocketUrlSchema = z
+    .string()
+    .regex(/^wss:\/\/\S+$/u, "connectUrl must use wss:// without whitespace")
+    .url();
+export const relaySessionDescriptorSchema = z
+    .object({
+    connectUrl: secureWebSocketUrlSchema,
+    expiresAt: z.string().datetime({ offset: true }),
+})
+    .strict()
+    .readonly();
+export const RELAY_WORKSPACE_STATUSES = ["online", "offline"];
+export const relayWorkspaceStatusSchema = z.enum(RELAY_WORKSPACE_STATUSES);
+export const RELAY_BROWSER_CONTROL_MESSAGE_TYPES = {
+    sessionReady: "session.ready",
+    workspaceStatus: "workspace.status",
+    sessionError: "session.error",
+};
+export const RELAY_BROWSER_CONTROL_MESSAGE_TYPE_VALUES = [
+    RELAY_BROWSER_CONTROL_MESSAGE_TYPES.sessionReady,
+    RELAY_BROWSER_CONTROL_MESSAGE_TYPES.workspaceStatus,
+    RELAY_BROWSER_CONTROL_MESSAGE_TYPES.sessionError,
+];
+export const relaySessionReadyControlMessageSchema = z
+    .object({
+    type: z.literal(RELAY_BROWSER_CONTROL_MESSAGE_TYPES.sessionReady),
+    controlVersion: z.literal(RELAY_CONTROL_VERSION),
+    relayProtocolVersion: z.literal(RELAY_BROWSER_PROTOCOL_VERSION),
+    sessionId: relayBrowserSessionIdSchema,
+    workspaceId: workspaceIdSchema,
+    workspaceStatus: relayWorkspaceStatusSchema,
+})
+    .strict()
+    .readonly();
+export const relayWorkspaceStatusControlMessageSchema = z
+    .object({
+    type: z.literal(RELAY_BROWSER_CONTROL_MESSAGE_TYPES.workspaceStatus),
+    workspaceId: workspaceIdSchema,
+    status: relayWorkspaceStatusSchema,
+})
+    .strict()
+    .readonly();
+export const relaySessionErrorControlMessageSchema = z
+    .object({
+    type: z.literal(RELAY_BROWSER_CONTROL_MESSAGE_TYPES.sessionError),
+    code: relayClientErrorCodeSchema,
+    retryable: z.boolean(),
+})
+    .strict()
+    .readonly();
+export const relayBrowserControlMessageSchema = z.discriminatedUnion("type", [
+    relaySessionReadyControlMessageSchema,
+    relayWorkspaceStatusControlMessageSchema,
+    relaySessionErrorControlMessageSchema,
+]);
+/** Browser WebSocket connections must validate their first received frame with this schema. */
+export const relayBrowserFirstControlFrameSchema = relaySessionReadyControlMessageSchema;
+export function parseRelayBrowserFirstControlFrame(value) {
+    return relayBrowserFirstControlFrameSchema.parse(value);
+}
+export const RELAY_CONTROL_DIRECTIONS = {
+    relayToBrowser: "relay-to-browser",
+    browserToRelay: "browser-to-relay",
+    relayToCompanion: "relay-to-companion",
+    companionToRelay: "companion-to-relay",
+};
+export const RELAY_CONTROL_DIRECTION_VALUES = [
+    RELAY_CONTROL_DIRECTIONS.relayToBrowser,
+    RELAY_CONTROL_DIRECTIONS.browserToRelay,
+    RELAY_CONTROL_DIRECTIONS.relayToCompanion,
+    RELAY_CONTROL_DIRECTIONS.companionToRelay,
+];
+export const relayControlDirectionSchema = z.enum(RELAY_CONTROL_DIRECTION_VALUES);
+/** Control 1.0 is Relay-to-Browser only. Data-plane frames remain governed by Relay Wire 1.1. */
+export const RELAY_CONTROL_MESSAGE_TYPES_BY_DIRECTION = {
+    [RELAY_CONTROL_DIRECTIONS.relayToBrowser]: RELAY_BROWSER_CONTROL_MESSAGE_TYPE_VALUES,
+    [RELAY_CONTROL_DIRECTIONS.browserToRelay]: [],
+    [RELAY_CONTROL_DIRECTIONS.relayToCompanion]: [],
+    [RELAY_CONTROL_DIRECTIONS.companionToRelay]: [],
+};
+export function isRelayControlMessageTypeAllowed(direction, messageType) {
+    const allowed = RELAY_CONTROL_MESSAGE_TYPES_BY_DIRECTION[direction];
+    return allowed.includes(messageType);
+}
+export const RELAY_WSS_DIRECTIONS = {
+    relayToPeer: "relay-to-peer",
+    peerToRelay: "peer-to-relay",
+};
+export const RELAY_WSS_DIRECTION_VALUES = [
+    RELAY_WSS_DIRECTIONS.relayToPeer,
+    RELAY_WSS_DIRECTIONS.peerToRelay,
+];
+export const relayWssDirectionSchema = z.enum(RELAY_WSS_DIRECTION_VALUES);
+/**
+ * P0 Browser WebSocket direction contract. `runtime.ack` is a Wire 1.1 data-plane frame,
+ * not a Control frame. `runtime.encrypted` is intentionally absent because P0 does not offer E2EE.
+ */
+export const RELAY_BROWSER_WSS_MESSAGE_TYPES_BY_DIRECTION = {
+    [RELAY_WSS_DIRECTIONS.relayToPeer]: [
+        ...RELAY_BROWSER_CONTROL_MESSAGE_TYPE_VALUES,
+        RELAY_MESSAGE_TYPES_V11.runtimeResponse,
+        RELAY_MESSAGE_TYPES_V11.runtimeEvent,
+        RELAY_MESSAGE_TYPES_V11.runtimeGap,
+        RELAY_MESSAGE_TYPES_V11.interactionRequest,
+        RELAY_MESSAGE_TYPES_V11.interactionResolved,
+        RELAY_MESSAGE_TYPES_V11.interactionCancelled,
+    ],
+    [RELAY_WSS_DIRECTIONS.peerToRelay]: [
+        RELAY_MESSAGE_TYPES_V11.runtimeRequest,
+        RELAY_MESSAGE_TYPES_V11.runtimeAck,
+    ],
+};
+/**
+ * P0 Companion WebSocket direction contract. A Cloud Relay must additionally require
+ * `device.connect` as the Companion connection's first frame.
+ */
+export const RELAY_COMPANION_WSS_MESSAGE_TYPES_BY_DIRECTION = {
+    [RELAY_WSS_DIRECTIONS.relayToPeer]: [
+        RELAY_MESSAGE_TYPES_V11.runtimeRequest,
+        RELAY_MESSAGE_TYPES_V11.runtimeAck,
+    ],
+    [RELAY_WSS_DIRECTIONS.peerToRelay]: [
+        RELAY_MESSAGE_TYPES_V11.deviceConnect,
+        RELAY_MESSAGE_TYPES_V11.runtimeResponse,
+        RELAY_MESSAGE_TYPES_V11.runtimeEvent,
+        RELAY_MESSAGE_TYPES_V11.runtimeGap,
+        RELAY_MESSAGE_TYPES_V11.interactionRequest,
+        RELAY_MESSAGE_TYPES_V11.interactionResolved,
+        RELAY_MESSAGE_TYPES_V11.interactionCancelled,
+    ],
+};
+function includesMessageType(allowedByDirection, direction, messageType) {
+    return allowedByDirection[direction].includes(messageType);
+}
+export function isRelayBrowserWssMessageTypeAllowed(direction, messageType) {
+    return includesMessageType(RELAY_BROWSER_WSS_MESSAGE_TYPES_BY_DIRECTION, direction, messageType);
+}
+export function isRelayCompanionWssMessageTypeAllowed(direction, messageType) {
+    return includesMessageType(RELAY_COMPANION_WSS_MESSAGE_TYPES_BY_DIRECTION, direction, messageType);
+}

package/dist/index.d.ts

@@ -182,6 +182,35 @@ export declare const RELAY_ERROR_RETRYABILITY: {
     readonly COMPANION_ERROR: false;
 };
 export declare function getRelayErrorRetryability(code: RelayErrorCode): boolean;
+/** Wire 1.1 adds Host-level request authorization without mutating frozen Wire 1.0 exports. */
+export declare const RELAY_ERROR_CODES_V11: {
+    readonly remoteRequestDenied: "REMOTE_REQUEST_DENIED";
+    readonly protocolVersionUnsupported: "RELAY_PROTOCOL_VERSION_UNSUPPORTED";
+    readonly invalidFrame: "RELAY_INVALID_FRAME";
+    readonly invalidParams: "INVALID_PARAMS";
+    readonly requestIdConflict: "RELAY_REQUEST_ID_CONFLICT";
+    readonly workspaceNotFound: "WORKSPACE_NOT_FOUND";
+    readonly encryptionRequired: "RELAY_ENCRYPTION_REQUIRED";
+    readonly encryptedPayloadInvalid: "ENCRYPTED_PAYLOAD_INVALID";
+    readonly localApprovalDenied: "LocalApprovalDeniedError";
+    readonly localConfirmationRequired: "LocalConfirmationRequiredError";
+    readonly companionError: "COMPANION_ERROR";
+};
+export type RelayErrorCodeV11 = (typeof RELAY_ERROR_CODES_V11)[keyof typeof RELAY_ERROR_CODES_V11];
+export declare const RELAY_ERROR_RETRYABILITY_V11: {
+    readonly REMOTE_REQUEST_DENIED: false;
+    readonly RELAY_PROTOCOL_VERSION_UNSUPPORTED: false;
+    readonly RELAY_INVALID_FRAME: false;
+    readonly INVALID_PARAMS: false;
+    readonly RELAY_REQUEST_ID_CONFLICT: false;
+    readonly WORKSPACE_NOT_FOUND: false;
+    readonly RELAY_ENCRYPTION_REQUIRED: false;
+    readonly ENCRYPTED_PAYLOAD_INVALID: false;
+    readonly LocalApprovalDeniedError: false;
+    readonly LocalConfirmationRequiredError: false;
+    readonly COMPANION_ERROR: false;
+};
+export declare function getRelayErrorRetryabilityV11(code: RelayErrorCodeV11): boolean;
 export declare const relayProtocolVersionSchema: z.ZodEnum<{
     1.1: "1.1";
     "1.0": "1.0";
@@ -4704,6 +4733,7 @@ export type RelayTimelineEventV11 = z.output<typeof relayTimelineEventSchemaV11>
 export type RelayRuntimeEventEnvelopeV11 = z.output<typeof relayRuntimeEventEnvelopeSchemaV11>;
 export type RelayMessageV10 = z.output<typeof relayMessageSchemaV10>;
 export type RelayMessageV11 = z.output<typeof relayMessageSchemaV11>;
+export type RelayRequestMethodV11 = RelayRequestMethodForVersion<"1.1">;
 export type RelayRuntimeRequestV10 = z.output<typeof relayRuntimeRequestSchemaV10>;
 export type RelayRuntimeRequestV11 = z.output<typeof relayRuntimeRequestSchemaV11>;
 export type RelayRuntimeEventV10 = z.output<typeof relayRuntimeEventSchemaV10>;

package/dist/index.js

@@ -197,6 +197,18 @@ export const RELAY_ERROR_RETRYABILITY = {
 export function getRelayErrorRetryability(code) {
     return RELAY_ERROR_RETRYABILITY[code];
 }
+/** Wire 1.1 adds Host-level request authorization without mutating frozen Wire 1.0 exports. */
+export const RELAY_ERROR_CODES_V11 = {
+    ...RELAY_ERROR_CODES,
+    remoteRequestDenied: "REMOTE_REQUEST_DENIED",
+};
+export const RELAY_ERROR_RETRYABILITY_V11 = {
+    ...RELAY_ERROR_RETRYABILITY,
+    [RELAY_ERROR_CODES_V11.remoteRequestDenied]: false,
+};
+export function getRelayErrorRetryabilityV11(code) {
+    return RELAY_ERROR_RETRYABILITY_V11[code];
+}
 export const relayProtocolVersionSchema = z.enum(SUPPORTED_RELAY_PROTOCOL_VERSIONS);
 export const deviceIdSchema = z.string().uuid().brand();
 export const workspaceIdSchema = z.string().uuid().brand();

package/dist/schema/roll-relay-browser-session-v1.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "readOnly": true,
+  "type": "object",
+  "properties": {
+    "connectUrl": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^wss:\\/\\/\\S+$"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"
+    }
+  },
+  "required": ["connectUrl", "expiresAt"],
+  "additionalProperties": false,
+  "$id": "urn:roll-agent:schema:relay-browser-session:1.0",
+  "title": "Roll Relay Browser Session Descriptor v1.0",
+  "description": "Short-lived single-use Browser WebSocket connection descriptor.",
+  "x-roll-control-version": "1.0"
+}

package/dist/schema/roll-relay-control-v1.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "anyOf": [
+    {
+      "readOnly": true,
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "session.ready"
+        },
+        "controlVersion": {
+          "type": "string",
+          "const": "1.0"
+        },
+        "relayProtocolVersion": {
+          "type": "string",
+          "const": "1.1"
+        },
+        "sessionId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "workspaceId": {
+          "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)$"
+        },
+        "workspaceStatus": {
+          "type": "string",
+          "enum": ["online", "offline"]
+        }
+      },
+      "required": [
+        "type",
+        "controlVersion",
+        "relayProtocolVersion",
+        "sessionId",
+        "workspaceId",
+        "workspaceStatus"
+      ],
+      "additionalProperties": false
+    },
+    {
+      "readOnly": true,
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "workspace.status"
+        },
+        "workspaceId": {
+          "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)$"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["online", "offline"]
+        }
+      },
+      "required": ["type", "workspaceId", "status"],
+      "additionalProperties": false
+    },
+    {
+      "readOnly": true,
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "session.error"
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "WORKSPACE_NOT_FOUND",
+            "WORKSPACE_OFFLINE",
+            "CONTROLLER_CONFLICT",
+            "RELAY_PROTOCOL_VERSION_UNSUPPORTED",
+            "RATE_LIMITED",
+            "RELAY_INTERNAL_ERROR"
+          ]
+        },
+        "retryable": {
+          "type": "boolean"
+        }
+      },
+      "required": ["type", "code", "retryable"],
+      "additionalProperties": false
+    }
+  ],
+  "$id": "urn:roll-agent:schema:relay-control:1.0",
+  "title": "Roll Relay Browser Control v1.0",
+  "description": "Relay-to-Browser session and workspace control messages.",
+  "x-roll-control-version": "1.0",
+  "x-roll-browser-first-message-type": "session.ready",
+  "x-roll-browser-message-types-by-direction": {
+    "relay-to-peer": [
+      "session.ready",
+      "workspace.status",
+      "session.error",
+      "runtime.response",
+      "runtime.event",
+      "runtime.gap",
+      "interaction.request",
+      "interaction.resolved",
+      "interaction.cancelled"
+    ],
+    "peer-to-relay": ["runtime.request", "runtime.ack"]
+  },
+  "x-roll-companion-message-types-by-direction": {
+    "relay-to-peer": ["runtime.request", "runtime.ack"],
+    "peer-to-relay": [
+      "device.connect",
+      "runtime.response",
+      "runtime.event",
+      "runtime.gap",
+      "interaction.request",
+      "interaction.resolved",
+      "interaction.cancelled"
+    ]
+  },
+  "x-roll-wss-directions": {
+    "relayToPeer": "relay-to-peer",
+    "peerToRelay": "peer-to-relay"
+  }
+}

package/dist/schema/roll-relay-protocol-v1.1.schema.json

@@ -1108,7 +1108,7 @@
     }
   ],
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://roll-agent.dev/schemas/relay-protocol/1.1",
+  "$id": "urn:roll-agent:schema:relay-protocol:1.1",
   "title": "Roll Relay Protocol v1.1",
   "description": "Versioned Companion Relay frames shared by Browser, Cloud Relay and Companion.",
   "$defs": {

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

@@ -718,7 +718,7 @@
     }
   ],
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://roll-agent.dev/schemas/relay-protocol/1.0",
+  "$id": "urn:roll-agent:schema:relay-protocol:1.0",
   "title": "Roll Relay Protocol v1.0",
   "description": "Versioned Companion Relay frames shared by Browser, Cloud Relay and Companion.",
   "$defs": {

package/fixtures/control/v1.0/invalid-browser-session-trailing-whitespace.json

@@ -0,0 +1,4 @@
+{
+  "connectUrl": "wss://relay.example.test/v1/browser?ticket=single-use ",
+  "expiresAt": "2026-08-06T12:00:00.000Z"
+}

package/fixtures/control/v1.0/invalid-browser-session-uppercase-scheme.json

@@ -0,0 +1,4 @@
+{
+  "connectUrl": "WSS://relay.example.test/v1/browser?ticket=single-use",
+  "expiresAt": "2026-08-06T12:00:00.000Z"
+}

package/fixtures/control/v1.0/invalid-browser-session-url.json

@@ -0,0 +1,4 @@
+{
+  "connectUrl": "wss://not a valid url",
+  "expiresAt": "2026-08-06T12:00:00.000Z"
+}

package/fixtures/control/v1.0/invalid-browser-session-ws.json

@@ -0,0 +1,4 @@
+{
+  "connectUrl": "ws://relay.example.test/v1/browser?ticket=single-use",
+  "expiresAt": "2026-08-06T12:00:00.000Z"
+}

package/fixtures/control/v1.0/invalid-control-extra-field.json

@@ -0,0 +1,6 @@
+{
+  "type": "workspace.status",
+  "workspaceId": "00000000-0000-4000-8000-000000000302",
+  "status": "online",
+  "deviceId": "00000000-0000-4000-8000-000000000303"
+}

package/fixtures/control/v1.0/invalid-session-ready-wire-version.json

@@ -0,0 +1,8 @@
+{
+  "type": "session.ready",
+  "controlVersion": "1.0",
+  "relayProtocolVersion": "1.0",
+  "sessionId": "browser-session-301",
+  "workspaceId": "00000000-0000-4000-8000-000000000302",
+  "workspaceStatus": "online"
+}

package/fixtures/control/v1.0/manifest.json

@@ -0,0 +1,52 @@
+{
+  "controlVersion": "1.0",
+  "messages": [
+    {
+      "fixture": "valid-session-ready.json",
+      "valid": true,
+      "validFirstFrame": true
+    },
+    {
+      "fixture": "valid-workspace-status.json",
+      "valid": true,
+      "validFirstFrame": false
+    },
+    {
+      "fixture": "valid-session-error.json",
+      "valid": true,
+      "validFirstFrame": false
+    },
+    {
+      "fixture": "invalid-session-ready-wire-version.json",
+      "valid": false,
+      "validFirstFrame": false
+    },
+    {
+      "fixture": "invalid-control-extra-field.json",
+      "valid": false,
+      "validFirstFrame": false
+    }
+  ],
+  "sessions": [
+    {
+      "fixture": "valid-browser-session.json",
+      "valid": true
+    },
+    {
+      "fixture": "invalid-browser-session-ws.json",
+      "valid": false
+    },
+    {
+      "fixture": "invalid-browser-session-url.json",
+      "valid": false
+    },
+    {
+      "fixture": "invalid-browser-session-uppercase-scheme.json",
+      "valid": false
+    },
+    {
+      "fixture": "invalid-browser-session-trailing-whitespace.json",
+      "valid": false
+    }
+  ]
+}

package/fixtures/control/v1.0/valid-browser-session.json

@@ -0,0 +1,4 @@
+{
+  "connectUrl": "wss://relay.example.test/v1/browser?ticket=single-use",
+  "expiresAt": "2026-08-06T12:00:00.000Z"
+}

package/fixtures/control/v1.0/valid-session-error.json

@@ -0,0 +1,5 @@
+{
+  "type": "session.error",
+  "code": "CONTROLLER_CONFLICT",
+  "retryable": false
+}

package/fixtures/control/v1.0/valid-session-ready.json

@@ -0,0 +1,8 @@
+{
+  "type": "session.ready",
+  "controlVersion": "1.0",
+  "relayProtocolVersion": "1.1",
+  "sessionId": "browser-session-301",
+  "workspaceId": "00000000-0000-4000-8000-000000000302",
+  "workspaceStatus": "online"
+}

package/fixtures/control/v1.0/valid-workspace-status.json

@@ -0,0 +1,5 @@
+{
+  "type": "workspace.status",
+  "workspaceId": "00000000-0000-4000-8000-000000000302",
+  "status": "offline"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/relay-protocol",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -23,6 +23,13 @@
       "types": "./dist/reference-adapter.d.ts",
       "default": "./dist/reference-adapter.js"
     },
+    "./control": {
+      "types": "./dist/control.d.ts",
+      "default": "./dist/control.js"
+    },
+    "./control/schema": "./dist/schema/roll-relay-control-v1.schema.json",
+    "./control/session-schema": "./dist/schema/roll-relay-browser-session-v1.schema.json",
+    "./control/fixtures/*": "./fixtures/control/v1.0/*",
     "./schema": "./dist/schema/roll-relay-protocol-v1.schema.json",
     "./schema/v1.0": "./dist/schema/roll-relay-protocol-v1.schema.json",
     "./schema/v1.1": "./dist/schema/roll-relay-protocol-v1.1.schema.json",
@@ -40,7 +47,7 @@
   },
   "dependencies": {
     "zod": "3.25.76",
-    "@roll-agent/protocol": "0.4.0"
+    "@roll-agent/protocol": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -49,7 +56,7 @@
     "prettier": "3.8.1"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && node --experimental-strip-types scripts/generate-schema.mjs",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node --experimental-strip-types scripts/generate-schema.mjs && node --experimental-strip-types scripts/generate-control-schema.mjs",
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
     "clean": "rm -rf dist"