diff --git a/packages/plugin/src/client-runtime-contract.ts b/packages/plugin/src/client-runtime-contract.ts new file mode 100644 index 0000000..48666f6 --- /dev/null +++ b/packages/plugin/src/client-runtime-contract.ts @@ -0,0 +1,277 @@ +import type { ControlResult } from './control-result.js' +import { RemoteClientCore } from '@dsh-remote/client-core' +import type { CodexAppFrameData, CodexAppStreamClosedData, RemoteWorkspaceTypeDescription } from '@dsh-remote/protocol' +import type { RtcConnectionDiagnostics, RtcIceServer } from '@dsh-remote/webrtc' +import { AdaptiveTransport, stunOnlyIceServers } from '@dsh-remote/webrtc' +import type { ResolvedConfig } from './config.js' +import type { TrustedPeer } from './identity-store.js' +import type { AuthorizedPeerDevice, ServerHostDevice } from './server-api.js' + +export interface ConnectedRemote { + client: RemoteClientCore + target: TrustedPeer + transport: AdaptiveTransport + features: RemoteHostFeatures + progressRunId: number + clientVersion?: string + harnessVersion?: string +} + +export interface RemoteHostFeatures { + commandList: boolean + fileViewer: boolean + terminal: boolean + remoteGateway: boolean + sessionFormat?: 3 + codex: boolean + cursor: boolean + antigravity: boolean + pi?: boolean + opencode: boolean + claude?: boolean + hermes?: boolean + acpModelLoadsSession?: boolean + workspaceTypes?: readonly RemoteWorkspaceTypeDescription[] + pluginRoute: boolean +} + +export interface CodexLoopbackStream { + target: { kind: 'remote'; client: RemoteClientCore } | { kind: 'local' } + frames: Array<{ method: string; params: unknown }> + closed?: string + unsubscribe: () => void + close: () => Promise + wake: () => void +} + +export const DIRECT_WEBRTC_NEGOTIATE_TIMEOUT_MS = 12_000 + +export const DIRECT_LAN_PROGRESS_DISPLAY_MS = 1_400 + +export const HOST_AUTHORIZATION_ERRORS = new Set([ + 'ACCOUNT_AUTH_REQUIRED', + 'AUTH_INVALID', + 'DEVICE_OWNERSHIP_REQUIRED', + 'DEVICE_REVOKED', + 'TOKEN_EXPIRED', +]) + +export type TransportAttempt = 'direct' | 'turn' | 'relay' + +export interface ConnectionProgressState { + runId: number + targetDeviceId: string + phase: 'checking-host' | 'authorizing-peer' | 'probing' | 'connected' + activeTransports?: Array<'lan' | 'p2p' | 'turn' | 'relay'> +} + +export interface RemoteDirectoryEntry { + name: string + path: string + hidden: boolean +} + +export interface RemoteDirectoryListing { + path: string + home: string + crumbs: RemoteDirectoryEntry[] + entries: RemoteDirectoryEntry[] + truncated: boolean +} + +export interface RemoteWorkspaceView { + workspaceId: string + path: string + title: string +} + +export interface RemoteWorkspaceSelection { + targetDeviceId: string + workspaceId: string + backend?: 'harness' | 'codex' | 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' + sessionId?: string +} + +export interface RemoteDeviceView { + deviceId: string + name: string + platform: string + membershipId: string + online: boolean + lastSeenAt?: number + clientVersion?: string + harnessVersion?: string +} + +export interface HostConnectionRpc { + handle( + channel: string, + handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise>, + options: { authority: 'loopback' | 'trusted-host' }, + ): () => Promise +} + +export interface HostConnectionHandle { + requestRejection?(request: { headers: Record }): number | undefined + rpc: HostConnectionRpc +} + +export interface HostAuthorizationControl { + setAgentBackends?(config: ResolvedConfig): Promise + setTerminalEnabled?(enabled: boolean): void + setLoopbackPorts?(ports: readonly number[]): void + pairingControl?(action: 'start' | 'status' | 'confirm' | 'cancel', input: { sessionId?: string; verificationCode?: string }): Promise + hostStatus(): { + deviceId?: string + configured: boolean + online: boolean + reconnecting: boolean + recoveryExpiresAt?: number + lastActiveAt?: number + error?: string + account?: string + authorized: boolean + accountRequired: boolean + pairingHostOnly?: boolean + connectedClients?: Array<{ + deviceId: string + name: string + platform?: string + mode?: 'LAN' | 'P2P' | 'TURN' | 'Relay' + }> + } + hasStoredAuthorization?(): Promise + reconnectHost(): void + clearHostAuthorization(): Promise + localHarnessVersion?(): string | undefined + authorizeHostAsOwned(accessToken: string, account?: string): Promise + authorizeHostWithAccount(email: string, password: string): Promise + authorizeHostWithCode(code: string): Promise + codexStatus?(): { available: boolean } + codexCall?(input: unknown, signal?: AbortSignal): Promise + codexRespond?(input: unknown, signal?: AbortSignal): Promise<{ resolved: true }> + codexOpenStream?( + input: unknown, + publish: (event: 'codex.app.frame' | 'codex.app.stream.closed', data: CodexAppFrameData | CodexAppStreamClosedData) => Promise, + signal?: AbortSignal, + ): Promise + codexCloseStream?(input: unknown): Promise +} + +export class ClientModeError extends Error { + constructor(readonly code: string, message: string, readonly retryable = false) { super(message) } +} + +export function assertAuthorizedHost(listed: ServerHostDevice, descriptor: AuthorizedPeerDevice): void { + if (descriptor.role !== 'host' || descriptor.deviceId !== listed.deviceId + || descriptor.membershipId !== listed.membershipId) { + throw new ClientModeError('PEER_IDENTITY_MISMATCH', 'Server Host details do not match the authorized device list.') + } +} + +export function websocketUrl(baseUrl: string): string { + const url = new URL(baseUrl) + url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:' + url.pathname = `${url.pathname.replace(/\/$/, '')}/ws/v1/connect` + return url.toString() +} + +export function webrtcDiagnosticsLogFields(diagnostics: RtcConnectionDiagnostics | undefined): Record { + if (diagnostics === undefined) return {} + return { + rtcConnectionState: diagnostics.connectionState, + rtcIceConnectionState: diagnostics.iceConnectionState, + rtcIceGatheringState: diagnostics.iceGatheringState, + rtcLocalCandidates: diagnostics.localCandidates, + rtcRemoteCandidates: diagnostics.remoteCandidates, + rtcCandidatePairs: diagnostics.candidatePairs, + rtcFilteredLocalCandidates: diagnostics.filteredLocalCandidates, + rtcFilteredCandidatePairs: diagnostics.filteredCandidatePairs, + ...(diagnostics.selectedPath === undefined ? {} : { rtcSelectedPath: diagnostics.selectedPath }), + } +} + +export function record(value: unknown): Record { + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new ClientModeError('INVALID_MESSAGE', 'The control request payload is invalid.') + } + return value as Record +} + +export function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +export function ok(value: unknown): ControlResult { return { ok: true, value } } + +export function fail(error: unknown): ControlResult { + const source = error instanceof Error ? error : undefined + const remoteCode = source !== undefined && 'code' in source && typeof source.code === 'string' + ? source.code + : source instanceof ClientModeError ? source.code : undefined + const retryable = source !== undefined && 'retryable' in source && typeof source.retryable === 'boolean' + ? source.retryable + : source instanceof ClientModeError ? source.retryable : false + return { + ok: false, + error: { + code: 'internal', + message: source?.message ?? 'The remote-mode operation failed.', + details: remoteCode === undefined ? {} : { remoteCode, retryable }, + }, + } +} + +export function shortId(value: string): string { return value.length <= 12 ? value : `${value.slice(0, 8)}…${value.slice(-4)}` } + +export async function waitForCodexFrames(stream: CodexLoopbackStream, signal?: AbortSignal): Promise { + if (signal?.aborted) throw new ClientModeError('RPC_ABORTED', 'The Codex event poll was cancelled.') + await new Promise((resolve, reject) => { + const previousWake = stream.wake + const timer = setTimeout(done, 25_000) + const onAbort = () => { + cleanup() + reject(new ClientModeError('RPC_ABORTED', 'The Codex event poll was cancelled.')) + } + function cleanup() { + clearTimeout(timer) + stream.wake = previousWake + signal?.removeEventListener('abort', onAbort) + } + function done() { + cleanup() + resolve() + } + stream.wake = () => { + previousWake() + done() + } + signal?.addEventListener('abort', onAbort, { once: true }) + }) +} + +export function diagnosticReason(error: Error): string { + const code = 'code' in error && typeof error.code === 'string' ? error.code : undefined + const message = error.message.replace(/[\r\n\t]+/g, ' ').slice(0, 240) + return code === undefined ? message : `${code}: ${message}` +} + +export function preferredTransportsForAttempt(attempt: TransportAttempt): Array<'lan' | 'p2p' | 'turn' | 'relay'> { + if (attempt === 'direct') return ['lan', 'p2p', 'relay'] + if (attempt === 'turn') return ['turn', 'relay'] + return ['relay'] +} + +export function transportPreferenceForMode( + mode: 'LAN' | 'P2P' | 'TURN' | 'Relay' | 'Disconnected', +): 'lan' | 'p2p' | 'turn' | 'relay' | undefined { + if (mode === 'LAN') return 'lan' + if (mode === 'P2P') return 'p2p' + if (mode === 'TURN') return 'turn' + if (mode === 'Relay') return 'relay' + return undefined +} + +export function iceServersForAttempt(attempt: TransportAttempt, iceServers: RtcIceServer[]): RtcIceServer[] { + return attempt === 'direct' ? stunOnlyIceServers(iceServers) : iceServers +}