@roll-agent/companion 0.0.0

package/README.md

@@ -0,0 +1,59 @@
+# `@roll-agent/companion`
+
+连接云端 Web UI 与用户本机 Roll 的 Local Companion / Relay 基础库。
+
+本包提供 Relay 消息 Schema、Workspace 生命周期 lease、事件 ACK/gap 缓冲、mutation
+去重、出站重连和可插拔的 Workspace payload cipher。它不包含生产 Cloud Relay Server、
+Browser SDK、账号/设备存储、TLS、鉴权授权、本地确认 UI、HA 或监控。
+
+## 安装
+
+```bash
+pnpm add @roll-agent/companion @roll-agent/client-node
+```
+
+## 最小骨架
+
+```ts
+import { RollNodeClient } from "@roll-agent/client-node";
+import {
+  CompanionRelayBridge,
+  CompanionWorkspace,
+  OutboundCompanionRelay,
+  deviceIdSchema,
+  workspaceIdSchema,
+} from "@roll-agent/companion";
+
+const runtime = await RollNodeClient.start({ cwd: workspacePath });
+const workspaceId = workspaceIdSchema.parse(savedWorkspaceId);
+const workspace = new CompanionWorkspace({
+  client: runtime,
+  localApprovalPolicy: async () => "require-local-confirmation",
+});
+const bridge = new CompanionRelayBridge({
+  deviceId: deviceIdSchema.parse(savedDeviceId),
+  pairingToken,
+  workspaces: new Map([[workspaceId, workspace]]),
+});
+const outbound = new OutboundCompanionRelay({
+  bridge,
+  connectTransport: openAuthenticatedRelayTransport,
+});
+
+outbound.start();
+```
+
+Browser 与后台 Shell lease 由宿主显式接线；Turn 与 Approval lease 由
+`CompanionWorkspace` 自动维护。`require-local-confirmation` 只会以错误拒绝这次远程批准，
+不会自动显示本机确认 UI。
+
+为 Workspace 配置 `RelayPayloadCipher` 后，Runtime request、response 和 event 必须走
+`runtime.encrypted`。明文 request 不会进入 Runtime，而会收到加密的
+`RELAY_ENCRYPTION_REQUIRED`（`retryable: false`）响应；cipher、密钥管理和 Browser 端
+实现由宿主提供。
+
+## 文档
+
+- [Companion Relay v1 参考](https://github.com/steveoon/roll-agent/blob/main/docs/companion-relay-v1-reference.md)
+- [使用自己的技术栈接入 Roll](https://github.com/steveoon/roll-agent/blob/main/docs/how-to-build-roll-runtime-ui.md)
+- [Runtime Protocol 架构与安全边界](https://github.com/steveoon/roll-agent/blob/main/docs/runtime-protocol-architecture.md)

package/dist/companion-workspace.d.ts

@@ -0,0 +1,50 @@
+import { type PendingApproval, type RuntimeEventEnvelope, type RuntimeMethod, type RuntimeMethodInput, type RuntimeMethodResult } from "@roll-agent/protocol";
+import type { RollNodeClient } from "@roll-agent/client-node";
+import { CompanionEventBuffer, type CompanionEventBufferOptions, type EventBufferReplay } from "./event-buffer.ts";
+import { WorkspaceLeaseManager } from "./lease-manager.ts";
+import type { RelayRuntimeRequest } from "./relay-protocol.ts";
+export declare const LOCAL_APPROVAL_DECISIONS: readonly ["allow", "deny", "require-local-confirmation"];
+export type LocalApprovalDecision = (typeof LOCAL_APPROVAL_DECISIONS)[number];
+export type LocalApprovalPolicy = (approval: PendingApproval) => LocalApprovalDecision | Promise<LocalApprovalDecision>;
+export interface CompanionRuntimeClient {
+    request<TMethod extends RuntimeMethod>(method: TMethod, input: RuntimeMethodInput<TMethod>): Promise<RuntimeMethodResult<TMethod>>;
+    onEvent(listener: (event: RuntimeEventEnvelope) => void): () => void;
+    close(): void;
+    shutdown?(): Promise<unknown>;
+}
+export interface CompanionWorkspaceOptions extends CompanionEventBufferOptions {
+    readonly client: CompanionRuntimeClient;
+    readonly localApprovalPolicy: LocalApprovalPolicy;
+}
+export declare class LocalApprovalDeniedError extends Error {
+    constructor(message: string);
+}
+export declare class LocalConfirmationRequiredError extends Error {
+    constructor(message: string);
+}
+export declare class CompanionWorkspace {
+    readonly leases: WorkspaceLeaseManager;
+    readonly events: CompanionEventBuffer;
+    private readonly client;
+    private readonly localApprovalPolicy;
+    private readonly approvals;
+    private readonly eventListeners;
+    private readonly releaseClientSubscription;
+    constructor(options: CompanionWorkspaceOptions);
+    attachBrowser(clientId: string): () => void;
+    detachBrowser(clientId: string): boolean;
+    acquireBackgroundShellLease(sessionId: string): () => void;
+    onBufferedEvent(listener: (entry: {
+        readonly relaySequence: number;
+        readonly event: RuntimeEventEnvelope;
+    }) => void): () => void;
+    replay(afterRelaySequence?: number): EventBufferReplay;
+    acknowledge(throughRelaySequence: number): void;
+    startTurn(input: RuntimeMethodInput<"turn.start">): Promise<RuntimeMethodResult<"turn.start">>;
+    respondApproval(input: RuntimeMethodInput<"approval.respond">): Promise<RuntimeMethodResult<"approval.respond">>;
+    handleRemoteRequest(request: RelayRuntimeRequest): Promise<unknown>;
+    closeIfIdle(): Promise<boolean>;
+    private handleEvent;
+    private updateLeases;
+}
+export declare function isRollNodeClient(client: CompanionRuntimeClient): client is RollNodeClient;

package/dist/companion-workspace.js

@@ -0,0 +1 @@
+import{RUNTIME_METHODS as e,parseRuntimeMethodParams as t}from"@roll-agent/protocol";import{CompanionEventBuffer as r}from"./event-buffer.js";import{WorkspaceLeaseManager as a}from"./lease-manager.js";export const LOCAL_APPROVAL_DECISIONS=["allow","deny","require-local-confirmation"];export class LocalApprovalDeniedError extends Error{constructor(e){super(e),this.name="LocalApprovalDeniedError"}}export class LocalConfirmationRequiredError extends Error{constructor(e){super(e),this.name="LocalConfirmationRequiredError"}}export class CompanionWorkspace{leases=new a;events;client;localApprovalPolicy;approvals=new Map;eventListeners=new Set;releaseClientSubscription;constructor(e){this.client=e.client,this.localApprovalPolicy=e.localApprovalPolicy,this.events=new r({...void 0!==e.maxEvents?{maxEvents:e.maxEvents}:{},...void 0!==e.maxBytes?{maxBytes:e.maxBytes}:{}}),this.releaseClientSubscription=this.client.onEvent(e=>this.handleEvent(e))}attachBrowser(e){return this.leases.acquire({kind:"client",id:e})}detachBrowser(e){return this.leases.releaseClient(e)}acquireBackgroundShellLease(e){return this.leases.acquire({kind:"shell-session",id:e})}onBufferedEvent(e){return this.eventListeners.add(e),()=>{this.eventListeners.delete(e)}}replay(e=-1){return this.events.replay(e)}acknowledge(e){this.events.acknowledge(e)}async startTurn(r){const a=t(e.turnStart,r);this.leases.acquire({kind:"turn",id:a.turnId});try{return await this.client.request(e.turnStart,a)}catch(e){throw this.leases.release({kind:"turn",id:a.turnId}),e}}async respondApproval(r){const a=t(e.approvalRespond,r),n=this.approvals.get(a.approvalId);if(void 0===n)throw new LocalApprovalDeniedError(`Approval "${a.approvalId}" is no longer pending`);if("approve"===a.decision){const e=await this.localApprovalPolicy(n);if("deny"===e)throw new LocalApprovalDeniedError("Local Companion policy denied remote approval");if("require-local-confirmation"===e)throw new LocalConfirmationRequiredError("Local confirmation is required before this approval can continue")}const s=await this.client.request(e.approvalRespond,a);return this.approvals.delete(a.approvalId),this.leases.release({kind:"approval",id:a.approvalId}),s}async handleRemoteRequest(r){switch(r.method){case e.initialize:throw new LocalApprovalDeniedError("initialize is owned by the local Companion and cannot be relayed");case e.threadList:return this.client.request(e.threadList,t(e.threadList,r.params));case e.threadCreate:return this.client.request(e.threadCreate,t(e.threadCreate,r.params));case e.threadOpen:return this.client.request(e.threadOpen,t(e.threadOpen,r.params));case e.threadSnapshot:return this.client.request(e.threadSnapshot,t(e.threadSnapshot,r.params));case e.threadRename:return this.client.request(e.threadRename,t(e.threadRename,r.params));case e.threadDelete:return this.client.request(e.threadDelete,t(e.threadDelete,r.params));case e.threadDetach:return this.client.request(e.threadDetach,t(e.threadDetach,r.params));case e.threadCapabilities:return this.client.request(e.threadCapabilities,t(e.threadCapabilities,r.params));case e.turnStart:return this.startTurn(t(e.turnStart,r.params));case e.turnCancel:return this.client.request(e.turnCancel,t(e.turnCancel,r.params));case e.approvalRespond:return this.respondApproval(t(e.approvalRespond,r.params));case e.operationGet:return this.client.request(e.operationGet,t(e.operationGet,r.params))}}async closeIfIdle(){return!!this.leases.canStopRuntime()&&(this.releaseClientSubscription(),void 0===this.client.shutdown?this.client.close():await this.client.shutdown(),!0)}handleEvent(e){this.updateLeases(e);const t=this.events.append(e);for(const e of this.eventListeners)e(t)}updateLeases(e){if(void 0===e.turnId||"turn.completed"!==e.event.type&&"turn.cancelled"!==e.event.type&&"turn.failed"!==e.event.type){if("approval.required"===e.event.type){const t=e.event.approval;this.approvals.set(t.id,t),this.leases.acquire({kind:"approval",id:t.id})}}else{this.leases.release({kind:"turn",id:e.turnId});for(const[t,r]of this.approvals)r.turnId===e.turnId&&(this.approvals.delete(t),this.leases.release({kind:"approval",id:t}))}}}export function isRollNodeClient(e){return"getOutcomeUnknownTurnIds"in e}

package/dist/event-buffer.d.ts

@@ -0,0 +1,35 @@
+import type { RuntimeEventEnvelope } from "@roll-agent/protocol";
+export declare const DEFAULT_COMPANION_MAX_EVENTS = 10000;
+export declare const DEFAULT_COMPANION_MAX_BYTES: number;
+export interface BufferedRuntimeEvent {
+    readonly relaySequence: number;
+    readonly event: RuntimeEventEnvelope;
+}
+export interface EventBufferGap {
+    readonly fromRelaySequence: number;
+    readonly throughRelaySequence: number;
+}
+export interface EventBufferReplay {
+    readonly events: readonly BufferedRuntimeEvent[];
+    readonly gap: EventBufferGap | undefined;
+}
+export interface CompanionEventBufferOptions {
+    readonly maxEvents?: number;
+    readonly maxBytes?: number;
+}
+export declare class CompanionEventBuffer {
+    private readonly maxEvents;
+    private readonly maxBytes;
+    private readonly entries;
+    private nextSequence;
+    private retainedBytes;
+    private droppedThroughSequence;
+    constructor(options?: CompanionEventBufferOptions);
+    append(event: RuntimeEventEnvelope): BufferedRuntimeEvent;
+    replay(afterRelaySequence?: number): EventBufferReplay;
+    acknowledge(throughRelaySequence: number): void;
+    get size(): number;
+    get bytes(): number;
+    get highestRelaySequence(): number;
+    private enforceLimits;
+}

package/dist/event-buffer.js

@@ -0,0 +1 @@
+export const DEFAULT_COMPANION_MAX_EVENTS=1e4;export const DEFAULT_COMPANION_MAX_BYTES=16777216;export class CompanionEventBuffer{maxEvents;maxBytes;entries=[];nextSequence=0;retainedBytes=0;droppedThroughSequence=-1;constructor(e={}){if(this.maxEvents=e.maxEvents??1e4,this.maxBytes=e.maxBytes??16777216,!Number.isInteger(this.maxEvents)||this.maxEvents<1)throw new Error("maxEvents must be a positive integer");if(!Number.isInteger(this.maxBytes)||this.maxBytes<1)throw new Error("maxBytes must be a positive integer")}append(e){const t={relaySequence:this.nextSequence,event:e,bytes:Buffer.byteLength(JSON.stringify(e),"utf8")};return this.nextSequence+=1,this.entries.push(t),this.retainedBytes+=t.bytes,this.enforceLimits(),{relaySequence:t.relaySequence,event:e}}replay(e=-1){if(!Number.isInteger(e)||e<-1)throw new Error("afterRelaySequence must be an integer greater than or equal to -1");const t=e<this.droppedThroughSequence?{fromRelaySequence:e+1,throughRelaySequence:this.droppedThroughSequence}:void 0;return{events:this.entries.filter(t=>t.relaySequence>e).map(({relaySequence:e,event:t})=>({relaySequence:e,event:t})),gap:t}}acknowledge(e){if(!Number.isInteger(e)||e<-1)throw new Error("throughRelaySequence must be an integer greater than or equal to -1");if(!(e>this.highestRelaySequence))for(;void 0!==this.entries[0]&&this.entries[0].relaySequence<=e;){const e=this.entries.shift();void 0!==e&&(this.retainedBytes-=e.bytes,this.droppedThroughSequence=Math.max(this.droppedThroughSequence,e.relaySequence))}}get size(){return this.entries.length}get bytes(){return this.retainedBytes}get highestRelaySequence(){return this.nextSequence-1}enforceLimits(){for(;this.entries.length>this.maxEvents||this.retainedBytes>this.maxBytes&&this.entries.length>0;){const e=this.entries.shift();void 0!==e&&(this.retainedBytes-=e.bytes,this.droppedThroughSequence=e.relaySequence)}}}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { COMPANION_RELAY_PROTOCOL_VERSION, deviceIdSchema, workspaceIdSchema, relayRequestIdSchema, relayDeviceConnectSchema, relayRuntimeRequestSchema, relayRuntimeResponseSchema, relayRuntimeEventSchema, relayAckSchema, relayGapSchema, relayEncryptedMessageSchema, relayMessageSchema, } from "./relay-protocol.ts";
+export type { DeviceId, WorkspaceId, RelayRequestId, RelayMessage, RelayRuntimeRequest, RelayRuntimeResponse, RelayRuntimeEvent, RelayGap, RelayEncryptedMessage, } from "./relay-protocol.ts";
+export { CompanionEventBuffer, DEFAULT_COMPANION_MAX_BYTES, DEFAULT_COMPANION_MAX_EVENTS, } from "./event-buffer.ts";
+export type { BufferedRuntimeEvent, CompanionEventBufferOptions, EventBufferGap, EventBufferReplay, } from "./event-buffer.ts";
+export { COMPANION_LEASE_KINDS, WorkspaceLeaseManager } from "./lease-manager.ts";
+export type { CompanionLease, CompanionLeaseKind } from "./lease-manager.ts";
+export { CompanionWorkspace, LOCAL_APPROVAL_DECISIONS, LocalApprovalDeniedError, LocalConfirmationRequiredError, isRollNodeClient, } from "./companion-workspace.ts";
+export { CompanionRelayBridge, OutboundCompanionRelay, createWebSocketRelayTransport, relayEventMessage, } from "./relay-bridge.ts";
+export type { CompanionRelayBridgeOptions, OutboundCompanionRelayOptions, RelayPayloadCipher, RelayTransport, WebSocketLike, WebSocketMessageEventLike, } from "./relay-bridge.ts";
+export type { CompanionRuntimeClient, CompanionWorkspaceOptions, LocalApprovalDecision, LocalApprovalPolicy, } from "./companion-workspace.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export{COMPANION_RELAY_PROTOCOL_VERSION,deviceIdSchema,workspaceIdSchema,relayRequestIdSchema,relayDeviceConnectSchema,relayRuntimeRequestSchema,relayRuntimeResponseSchema,relayRuntimeEventSchema,relayAckSchema,relayGapSchema,relayEncryptedMessageSchema,relayMessageSchema}from"./relay-protocol.js";export{CompanionEventBuffer,DEFAULT_COMPANION_MAX_BYTES,DEFAULT_COMPANION_MAX_EVENTS}from"./event-buffer.js";export{COMPANION_LEASE_KINDS,WorkspaceLeaseManager}from"./lease-manager.js";export{CompanionWorkspace,LOCAL_APPROVAL_DECISIONS,LocalApprovalDeniedError,LocalConfirmationRequiredError,isRollNodeClient}from"./companion-workspace.js";export{CompanionRelayBridge,OutboundCompanionRelay,createWebSocketRelayTransport,relayEventMessage}from"./relay-bridge.js";

package/dist/lease-manager.d.ts

@@ -0,0 +1,15 @@
+export declare const COMPANION_LEASE_KINDS: readonly ["client", "turn", "shell-session", "approval"];
+export type CompanionLeaseKind = (typeof COMPANION_LEASE_KINDS)[number];
+export interface CompanionLease {
+    readonly kind: CompanionLeaseKind;
+    readonly id: string;
+}
+export declare class WorkspaceLeaseManager {
+    private readonly leases;
+    acquire(lease: CompanionLease): () => void;
+    release(lease: CompanionLease): boolean;
+    releaseClient(clientId: string): boolean;
+    has(lease: CompanionLease): boolean;
+    canStopRuntime(): boolean;
+    list(): readonly CompanionLease[];
+}

package/dist/lease-manager.js

@@ -0,0 +1 @@
+export const COMPANION_LEASE_KINDS=["client","turn","shell-session","approval"];function e(e){return`${e.kind}:${e.id}`}export class WorkspaceLeaseManager{leases=new Map;acquire(s){const t=e(s);return this.leases.set(t,s),()=>{this.leases.delete(t)}}release(s){return this.leases.delete(e(s))}releaseClient(e){return this.release({kind:"client",id:e})}has(s){return this.leases.has(e(s))}canStopRuntime(){return 0===this.leases.size}list(){return[...this.leases.values()]}}

package/dist/relay-bridge.d.ts

@@ -0,0 +1,85 @@
+import { type JsonValue, type RuntimeEventEnvelope } from "@roll-agent/protocol";
+import { CompanionWorkspace } from "./companion-workspace.ts";
+import { type DeviceId, type RelayEncryptedMessage, type RelayMessage, type WorkspaceId } from "./relay-protocol.ts";
+export interface RelayTransport {
+    send(message: RelayMessage): void | Promise<void>;
+    onMessage(listener: (message: unknown) => void): () => void;
+    onClose(listener: () => void): () => void;
+    close(): void;
+}
+export interface CompanionRelayBridgeOptions {
+    readonly deviceId: DeviceId;
+    readonly pairingToken: string;
+    readonly workspaces: ReadonlyMap<WorkspaceId, CompanionWorkspace>;
+    readonly ciphers?: ReadonlyMap<WorkspaceId, RelayPayloadCipher>;
+    readonly maxRequestCacheEntries?: number;
+}
+export interface RelayPayloadCipher {
+    readonly algorithm: string;
+    encrypt(value: JsonValue): Promise<{
+        readonly nonce: string;
+        readonly ciphertext: string;
+    }>;
+    decrypt(message: RelayEncryptedMessage): Promise<JsonValue>;
+}
+export declare class CompanionRelayBridge {
+    private readonly deviceId;
+    private readonly pairingToken;
+    private readonly workspaces;
+    private readonly ciphers;
+    private readonly maxRequestCacheEntries;
+    private readonly acknowledged;
+    private readonly inFlightRequestCache;
+    private readonly settledRequestCache;
+    private readonly releaseWorkspaceSubscriptions;
+    private transportGeneration;
+    private releaseTransportSubscriptions;
+    constructor(options: CompanionRelayBridgeOptions);
+    connect(transport: RelayTransport): void;
+    close(): void;
+    private enqueue;
+    private enqueueTask;
+    private handleMessage;
+    private resolveRuntimeRequest;
+    private executeRuntimeRequest;
+    private settleRequest;
+    private sendRuntimeEvent;
+    private sendRuntimeResponse;
+    private releaseCurrentTransport;
+    private markAdvertised;
+}
+export interface WebSocketMessageEventLike {
+    readonly data: unknown;
+}
+export interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: "message", listener: (event: WebSocketMessageEventLike) => void): void;
+    addEventListener(type: "close", listener: () => void): void;
+    removeEventListener(type: "message", listener: (event: WebSocketMessageEventLike) => void): void;
+    removeEventListener(type: "close", listener: () => void): void;
+}
+export declare function createWebSocketRelayTransport(socket: WebSocketLike): RelayTransport;
+export interface OutboundCompanionRelayOptions {
+    readonly bridge: CompanionRelayBridge;
+    readonly connectTransport: () => Promise<RelayTransport>;
+    readonly minReconnectMs?: number;
+    readonly maxReconnectMs?: number;
+}
+export declare class OutboundCompanionRelay {
+    private readonly bridge;
+    private readonly connectTransport;
+    private readonly minReconnectMs;
+    private readonly maxReconnectMs;
+    private reconnectMs;
+    private timer;
+    private transport;
+    private stopped;
+    private connecting;
+    constructor(options: OutboundCompanionRelayOptions);
+    start(): void;
+    stop(): void;
+    private connect;
+    private scheduleReconnect;
+}
+export declare function relayEventMessage(workspaceId: WorkspaceId, relaySequence: number, event: RuntimeEventEnvelope): RelayMessage;

package/dist/relay-bridge.js

@@ -0,0 +1 @@
+import{createHash as e,randomUUID as t}from"node:crypto";import{RollRpcError as s}from"@roll-agent/client-node";import{RUNTIME_METHODS as r,jsonValueSchema as n}from"@roll-agent/protocol";import{CompanionWorkspace as o}from"./companion-workspace.js";import{COMPANION_RELAY_PROTOCOL_VERSION as i,relayMessageSchema as a,relayRuntimeRequestSchema as c}from"./relay-protocol.js";const h=1e4,p={code:"RELAY_ENCRYPTION_REQUIRED",message:"Encrypted Relay request required for this workspace",retryable:!1},d=new Set([r.threadCreate,r.threadRename,r.threadDelete,r.threadDetach,r.turnStart,r.turnCancel,r.approvalRespond]);function u(t){return e("sha256").update(JSON.stringify({workspaceId:t.workspaceId,method:t.method,params:t.params})).digest("hex")}function l(e){return e instanceof s?{code:e.data?.rollCode??`JSON_RPC_${String(e.code)}`,message:e.message,retryable:e.data?.retryable??!1}:{code:e instanceof Error?e.name:"COMPANION_ERROR",message:e instanceof Error?e.message:String(e),retryable:!1}}export class CompanionRelayBridge{deviceId;pairingToken;workspaces;ciphers;maxRequestCacheEntries;acknowledged=new Map;inFlightRequestCache=new Map;settledRequestCache=new Map;releaseWorkspaceSubscriptions;transportGeneration;releaseTransportSubscriptions=[];constructor(e){if(this.deviceId=e.deviceId,this.pairingToken=e.pairingToken,this.workspaces=e.workspaces,this.ciphers=e.ciphers??new Map,this.maxRequestCacheEntries=e.maxRequestCacheEntries??h,!Number.isInteger(this.maxRequestCacheEntries)||this.maxRequestCacheEntries<1)throw new Error("maxRequestCacheEntries must be a positive integer");this.releaseWorkspaceSubscriptions=[...this.workspaces.entries()].map(([e,t])=>t.onBufferedEvent(t=>{void 0!==this.transportGeneration&&this.sendRuntimeEvent(e,t.relaySequence,t.event)}))}connect(e){this.releaseCurrentTransport(!0);const t={transport:e,advertisedThrough:new Map,queue:Promise.resolve()};this.transportGeneration=t,this.releaseTransportSubscriptions=[e.onMessage(e=>{this.handleMessage(e,t).catch(()=>{})}),e.onClose(()=>{this.transportGeneration===t&&this.releaseCurrentTransport()})],this.enqueue({type:"device.connect",protocolVersion:i,deviceId:this.deviceId,pairingToken:this.pairingToken});for(const[e,t]of this.workspaces){const s=t.replay(this.acknowledged.get(e)??-1);void 0!==s.gap&&this.enqueue({type:"runtime.gap",workspaceId:e,fromRelaySequence:s.gap.fromRelaySequence,throughRelaySequence:s.gap.throughRelaySequence,recovery:"thread.snapshot"});for(const t of s.events)this.sendRuntimeEvent(e,t.relaySequence,t.event)}}close(){this.releaseCurrentTransport(!0);for(const e of this.releaseWorkspaceSubscriptions)e()}enqueue(e){const t=this.transportGeneration;void 0!==t&&this.enqueueTask(t,async()=>{await t.transport.send(e),this.transportGeneration===t&&("runtime.event"===e.type?this.markAdvertised(t,e.workspaceId,e.relaySequence):"runtime.gap"===e.type&&this.markAdvertised(t,e.workspaceId,e.throughRelaySequence))})}enqueueTask(e,t){e.queue=e.queue.then(async()=>{this.transportGeneration===e&&await t()}).catch(()=>{})}async handleMessage(e,t,s=!1){if(this.transportGeneration!==t)return;const r=a.safeParse(e);if(!r.success)return;const n=r.data;if("runtime.encrypted"===n.type){if("request"!==n.payloadKind||void 0===n.requestId)return;const e=this.ciphers.get(n.workspaceId);if(void 0===e)return;try{const s=c.parse(await e.decrypt(n));if(s.workspaceId!==n.workspaceId||s.requestId!==n.requestId)return;await this.handleMessage(s,t,!0)}catch{this.sendRuntimeResponse({type:"runtime.response",requestId:n.requestId,workspaceId:n.workspaceId,error:{code:"ENCRYPTED_PAYLOAD_INVALID",message:"Encrypted Relay payload could not be authenticated or parsed",retryable:!1}})}return}if("runtime.ack"===n.type){const e=this.workspaces.get(n.workspaceId);if(void 0===e||n.throughRelaySequence>(t.advertisedThrough.get(n.workspaceId)??-1))return;const s=this.acknowledged.get(n.workspaceId)??-1;return void(n.throughRelaySequence>s&&(this.acknowledged.set(n.workspaceId,n.throughRelaySequence),e.acknowledge(n.throughRelaySequence)))}if("runtime.request"!==n.type)return;if(!s&&this.ciphers.has(n.workspaceId))return void this.sendRuntimeResponse({type:"runtime.response",requestId:n.requestId,workspaceId:n.workspaceId,error:p});const o=this.workspaces.get(n.workspaceId);if(void 0===o)return void this.sendRuntimeResponse({type:"runtime.response",requestId:n.requestId,workspaceId:n.workspaceId,error:{code:"WORKSPACE_NOT_FOUND",message:"The requested workspace is not paired with this Companion",retryable:!1}});const i=await this.resolveRuntimeRequest(n,o);this.sendRuntimeResponse(i)}resolveRuntimeRequest(e,t){const s=`${e.workspaceId}:${e.requestId}`,r=this.inFlightRequestCache.get(s),n=this.settledRequestCache.get(s),o=r??n;if(void 0!==o){const t=u(e);return o.fingerprint===t?(void 0!==n&&(this.settledRequestCache.delete(s),this.settledRequestCache.set(s,n)),o.response):Promise.resolve({type:"runtime.response",requestId:e.requestId,workspaceId:e.workspaceId,error:{code:"RELAY_REQUEST_ID_CONFLICT",message:"Relay requestId was reused with different method or params",retryable:!1}})}if(!d.has(e.method))return this.executeRuntimeRequest(e,t);const i={fingerprint:u(e),response:this.executeRuntimeRequest(e,t)};return this.inFlightRequestCache.set(s,i),i.response.then(()=>this.settleRequest(s,i),()=>this.settleRequest(s,i)).catch(()=>{}),i.response}async executeRuntimeRequest(e,t){try{const s=await t.handleRemoteRequest(e);return{type:"runtime.response",requestId:e.requestId,workspaceId:e.workspaceId,result:n.parse(s)}}catch(t){return{type:"runtime.response",requestId:e.requestId,workspaceId:e.workspaceId,error:l(t)}}}settleRequest(e,t){if(this.inFlightRequestCache.get(e)===t)for(this.inFlightRequestCache.delete(e),this.settledRequestCache.set(e,t);this.settledRequestCache.size>this.maxRequestCacheEntries;){const e=this.settledRequestCache.keys().next().value;if(void 0===e)return;this.settledRequestCache.delete(e)}}sendRuntimeEvent(e,s,r){const o=this.ciphers.get(e);if(void 0===o)return void this.enqueue({type:"runtime.event",workspaceId:e,relaySequence:s,event:r});const i=this.transportGeneration;void 0!==i&&this.enqueueTask(i,async()=>{const a=await o.encrypt(n.parse(r));this.transportGeneration===i&&(await i.transport.send({type:"runtime.encrypted",workspaceId:e,envelopeId:t(),payloadKind:"event",relaySequence:s,algorithm:o.algorithm,nonce:a.nonce,ciphertext:a.ciphertext}),this.transportGeneration===i&&this.markAdvertised(i,e,s))})}sendRuntimeResponse(e){const s=this.ciphers.get(e.workspaceId);if(void 0===s)return void this.enqueue(e);const r=this.transportGeneration;void 0!==r&&this.enqueueTask(r,async()=>{const o=await s.encrypt(n.parse(e));this.transportGeneration===r&&await r.transport.send({type:"runtime.encrypted",workspaceId:e.workspaceId,envelopeId:t(),payloadKind:"response",requestId:e.requestId,algorithm:s.algorithm,nonce:o.nonce,ciphertext:o.ciphertext})})}releaseCurrentTransport(e=!1){const t=this.transportGeneration;this.transportGeneration=void 0;for(const e of this.releaseTransportSubscriptions)e();this.releaseTransportSubscriptions=[],e&&t?.transport.close()}markAdvertised(e,t,s){e.advertisedThrough.set(t,Math.max(e.advertisedThrough.get(t)??-1,s))}}export function createWebSocketRelayTransport(e){return{send(t){e.send(JSON.stringify(t))},onMessage(t){const s=e=>{if("string"==typeof e.data)try{t(JSON.parse(e.data))}catch{}};return e.addEventListener("message",s),()=>e.removeEventListener("message",s)},onClose:t=>(e.addEventListener("close",t),()=>e.removeEventListener("close",t)),close(){e.close()}}}export class OutboundCompanionRelay{bridge;connectTransport;minReconnectMs;maxReconnectMs;reconnectMs;timer;transport;stopped=!0;connecting=!1;constructor(e){this.bridge=e.bridge,this.connectTransport=e.connectTransport,this.minReconnectMs=e.minReconnectMs??500,this.maxReconnectMs=e.maxReconnectMs??3e4,this.reconnectMs=this.minReconnectMs}start(){this.stopped&&(this.stopped=!1,this.connect().catch(()=>{}))}stop(){this.stopped=!0,void 0!==this.timer&&(clearTimeout(this.timer),this.timer=void 0),this.transport?.close(),this.transport=void 0,this.bridge.close()}async connect(){if(!this.stopped&&!this.connecting){this.connecting=!0;try{const e=await this.connectTransport();if(this.stopped)return void e.close();this.transport=e,this.reconnectMs=this.minReconnectMs,e.onClose(()=>{this.transport===e&&(this.transport=void 0,this.scheduleReconnect())}),this.bridge.connect(e)}catch{this.scheduleReconnect()}finally{this.connecting=!1}}}scheduleReconnect(){if(this.stopped||void 0!==this.timer)return;const e=this.reconnectMs;this.reconnectMs=Math.min(2*this.reconnectMs,this.maxReconnectMs),this.timer=setTimeout(()=>{this.timer=void 0,this.connect().catch(()=>{})},e)}}export function relayEventMessage(e,t,s){return{type:"runtime.event",workspaceId:e,relaySequence:t,event:s}}

package/dist/relay-protocol.d.ts

@@ -0,0 +1,320 @@
+import { z } from "zod/v4";
+export declare const COMPANION_RELAY_PROTOCOL_VERSION: "1.0";
+export declare const deviceIdSchema: z.core.$ZodBranded<z.ZodString, "DeviceId">;
+export declare const workspaceIdSchema: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+export declare const relayRequestIdSchema: z.core.$ZodBranded<z.ZodString, "RelayRequestId">;
+export declare const relayDeviceConnectSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"device.connect">;
+    protocolVersion: z.ZodLiteral<"1.0">;
+    deviceId: z.core.$ZodBranded<z.ZodString, "DeviceId">;
+    pairingToken: z.ZodString;
+}, z.core.$strict>>;
+export declare const relayRuntimeRequestSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.request">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RelayRequestId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    method: z.ZodEnum<{
+        initialize: "initialize";
+        "thread.list": "thread.list";
+        "thread.create": "thread.create";
+        "thread.open": "thread.open";
+        "thread.snapshot": "thread.snapshot";
+        "thread.rename": "thread.rename";
+        "thread.delete": "thread.delete";
+        "thread.detach": "thread.detach";
+        "thread.capabilities": "thread.capabilities";
+        "turn.start": "turn.start";
+        "turn.cancel": "turn.cancel";
+        "approval.respond": "approval.respond";
+        "operation.get": "operation.get";
+    }>;
+    params: z.ZodJSONSchema;
+}, z.core.$strict>>;
+export declare const relayRuntimeResponseSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.response">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RelayRequestId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    result: z.ZodOptional<z.ZodJSONSchema>;
+    error: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+export declare const relayRuntimeEventSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.event">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    relaySequence: z.ZodNumber;
+    event: z.ZodReadonly<z.ZodObject<{
+        protocolVersion: z.ZodLiteral<"1.0">;
+        runtimeInstanceId: z.core.$ZodBranded<z.ZodString, "RuntimeInstanceId">;
+        sequence: z.ZodNumber;
+        timestamp: z.ZodString;
+        threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
+        turnId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TurnId">>;
+        event: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.started">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"message.started">;
+            streamId: z.core.$ZodBranded<z.ZodString, "StreamId">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"message.delta">;
+            streamId: z.core.$ZodBranded<z.ZodString, "StreamId">;
+            delta: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"message.completed">;
+            streamId: z.core.$ZodBranded<z.ZodString, "StreamId">;
+            text: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"reasoning.summary.delta">;
+            reasoningId: z.ZodString;
+            delta: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"tool.started">;
+            toolCallId: z.ZodString;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            input: z.ZodJSONSchema;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"tool.output">;
+            toolCallId: z.ZodString;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            stream: z.ZodEnum<{
+                stdout: "stdout";
+                stderr: "stderr";
+            }>;
+            delta: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"tool.completed">;
+            toolCallId: z.ZodString;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            operationId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "OperationId">>;
+            outcome: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    success: "success";
+                    user_rejected: "user_rejected";
+                    policy_denied: "policy_denied";
+                    invalid_input: "invalid_input";
+                    cancelled: "cancelled";
+                    tool_failed: "tool_failed";
+                }>;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            display: z.ZodJSONSchema;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"approval.required">;
+            approval: z.ZodReadonly<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+                turnId: z.core.$ZodBranded<z.ZodString, "TurnId">;
+                agentName: z.ZodString;
+                toolName: z.ZodString;
+                preview: z.ZodJSONSchema;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.completed">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.cancelled">;
+            reason: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.failed">;
+            stage: z.ZodEnum<{
+                bootstrap: "bootstrap";
+                plan: "plan";
+                execute: "execute";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"capabilities.changed">;
+        }, z.core.$strict>>]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+export declare const relayAckSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.ack">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    throughRelaySequence: z.ZodNumber;
+}, z.core.$strict>>;
+export declare const relayGapSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.gap">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    fromRelaySequence: z.ZodNumber;
+    throughRelaySequence: z.ZodNumber;
+    recovery: z.ZodLiteral<"thread.snapshot">;
+}, z.core.$strict>>;
+export declare const relayEncryptedMessageSchema: z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.encrypted">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    envelopeId: z.ZodString;
+    payloadKind: z.ZodEnum<{
+        event: "event";
+        request: "request";
+        response: "response";
+    }>;
+    requestId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RelayRequestId">>;
+    relaySequence: z.ZodOptional<z.ZodNumber>;
+    algorithm: z.ZodString;
+    nonce: z.ZodString;
+    ciphertext: z.ZodString;
+}, z.core.$strict>>;
+export declare const relayMessageSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"device.connect">;
+    protocolVersion: z.ZodLiteral<"1.0">;
+    deviceId: z.core.$ZodBranded<z.ZodString, "DeviceId">;
+    pairingToken: z.ZodString;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.request">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RelayRequestId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    method: z.ZodEnum<{
+        initialize: "initialize";
+        "thread.list": "thread.list";
+        "thread.create": "thread.create";
+        "thread.open": "thread.open";
+        "thread.snapshot": "thread.snapshot";
+        "thread.rename": "thread.rename";
+        "thread.delete": "thread.delete";
+        "thread.detach": "thread.detach";
+        "thread.capabilities": "thread.capabilities";
+        "turn.start": "turn.start";
+        "turn.cancel": "turn.cancel";
+        "approval.respond": "approval.respond";
+        "operation.get": "operation.get";
+    }>;
+    params: z.ZodJSONSchema;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.response">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RelayRequestId">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    result: z.ZodOptional<z.ZodJSONSchema>;
+    error: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.event">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    relaySequence: z.ZodNumber;
+    event: z.ZodReadonly<z.ZodObject<{
+        protocolVersion: z.ZodLiteral<"1.0">;
+        runtimeInstanceId: z.core.$ZodBranded<z.ZodString, "RuntimeInstanceId">;
+        sequence: z.ZodNumber;
+        timestamp: z.ZodString;
+        threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
+        turnId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TurnId">>;
+        event: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.started">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"message.started">;
+            streamId: z.core.$ZodBranded<z.ZodString, "StreamId">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"message.delta">;
+            streamId: z.core.$ZodBranded<z.ZodString, "StreamId">;
+            delta: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"message.completed">;
+            streamId: z.core.$ZodBranded<z.ZodString, "StreamId">;
+            text: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"reasoning.summary.delta">;
+            reasoningId: z.ZodString;
+            delta: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"tool.started">;
+            toolCallId: z.ZodString;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            input: z.ZodJSONSchema;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"tool.output">;
+            toolCallId: z.ZodString;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            stream: z.ZodEnum<{
+                stdout: "stdout";
+                stderr: "stderr";
+            }>;
+            delta: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"tool.completed">;
+            toolCallId: z.ZodString;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            operationId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "OperationId">>;
+            outcome: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    success: "success";
+                    user_rejected: "user_rejected";
+                    policy_denied: "policy_denied";
+                    invalid_input: "invalid_input";
+                    cancelled: "cancelled";
+                    tool_failed: "tool_failed";
+                }>;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            display: z.ZodJSONSchema;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"approval.required">;
+            approval: z.ZodReadonly<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+                turnId: z.core.$ZodBranded<z.ZodString, "TurnId">;
+                agentName: z.ZodString;
+                toolName: z.ZodString;
+                preview: z.ZodJSONSchema;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.completed">;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.cancelled">;
+            reason: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"turn.failed">;
+            stage: z.ZodEnum<{
+                bootstrap: "bootstrap";
+                plan: "plan";
+                execute: "execute";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+            type: z.ZodLiteral<"capabilities.changed">;
+        }, z.core.$strict>>]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.ack">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    throughRelaySequence: z.ZodNumber;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.gap">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    fromRelaySequence: z.ZodNumber;
+    throughRelaySequence: z.ZodNumber;
+    recovery: z.ZodLiteral<"thread.snapshot">;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"runtime.encrypted">;
+    workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId">;
+    envelopeId: z.ZodString;
+    payloadKind: z.ZodEnum<{
+        event: "event";
+        request: "request";
+        response: "response";
+    }>;
+    requestId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RelayRequestId">>;
+    relaySequence: z.ZodOptional<z.ZodNumber>;
+    algorithm: z.ZodString;
+    nonce: z.ZodString;
+    ciphertext: z.ZodString;
+}, z.core.$strict>>]>;
+export type DeviceId = z.infer<typeof deviceIdSchema>;
+export type WorkspaceId = z.infer<typeof workspaceIdSchema>;
+export type RelayRequestId = z.infer<typeof relayRequestIdSchema>;
+export type RelayMessage = z.infer<typeof relayMessageSchema>;
+export type RelayRuntimeRequest = z.infer<typeof relayRuntimeRequestSchema>;
+export type RelayRuntimeResponse = z.infer<typeof relayRuntimeResponseSchema>;
+export type RelayRuntimeEvent = z.infer<typeof relayRuntimeEventSchema>;
+export type RelayGap = z.infer<typeof relayGapSchema>;
+export type RelayEncryptedMessage = z.infer<typeof relayEncryptedMessageSchema>;

package/dist/relay-protocol.js

@@ -0,0 +1 @@
+import{z as e}from"zod/v4";import{RUNTIME_METHODS as t,jsonValueSchema as r,runtimeEventEnvelopeSchema as n}from"@roll-agent/protocol";export const COMPANION_RELAY_PROTOCOL_VERSION="1.0";export const deviceIdSchema=e.string().uuid().brand();export const workspaceIdSchema=e.string().uuid().brand();export const relayRequestIdSchema=e.string().uuid().brand();export const relayDeviceConnectSchema=e.object({type:e.literal("device.connect"),protocolVersion:e.literal("1.0"),deviceId:deviceIdSchema,pairingToken:e.string().min(16)}).strict().readonly();export const relayRuntimeRequestSchema=e.object({type:e.literal("runtime.request"),requestId:relayRequestIdSchema,workspaceId:workspaceIdSchema,method:e.enum(Object.values(t)),params:r}).strict().readonly();export const relayRuntimeResponseSchema=e.object({type:e.literal("runtime.response"),requestId:relayRequestIdSchema,workspaceId:workspaceIdSchema,result:r.optional(),error:e.object({code:e.string().min(1),message:e.string(),retryable:e.boolean()}).strict().readonly().optional()}).strict().readonly();export const relayRuntimeEventSchema=e.object({type:e.literal("runtime.event"),workspaceId:workspaceIdSchema,relaySequence:e.number().int().nonnegative(),event:n}).strict().readonly();export const relayAckSchema=e.object({type:e.literal("runtime.ack"),workspaceId:workspaceIdSchema,throughRelaySequence:e.number().int().min(-1)}).strict().readonly();export const relayGapSchema=e.object({type:e.literal("runtime.gap"),workspaceId:workspaceIdSchema,fromRelaySequence:e.number().int().nonnegative(),throughRelaySequence:e.number().int().nonnegative(),recovery:e.literal("thread.snapshot")}).strict().readonly();export const relayEncryptedMessageSchema=e.object({type:e.literal("runtime.encrypted"),workspaceId:workspaceIdSchema,envelopeId:e.string().uuid(),payloadKind:e.enum(["request","response","event"]),requestId:relayRequestIdSchema.optional(),relaySequence:e.number().int().nonnegative().optional(),algorithm:e.string().min(1),nonce:e.string().min(1),ciphertext:e.string().min(1)}).strict().readonly();export const relayMessageSchema=e.discriminatedUnion("type",[relayDeviceConnectSchema,relayRuntimeRequestSchema,relayRuntimeResponseSchema,relayRuntimeEventSchema,relayAckSchema,relayGapSchema,relayEncryptedMessageSchema]);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@roll-agent/companion",
+  "version": "0.0.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/steveoon/roll-agent"
+  },
+  "homepage": "https://github.com/steveoon/roll-agent",
+  "bugs": {
+    "url": "https://github.com/steveoon/roll-agent/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "dependencies": {
+    "zod": "3.25.76",
+    "@roll-agent/client-node": "0.0.0",
+    "@roll-agent/protocol": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/obfuscate.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
+    "clean": "rm -rf dist"
+  }
+}