export * from './loopback.js' import { parseWireJson } from './wire-json.js' export { parseWireJson } from './wire-json.js' import { z } from 'zod' export const WEBRTC_RESUME_CAPABILITY = 'transport.webrtc.resume.v1' export const RELAY_RESUME_CAPABILITY = 'transport.relay.resume.v1' export const WEBRTC_LEASE_MS = 300_000 import { SERVER_SHUTDOWN_REASON as SERVER_SHUTDOWN_REASON_NAME } from './close-semantics.js' export { SERVER_SHUTDOWN_REASON, SERVER_SHUTDOWN_CLOSE_CODES, HEARTBEAT_TIMEOUT_CLOSE_CODE, HEARTBEAT_TIMEOUT_REASON, HEARTBEAT_CONNECTION_FAILED_REASON, TRANSIENT_CONTROL_CLOSE_CODES, TERMINAL_CONTROL_CLOSE_CODES, isServerShutdownClose, isHeartbeatTimeoutClose, classifyControlClose, type ControlCloseClassification, } from './close-semantics.js' /** * WebSocket close code a Server uses when shutting down for restart. * * Deployments disagree on the code (`apps/server` sends 4009, the hosted * Server sends 4001 and reserves 4009 for heartbeat expiry), so endpoints must * classify with `isServerShutdownClose()` / `classifyControlClose()` and never * by comparing the code alone. */ export const SERVER_SHUTDOWN_CLOSE_CODE = 4009 /** Close reason paired with the shutdown code; this is the semantic key. */ export const SERVER_SHUTDOWN_CLOSE_REASON: string = SERVER_SHUTDOWN_REASON_NAME export const PROTOCOL_VERSION = 1 export const MAX_CONTROL_FRAME_BYTES = 64 * 1024 export const MAX_RELAY_FRAME_BYTES = 1024 * 1024 export const SECURE_FRAGMENT_CHUNK_BYTES = 48 * 1024 export const MAX_SECURE_MESSAGE_BYTES = 4 * 1024 * 1024 /** Decoded bytes carried by one authenticated Harness business transfer chunk. */ export const HARNESS_API_TRANSFER_CHUNK_BYTES = 512 * 1024 /** Decoded bytes carried by one authenticated Codex domain transfer chunk. */ export const CODEX_APP_TRANSFER_CHUNK_BYTES = 512 * 1024 /** Decoded bytes carried by one authenticated Agent ACP domain transfer chunk. */ export const AGENT_ACP_TRANSFER_CHUNK_BYTES = 512 * 1024 /** * Bounded transfer size for Harness image prompts. The upstream default admits * up to 200 MiB of source images; their base64 JSON envelope needs roughly * 267 MiB, so 288 MiB leaves room for the native request structure. */ export const MAX_HARNESS_API_TRANSFER_BYTES = 288 * 1024 * 1024 export const MAX_CODEX_APP_TRANSFER_BYTES = 288 * 1024 * 1024 export const MAX_AGENT_ACP_TRANSFER_BYTES = 288 * 1024 * 1024 export const MAX_DEVICE_NAME_LENGTH = 128 export const MAX_DEVICE_PLATFORM_LENGTH = 64 export const MAX_DEVICE_VERSION_LENGTH = 64 export const MAX_AUTH_TOKEN_LENGTH = 8 * 1024 /** Maximum entries accepted in capability and workspace type advertisements. */ export const MAX_REMOTE_CAPABILITY_ENTRIES = 128 export const MAX_REMOTE_WORKSPACE_TYPE_ENTRIES = 32 // ──────────────────────────────────────────────────────────────────────────── // §24 Default limits // ──────────────────────────────────────────────────────────────────────────── /** Hello frame must arrive within this timeout after WebSocket open. */ export const HELLO_TIMEOUT_MS = 5_000 /** Host registration code time-to-live. */ export const HOST_REGISTRATION_CODE_TTL_MS = 10 * 60_000 /** Default control channel heartbeat interval. */ export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000 /** Disconnection threshold: no valid pong within this window. */ export const HEARTBEAT_DISCONNECT_MS = 75_000 /** Maximum in-flight RPC requests per connection. */ export const MAX_PENDING_RPC_PER_CONNECTION = 128 /** Maximum pending permission requests per session. */ export const MAX_PENDING_PERMISSION_PER_SESSION = 16 /** Maximum ICE candidates收集 per connection. */ export const MAX_ICE_CANDIDATES_PER_CONNECTION = 256 /** Maximum active transfers per direction per connection. */ export const MAX_ACTIVE_TRANSFERS_PER_DIRECTION = 2 /** Transfer idle timeout before automatic cleanup. */ export const TRANSFER_IDLE_MS = 2 * 60_000 /** Maximum RPC text input size. */ export const MAX_RPC_TEXT_INPUT_BYTES = 64 * 1024 /** Maximum File Viewer range per RPC call. */ export const MAX_FILEVIEWER_RANGE_BYTES = 512 * 1024 /** Maximum directory entries returned by File Viewer per RPC. */ export const MAX_FILEVIEWER_DIRECTORY_ENTRIES = 1_000 /** Minimum event replay window by event count. */ export const MIN_REPLAY_WINDOW_EVENTS = 10_000 /** Minimum event replay window by time. */ export const MIN_REPLAY_WINDOW_MS = 15 * 60_000 /** Maximum concurrent alpha streams per connection. */ export const MAX_ALPHA_STREAMS_PER_CONNECTION = 16 /** Generic Agent Client Protocol capability and bounded gateway limits. */ export const ACP_CAPABILITY = 'agent.acp.v1' as const export const ACP_PI_CAPABILITY = 'agent.acp.pi.v1' as const export const ACP_WORKSPACE_FILES_CAPABILITY = 'agent.acp.workspace-files.v1' as const export const ACP_TERMINAL_CAPABILITY = 'agent.acp.terminal.v1' as const export const ACP_ANTIGRAVITY_MODELS_CAPABILITY = 'agent.acp.antigravity.models.v1' as const export const ACP_ANTIGRAVITY_MODEL_LOAD_CAPABILITY = 'agent.acp.antigravity.model-load.v1' as const export const ACP_OPENCODE_CAPABILITY = 'agent.acp.opencode.v1' as const export const ACP_OPENCODE_ARCHIVE_CAPABILITY = 'agent.acp.opencode.archive.v1' as const export const ACP_TOOL_CALL_ENDPOINTS = ['workspaceFiles/list', 'workspaceFiles/stat', 'workspaceFiles/read', 'workspaceFiles/readBytes', 'workspaceFiles/readAll', 'terminal/environment', 'terminal/shells', 'terminal/list', 'terminal/create', 'terminal/write', 'terminal/resize', 'terminal/rename', 'terminal/close'] as const export const ACP_TOOL_STREAM_ENDPOINTS = ['workspaceFiles/changes', 'terminal/follow', 'terminal/retain'] as const export interface AcpModelSelection { provider: string; model: string; reasoningEffort?: string } export interface AcpSessionModels { current: AcpModelSelection; routable: boolean; groups: Array<{ id: string; name: string; models: Array<{ id: string; name: string; reasoning?: { efforts: Array<{ id: string; name: string }>; defaultEffort?: string } }> }>; failures: Array<{ id: string; name: string; message: string }>; } export const MAX_ACP_PROMPT_BYTES = 64 * 1024 export const MAX_ACP_UPDATE_BYTES = 512 * 1024 const SECURE_FRAGMENT_MAGIC = new Uint8Array([0x44, 0x53, 0x48, 0x46]) // DSHF const SECURE_FRAGMENT_VERSION = 1 const SECURE_FRAGMENT_HEADER_BYTES = 17 const MAX_IN_FLIGHT_SECURE_MESSAGES = 8 export const messageTypes = [ 'rpc.request', 'rpc.response', 'rpc.error', 'event', ] as const export const controlFrameTypes = [ 'hello', 'hello.ack', 'connect.request', 'connect.incoming', 'connect.accepted', 'connect.rejected', 'secure.handshake', 'relay', 'signal.offer', 'signal.answer', 'signal.ice', 'transport.selected', 'connection.lease.request', 'connection.lease.ack', 'connection.lease.close', 'ping', 'pong', 'error', ] as const export const rpcMethods = [ 'workspace.upload.open', 'workspace.upload.chunk', 'workspace.upload.commit', 'workspace.upload.abort', 'harness.transport.describe', 'remote.history.configure', 'harness.api.call', 'harness.api.transfer.open', 'harness.api.transfer.chunk', 'harness.api.transfer.commit', 'harness.api.transfer.read', 'harness.api.transfer.close', 'harness.api.respond', 'harness.api.stream.open', 'harness.api.stream.close', 'harness.remote.call', 'harness.remote.transfer.open', 'harness.remote.transfer.chunk', 'harness.remote.transfer.commit', 'harness.remote.transfer.read', 'harness.remote.transfer.close', 'harness.remote.stream.open', 'harness.remote.stream.close', 'loopback.call', 'fileviewer.call', 'codex.app.call', 'codex.app.respond', 'codex.app.stream.open', 'codex.app.stream.close', 'codex.app.transfer.open', 'codex.app.transfer.chunk', 'codex.app.transfer.commit', 'codex.app.transfer.read', 'codex.app.transfer.close', 'agent.acp.call', 'agent.acp.respond', 'agent.acp.stream.open', 'agent.acp.stream.close', 'agent.acp.transfer.open', 'agent.acp.transfer.chunk', 'agent.acp.transfer.commit', 'agent.acp.transfer.read', 'agent.acp.transfer.close', 'acp.initialize', 'acp.session.new', 'acp.session.load', 'acp.session.prompt', 'acp.session.respond_permission', 'acp.session.cancel', 'acp.session.set_mode', 'plugin.route.call', ] as const export const remoteEvents = [ 'harness.api.frame', 'harness.api.stream.closed', 'harness.remote.frame', 'harness.remote.stream.closed', 'codex.app.frame', 'codex.app.stream.closed', 'agent.acp.frame', 'agent.acp.stream.closed', 'agent.acp.catalog.changed', 'acp.session.update', 'acp.session.request_permission', 'acp.session.closed', ] as const export const errorCodes = [ // Protocol / Version 'INVALID_MESSAGE', 'UNSUPPORTED_VERSION', 'CAPABILITY_NOT_SUPPORTED', 'METHOD_NOT_FOUND', 'METHOD_NOT_ALLOWED', 'REQUEST_CONFLICT', 'FRAME_TOO_LARGE', 'RATE_LIMITED', // Auth / Device 'AUTH_REQUIRED', 'AUTH_INVALID', 'ACCOUNT_AUTH_REQUIRED', 'TOKEN_EXPIRED', 'DEVICE_NOT_FOUND', 'DEVICE_REVOKED', 'DEVICE_OWNERSHIP_REQUIRED', 'MEMBERSHIP_REQUIRED', 'PEER_IDENTITY_MISMATCH', 'HOST_REGISTRATION_CODE_NOT_FOUND', 'HOST_REGISTRATION_CODE_EXPIRED', 'HOST_REGISTRATION_CODE_CONSUMED', // Connection / Transport 'HOST_OFFLINE', 'CONNECTION_NOT_FOUND', 'CONNECTION_FAILED', 'CONNECTION_REPLACED', 'P2P_FAILED', 'TURN_UNAVAILABLE', 'RELAY_UNAVAILABLE', 'SLOW_CONSUMER', 'SECURE_CHANNEL_FAILED', // Harness 'HARNESS_UNAVAILABLE', 'HARNESS_VERSION_INCOMPATIBLE', 'RESPONSE_TOO_LARGE', 'SESSION_NOT_FOUND', 'SESSION_NOT_READY', 'AGENT_BUSY', 'PERMISSION_DENIED', 'PERMISSION_NOT_PENDING', 'RPC_TIMEOUT', 'FULL_RESYNC_REQUIRED', 'INTERNAL_ERROR', ] as const /** * Known wire-protocol error codes from §23. * * This is the authoritative reference set; callers should prefer these codes but * the wire format accepts any string to allow subsystem-specific extensions * (e.g. CODEX_*, FILE_VIEWER_*) without a protocol version bump. */ export type ErrorCode = typeof errorCodes[number] export type MessageType = typeof messageTypes[number] export type ControlFrameType = typeof controlFrameTypes[number] export type RpcMethod = typeof rpcMethods[number] export type RemoteEventName = typeof remoteEvents[number] export interface HostDeviceDescriptor { deviceId: string name: string role: 'host' platform: string identityKey: string clientVersion: string harnessVersion?: string } export interface ClientDeviceDescriptor { deviceId: string name: string role: 'client' platform: string identityKey: string clientVersion: string } export type AccountDeviceDescriptor = HostDeviceDescriptor | ClientDeviceDescriptor export interface DeviceRegistrationRequest { v: typeof PROTOCOL_VERSION device: AccountDeviceDescriptor } export interface HostRegistrationCodeRequest { v: typeof PROTOCOL_VERSION code: string device: HostDeviceDescriptor } export interface DeviceRefreshRequest { deviceId: string refreshToken: string } export interface DeviceTokenPair { accessToken: string accessTokenExpiresAt: number refreshToken: string refreshTokenExpiresAt: number } export interface BrowserAuthorizationExchangeRequest { v: typeof PROTOCOL_VERSION device: ClientDeviceDescriptor & { platform: 'browser' } } export interface BrowserAuthorizationExchangeResponse extends DeviceTokenPair { account: string } export interface ControlFrame { v: typeof PROTOCOL_VERSION id: string type: ControlFrameType timestamp: number payload: TPayload } /** Envelope used by the independent Relay data WebSocket. */ export interface RelayDataFrame = Record> { v: typeof PROTOCOL_VERSION id: string type: string timestamp: number payload: TPayload } export interface ControlFrameByteLimits { maxControlFrameBytes?: number maxRelayFrameBytes?: number } export interface HelloPayload { recoveryTickets?: string[] role: 'host' | 'client' deviceId: string accessToken: string protocols: number[] capabilities: string[] /** Version of the Client/Plugin software reporting in; symmetric to ``HelloAckPayload.serverVersion``. */ clientVersion?: string /** Host Harness version; sent on first hello to refresh the device record. */ harnessVersion?: string } export interface HelloAckPayload { protocol: typeof PROTOCOL_VERSION serverVersion: string connectionSessionId: string heartbeatIntervalMs: number maxControlFrameBytes: number maxRelayFrameBytes: number capabilities?: string[] /** Optional implementation extension. This field reports WebRTC DataChannel support. */ webrtcEnabled?: boolean /** Optional implementation extension. This field sets the Relay fallback timeout. */ webrtcFallbackTimeoutMs?: number } export interface ConnectRequestPayload { hostDeviceId: string preferredTransports: Array<'lan' | 'p2p' | 'turn' | 'relay'> } export interface ConnectIncomingPayload { relayRecoveryTicket?: string recoveryTicket?: string connectionId: string clientDeviceId: string clientIdentityKey: string authorization: 'account' preferredTransports: Array<'lan' | 'p2p' | 'turn' | 'relay'> /** Optional independent Relay data-plane assignment. */ relayEndpoint?: string relayTicket?: string relayNodeId?: string relayEpoch?: number } export interface ConnectAcceptedPayload { relayRecoveryTicket?: string recoveryTicket?: string connectionId: string /** Optional independent Relay data-plane assignment. */ relayEndpoint?: string relayTicket?: string relayNodeId?: string relayEpoch?: number } export interface ConnectRejectedPayload { connectionId: string code?: string message?: string } export interface SecureHandshakePayload { connectionId: string targetDeviceId: string step: number data: string } export interface ControlErrorPayload { /** §23 defines standard codes. Subsystems can add names such as CODEX_* and FILE_VIEWER_*. */ code: ErrorCode | (string & {}) message: string retryable?: boolean connectionId?: string } export interface RelayPayload { connectionId: string targetDeviceId: string counter: number ciphertext: string } export const selectedTransports = ['lan', 'p2p', 'turn', 'relay'] as const export type SelectedTransport = typeof selectedTransports[number] export interface SignalPayload { connectionId: string targetDeviceId: string sdp: string } export interface IceCandidatePayload { candidate?: string sdpMid?: string | null sdpMLineIndex?: number | null usernameFragment?: string | null } export interface SignalIcePayload { connectionId: string targetDeviceId: string candidate: IceCandidatePayload } export function normalizeSdpMLineIndex(value: unknown): number | null | undefined { if (value === undefined) return undefined if (value === null) return null if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) return null return value } export interface TransportSelectedPayload { connectionId: string targetDeviceId: string transport: SelectedTransport /** Relay hostname the client actually used when transport is "turn" * (best-effort, from ICE stats; absent for other transports). */ turnNode?: string } /** Capabilities both ends announce in ``hello`` to negotiate the data plane. */ export const transportCapabilities = [ 'transport.lan', 'transport.p2p', 'transport.turn', 'transport.relay', ] as const /** * Universe of known harness/transfer/file-viewer/codex capability values (§17). * * This is a reference set for type checking and validation, NOT a capability * set that a Host may advertise wholesale. A Typert Host must advertise only * the capability matching its Session generation (harness.remote.v1 XOR * harness.remote.v3); advertising both is a protocol violation. */ export const harnessCapabilityValues = [ 'remote.history.compact.v1', 'workspace.upload.v1', 'harness.api.v1', 'harness.api.transfer.v1', 'harness.remote.v1', 'harness.remote.v3', 'harness.remote.transfer.v1', 'harness.remote.stream.transfer.v1', 'fileviewer.read.v1', 'codex.appserver.v1', 'codex.appserver.transfer.v1', 'plugin.route.v1', ] as const export type TransportCapability = typeof transportCapabilities[number] export type HarnessCapabilityValue = typeof harnessCapabilityValues[number] export function selectProtocolVersion( offered: readonly number[], supported: readonly number[] = [PROTOCOL_VERSION], ): number | undefined { const supportedVersions = new Set(supported) return [...offered] .filter(version => supportedVersions.has(version)) .sort((left, right) => right - left)[0] } export function selectCapabilities( offered: readonly string[], supported: readonly string[], ): string[] { const offeredCapabilities = new Set(offered) return [...new Set(supported)].filter(capability => offeredCapabilities.has(capability)) } export function acceptNegotiatedCapabilities( offered: readonly string[], negotiated: readonly string[] | undefined, ): string[] { const accepted = negotiated ?? ['transport.relay'] if (selectCapabilities(accepted, offered).length !== accepted.length) { throw new Error('Server selected a capability that the peer did not offer.') } return [...accepted] } export interface RemoteMessage { v: typeof PROTOCOL_VERSION id: string type: MessageType timestamp: number payload: TPayload } export interface RpcRequestPayload { method: RpcMethod params: TParams } export type AcpBackend = 'cursor' | 'claude' | 'opencode' | 'pi' | 'hermes' | 'antigravity' | (string & {}) export interface AcpInitializeParams { protocolVersion: 1; backend?: AcpBackend } export interface AcpInitializeResult { protocolVersion: 1; capability: typeof ACP_CAPABILITY; backend: AcpBackend; capabilities: string[]; availableBackends?: AcpBackend[] } export interface AcpSessionParams { sessionId?: string; cwd?: string; mode?: string; backend?: AcpBackend } export interface AcpPromptParams { sessionId: string; prompt: string; images?: Array<{ mimeType: string; data: string }> } export interface AcpPermissionResponseParams { sessionId: string; requestId: string; decision: 'allow_once' | 'deny' } export interface AcpCancelParams { sessionId: string } export interface AcpSetModeParams { sessionId: string; mode: string } export interface AcpSessionUpdate { sessionId: string; update: unknown; seq: number } export interface RpcResponsePayload { requestId: string result: TResult } export interface RpcErrorPayload { requestId: string /** §23 defines standard codes. Subsystems can add names such as CODEX_* and FILE_VIEWER_*. */ code: ErrorCode | (string & {}) message: string retryable?: boolean details?: unknown } export interface EventPayload { seq?: number event: RemoteEventName sessionId?: string data: TData } export interface DeviceDescriptor { deviceId: string name: string role: 'host' | 'client' platform: string identityKey: string clientVersion: string harnessVersion?: string } export interface TransportStats { mode: 'LAN' | 'P2P' | 'TURN' | 'Relay' | 'Disconnected' connected: boolean rttMs?: number bytesSent?: number bytesReceived?: number } /** Local plugin web route call tunneled inside the authenticated business channel. */ export interface PluginRouteCallParams { route: string body: { endpoint: string; payload?: Record | null } } export interface PluginRouteCallResult { status: number json: unknown } /** Native Harness API request tunneled inside the authenticated business channel. */ export interface HarnessApiCallParams { method: string rpcId: string payload: unknown } export interface HarnessApiTransferOpenParams { transferId: string totalBytes: number totalChunks: number } export interface HarnessApiTransferChunkParams { transferId: string index: number data: string } export interface HarnessApiTransferCommitParams { transferId: string } export interface HarnessApiTransferReadParams { transferId: string index: number } export interface HarnessApiTransferCloseParams { transferId: string } export type HarnessApiTransferCommitResult = | { kind: 'inline'; response: unknown } | { kind: 'chunked'; transferId: string; totalBytes: number; totalChunks: number } export interface HarnessApiTransferReadResult { transferId: string index: number data: string } /** Response to an answerable native Harness server request (approval/question). */ export interface HarnessApiRespondParams { message: { type: 'client-response' rpcId: string result: unknown } } export interface HarnessApiStreamOpenParams { streamId: string stream: 'mux' | 'host' rpcId: string payload: { /** Optional mux focus: only forward frames for this session. */ sessionId?: string } } export interface HarnessApiStreamCloseParams { streamId: string } export interface HarnessApiFrameData { streamId: string frame: { rpcId: string payload: unknown } } export interface HarnessApiStreamClosedData { streamId: string reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' } /** Alpha Typert Remote carrier request after the local Gateway encoded it. */ export interface HarnessRemoteCallParams { endpoint: string payload: unknown } export interface HarnessRemoteStreamOpenParams { streamId: string endpoint: string payload: unknown /** Opt in only after the Host advertises harness.remote.stream.transfer.v1. */ transferFrames?: boolean } export interface HarnessRemoteStreamCloseParams { streamId: string } export interface HarnessRemoteFrameData { streamId: string hasValue: true value?: unknown /** Mutually exclusive with value; reads reconstruct the complete original frame. */ transfer?: Extract } export interface HarnessRemoteStreamClosedData { streamId: string reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' failure?: { code: string message: string details: Record } } export interface RemoteWorkspaceTypeDescription { id: string name: string capability: string available: boolean } /** Read-only history delivery preference, scoped to one authenticated connection. */ export interface RemoteHistoryConfigureParams { compact: boolean } export interface HarnessTransportDescription { capabilities: string[] workspaceTypes?: RemoteWorkspaceTypeDescription[] } export type CodexPermissionPreset = 'workspace-write' | 'danger-full-access' /** Optional dsh/sessionHistory metadata; null means the Host has no confirmed preset. */ export interface CodexPermissionSnapshot { permissionPreset?: CodexPermissionPreset | null } /** Fixed allowlisted Codex App Server call carried inside Remote. */ export interface CodexAppCallParams { method: string params: unknown } export interface CodexAppRespondParams { requestHandle: string decision: 'accept' | 'decline' | 'cancel' } export interface CodexAppStreamOpenParams { streamId: string threadId: string } export interface CodexAppStreamCloseParams { streamId: string } export interface CodexAppFrameData { streamId: string frame: { method: string params: unknown } } export interface CodexAppStreamClosedData { streamId: string reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' } export interface CodexAppTransferOpenParams { transferId: string totalBytes: number totalChunks: number } export interface CodexAppTransferChunkParams { transferId: string index: number data: string } export interface CodexAppTransferCommitParams { transferId: string } export interface CodexAppTransferReadParams { transferId: string; index: number } export interface CodexAppTransferCloseParams { transferId: string } export type CodexAppTransferCommitResult = | { kind: 'inline'; response: unknown } | { kind: 'chunked'; transferId: string; totalBytes: number; totalChunks: number } export interface CodexAppTransferReadResult { transferId: string index: number data: string } /** Fixed allowlisted Agent ACP call carried inside Remote. */ export interface AgentAcpCallParams { method: string params: unknown } export interface AcpSessionArchivedData { backend: 'opencode'; sessionId: string; archived: true } export interface AgentAcpRespondParams { requestHandle: string decision: 'allow-once' | 'reject-once' | 'cancel' /** Optional structured answer for backend extension methods (ask_question / create_plan). */ result?: unknown } export type AcpWorkspaceToolCallEndpoint = 'workspaceFiles/list' | 'workspaceFiles/stat' | 'workspaceFiles/read' | 'workspaceFiles/readBytes' | 'workspaceFiles/readAll' | 'terminal/environment' | 'terminal/shells' | 'terminal/list' | 'terminal/create' | 'terminal/write' | 'terminal/resize' | 'terminal/rename' | 'terminal/close' export type AcpWorkspaceToolStreamEndpoint = 'workspaceFiles/changes' | 'terminal/follow' | 'terminal/retain' export interface AcpWorkspaceToolParams { sessionId: string; backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes'; endpoint: AcpWorkspaceToolCallEndpoint; args: Record } export interface AcpModelParams { sessionId: string; backend: 'cursor' | 'claude' | 'antigravity' | 'pi' | 'opencode' } export interface AcpModelSelectionParams extends AcpModelParams { model: string; reasoningEffort?: string } export interface AgentAcpStreamOpenParams { streamId: string sessionId: string tool?: { backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes'; endpoint: AcpWorkspaceToolStreamEndpoint; args: Record } } export interface AgentAcpStreamCloseParams { streamId: string } export interface AgentAcpFrameData { streamId: string frame: { method: string params: unknown } } export interface AgentAcpStreamClosedData { streamId: string reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' } export interface AgentAcpTransferOpenParams { transferId: string totalBytes: number totalChunks: number } export interface AgentAcpTransferChunkParams { transferId: string index: number data: string } export interface AgentAcpTransferCommitParams { transferId: string } export interface AgentAcpTransferReadParams { transferId: string; index: number } export interface AgentAcpTransferCloseParams { transferId: string } export type AgentAcpTransferCommitResult = | { kind: 'inline'; response: unknown } | { kind: 'chunked'; transferId: string; totalBytes: number; totalChunks: number } export interface AgentAcpTransferReadResult { transferId: string index: number data: string } const rpcMethodSchema = z.enum(rpcMethods) const messageTypeSchema = z.enum(messageTypes) const controlFrameTypeSchema = z.enum(controlFrameTypes) export const errorCodeSchema = z.enum(errorCodes) const uniqueStrings = (values: string[]): boolean => new Set(values).size === values.length const uniqueNumbers = (values: number[]): boolean => new Set(values).size === values.length const utf8Length = (value: string): number => new TextEncoder().encode(value).byteLength const boundedUtf8Schema = (minimum: number, maximum: number): z.ZodType => z.string() .refine(value => utf8Length(value) >= minimum && utf8Length(value) <= maximum) const deviceIdSchema = z.string().refine(value => ( /^[0-9A-HJKMNP-TV-Z]{26}$/iu.test(value) || /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value) ), 'Device ID must be a ULID or UUID.') const deviceNameSchema = boundedUtf8Schema(1, MAX_DEVICE_NAME_LENGTH) .refine(value => value.trim().length > 0, 'Device name must contain visible text.') const devicePlatformSchema = z.string().min(1).max(MAX_DEVICE_PLATFORM_LENGTH) .regex(/^[a-z0-9][a-z0-9._-]*$/u) const identityKeySchema = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/u) const canonicalBase64UrlSchema = z.string().min(1).regex(/^[A-Za-z0-9_-]+$/u).refine(value => { const remainder = value.length % 4 if (remainder === 1) return false if (remainder === 0) return true const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_' const last = alphabet.indexOf(value.at(-1)!) return remainder === 2 ? (last & 15) === 0 : (last & 3) === 0 }, 'Value must use canonical Base64URL without padding.') const deviceVersionSchema = boundedUtf8Schema(1, MAX_DEVICE_VERSION_LENGTH) const authTokenSchema = boundedUtf8Schema(16, MAX_AUTH_TOKEN_LENGTH) const expiresAtSchema = z.number().int().positive().safe() export const hostDeviceDescriptorSchema: z.ZodType = z.object({ deviceId: deviceIdSchema, name: deviceNameSchema, role: z.literal('host'), platform: devicePlatformSchema, identityKey: identityKeySchema, clientVersion: deviceVersionSchema, harnessVersion: deviceVersionSchema.optional(), }).strict() export const clientDeviceDescriptorSchema: z.ZodType = z.object({ deviceId: deviceIdSchema, name: deviceNameSchema, role: z.literal('client'), platform: devicePlatformSchema, identityKey: identityKeySchema, clientVersion: deviceVersionSchema, }).strict() export const accountDeviceDescriptorSchema: z.ZodType = z.union([ hostDeviceDescriptorSchema, clientDeviceDescriptorSchema, ]) export const deviceRegistrationRequestSchema: z.ZodType = z.object({ v: z.literal(PROTOCOL_VERSION), device: accountDeviceDescriptorSchema, }).strict() export const hostRegistrationCodeRequestSchema: z.ZodType = z.object({ v: z.literal(PROTOCOL_VERSION), code: z.string().regex(/^[A-Z0-9]{4}-[A-Z0-9]{4}$/u), device: hostDeviceDescriptorSchema, }).strict() /** §8.1.2 Register a new opposite-role device using an existing device access token. */ export interface RegisterOwnedRoleRequest { v: typeof PROTOCOL_VERSION device: AccountDeviceDescriptor } export const registerOwnedRoleRequestSchema: z.ZodType = z.object({ v: z.literal(PROTOCOL_VERSION), device: accountDeviceDescriptorSchema, }).strict() export const deviceRefreshRequestSchema: z.ZodType = z.object({ deviceId: deviceIdSchema, refreshToken: authTokenSchema, }).strict() export const deviceTokenPairSchema: z.ZodType = z.object({ accessToken: authTokenSchema, accessTokenExpiresAt: expiresAtSchema, refreshToken: authTokenSchema, refreshTokenExpiresAt: expiresAtSchema, }).strict() export const browserAuthorizationExchangeRequestSchema: z.ZodType = z.object({ v: z.literal(PROTOCOL_VERSION), device: z.object({ deviceId: deviceIdSchema, name: deviceNameSchema, role: z.literal('client'), platform: z.literal('browser'), identityKey: identityKeySchema, clientVersion: deviceVersionSchema, }).strict(), }).strict() export const browserAuthorizationExchangeResponseSchema: z.ZodType = z.object({ accessToken: authTokenSchema, accessTokenExpiresAt: expiresAtSchema, refreshToken: authTokenSchema, refreshTokenExpiresAt: expiresAtSchema, account: boundedUtf8Schema(1, 254).refine(value => value.trim().length > 0), }).strict() export const remoteMessageSchema = z.object({ v: z.literal(PROTOCOL_VERSION), id: z.string().min(1), type: messageTypeSchema, timestamp: z.number().int().positive(), payload: z.unknown(), }) as unknown as z.ZodType export const controlFrameSchema = z.object({ v: z.literal(PROTOCOL_VERSION), id: z.string().min(1), type: controlFrameTypeSchema, timestamp: z.number().int().positive(), payload: z.unknown(), }).strict() as unknown as z.ZodType export const relayDataFrameSchema: z.ZodType = z.object({ v: z.literal(PROTOCOL_VERSION), id: z.string().min(1), type: z.string().min(1), timestamp: z.number().int().positive().safe(), payload: z.record(z.string(), z.unknown()), }).strict() // ──────────────────────────────────────────────────────────────────────────── // Control frame payload schemas (protocol.md §10-§23) // ──────────────────────────────────────────────────────────────────────────── const transportEnum = z.enum(['lan', 'p2p', 'turn', 'relay']) const selectedTransportEnum = z.enum(selectedTransports) const MAX_PROTOCOL_LIST_ENTRIES = 16 const MAX_CAPABILITY_ENTRIES = MAX_REMOTE_CAPABILITY_ENTRIES const MAX_WORKSPACE_TYPE_ENTRIES = MAX_REMOTE_WORKSPACE_TYPE_ENTRIES const MAX_PREFERRED_TRANSPORT_ENTRIES = selectedTransports.length export const helloPayloadSchema = z.object({ recoveryTickets: z.array(z.string().min(1).max(4096)).max(64).optional(), role: z.enum(['host', 'client']), deviceId: z.string().min(1), accessToken: z.string().min(1), protocols: z.array(z.unknown()).min(1).max(MAX_PROTOCOL_LIST_ENTRIES).pipe( z.array(z.number().int().nonnegative().safe()).refine(uniqueNumbers), ), capabilities: z.array(z.unknown()).max(MAX_CAPABILITY_ENTRIES).pipe( z.array(z.string().min(1)).refine(uniqueStrings), ), clientVersion: z.string().optional(), harnessVersion: z.string().optional(), }) export const helloAckPayloadSchema = z.object({ protocol: z.literal(PROTOCOL_VERSION), serverVersion: z.string().min(1), connectionSessionId: z.string().min(1), heartbeatIntervalMs: z.number().int().positive().safe(), maxControlFrameBytes: z.number().int().positive().max(MAX_CONTROL_FRAME_BYTES), maxRelayFrameBytes: z.number().int().positive().max(MAX_RELAY_FRAME_BYTES), capabilities: z.array(z.unknown()).max(MAX_CAPABILITY_ENTRIES).pipe( z.array(z.string().min(1)).refine(uniqueStrings), ).optional(), webrtcEnabled: z.boolean().optional(), webrtcFallbackTimeoutMs: z.number().int().positive().safe().optional(), }) export const remoteWorkspaceTypeDescriptionSchema = z.object({ id: z.string().min(1), name: z.string().min(1), capability: z.string().min(1), available: z.boolean(), }) export const harnessTransportDescriptionSchema = z.object({ capabilities: z.array(z.unknown()).max(MAX_CAPABILITY_ENTRIES).pipe( z.array(z.string().min(1)).refine(uniqueStrings), ), workspaceTypes: z.array(z.unknown()).max(MAX_WORKSPACE_TYPE_ENTRIES).pipe( z.array(remoteWorkspaceTypeDescriptionSchema), ).optional(), }) export function parseRemoteWorkspaceTypes(value: unknown): RemoteWorkspaceTypeDescription[] { if (!Array.isArray(value)) return [] if (value.length > MAX_WORKSPACE_TYPE_ENTRIES) return [] const types: RemoteWorkspaceTypeDescription[] = [] for (const item of value) { const result = remoteWorkspaceTypeDescriptionSchema.safeParse(item) if (result.success) { types.push(result.data) } } return types } export const connectRequestPayloadSchema = z.object({ hostDeviceId: z.string().min(1), preferredTransports: z.array(z.unknown()).min(1).max(MAX_PREFERRED_TRANSPORT_ENTRIES).pipe( z.array(transportEnum), ), }) export const connectIncomingPayloadSchema = z.object({ relayRecoveryTicket: z.string().min(1).max(4096).optional(), recoveryTicket: z.string().min(1).max(4096).optional(), connectionId: z.string().min(1), clientDeviceId: z.string().min(1), clientIdentityKey: identityKeySchema, authorization: z.literal('account'), preferredTransports: z.array(z.unknown()).min(1).max(MAX_PREFERRED_TRANSPORT_ENTRIES).pipe( z.array(transportEnum), ), relayEndpoint: z.string().url().optional(), relayTicket: z.string().min(1).optional(), relayNodeId: z.string().min(1).optional(), relayEpoch: z.number().int().nonnegative().optional(), }) export const connectAcceptedPayloadSchema = z.object({ relayRecoveryTicket: z.string().min(1).max(4096).optional(), recoveryTicket: z.string().min(1).max(4096).optional(), connectionId: z.string().min(1), relayEndpoint: z.string().url().optional(), relayTicket: z.string().min(1).optional(), relayNodeId: z.string().min(1).optional(), relayEpoch: z.number().int().nonnegative().optional(), }) export const connectRejectedPayloadSchema = z.object({ connectionId: z.string().min(1), code: z.string().optional(), message: z.string().optional(), }) export const secureHandshakePayloadSchema = z.object({ connectionId: z.string().min(1), targetDeviceId: z.string().min(1), step: z.union([z.literal(1), z.literal(2)]), data: canonicalBase64UrlSchema, }) export const relayPayloadSchema = z.object({ connectionId: z.string().min(1), targetDeviceId: z.string().min(1), counter: z.number().int().nonnegative().safe(), ciphertext: canonicalBase64UrlSchema, }) export const signalPayloadSchema = z.object({ connectionId: z.string().min(1), targetDeviceId: z.string().min(1), sdp: z.string().min(1), }) export const signalIcePayloadSchema = z.object({ connectionId: z.string().min(1), targetDeviceId: z.string().min(1), candidate: z.object({ candidate: z.string().optional(), sdpMid: z.string().nullable().optional(), sdpMLineIndex: z.preprocess(normalizeSdpMLineIndex, z.number().int().nonnegative().nullable().optional()), usernameFragment: z.string().nullable().optional(), }), }) export const transportSelectedPayloadSchema = z.object({ connectionId: z.string().min(1), targetDeviceId: z.string().min(1), transport: selectedTransportEnum, /** Relay hostname the initiator actually used when transport is "turn" * (best-effort, from ICE stats; absent for other transports). */ turnNode: z.string().min(1).max(253).optional(), }) export const pingPongPayloadSchema = z.object({ nonce: z.string().min(1), }) export const controlErrorPayloadSchema = z.object({ code: z.string().min(1), message: z.string().min(1), retryable: z.boolean().optional(), connectionId: z.string().min(1).optional(), }) export const connectionLeaseRequestSchema = z.object({ connectionId: z.string().min(1).max(128), requestId: z.string().min(1).max(128), ticket: z.string().min(1).max(4096), }) export const connectionLeaseAckSchema = connectionLeaseRequestSchema.extend({ leaseMs: z.literal(WEBRTC_LEASE_MS), }) export type ConnectionLeaseAck = z.infer const controlFramePayloadSchemas: Record = { 'hello': helloPayloadSchema, 'hello.ack': helloAckPayloadSchema, 'connect.request': connectRequestPayloadSchema, 'connect.incoming': connectIncomingPayloadSchema, 'connect.accepted': connectAcceptedPayloadSchema, 'connect.rejected': connectRejectedPayloadSchema, 'secure.handshake': secureHandshakePayloadSchema, 'relay': relayPayloadSchema, 'signal.offer': signalPayloadSchema, 'signal.answer': signalPayloadSchema, 'signal.ice': signalIcePayloadSchema, 'transport.selected': transportSelectedPayloadSchema, 'connection.lease.request': connectionLeaseRequestSchema, 'connection.lease.ack': connectionLeaseAckSchema, 'connection.lease.close': z.object({ connectionId: z.string().min(1).max(128) }), 'ping': pingPongPayloadSchema, 'pong': pingPongPayloadSchema, 'error': controlErrorPayloadSchema, } export const rpcRequestPayloadSchema = z.object({ method: rpcMethodSchema, params: z.unknown(), }) as unknown as z.ZodType export const rpcResponsePayloadSchema = z.object({ requestId: z.string().min(1), result: z.unknown(), }) as unknown as z.ZodType export const rpcErrorPayloadSchema: z.ZodType = z.object({ requestId: z.string().min(1), code: z.string().min(1), message: z.string().min(1), retryable: z.boolean().optional(), details: z.unknown().optional(), }) export function createMessage( type: MessageType, payload: TPayload, id = cryptoRandomId(), ): RemoteMessage { return { v: PROTOCOL_VERSION, id, type, timestamp: Date.now(), payload, } } export function createControlFrame( type: ControlFrameType, payload: TPayload, id = cryptoRandomId(), ): ControlFrame { return { v: PROTOCOL_VERSION, id, type, timestamp: Date.now(), payload, } } export function createRelayDataFrame>( type: string, payload: TPayload, id = cryptoRandomId(), ): RelayDataFrame { return { v: PROTOCOL_VERSION, id, type, timestamp: Date.now(), payload, } } export function createRpcRequest( method: RpcMethod, params: TParams, id?: string, ): RemoteMessage> { return createMessage('rpc.request', { method, params }, id) } export function createRpcResponse( requestId: string, result: TResult, ): RemoteMessage> { return createMessage('rpc.response', { requestId, result }) } export function createRpcError( requestId: string, code: ErrorCode | (string & {}), message: string, details?: unknown, retryable?: boolean, ): RemoteMessage { return createMessage('rpc.error', { requestId, code, message, details, retryable }) } export function createEvent( event: RemoteEventName, data: TData, options: { seq?: number; sessionId?: string } = {}, ): RemoteMessage> { return createMessage('event', { event, data, ...options }) } export function parseRemoteMessage(input: unknown): RemoteMessage { return remoteMessageSchema.parse(input) } export function parseControlFrame(input: unknown): ControlFrame { const frame = controlFrameSchema.parse(input) const payloadSchema = controlFramePayloadSchemas[frame.type] if (payloadSchema) { return { ...frame, payload: payloadSchema.parse(frame.payload) } } return frame } export function encodeControlFrame(frame: ControlFrame, limits: ControlFrameByteLimits = {}): string { const parsed = parseControlFrame(frame) const encoded = JSON.stringify(parsed) assertControlFrameSize(new TextEncoder().encode(encoded).byteLength, parsed.type, limits) return encoded } export function decodeControlFrame(data: Uint8Array | string, limits: ControlFrameByteLimits = {}): ControlFrame { const encoded = typeof data === 'string' ? new TextEncoder().encode(data) : data if (encoded.byteLength > MAX_RELAY_FRAME_BYTES) throw new Error('Control frame exceeds the Relay frame limit.') const frame = parseControlFrame(parseWireJson(data)) assertControlFrameSize(encoded.byteLength, frame.type, limits) return frame } export function encodeRelayDataFrame( frame: RelayDataFrame, limits: ControlFrameByteLimits = {}, ): string { const parsed = parseRelayDataFrame(frame) const encoded = JSON.stringify(parsed) assertControlFrameSize(new TextEncoder().encode(encoded).byteLength, 'relay', limits) return encoded } export function decodeRelayDataFrame( data: Uint8Array | string, limits: ControlFrameByteLimits = {}, ): RelayDataFrame { const encoded = typeof data === 'string' ? new TextEncoder().encode(data) : data assertControlFrameSize(encoded.byteLength, 'relay', limits) try { return parseRelayDataFrame(parseWireJson(data)) } catch { throw new Error('Invalid Relay data frame.') } } function parseRelayDataFrame(input: unknown): RelayDataFrame { const frame = relayDataFrameSchema.parse(input) if (frame.type === 'relay') return { ...frame, payload: relayPayloadSchema.parse(frame.payload) } if (frame.type === 'secure.handshake') return { ...frame, payload: secureHandshakePayloadSchema.parse(frame.payload) } return frame } export function encodeMessage(message: RemoteMessage): Uint8Array { return new TextEncoder().encode(JSON.stringify(message)) } export function decodeMessage(data: Uint8Array | string): RemoteMessage { return parseRemoteMessage(parseWireJson(data)) } interface FragmentAssembly { total: number totalBytes: number receivedBytes: number chunks: Uint8Array[] } /** * Splits application plaintext before Noise encryption and reassembles it * after decryption. Noise transport messages have a 65,535-byte ceiling, so * large native ApiProxy responses cannot be encrypted as one message. */ export class SecureMessageCodec { private nextMessageId = 1 private readonly assemblies = new Map() encode(message: Uint8Array): Uint8Array[] { if (message.byteLength > MAX_SECURE_MESSAGE_BYTES) { throw new Error('Secure message exceeds the reassembly limit.') } if (message.byteLength <= SECURE_FRAGMENT_CHUNK_BYTES) return [message] const messageId = this.nextMessageId this.nextMessageId = messageId === 0xffff_ffff ? 1 : messageId + 1 const total = Math.ceil(message.byteLength / SECURE_FRAGMENT_CHUNK_BYTES) const frames: Uint8Array[] = [] for (let index = 0; index < total; index += 1) { const start = index * SECURE_FRAGMENT_CHUNK_BYTES const chunk = message.subarray(start, Math.min(message.byteLength, start + SECURE_FRAGMENT_CHUNK_BYTES)) const frame = new Uint8Array(SECURE_FRAGMENT_HEADER_BYTES + chunk.byteLength) frame.set(SECURE_FRAGMENT_MAGIC) frame[4] = SECURE_FRAGMENT_VERSION const view = new DataView(frame.buffer) view.setUint32(5, messageId) view.setUint16(9, index) view.setUint16(11, total) view.setUint32(13, message.byteLength) frame.set(chunk, SECURE_FRAGMENT_HEADER_BYTES) frames.push(frame) } return frames } decode(frame: Uint8Array): Uint8Array | undefined { if (!isSecureFragment(frame)) return frame if (frame.byteLength < SECURE_FRAGMENT_HEADER_BYTES || frame[4] !== SECURE_FRAGMENT_VERSION) { throw new Error('Secure fragment header is invalid.') } const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength) const messageId = view.getUint32(5) const index = view.getUint16(9) const total = view.getUint16(11) const totalBytes = view.getUint32(13) if (messageId === 0 || total < 2 || index >= total || totalBytes <= SECURE_FRAGMENT_CHUNK_BYTES || totalBytes > MAX_SECURE_MESSAGE_BYTES || total !== Math.ceil(totalBytes / SECURE_FRAGMENT_CHUNK_BYTES)) { throw new Error('Secure fragment metadata is invalid.') } const expectedChunkBytes = Math.min( SECURE_FRAGMENT_CHUNK_BYTES, totalBytes - index * SECURE_FRAGMENT_CHUNK_BYTES, ) const chunk = frame.subarray(SECURE_FRAGMENT_HEADER_BYTES) if (chunk.byteLength !== expectedChunkBytes) throw new Error('Secure fragment length is invalid.') let assembly = this.assemblies.get(messageId) if (assembly === undefined) { if (index !== 0 || this.assemblies.size >= MAX_IN_FLIGHT_SECURE_MESSAGES) { throw new Error('Secure fragment sequence is invalid.') } assembly = { total, totalBytes, receivedBytes: 0, chunks: [] } this.assemblies.set(messageId, assembly) } if (assembly.total !== total || assembly.totalBytes !== totalBytes || index !== assembly.chunks.length) { this.assemblies.delete(messageId) throw new Error('Secure fragment sequence is invalid.') } assembly.chunks.push(Uint8Array.from(chunk)) assembly.receivedBytes += chunk.byteLength if (assembly.chunks.length < total) return undefined this.assemblies.delete(messageId) if (assembly.receivedBytes !== totalBytes) throw new Error('Secure message length is invalid.') const message = new Uint8Array(totalBytes) let offset = 0 for (const part of assembly.chunks) { message.set(part, offset) offset += part.byteLength } return message } reset(): void { this.nextMessageId = 1 this.assemblies.clear() } } function isSecureFragment(frame: Uint8Array): boolean { if (frame.byteLength < SECURE_FRAGMENT_MAGIC.byteLength) return false for (let index = 0; index < SECURE_FRAGMENT_MAGIC.byteLength; index += 1) { if (frame[index] !== SECURE_FRAGMENT_MAGIC[index]) return false } return true } function assertControlFrameSize(bytes: number, type: ControlFrameType, limits: ControlFrameByteLimits): void { const configured = type === 'relay' ? limits.maxRelayFrameBytes : limits.maxControlFrameBytes const protocolMaximum = type === 'relay' ? MAX_RELAY_FRAME_BYTES : MAX_CONTROL_FRAME_BYTES const maximum = configured === undefined ? protocolMaximum : Math.min(protocolMaximum, configured) if (!Number.isSafeInteger(maximum) || maximum <= 0) throw new Error('Control frame limit is invalid.') if (bytes > maximum) throw new Error(`${type === 'relay' ? 'Relay' : 'Control'} frame exceeds its limit.`) } function cryptoRandomId(): string { const g = globalThis.crypto if (g?.randomUUID) return g.randomUUID() return `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}` }