@roll-agent/relay-protocol 0.1.1 → 0.3.0

package/dist/reference-adapter.d.ts

@@ -0,0 +1,56 @@
+import { type InteractionId, type RelayInteractionCancelledV11, type RelayInteractionRequestV11, type RelayInteractionResolvedV11, type RelayRequestId, type RelayRuntimeRequestV11, type WorkspaceId } from "./index.ts";
+export declare const RELAY_REFERENCE_ADAPTER_ERROR_CODES: {
+    readonly protocolVersionUnsupported: "RELAY_REFERENCE_PROTOCOL_VERSION_UNSUPPORTED";
+    readonly invalidFrame: "RELAY_REFERENCE_INVALID_FRAME";
+    readonly interactionConflict: "RELAY_REFERENCE_INTERACTION_CONFLICT";
+    readonly interactionNotPending: "RELAY_REFERENCE_INTERACTION_NOT_PENDING";
+    readonly interactionTerminated: "RELAY_REFERENCE_INTERACTION_TERMINATED";
+    readonly interactionIdentityMismatch: "RELAY_REFERENCE_INTERACTION_IDENTITY_MISMATCH";
+    readonly candidateMethodMismatch: "RELAY_REFERENCE_CANDIDATE_METHOD_MISMATCH";
+    readonly requestIdUnavailable: "RELAY_REFERENCE_REQUEST_ID_UNAVAILABLE";
+};
+export type RelayReferenceAdapterErrorCode = (typeof RELAY_REFERENCE_ADAPTER_ERROR_CODES)[keyof typeof RELAY_REFERENCE_ADAPTER_ERROR_CODES];
+export declare class RelayReferenceAdapterError extends Error {
+    readonly code: RelayReferenceAdapterErrorCode;
+    constructor(code: RelayReferenceAdapterErrorCode, message: string);
+}
+export interface RelayBrowserReferenceAdapterOptions {
+    /** Wire version is explicit so a legacy 1.0 connection cannot opt in accidentally. */
+    readonly protocolVersion: "1.1";
+    /** The embedding host owns Relay request ID allocation. */
+    readonly createRequestId?: () => RelayRequestId;
+}
+export type RelayInteractionMethodV11 = RelayInteractionRequestV11["method"];
+export interface RelayInteractionCandidateInputV11 {
+    readonly workspaceId: WorkspaceId;
+    readonly interactionId: InteractionId;
+    readonly method: RelayInteractionMethodV11;
+    readonly candidate: unknown;
+}
+export type RelayReferenceAdapterReceiveResultV11 = {
+    readonly status: "pending" | "duplicate";
+    readonly request: RelayInteractionRequestV11;
+} | {
+    readonly status: "resolved";
+    readonly request: RelayInteractionRequestV11;
+    readonly frame: RelayInteractionResolvedV11;
+} | {
+    readonly status: "cancelled";
+    readonly request: RelayInteractionRequestV11;
+    readonly frame: RelayInteractionCancelledV11;
+};
+/**
+ * Browser-safe, in-memory correlation for Relay Wire 1.1 interaction frames.
+ * Authentication, responder policy, delivery retries, and persistence remain host responsibilities.
+ */
+export declare class RelayBrowserReferenceAdapter {
+    private readonly createRequestId;
+    private readonly pending;
+    private readonly terminated;
+    constructor(options: RelayBrowserReferenceAdapterOptions);
+    receive(value: unknown): RelayReferenceAdapterReceiveResultV11;
+    createCandidate(input: RelayInteractionCandidateInputV11): RelayRuntimeRequestV11;
+    getPending(workspaceId: WorkspaceId, interactionId: InteractionId): RelayInteractionRequestV11 | undefined;
+    listPending(): readonly RelayInteractionRequestV11[];
+}
+export declare function createRelayBrowserReferenceAdapter(options: RelayBrowserReferenceAdapterOptions): RelayBrowserReferenceAdapter;

package/dist/reference-adapter.js

@@ -0,0 +1,122 @@
+import { RELAY_REQUEST_METHODS_V11, relayInteractionCancelledSchemaV11, relayInteractionCandidateParamsSchemaV11, relayInteractionRequestSchemaV11, relayInteractionResolvedSchemaV11, relayRequestIdSchema, relayRuntimeRequestSchemaV11, parseRelayInteractionCandidateForRequestV11, } from "./index.js";
+export const RELAY_REFERENCE_ADAPTER_ERROR_CODES = {
+    protocolVersionUnsupported: "RELAY_REFERENCE_PROTOCOL_VERSION_UNSUPPORTED",
+    invalidFrame: "RELAY_REFERENCE_INVALID_FRAME",
+    interactionConflict: "RELAY_REFERENCE_INTERACTION_CONFLICT",
+    interactionNotPending: "RELAY_REFERENCE_INTERACTION_NOT_PENDING",
+    interactionTerminated: "RELAY_REFERENCE_INTERACTION_TERMINATED",
+    interactionIdentityMismatch: "RELAY_REFERENCE_INTERACTION_IDENTITY_MISMATCH",
+    candidateMethodMismatch: "RELAY_REFERENCE_CANDIDATE_METHOD_MISMATCH",
+    requestIdUnavailable: "RELAY_REFERENCE_REQUEST_ID_UNAVAILABLE",
+};
+export class RelayReferenceAdapterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "RelayReferenceAdapterError";
+        this.code = code;
+    }
+}
+function pendingKey(workspaceId, interactionId) {
+    return `${workspaceId}:${interactionId}`;
+}
+function hasSameInteractionIdentity(request, terminal) {
+    return (request.workspaceId === terminal.workspaceId &&
+        request.interactionId === terminal.interactionId &&
+        request.threadId === terminal.threadId &&
+        request.turnId === terminal.turnId &&
+        request.method === terminal.method);
+}
+function parseInteractionFrame(value) {
+    const request = relayInteractionRequestSchemaV11.safeParse(value);
+    if (request.success) {
+        return request.data;
+    }
+    const resolved = relayInteractionResolvedSchemaV11.safeParse(value);
+    if (resolved.success) {
+        return resolved.data;
+    }
+    const cancelled = relayInteractionCancelledSchemaV11.safeParse(value);
+    if (cancelled.success) {
+        return cancelled.data;
+    }
+    throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.invalidFrame, "Expected a Relay Wire 1.1 interaction request, resolved, or cancelled frame");
+}
+function createBrowserRequestId() {
+    if (typeof globalThis.crypto?.randomUUID !== "function") {
+        throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.requestIdUnavailable, "Relay candidate request IDs require crypto.randomUUID or an injected createRequestId");
+    }
+    return relayRequestIdSchema.parse(globalThis.crypto.randomUUID());
+}
+/**
+ * Browser-safe, in-memory correlation for Relay Wire 1.1 interaction frames.
+ * Authentication, responder policy, delivery retries, and persistence remain host responsibilities.
+ */
+export class RelayBrowserReferenceAdapter {
+    createRequestId;
+    pending = new Map();
+    terminated = new Set();
+    constructor(options) {
+        if (options.protocolVersion !== "1.1") {
+            throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.protocolVersionUnsupported, `Relay reference adapter requires Wire 1.1, received ${JSON.stringify(options.protocolVersion)}`);
+        }
+        this.createRequestId = options.createRequestId ?? createBrowserRequestId;
+    }
+    receive(value) {
+        const frame = parseInteractionFrame(value);
+        if (frame.type === "interaction.request") {
+            const key = pendingKey(frame.workspaceId, frame.interactionId);
+            if (this.terminated.has(key)) {
+                throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.interactionTerminated, `Interaction ${frame.interactionId} has already terminated in this workspace`);
+            }
+            const existing = this.pending.get(key);
+            if (existing === undefined) {
+                this.pending.set(key, frame);
+                return { status: "pending", request: frame };
+            }
+            if (JSON.stringify(existing) === JSON.stringify(frame)) {
+                return { status: "duplicate", request: existing };
+            }
+            throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.interactionConflict, `Interaction ${frame.interactionId} is already pending with different metadata`);
+        }
+        const key = pendingKey(frame.workspaceId, frame.interactionId);
+        const request = this.pending.get(key);
+        if (request === undefined) {
+            throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.interactionNotPending, `Interaction ${frame.interactionId} is not pending in this workspace`);
+        }
+        if (!hasSameInteractionIdentity(request, frame)) {
+            throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.interactionIdentityMismatch, `Interaction ${frame.interactionId} terminal frame does not match its pending request`);
+        }
+        this.pending.delete(key);
+        this.terminated.add(key);
+        return frame.type === "interaction.resolved"
+            ? { status: "resolved", request, frame }
+            : { status: "cancelled", request, frame };
+    }
+    createCandidate(input) {
+        const request = this.pending.get(pendingKey(input.workspaceId, input.interactionId));
+        if (request === undefined) {
+            throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.interactionNotPending, `Interaction ${input.interactionId} is not pending in this workspace`);
+        }
+        if (request.method !== input.method) {
+            throw new RelayReferenceAdapterError(RELAY_REFERENCE_ADAPTER_ERROR_CODES.candidateMethodMismatch, `Candidate method ${input.method} does not match pending method ${request.method}`);
+        }
+        const params = relayInteractionCandidateParamsSchemaV11.parse(parseRelayInteractionCandidateForRequestV11(request, input.candidate));
+        return relayRuntimeRequestSchemaV11.parse({
+            type: "runtime.request",
+            requestId: this.createRequestId(),
+            workspaceId: request.workspaceId,
+            method: RELAY_REQUEST_METHODS_V11.interactionCandidate,
+            params,
+        });
+    }
+    getPending(workspaceId, interactionId) {
+        return this.pending.get(pendingKey(workspaceId, interactionId));
+    }
+    listPending() {
+        return [...this.pending.values()];
+    }
+}
+export function createRelayBrowserReferenceAdapter(options) {
+    return new RelayBrowserReferenceAdapter(options);
+}

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"
+  }
+}