@roll-agent/relay-protocol 0.1.1 → 0.3.0

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);
+}