@roll-agent/relay-protocol 0.0.0

package/dist/index.js

@@ -0,0 +1,343 @@
+import { approvalIdSchema, jsonValueSchema, runtimeEventEnvelopeSchema, runtimeMethodSchemas, threadIdSchema, turnIdSchema, } from "@roll-agent/protocol";
+import { z } from "zod/v4";
+export const SUPPORTED_RELAY_PROTOCOL_VERSIONS = ["1.0"];
+export const RELAY_PROTOCOL_VERSION = SUPPORTED_RELAY_PROTOCOL_VERSIONS[0];
+/** @deprecated Use `RELAY_PROTOCOL_VERSION`. */
+export const COMPANION_RELAY_PROTOCOL_VERSION = RELAY_PROTOCOL_VERSION;
+export const RELAY_MESSAGE_TYPES = {
+    deviceConnect: "device.connect",
+    runtimeRequest: "runtime.request",
+    runtimeResponse: "runtime.response",
+    runtimeEvent: "runtime.event",
+    runtimeAck: "runtime.ack",
+    runtimeGap: "runtime.gap",
+    runtimeEncrypted: "runtime.encrypted",
+};
+export const RELAY_MESSAGE_TYPE_VALUES = [
+    RELAY_MESSAGE_TYPES.deviceConnect,
+    RELAY_MESSAGE_TYPES.runtimeRequest,
+    RELAY_MESSAGE_TYPES.runtimeResponse,
+    RELAY_MESSAGE_TYPES.runtimeEvent,
+    RELAY_MESSAGE_TYPES.runtimeAck,
+    RELAY_MESSAGE_TYPES.runtimeGap,
+    RELAY_MESSAGE_TYPES.runtimeEncrypted,
+];
+/**
+ * Relay Wire 1.0 is intentionally independent from the latest Runtime registry.
+ * New Runtime methods never become remotely callable without a Relay version change.
+ */
+export const RELAY_REQUEST_METHODS = {
+    initialize: "initialize",
+    threadList: "thread.list",
+    threadCreate: "thread.create",
+    threadOpen: "thread.open",
+    threadSnapshot: "thread.snapshot",
+    threadRename: "thread.rename",
+    threadDelete: "thread.delete",
+    threadDetach: "thread.detach",
+    threadCapabilities: "thread.capabilities",
+    turnStart: "turn.start",
+    turnCancel: "turn.cancel",
+    approvalRespond: "approval.respond",
+    operationGet: "operation.get",
+    approvalCandidate: "approval.candidate",
+};
+export const RELAY_REQUEST_METHOD_VALUES = [
+    RELAY_REQUEST_METHODS.initialize,
+    RELAY_REQUEST_METHODS.threadList,
+    RELAY_REQUEST_METHODS.threadCreate,
+    RELAY_REQUEST_METHODS.threadOpen,
+    RELAY_REQUEST_METHODS.threadSnapshot,
+    RELAY_REQUEST_METHODS.threadRename,
+    RELAY_REQUEST_METHODS.threadDelete,
+    RELAY_REQUEST_METHODS.threadDetach,
+    RELAY_REQUEST_METHODS.threadCapabilities,
+    RELAY_REQUEST_METHODS.turnStart,
+    RELAY_REQUEST_METHODS.turnCancel,
+    RELAY_REQUEST_METHODS.approvalRespond,
+    RELAY_REQUEST_METHODS.operationGet,
+    RELAY_REQUEST_METHODS.approvalCandidate,
+];
+export const RELAY_REQUEST_METHOD_DISPOSITIONS = {
+    [RELAY_REQUEST_METHODS.initialize]: "local-only",
+    [RELAY_REQUEST_METHODS.threadList]: "query",
+    [RELAY_REQUEST_METHODS.threadCreate]: "mutation",
+    [RELAY_REQUEST_METHODS.threadOpen]: "query",
+    [RELAY_REQUEST_METHODS.threadSnapshot]: "query",
+    [RELAY_REQUEST_METHODS.threadRename]: "mutation",
+    [RELAY_REQUEST_METHODS.threadDelete]: "mutation",
+    [RELAY_REQUEST_METHODS.threadDetach]: "mutation",
+    [RELAY_REQUEST_METHODS.threadCapabilities]: "query",
+    [RELAY_REQUEST_METHODS.turnStart]: "mutation",
+    [RELAY_REQUEST_METHODS.turnCancel]: "mutation",
+    [RELAY_REQUEST_METHODS.approvalRespond]: "mutation",
+    [RELAY_REQUEST_METHODS.operationGet]: "query",
+    [RELAY_REQUEST_METHODS.approvalCandidate]: "mutation",
+};
+export const RELAY_MUTATION_REQUEST_METHODS = [
+    RELAY_REQUEST_METHODS.threadCreate,
+    RELAY_REQUEST_METHODS.threadRename,
+    RELAY_REQUEST_METHODS.threadDelete,
+    RELAY_REQUEST_METHODS.threadDetach,
+    RELAY_REQUEST_METHODS.turnStart,
+    RELAY_REQUEST_METHODS.turnCancel,
+    RELAY_REQUEST_METHODS.approvalRespond,
+    RELAY_REQUEST_METHODS.approvalCandidate,
+];
+export const RELAY_LOCAL_ONLY_REQUEST_METHODS = [
+    RELAY_REQUEST_METHODS.initialize,
+];
+export const RELAY_ERROR_CODES = {
+    protocolVersionUnsupported: "RELAY_PROTOCOL_VERSION_UNSUPPORTED",
+    invalidFrame: "RELAY_INVALID_FRAME",
+    invalidParams: "INVALID_PARAMS",
+    requestIdConflict: "RELAY_REQUEST_ID_CONFLICT",
+    workspaceNotFound: "WORKSPACE_NOT_FOUND",
+    encryptionRequired: "RELAY_ENCRYPTION_REQUIRED",
+    encryptedPayloadInvalid: "ENCRYPTED_PAYLOAD_INVALID",
+    localApprovalDenied: "LocalApprovalDeniedError",
+    localConfirmationRequired: "LocalConfirmationRequiredError",
+    companionError: "COMPANION_ERROR",
+};
+export const RELAY_ERROR_RETRYABILITY = {
+    [RELAY_ERROR_CODES.protocolVersionUnsupported]: false,
+    [RELAY_ERROR_CODES.invalidFrame]: false,
+    [RELAY_ERROR_CODES.invalidParams]: false,
+    [RELAY_ERROR_CODES.requestIdConflict]: false,
+    [RELAY_ERROR_CODES.workspaceNotFound]: false,
+    [RELAY_ERROR_CODES.encryptionRequired]: false,
+    [RELAY_ERROR_CODES.encryptedPayloadInvalid]: false,
+    [RELAY_ERROR_CODES.localApprovalDenied]: false,
+    [RELAY_ERROR_CODES.localConfirmationRequired]: false,
+    [RELAY_ERROR_CODES.companionError]: false,
+};
+export function getRelayErrorRetryability(code) {
+    return RELAY_ERROR_RETRYABILITY[code];
+}
+export const relayProtocolVersionSchema = z.enum(SUPPORTED_RELAY_PROTOCOL_VERSIONS);
+export const deviceIdSchema = z.string().uuid().brand();
+export const workspaceIdSchema = z.string().uuid().brand();
+export const relayRequestIdSchema = z.string().uuid().brand();
+export const relayEnvelopeIdSchema = z.string().uuid();
+export const relayApprovalCandidateParamsSchema = z
+    .object({
+    threadId: threadIdSchema,
+    turnId: turnIdSchema,
+    approvalId: approvalIdSchema,
+    decision: z.enum(["approve", "reject"]),
+    reason: z.string().min(1).optional(),
+})
+    .strict()
+    .readonly();
+export const relayApprovalCandidateResultSchema = z
+    .object({
+    accepted: z.literal(true),
+})
+    .strict()
+    .readonly();
+export const relayRequestMethodSchemas = {
+    [RELAY_REQUEST_METHODS.initialize]: runtimeMethodSchemas["initialize"],
+    [RELAY_REQUEST_METHODS.threadList]: runtimeMethodSchemas["thread.list"],
+    [RELAY_REQUEST_METHODS.threadCreate]: runtimeMethodSchemas["thread.create"],
+    [RELAY_REQUEST_METHODS.threadOpen]: runtimeMethodSchemas["thread.open"],
+    [RELAY_REQUEST_METHODS.threadSnapshot]: runtimeMethodSchemas["thread.snapshot"],
+    [RELAY_REQUEST_METHODS.threadRename]: runtimeMethodSchemas["thread.rename"],
+    [RELAY_REQUEST_METHODS.threadDelete]: runtimeMethodSchemas["thread.delete"],
+    [RELAY_REQUEST_METHODS.threadDetach]: runtimeMethodSchemas["thread.detach"],
+    [RELAY_REQUEST_METHODS.threadCapabilities]: runtimeMethodSchemas["thread.capabilities"],
+    [RELAY_REQUEST_METHODS.turnStart]: runtimeMethodSchemas["turn.start"],
+    [RELAY_REQUEST_METHODS.turnCancel]: runtimeMethodSchemas["turn.cancel"],
+    [RELAY_REQUEST_METHODS.approvalRespond]: runtimeMethodSchemas["approval.respond"],
+    [RELAY_REQUEST_METHODS.operationGet]: runtimeMethodSchemas["operation.get"],
+    [RELAY_REQUEST_METHODS.approvalCandidate]: {
+        params: relayApprovalCandidateParamsSchema,
+        result: relayApprovalCandidateResultSchema,
+    },
+};
+export function isRelayRequestMethod(value) {
+    return Object.hasOwn(relayRequestMethodSchemas, value);
+}
+export function getRelayRequestMethodDisposition(value) {
+    return isRelayRequestMethod(value) ? RELAY_REQUEST_METHOD_DISPOSITIONS[value] : undefined;
+}
+export function isRelayMutationRequestMethod(method) {
+    return RELAY_REQUEST_METHOD_DISPOSITIONS[method] === "mutation";
+}
+export function parseRelayRequestParams(method, value) {
+    return relayRequestMethodSchemas[method].params.parse(value);
+}
+export function parseRelayRequestResult(method, value) {
+    return relayRequestMethodSchemas[method].result.parse(value);
+}
+export const relayDeviceConnectSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.deviceConnect),
+    protocolVersion: z.literal(RELAY_PROTOCOL_VERSION),
+    deviceId: deviceIdSchema,
+    pairingToken: z.string().min(16),
+})
+    .strict()
+    .readonly();
+export const relayRuntimeRequestSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.runtimeRequest),
+    requestId: relayRequestIdSchema,
+    workspaceId: workspaceIdSchema,
+    method: z.enum(RELAY_REQUEST_METHOD_VALUES),
+    params: jsonValueSchema,
+})
+    .strict()
+    .readonly();
+export const relayErrorSchema = z
+    .object({
+    code: z.string().min(1),
+    message: z.string(),
+    retryable: z.boolean(),
+})
+    .strict()
+    .readonly();
+/**
+ * This preserves the pre-freeze v1.0 shape: result/error are independently optional.
+ * A strict exactly-one response belongs in a later Relay Wire version.
+ */
+export const relayRuntimeResponseSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.runtimeResponse),
+    requestId: relayRequestIdSchema,
+    workspaceId: workspaceIdSchema,
+    result: jsonValueSchema.optional(),
+    error: relayErrorSchema.optional(),
+})
+    .strict()
+    .readonly();
+export const relayRuntimeEventSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.runtimeEvent),
+    workspaceId: workspaceIdSchema,
+    relaySequence: z.number().int().nonnegative(),
+    event: runtimeEventEnvelopeSchema,
+})
+    .strict()
+    .readonly();
+export const relayAckSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.runtimeAck),
+    workspaceId: workspaceIdSchema,
+    throughRelaySequence: z.number().int().min(-1),
+})
+    .strict()
+    .readonly();
+export const relayGapSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.runtimeGap),
+    workspaceId: workspaceIdSchema,
+    fromRelaySequence: z.number().int().nonnegative(),
+    throughRelaySequence: z.number().int().nonnegative(),
+    recovery: z.literal("thread.snapshot"),
+})
+    .strict()
+    .readonly();
+/**
+ * This preserves the pre-freeze v1.0 metadata shape. Payload-kind-specific required
+ * fields must be introduced under a later Relay Wire version.
+ */
+export const relayEncryptedMessageSchema = z
+    .object({
+    type: z.literal(RELAY_MESSAGE_TYPES.runtimeEncrypted),
+    workspaceId: workspaceIdSchema,
+    envelopeId: relayEnvelopeIdSchema,
+    payloadKind: z.enum(["request", "response", "event"]),
+    requestId: relayRequestIdSchema.optional(),
+    relaySequence: z.number().int().nonnegative().optional(),
+    algorithm: z.string().min(1),
+    nonce: z.string().min(1),
+    ciphertext: z.string().min(1),
+})
+    .strict()
+    .readonly();
+export const relayMessageSchemas = {
+    [RELAY_MESSAGE_TYPES.deviceConnect]: relayDeviceConnectSchema,
+    [RELAY_MESSAGE_TYPES.runtimeRequest]: relayRuntimeRequestSchema,
+    [RELAY_MESSAGE_TYPES.runtimeResponse]: relayRuntimeResponseSchema,
+    [RELAY_MESSAGE_TYPES.runtimeEvent]: relayRuntimeEventSchema,
+    [RELAY_MESSAGE_TYPES.runtimeAck]: relayAckSchema,
+    [RELAY_MESSAGE_TYPES.runtimeGap]: relayGapSchema,
+    [RELAY_MESSAGE_TYPES.runtimeEncrypted]: relayEncryptedMessageSchema,
+};
+export const relayMessageSchema = z.discriminatedUnion("type", [
+    relayDeviceConnectSchema,
+    relayRuntimeRequestSchema,
+    relayRuntimeResponseSchema,
+    relayRuntimeEventSchema,
+    relayAckSchema,
+    relayGapSchema,
+    relayEncryptedMessageSchema,
+]);
+export const RELAY_PROTOCOL_REGISTRY = {
+    "1.0": {
+        messageTypes: RELAY_MESSAGE_TYPE_VALUES,
+        requestMethods: RELAY_REQUEST_METHOD_VALUES,
+        mutationMethods: RELAY_MUTATION_REQUEST_METHODS,
+        localOnlyMethods: RELAY_LOCAL_ONLY_REQUEST_METHODS,
+    },
+};
+export function getRelayProtocolRegistry(version) {
+    return RELAY_PROTOCOL_REGISTRY[version];
+}
+export function negotiateRelayProtocolVersion(peerVersions) {
+    return SUPPORTED_RELAY_PROTOCOL_VERSIONS.find((version) => peerVersions.includes(version));
+}
+export function canonicalizeRelayJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalizeRelayJson(entry)).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalizeRelayJson(entry)}`)
+            .join(",")}}`;
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined) {
+        throw new Error("Relay canonical JSON received a non-JSON value");
+    }
+    return encoded;
+}
+export const RELAY_REQUEST_REPLAY_DISPOSITIONS = {
+    new: "new",
+    replay: "replay",
+    conflict: "conflict",
+};
+export function classifyRelayRequestReplay(existing, candidate) {
+    if (existing.workspaceId !== candidate.workspaceId ||
+        existing.requestId !== candidate.requestId) {
+        return { disposition: RELAY_REQUEST_REPLAY_DISPOSITIONS.new };
+    }
+    const existingIdentity = {
+        method: existing.method,
+        params: existing.params,
+    };
+    const candidateIdentity = {
+        method: candidate.method,
+        params: candidate.params,
+    };
+    if (canonicalizeRelayJson(existingIdentity) === canonicalizeRelayJson(candidateIdentity)) {
+        return { disposition: RELAY_REQUEST_REPLAY_DISPOSITIONS.replay };
+    }
+    return {
+        disposition: RELAY_REQUEST_REPLAY_DISPOSITIONS.conflict,
+        errorCode: RELAY_ERROR_CODES.requestIdConflict,
+    };
+}
+export function classifyRelayAck(state) {
+    if (!Number.isInteger(state.acknowledgedThrough) ||
+        !Number.isInteger(state.advertisedThrough) ||
+        !Number.isInteger(state.incomingThrough) ||
+        state.acknowledgedThrough < -1 ||
+        state.advertisedThrough < -1 ||
+        state.incomingThrough < -1 ||
+        state.incomingThrough > state.advertisedThrough) {
+        return "invalid";
+    }
+    return state.incomingThrough > state.acknowledgedThrough ? "advance" : "duplicate";
+}