import { uploadLocalMentions } from './local-mention-upload.js' import type { ControlResult } from './control-result.js' import { AgentAcpClient, CodexRemoteClient } from '@dsh-remote/client-core' import type { PluginRouteCallResult } from '@dsh-remote/protocol' import type { RtcPeerConnectionFactory } from '@dsh-remote/webrtc' import type { AcpVirtualWorkspaceView } from './acp/virtual-harness.js' import { acpCwdWorkspaceId, AcpVirtualHarness, discoverAcpVirtualWorkspaces } from './acp/virtual-harness.js' import type { HarnessMode } from './harness-target.js' import { probeRemoteHostFeatures, remoteHostFeatures } from './client-capabilities.js' import { ClientCodexStreams } from './client-codex-streams.js' import { ClientConnection } from './client-connection.js' import { isForceRelayEnabled } from './relay-preference.js' import { ClientReconnect } from './client-reconnect.js' import { ClientControl } from './client-control.js' import type { CodexLoopbackStream, ConnectedRemote, ConnectionProgressState, HostAuthorizationControl, HostConnectionHandle, RemoteDeviceView, RemoteDirectoryListing, RemoteHostFeatures, RemoteWorkspaceSelection, RemoteWorkspaceView, } from './client-runtime-contract.js' import { ClientModeError, HOST_AUTHORIZATION_ERRORS, record, shortId } from './client-runtime-contract.js' import { readRemoteWorkspaceBaseline, remoteWorkspaceTitle, workspaceRecordId, } from './client-workspace-queries.js' import type { CodexVirtualWorkspaceView } from './codex/virtual-harness.js' import { codexProjectWorkspaceId, CodexVirtualHarness, discoverCodexVirtualWorkspaces, } from './codex/virtual-harness.js' import type { ResolvedConfig } from './config.js' import type { HostWebServerLike } from './control-route.js' import { registerControlRoute } from './control-route.js' import type { RemoteFileViewerEndpoint } from './file-viewer-contract.js' import { harnessSessionGeneration } from './harness-version.js' import type { HostIdentity, IdentityStore } from './identity-store.js' import { uuidV7 } from './ids.js' import type { SafeLogger } from './logging.js' import { LoopbackPreview } from './loopback-preview.js' import { RemoteTypertGateway } from './remote-typert-gateway.js' import { AcpSessionHistoryCache, CodexSessionHistoryCache, RemoteSessionHistoryCache, } from './session-history-cache.js' import { safeErrorCode } from './safe-error.js' import { RemoteSessionTools, type SessionToolOperation } from './remote-session-tools.js' import type { OAuthProvider } from './server-api.js' import { ClientServerApi, ServerApiError } from './server-api.js' import type { TypertGatewayLike } from './typert-gateway-contract.js' import { TypertGatewaySwitch } from './typert-gateway-switch.js' import type { WeriftFactoryOptions } from './werift-rtc.js' import { loadNodeRtcFactory } from './werift-rtc.js' export class ClientModeRuntime { private async connect(targetDeviceId: string, signal?: AbortSignal): Promise { const lifetime = this.remoteLifetime.signal const connectionSignal = signal === undefined ? lifetime : AbortSignal.any([lifetime, signal]) connectionSignal.throwIfAborted() const remote = await this.connection.connect(targetDeviceId, connectionSignal).catch(error => { if (!connectionSignal.aborted && !this.connected && this.gatewaySwitch.status().target?.deviceId === targetDeviceId) { this.noteClientAuthFailure(error) } throw error }) if (connectionSignal.aborted || this.closed) { await remote.client.close().catch(() => undefined) throw new ClientModeError('CANCELLED', 'The Remote connection request was superseded or closed.') } if (!remote.client.getStats().connected) { await remote.client.close().catch(() => undefined) throw new ClientModeError('TRANSPORT_CLOSED', 'The Remote connection closed before it became ready.', true) } remote.client.onClose(error => this.handleRemoteClose(remote, error)) return remote } handleControl(endpoint: string, payload: unknown, signal: AbortSignal): Promise> { return this.control.handleControl(endpoint, payload, signal) } private readonly connection: ClientConnection private readonly control: ClientControl private readonly codexStreamBridge: ClientCodexStreams private preview?: LoopbackPreview private identity?: HostIdentity private connected?: ConnectedRemote private pendingWorkspaceSelection?: RemoteWorkspaceSelection private codexVirtual?: CodexVirtualHarness private codexVirtualSelection?: { targetDeviceId: string; workspaceId: string } private readonly codexOpenedSessions = new Map() private codexOpenGeneration = 0 private cursorVirtual?: AcpVirtualHarness private cursorVirtualSelection?: { targetDeviceId: string; workspaceId: string; backend: string } private readonly acpOpenedSessions = new Map() private acpVirtualBackend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' = 'cursor' private readonly remoteHistoryCaches = new Map() private readonly codexHistoryCaches = new Map() private readonly acpHistoryCaches = new Map() private readonly gatewaySwitch: TypertGatewaySwitch private readonly codexStreams = new Map() private connectionProgress?: ConnectionProgressState private connectionProgressRun = 0 private closed = false private remoteLifetime = new AbortController() private selectionLifetime = new AbortController() private readonly reconnect: ClientReconnect private readonly featureProbePromises = new WeakMap>() private recoverable?: ConnectedRemote private recoveryGeneration = 0 private clientAuthRequired = false private noteClientAuthFailure(error: unknown): void { if (error instanceof Error && 'code' in error && typeof error.code === 'string' && (error.code === 'AUTH_REQUIRED' || HOST_AUTHORIZATION_ERRORS.has(error.code))) { this.clientAuthRequired = true } } private readonly sessionTools = new RemoteSessionTools((hostId, signal, query) => this.withToolRemote(hostId, signal, query)) runSessionTool(operation: SessionToolOperation, args: unknown, signal: AbortSignal): Promise { this.assertHostAuthorizationForDeviceDiscovery() if (this.closed) throw new ClientModeError('CANCELLED', 'The Remote runtime is closed.') return this.sessionTools.run(operation, args, signal) } constructor( private readonly config: ResolvedConfig, private readonly identities: IdentityStore, private readonly server: ClientServerApi, typertGateway: TypertGatewayLike, private readonly logger: SafeLogger, private readonly host?: HostAuthorizationControl, private readonly rtcFactoryProvider: (options?: WeriftFactoryOptions) => Promise = loadNodeRtcFactory, ) { const owner = this this.reconnect = new ClientReconnect(config.reconnect) this.connection = new ClientConnection({ get connectionProgressRun() { return owner.connectionProgressRun }, set connectionProgressRun(value) { owner.connectionProgressRun = value }, get connectionProgress() { return owner.connectionProgress }, set connectionProgress(value) { owner.connectionProgress = value }, requireIdentity: (...args) => owner.requireIdentity(...args), get server() { return owner.server }, get config() { return owner.config }, get rtcFactoryProvider() { return owner.rtcFactoryProvider }, get logger() { return owner.logger }, get identities() { return owner.identities }, }) this.control = new ClientControl({ detailedStatus: (...args) => owner.detailedStatus(...args), devices: (...args) => owner.devices(...args), get server() { return owner.server }, authorizeClientWithAccount: (...args) => owner.authorizeClientWithAccount(...args), startClientOAuthQrLogin: (...args) => owner.startClientOAuthQrLogin(...args), pollClientOAuthQrLogin: (...args) => owner.pollClientOAuthQrLogin(...args), activeRemote: (...args) => owner.activeRemote(...args), get preview() { return owner.preview }, set preview(value) { owner.preview = value }, listRemoteDirectory: (...args) => owner.listRemoteDirectory(...args), listRemoteWorkspaces: (...args) => owner.listRemoteWorkspaces(...args), listCodexWorkspaces: (...args) => owner.listCodexWorkspaces(...args), openRemoteWorkspace: (...args) => owner.openRemoteWorkspace(...args), openCodexWorkspace: (...args) => owner.openCodexWorkspace(...args), createCodexWorkspace: (...args) => owner.createCodexWorkspace(...args), listCursorWorkspaces: (...args) => owner.listCursorWorkspaces(...args), openCursorWorkspace: (...args) => owner.openCursorWorkspace(...args), createCursorWorkspace: (...args) => owner.createCursorWorkspace(...args), consumeWorkspaceSelection: (...args) => owner.consumeWorkspaceSelection(...args), callRemoteFileViewer: (...args) => owner.callRemoteFileViewer(...args), activeCodexRemote: (...args) => owner.codexStreamBridge.activeCodexRemote(...args), requireLocalCodex: (...args) => owner.codexStreamBridge.requireLocalCodex(...args), localCodexAvailable: (...args) => owner.codexStreamBridge.localCodexAvailable(...args), pluginRoute: (...args) => owner.pluginRoute(...args), openCodexStream: (...args) => owner.codexStreamBridge.openCodexStream(...args), nextCodexFrames: (...args) => owner.codexStreamBridge.nextCodexFrames(...args), closeCodexStream: (...args) => owner.codexStreamBridge.closeCodexStream(...args), get host() { return owner.host }, setHostAuthorization: (...args) => owner.setHostAuthorization(...args), setMode: (...args) => owner.setMode(...args), }) this.codexStreamBridge = new ClientCodexStreams({ activeRemote: (...args) => owner.activeRemote(...args), get codexStreams() { return owner.codexStreams }, get host() { return owner.host }, }) this.gatewaySwitch = new TypertGatewaySwitch(typertGateway) } async start(): Promise { if (this.closed) throw new Error('client remote-mode runtime is closed') if (this.host?.hostStatus().pairingHostOnly) { this.gatewaySwitch.install(); return } this.identity = await this.identities.loadOrCreate(this.config.deviceName) this.server.bindIdentity(this.identity) this.gatewaySwitch.install() this.logger.info('client remote-mode identity ready', { deviceId: shortId(this.identity.deviceId), fingerprint: this.identity.fingerprint, }) // A previously authorized Client should make the local Host controllable // on startup as well. Do not register an anonymous Client just to probe: // only persisted Client credentials opt into this default. if (this.config.hostControl?.enabled !== false && this.host !== undefined && this.server.hasStoredAuthorization !== undefined) { try { if (await this.server.hasStoredAuthorization() && (this.host.hasStoredAuthorization === undefined || !await this.host.hasStoredAuthorization())) { await this.authorizeHostByDefault() } } catch (error) { this.logger.warn('automatic Host authorization failed', { code: safeErrorCode(error) }) } } } async authorizeHostByDefault(): Promise { try { if (this.host === undefined) return if (this.config.hostControl?.enabled === false) return // `authorized` and `hasStoredAuthorization` both answer "a credential // exists", never "the credential still works". The Server can revoke the // token family while this process keeps the credential in memory, and // nothing rewrites the file afterwards, so a dead Host still reports // itself authorized. Once the control connection reports an // authentication error that cache is disproven: re-authorize instead of // trusting it, otherwise signing in again repairs nothing and the Host // stays unusable until the process restarts. const status = this.host.hostStatus() if (!status.accountRequired) { if (status.authorized) return if (this.host.hasStoredAuthorization !== undefined && await this.host.hasStoredAuthorization()) return } const credentials = await this.server.authenticate(this.requireIdentity()) try { await this.host.authorizeHostAsOwned(credentials.accessToken, credentials.account) } catch (error) { if (!(error instanceof ServerApiError) || error.status !== 401 || (error.code !== 'AUTH_INVALID' && error.code !== 'TOKEN_EXPIRED')) throw error const refreshed = await this.server.refreshCredentials(credentials.accessToken) await this.host.authorizeHostAsOwned(refreshed.accessToken, refreshed.account) } } catch (error) { this.logger.warn('automatic Host authorization failed', { code: safeErrorCode(error) }) } } registerControl(connection: HostConnectionHandle, webServer?: HostWebServerLike): () => Promise { return registerControlRoute(connection, (endpoint, payload, signal) => this.control.handleControl(endpoint, payload, signal), webServer) } status(): Record { const targetStatus = this.gatewaySwitch.status() return { available: this.config.serverUrl !== undefined, identityReady: this.identity !== undefined, deviceId: this.identity?.deviceId, deviceName: this.identity?.name, serverUrl: this.config.serverUrl, ...targetStatus, connected: this.connected !== undefined, recoveryGeneration: this.recoveryGeneration, ...(this.clientAuthRequired && !this.connected && targetStatus.mode === 'remote' ? { clientAuthRequired: true } : {}), transport: this.connected?.client.getStats().mode ?? 'Disconnected', connectedTargetDeviceId: this.connected?.target.deviceId, preferredTransports: isForceRelayEnabled() || this.config.forceRelay ? ['relay'] : ['lan', 'p2p', 'turn', 'relay'], ...(this.connectionProgress === undefined ? {} : { connectionProgress: { targetDeviceId: this.connectionProgress.targetDeviceId, phase: this.connectionProgress.phase, ...(this.connectionProgress.activeTransports === undefined ? {} : { activeTransports: [...this.connectionProgress.activeTransports] }), }, }), remoteFeatures: this.connected?.features ?? remoteHostFeatures(), ...(this.pendingWorkspaceSelection === undefined ? {} : { workspaceSelection: { ...this.pendingWorkspaceSelection } }), backend: this.cursorVirtual !== undefined ? this.acpVirtualBackend : this.codexVirtual === undefined ? 'harness' : 'codex', hostAuthorizationAvailable: this.host !== undefined, ...(this.host === undefined ? {} : { host: this.host.hostStatus() }), } } private async closePreview(): Promise { const preview = this.preview; this.preview = undefined await preview?.close() } private async detailedStatus(): Promise> { const connected = this.connected if (connected === undefined || this.identity === undefined) return this.status() const details = await connected.transport.connectionDetails() if (this.connected !== connected) return this.status() return { ...this.status(), network: { ...details, local: { deviceId: this.identity.deviceId, name: this.identity.name, platform: process.platform, }, remote: { deviceId: connected.target.deviceId, name: connected.target.name, platform: connected.target.platform, }, }, } } async devices(signal?: AbortSignal): Promise { signal = signal === undefined ? this.remoteLifetime.signal : AbortSignal.any([signal, this.remoteLifetime.signal]) signal?.throwIfAborted() if (this.closed) throw new ClientModeError('CANCELLED', 'The Remote runtime is closed.') this.assertHostAuthorizationForDeviceDiscovery() this.requireIdentity() const devices: RemoteDeviceView[] = [] for await (const page of this.server.devicePages(signal)) { const remoteDevices = page.filter(device => device.deviceId !== this.host?.hostStatus().deviceId) const resolved: RemoteDeviceView[] = new Array(remoteDevices.length) let next = 0 let failed = false // Bound authorization/presence fan-out even when an older Server ignores // pagination. Finish this page before fetching the next one. const workers = await Promise.allSettled(Array.from({ length: Math.min(8, remoteDevices.length) }, async () => { try { while (!failed && next < remoteDevices.length) { signal.throwIfAborted() this.assertHostAuthorizationForDeviceDiscovery() const index = next++ const device = remoteDevices[index]! await this.connection.authorizeHostPeer(device, signal) const presence = await this.server.presenceFor(device.deviceId, signal).catch(() => ({ online: false })) signal.throwIfAborted() this.assertHostAuthorizationForDeviceDiscovery() resolved[index] = { ...device, ...presence } } } catch (error) { failed = true; throw error } })) signal.throwIfAborted() this.assertHostAuthorizationForDeviceDiscovery() const failure = workers.find(result => result.status === 'rejected') if (failure?.status === 'rejected') throw failure.reason devices.push(...resolved) } signal.throwIfAborted() this.assertHostAuthorizationForDeviceDiscovery() return devices } /** * Device discovery is exposed through the local app control route. When this * installation also runs a Host, keep that route closed after the Host's * Server credential has become terminally invalid. The Client credential can * remain usable for a short time after a revoke, so checking only * `ClientServerApi.listDevices()` would otherwise leak the device directory * from a Host that the user has already been told to re-authorize. */ private assertHostAuthorizationForDeviceDiscovery(): void { const status = this.host?.hostStatus() if (status?.pairingHostOnly) throw new ClientModeError('DEVICE_SCOPE_REQUIRED', 'This Host only accepts incoming Remote connections.') if (status === undefined || status.error === undefined || !HOST_AUTHORIZATION_ERRORS.has(status.error)) return const message = status.error === 'DEVICE_REVOKED' ? 'The local Host was revoked on the Server. Sign out and authorize this Host again.' : 'The local Host authorization is no longer valid. Sign out and authorize this Host again.' throw new ClientModeError(status.error, message) } async authorizeClientWithAccount(email: string, password: string): Promise { let authorization try { authorization = await this.server.authorizeWithAccount(this.requireIdentity(), email, password) } catch (error) { if (!(error instanceof ServerApiError) || error.code !== 'DEVICE_REVOKED') throw error this.identity = await this.identities.reset(this.config.deviceName) this.server.bindIdentity(this.identity) authorization = await this.server.authorizeWithAccount(this.identity, email, password) } await this.authorizeHostByDefault() this.clientAuthRequired = false this.logger.info('Client account authorized') return authorization } async startClientOAuthQrLogin(provider: OAuthProvider): Promise { return this.server.startOAuthQrLogin(provider) } async pollClientOAuthQrLogin(qrId: string): Promise { const result = await this.server.pollOAuthQrLogin(this.requireIdentity(), qrId, async () => { this.identity = await this.identities.reset(this.config.deviceName) this.server.bindIdentity(this.identity) this.logger.info('Rotated revoked Client identity before QR authorization retry') return this.identity }) if (result.status === 'complete') this.logger.info('Client account authorized with QR login') if (result.status === 'complete') { this.clientAuthRequired = false await this.authorizeHostByDefault() } return result } async clearClientAuthorization(): Promise { const cleanup = this.leaveRemote() this.codexOpenedSessions.clear() this.acpOpenedSessions.clear() this.clearHistoryCaches() if (this.identity === undefined) { await Promise.all([cleanup, this.server.clearAuthorization()]); return } const results = await Promise.allSettled([cleanup, this.server.revokeCurrentDevice()]) // A Host-only installation never creates a Client identity on logout. if (this.host?.hostStatus().pairingHostOnly) this.identity = undefined else { this.identity = await this.identities.reset(this.config.deviceName); this.server.bindIdentity(this.identity) } const failure = results.find(result => result.status === 'rejected') if (failure?.status === 'rejected') throw failure.reason } async setHostAuthorization(enabled: boolean): Promise { if (this.host === undefined) throw new ClientModeError('METHOD_NOT_ALLOWED', 'This plugin is not running as a Host.') if (!enabled) { await this.host.clearHostAuthorization() return this.status() } const credentials = await this.server.authenticate(this.requireIdentity()) try { await this.host.authorizeHostAsOwned(credentials.accessToken, credentials.account) } catch (error) { if (!(error instanceof ServerApiError) || error.status !== 401 || (error.code !== 'AUTH_INVALID' && error.code !== 'TOKEN_EXPIRED')) throw error const refreshed = await this.server.refreshCredentials(credentials.accessToken) await this.host.authorizeHostAsOwned(refreshed.accessToken, refreshed.account) } return this.status() } async setMode(mode: HarnessMode, targetDeviceId?: string, signal?: AbortSignal): Promise> { if (mode === 'local') { await this.leaveRemote() this.logger.info('Harness target switched', { mode: 'local' }) return this.status() } if (targetDeviceId === undefined || targetDeviceId.length === 0) { throw new ClientModeError('INVALID_MESSAGE', 'A targetDeviceId is required for remote mode.') } signal = this.beginSelection(signal) const lifetime = this.remoteLifetime.signal const next = await this.connect(targetDeviceId, signal) try { this.assertRemoteCompatible(next) } catch (error) { this.connection.clearConnectionProgress(next.progressRunId) await next.client.close().catch(() => undefined) throw error } const previous = this.connected await this.closePreview() if (signal.aborted || lifetime.aborted || this.closed) { await next.client.close().catch(() => undefined) throw new ClientModeError('CANCELLED', 'The Remote connection request was superseded or closed.') } this.connected = next this.connection.clearConnectionProgress(next.progressRunId) this.pendingWorkspaceSelection = undefined await this.closeCodexVirtual() this.assertRemoteCurrent(next, signal) await this.closeCursorVirtual() this.assertRemoteCurrent(next, signal) this.selectRemoteTarget(next) await this.codexStreamBridge.closeCodexStreams(previous?.client) await previous?.client.close().catch(() => undefined) this.logger.info('Harness target switched', { mode: 'remote', targetDeviceId: shortId(next.target.deviceId) }) return this.status() } async listRemoteDirectory(targetDeviceId: string, path?: string, signal?: AbortSignal): Promise { const remote = await this.ensureConnected(targetDeviceId, signal) const value = await new RemoteTypertGateway(remote.client).invoke({ namespace: 'directoryPicker', method: 'list', args: path === undefined ? {} : { path }, ...(signal === undefined ? {} : { signal }), }) return value as RemoteDirectoryListing } async listRemoteWorkspaces(targetDeviceId: string, signal?: AbortSignal): Promise { const remote = await this.ensureConnected(targetDeviceId, signal) return readRemoteWorkspaceBaseline(new RemoteTypertGateway(remote.client), signal) } /** Read-only Agent discovery owns a temporary carrier, never the UI selection. */ async discoverToolWorkspaces(targetDeviceId: string, signal: AbortSignal): Promise<{ workspaces: Array unavailable: Array<{ backend: string; code: string }> }> { return this.withToolRemote(targetDeviceId, signal, async (remote, activeSignal) => { const workspaces: Array = [] const unavailable: Array<{ backend: string; code: string }> = [] const read = async (backend: string, query: () => Promise) => { activeSignal.throwIfAborted() try { for (const row of await query()) { workspaces.push({ backend, workspaceId: row.workspaceId, path: row.path, title: row.title }) } } catch { activeSignal.throwIfAborted() unavailable.push({ backend, code: 'BACKEND_UNAVAILABLE' }) } } if (remote.features.remoteGateway) { await read('harness', () => readRemoteWorkspaceBaseline(new RemoteTypertGateway(remote.client), activeSignal)) } if (remote.features.codex) { await read('codex', () => discoverCodexVirtualWorkspaces(new CodexRemoteClient(remote.client), activeSignal)) } for (const backend of ['cursor', 'antigravity', 'pi', 'opencode', 'claude', 'hermes'] as const) { if (!remote.features[backend]) continue // Use the existing ACP catalog RPC directly: optional UI discovery swallows // backend errors, whereas a tool must distinguish unavailable from empty. await read(backend, async () => { const rows = await new AgentAcpClient(remote.client).call('dsh/workspaceList', { backend }, activeSignal) if (!Array.isArray(rows)) throw new ClientModeError('INVALID_MESSAGE', 'Invalid workspace catalog.') return rows.map(row => { if (typeof row?.path !== 'string' || !row.path.trim() || (row.title !== undefined && typeof row.title !== 'string')) { throw new ClientModeError('INVALID_MESSAGE', 'Invalid workspace catalog row.') } return { workspaceId: acpCwdWorkspaceId(row.path, backend), path: row.path, title: row.title ?? remoteWorkspaceTitle(row.path) } }) }) } return { workspaces, unavailable } }) } private async withToolRemote( targetDeviceId: string, signal: AbortSignal, query: (remote: ConnectedRemote, signal: AbortSignal) => Promise, ): Promise { this.assertHostAuthorizationForDeviceDiscovery() if (this.closed) throw new ClientModeError('CANCELLED', 'The Remote runtime is closed.') const activeSignal = AbortSignal.any([signal, this.remoteLifetime.signal]) // A device has one Control connection. Opening a second connection with // the same identity replaces the warm UI connection on the Server. const shared = this.connected if (shared?.target.deviceId === targetDeviceId) { this.assertRemoteCurrent(shared, activeSignal) const result = await query(shared, activeSignal) this.assertRemoteCurrent(shared, activeSignal) this.assertHostAuthorizationForDeviceDiscovery() return result } const remote = await this.connection.connect(targetDeviceId, activeSignal, { background: true }) let closing: Promise | undefined const close = () => closing ??= remote.client.close() const onAbort = () => { void close().catch(() => undefined) } activeSignal.addEventListener('abort', onAbort, { once: true }) try { activeSignal.throwIfAborted() const result = await query(remote, activeSignal) activeSignal.throwIfAborted() this.assertHostAuthorizationForDeviceDiscovery() return result } finally { activeSignal.removeEventListener('abort', onAbort) await close() } } async openRemoteWorkspace(targetDeviceId: string, path: string, signal?: AbortSignal): Promise> { if (path.trim() === '') throw new ClientModeError('INVALID_MESSAGE', 'A remote working directory is required.') const remote = await this.ensureConnected(targetDeviceId, signal) this.assertRemoteCompatible(remote) const workspace = await new RemoteTypertGateway(remote.client).invoke({ namespace: 'workspace', method: 'create', args: { request: { path } }, ...(signal === undefined ? {} : { signal }), }) as { workspace: unknown; created: boolean } this.assertRemoteCurrent(remote, signal) await this.closeCodexVirtual() this.assertRemoteCurrent(remote, signal) await this.closeCursorVirtual() this.assertRemoteCurrent(remote, signal) this.selectRemoteTarget(remote) const workspaceId = workspaceRecordId(workspace.workspace) this.pendingWorkspaceSelection = { targetDeviceId: remote.target.deviceId, workspaceId } this.logger.info('Remote workspace opened', { targetDeviceId: shortId(remote.target.deviceId) }) return { ...this.status(), workspace } } async listCodexWorkspaces(targetDeviceId: string, signal?: AbortSignal): Promise { const remote = await this.ensureConnected(targetDeviceId, signal) await this.refreshRemoteFeatures(remote) if (!remote.features.codex) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', 'The selected Host does not provide CodeX workspaces.') } return discoverCodexVirtualWorkspaces(new CodexRemoteClient(remote.client), signal) } async openCodexWorkspace( targetDeviceId: string, workspaceId: string, signal?: AbortSignal, ): Promise> { const generation = ++this.codexOpenGeneration const remote = await this.ensureConnected(targetDeviceId, signal, () => this.codexOpenGeneration === generation) const assertCurrent = (): void => { signal?.throwIfAborted() if (this.closed || this.connected !== remote || this.codexOpenGeneration !== generation) { throw new ClientModeError('CANCELLED', 'The CodeX workspace selection was superseded or disconnected.') } } assertCurrent() await this.refreshRemoteFeatures(remote) assertCurrent() if (!remote.features.codex) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', 'The selected Host does not provide CodeX workspaces.') } this.assertLocalHarnessCarrierAvailable() const virtual = CodexVirtualHarness.remote(remote.client, { deviceId: remote.target.deviceId, name: remote.target.name, }, harnessSessionGeneration(this.host?.localHarnessVersion?.()), this.remoteTypertGateway(remote), this.codexHistoryCache(remote.target.deviceId)) try { let workspace: CodexVirtualWorkspaceView try { workspace = await virtual.selectWorkspace(workspaceId, signal) } catch { assertCurrent() throw new ClientModeError('WORKSPACE_NOT_FOUND', 'The selected CodeX workspace is no longer available.') } assertCurrent() await this.closeCodexVirtual(false) assertCurrent() await this.closeCursorVirtual() assertCurrent() const selectionKey = JSON.stringify([remote.target.deviceId, workspaceId]) const preferredSessionId = await virtual.preferredSessionId(signal, this.codexOpenedSessions.get(selectionKey)) assertCurrent() this.codexVirtual = virtual this.codexVirtualSelection = { targetDeviceId: remote.target.deviceId, workspaceId } this.selectCodexTarget(virtual, remote) this.pendingWorkspaceSelection = { targetDeviceId: remote.target.deviceId, workspaceId, backend: 'codex', ...(preferredSessionId === undefined ? {} : { sessionId: preferredSessionId }), } this.logger.info('CodeX virtual workspace opened', { targetDeviceId: shortId(remote.target.deviceId) }) return { ...this.status(), workspace } } catch (error) { await virtual.close() throw error } } async createCodexWorkspace( targetDeviceId: string, path: string, signal?: AbortSignal, ): Promise> { const trimmedPath = path.trim() if (trimmedPath === '') throw new ClientModeError('INVALID_MESSAGE', 'A CodeX project directory is required.') const remote = await this.ensureConnected(targetDeviceId, signal) await this.refreshRemoteFeatures(remote) if (!remote.features.codex) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', 'The selected Host does not provide CodeX workspaces.') } this.assertLocalHarnessCarrierAvailable() const result = record(await new CodexRemoteClient(remote.client).request('project/create', { name: remoteWorkspaceTitle(trimmedPath), roots: [{ path: trimmedPath }], idempotencyKey: uuidV7(), }, signal)) const project = record(result.project) this.assertRemoteCurrent(remote, signal) if (typeof project.id !== 'string' || project.id.length === 0) { throw new ClientModeError('INVALID_MESSAGE', 'The Host returned an invalid CodeX project.') } return this.openCodexWorkspace(targetDeviceId, codexProjectWorkspaceId(project.id), signal) } async listCursorWorkspaces(targetDeviceId: string, signal?: AbortSignal, backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' = 'cursor'): Promise { const remote = await this.ensureConnected(targetDeviceId, signal) await this.refreshRemoteFeatures(remote) if (!remote.features[backend]) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', `The selected Host does not provide ${backend} workspaces.`) } if (this.cursorVirtual !== undefined && this.connected?.target.deviceId === targetDeviceId && this.acpVirtualBackend === backend) { return this.cursorVirtual.workspaces() } const acpClient = new AgentAcpClient(remote.client) const workspaces = await discoverAcpVirtualWorkspaces(acpClient, backend, signal) return workspaces } async openCursorWorkspace( targetDeviceId: string, workspaceId: string, signal?: AbortSignal, backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' = 'cursor', ): Promise> { const remote = await this.ensureConnected(targetDeviceId, signal) await this.refreshRemoteFeatures(remote) if (!remote.features[backend]) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', `The selected Host does not provide ${backend} workspaces.`) } this.assertLocalHarnessCarrierAvailable() const virtual = AcpVirtualHarness.remote( remote.client, { deviceId: remote.target.deviceId, name: remote.target.name, }, backend, remote.features.acpModelLoadsSession ? ['agent.acp.antigravity.model-load.v1'] : [], this.remoteTypertGateway(remote), this.acpHistoryCache(remote.target.deviceId, backend), ) let workspace: AcpVirtualWorkspaceView try { try { workspace = await virtual.selectWorkspace(workspaceId) } catch { this.assertRemoteCurrent(remote, signal) throw new ClientModeError('WORKSPACE_NOT_FOUND', `The selected ${backend} workspace is no longer available.`) } this.assertRemoteCurrent(remote, signal) await this.closeCodexVirtual() this.assertRemoteCurrent(remote, signal) await this.closeCursorVirtual() this.assertRemoteCurrent(remote, signal) const selectionKey = JSON.stringify([remote.target.deviceId, backend, workspace.workspaceId]) const rememberedSessionId = this.acpOpenedSessions.get(selectionKey) const preferredSessionId = rememberedSessionId === undefined ? await virtual.preferredSessionId() : await virtual.preferredSessionId(rememberedSessionId) this.assertRemoteCurrent(remote, signal) this.cursorVirtual = virtual this.cursorVirtualSelection = { targetDeviceId: remote.target.deviceId, workspaceId: workspace.workspaceId, backend } this.acpVirtualBackend = backend this.selectCursorTarget(virtual, remote) this.pendingWorkspaceSelection = { targetDeviceId: remote.target.deviceId, workspaceId: workspace.workspaceId, backend, ...(preferredSessionId === undefined ? {} : { sessionId: preferredSessionId }), } } catch (error) { await virtual.close() throw error } this.logger.info(`${backend} virtual workspace opened`, { targetDeviceId: shortId(remote.target.deviceId) }) return { ...this.status(), workspace } } async createCursorWorkspace( targetDeviceId: string, path: string, signal?: AbortSignal, backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' = 'cursor', ): Promise> { const trimmedPath = path.trim() if (trimmedPath === '') throw new ClientModeError('INVALID_MESSAGE', `A ${backend} project directory is required.`) const remote = await this.ensureConnected(targetDeviceId, signal) await this.refreshRemoteFeatures(remote) if (!remote.features[backend]) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', `The selected Host does not provide ${backend} workspaces.`) } this.assertLocalHarnessCarrierAvailable() const virtual = AcpVirtualHarness.remote( remote.client, { deviceId: remote.target.deviceId, name: remote.target.name, }, backend, remote.features.acpModelLoadsSession ? ['agent.acp.antigravity.model-load.v1'] : [], this.remoteTypertGateway(remote), this.acpHistoryCache(remote.target.deviceId, backend), ) try { const workspace = await virtual.selectOrCreateWorkspace(trimmedPath) this.assertRemoteCurrent(remote, signal) await this.closeCodexVirtual() this.assertRemoteCurrent(remote, signal) await this.closeCursorVirtual() this.assertRemoteCurrent(remote, signal) this.cursorVirtual = virtual this.cursorVirtualSelection = { targetDeviceId: remote.target.deviceId, workspaceId: workspace.workspaceId, backend } this.acpVirtualBackend = backend this.selectCursorTarget(virtual, remote) this.pendingWorkspaceSelection = { targetDeviceId: remote.target.deviceId, workspaceId: workspace.workspaceId, backend, } this.logger.info(`${backend} virtual workspace created`, { targetDeviceId: shortId(remote.target.deviceId) }) return { ...this.status(), workspace } } catch (error) { await virtual.close() throw error } } private consumeWorkspaceSelection(selection: RemoteWorkspaceSelection): Record { const pending = this.pendingWorkspaceSelection if (pending?.targetDeviceId === selection.targetDeviceId && pending.workspaceId === selection.workspaceId && (pending.backend ?? 'harness') === (selection.backend ?? 'harness')) { this.pendingWorkspaceSelection = undefined } return this.status() } async close(): Promise { if (this.closed) return this.closed = true this.server.close?.() try { await this.leaveRemote() } finally { this.clearHistoryCaches() this.gatewaySwitch.restore() } } private async leaveRemote(): Promise { this.clientAuthRequired = false this.beginSelection() this.sessionTools.invalidate() this.remoteLifetime.abort(new ClientModeError('CANCELLED', 'The Remote connection was closed.')) this.remoteLifetime = new AbortController() const previous = this.connected this.connected = undefined this.connectionProgress = undefined this.pendingWorkspaceSelection = undefined this.gatewaySwitch.selectLocal() // Detach authority synchronously. Closing the carrier also releases pending // stream RPCs; one failed stream/preview must never skip carrier cleanup. const results = await Promise.allSettled([ this.closeCodexVirtual(), this.closeCursorVirtual(), this.closePreview(), this.codexStreamBridge.closeCodexStreams(previous?.client), previous?.client.close(), ]) const failure = results.find(result => result.status === 'rejected') if (failure?.status === 'rejected') throw failure.reason } private async callRemoteFileViewer( endpoint: RemoteFileViewerEndpoint, payload: unknown, signal?: AbortSignal, ): Promise { const remote = this.connected if (remote === undefined || this.status().mode !== 'remote') { throw new ClientModeError('REMOTE_NOT_CONNECTED', 'No Remote Host is selected.', true) } if (!remote.features.fileViewer) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', 'The selected Remote Host does not support remote file viewing.') } return remote.client.rpc('fileviewer.call', { endpoint, payload }, signal) } private async pluginRoute(route: string, body: unknown, signal: AbortSignal): Promise { const remote = this.connected if (remote === undefined || this.status().mode !== 'remote') { throw new ClientModeError('REMOTE_NOT_CONNECTED', 'No Remote Host is selected.', true) } if (!remote.features.pluginRoute) { throw new ClientModeError('FEATURE_NOT_SUPPORTED', 'The connected Host cannot forward plugin routes.') } if (route === 'api/session/uploadFileBinary') { const result = await this.remoteTypertGateway(remote).dispatch('remoteUploads/upload', { args: body }, signal) if (!result.ok) throw new ClientModeError(result.error.code, result.error.message) return result.value as PluginRouteCallResult } return remote.client.rpc('plugin.route.call', { route, body }, signal) } private activeRemote(): ConnectedRemote | undefined { return this.connected } private selectRemoteTarget(remote: ConnectedRemote): void { this.assertRemoteCompatible(remote) this.clientAuthRequired = false const target = { deviceId: remote.target.deviceId, name: remote.target.name } const gateway = this.remoteTypertGateway(remote) const selected = { invoke: async (request: Parameters[0]) => { if (`${request.namespace}/${request.method}` !== 'session/prompt') return gateway.invoke(request) const payload = await uploadLocalMentions({ args: request.args }, gateway, request.signal ?? new AbortController().signal) return gateway.invoke({ ...request, args: (payload as { args: typeof request.args }).args }) }, dispatch: async (endpoint: string, payload: unknown, signal: AbortSignal) => gateway.dispatch(endpoint, endpoint === 'session/prompt' ? await uploadLocalMentions(payload, gateway, signal) : payload, signal), open: (endpoint: string, payload: unknown, signal: AbortSignal) => gateway.open(endpoint, payload, signal), } this.gatewaySwitch.selectRemote(selected, undefined, target) this.recoverable = remote } private remoteTypertGateway(remote: ConnectedRemote): RemoteTypertGateway { const localSessionGeneration = harnessSessionGeneration(this.host?.localHarnessVersion?.()) return new RemoteTypertGateway( remote.client, localSessionGeneration === 'v3' && remote.features.sessionFormat !== 3 ? 'legacy-to-v3' : undefined, remote.harnessVersion, true, this.remoteHistoryCache(remote.target.deviceId), ) } private remoteHistoryCache(deviceId: string): RemoteSessionHistoryCache { let cache = this.remoteHistoryCaches.get(deviceId) if (cache === undefined) { cache = new RemoteSessionHistoryCache() } else { this.remoteHistoryCaches.delete(deviceId) } this.remoteHistoryCaches.set(deviceId, cache) while (this.remoteHistoryCaches.size > 16) { const oldest = this.remoteHistoryCaches.keys().next().value if (oldest === undefined) break this.remoteHistoryCaches.get(oldest)?.clear() this.remoteHistoryCaches.delete(oldest) } return cache } private codexHistoryCache(deviceId: string): CodexSessionHistoryCache { let cache = this.codexHistoryCaches.get(deviceId) if (cache === undefined) { cache = new CodexSessionHistoryCache() } else { this.codexHistoryCaches.delete(deviceId) } this.codexHistoryCaches.set(deviceId, cache) while (this.codexHistoryCaches.size > 16) { const oldest = this.codexHistoryCaches.keys().next().value if (oldest === undefined) break this.codexHistoryCaches.get(oldest)?.clear() this.codexHistoryCaches.delete(oldest) } return cache } private acpHistoryCache(deviceId: string, backend: string): AcpSessionHistoryCache { const key = `${deviceId}:${backend}` let cache = this.acpHistoryCaches.get(key) if (cache === undefined) { cache = new AcpSessionHistoryCache() } else { this.acpHistoryCaches.delete(key) } this.acpHistoryCaches.set(key, cache) while (this.acpHistoryCaches.size > 32) { const oldest = this.acpHistoryCaches.keys().next().value if (oldest === undefined) break this.acpHistoryCaches.get(oldest)?.clear() this.acpHistoryCaches.delete(oldest) } return cache } private clearHistoryCaches(): void { for (const cache of this.remoteHistoryCaches.values()) cache.clear() for (const cache of this.codexHistoryCaches.values()) cache.clear() for (const cache of this.acpHistoryCaches.values()) cache.clear() this.remoteHistoryCaches.clear() this.codexHistoryCaches.clear() this.acpHistoryCaches.clear() } private selectCodexTarget(virtual: CodexVirtualHarness, remote: ConnectedRemote): void { this.recoverable = undefined const target = { deviceId: remote.target.deviceId, name: remote.target.name } this.gatewaySwitch.selectRemote(virtual, undefined, target) } private async closeCodexVirtual(invalidatePending = true): Promise { if (invalidatePending) this.codexOpenGeneration += 1 const virtual = this.codexVirtual const selection = this.codexVirtualSelection this.codexVirtual = undefined this.codexVirtualSelection = undefined // Keep only navigation IDs in memory, scoped to the Host and Workspace. // Capture before the first await: transport close clears `connected` first. if (selection !== undefined && virtual !== undefined) { for (const [workspaceId, sessionId] of virtual.openedSessions) { const key = JSON.stringify([selection.targetDeviceId, workspaceId]) this.codexOpenedSessions.delete(key) this.codexOpenedSessions.set(key, sessionId) if (this.codexOpenedSessions.size > 64) { this.codexOpenedSessions.delete(this.codexOpenedSessions.keys().next().value!) } } } await virtual?.close() } private async closeCursorVirtual(): Promise { const virtual = this.cursorVirtual const selection = this.cursorVirtualSelection this.cursorVirtual = undefined this.cursorVirtualSelection = undefined if (selection !== undefined && virtual !== undefined && virtual.openedSessions !== undefined) { for (const [workspaceId, sessionId] of virtual.openedSessions) { const key = JSON.stringify([selection.targetDeviceId, selection.backend, workspaceId]) this.acpOpenedSessions.delete(key) this.acpOpenedSessions.set(key, sessionId) if (this.acpOpenedSessions.size > 64) { this.acpOpenedSessions.delete(this.acpOpenedSessions.keys().next().value!) } } } await virtual?.close() } private selectCursorTarget(virtual: AcpVirtualHarness, remote: ConnectedRemote): void { this.recoverable = undefined const target = { deviceId: remote.target.deviceId, name: remote.target.name } this.gatewaySwitch.selectRemote(virtual, undefined, target) } private assertRemoteCompatible(remote: ConnectedRemote): void { const localRemoteGateway = this.gatewaySwitch.supportsCarrier() const localSessionGeneration = harnessSessionGeneration(this.host?.localHarnessVersion?.()) if (localRemoteGateway && remote.features.remoteGateway) { if (localSessionGeneration === 'v3' || remote.features.sessionFormat !== 3) return throw new ClientModeError( 'HARNESS_VERSION_INCOMPATIBLE', 'The selected Host uses Harness Session V3, but this Client uses the legacy Typert Remote session format.', ) } throw new ClientModeError( 'HARNESS_VERSION_INCOMPATIBLE', 'Both this Client and the selected Host must provide a compatible Harness Typert Remote Gateway transport.', ) } private assertLocalHarnessCarrierAvailable(): void { if (this.gatewaySwitch.supportsCarrier()) return throw new ClientModeError( 'HARNESS_VERSION_INCOMPATIBLE', 'This Client does not provide a compatible Harness carrier for the selected remote workspace.', ) } private async refreshRemoteFeatures(remote: ConnectedRemote): Promise { const key = remote.client as unknown as object let pending = this.featureProbePromises.get(key) if (pending === undefined) { pending = probeRemoteHostFeatures(remote.client, remote.clientVersion) this.featureProbePromises.set(key, pending) void pending.finally(() => { if (this.featureProbePromises.get(key) === pending) this.featureProbePromises.delete(key) }).catch(() => undefined) } const features = await pending remote.features = features return features } private async ensureConnected( targetDeviceId: string, signal?: AbortSignal, isCurrent?: () => boolean, ): Promise { const lifetime = this.remoteLifetime.signal if (this.connected?.target.deviceId === targetDeviceId) return this.connected signal = this.beginSelection(signal) const next = await this.connect(targetDeviceId, signal) const assertCurrent = (): void => { signal?.throwIfAborted() if (this.closed || lifetime.aborted || isCurrent?.() === false) { throw new ClientModeError('CANCELLED', 'The Remote connection request was superseded or closed.') } } try { // Reject a stale connection before it can detach a newer Host or restore // authority after sign-out. Also fence the preview-close await below. assertCurrent() await this.closePreview() assertCurrent() } catch (error) { this.connection.clearConnectionProgress(next.progressRunId) await next.client.close().catch(() => undefined) throw error } const previous = this.connected this.connected = next this.connection.clearConnectionProgress(next.progressRunId) await previous?.client.close().catch(() => undefined) return next } private assertRemoteCurrent(remote: ConnectedRemote, signal?: AbortSignal): void { signal?.throwIfAborted() if (this.closed || this.connected !== remote) { throw new ClientModeError('CANCELLED', 'The Remote workspace request was superseded or closed.') } } private requireIdentity(): HostIdentity { if (this.host?.hostStatus().pairingHostOnly) throw new ClientModeError('DEVICE_SCOPE_REQUIRED', 'This Host only accepts incoming Remote connections.') if (this.identity === undefined) throw new ClientModeError('IDENTITY_INVALID', 'The client identity is not ready.') return this.identity } private beginSelection(signal?: AbortSignal): AbortSignal { this.reconnect.cancel() this.recoverable = undefined this.selectionLifetime.abort(new ClientModeError('CANCELLED', 'The Remote connection request was superseded or closed.')) this.selectionLifetime = new AbortController() return AbortSignal.any([this.selectionLifetime.signal, this.remoteLifetime.signal, ...(signal === undefined ? [] : [signal])]) } private handleRemoteClose(remote: ConnectedRemote, error?: Error): void { if (this.connected !== remote) return const recover = this.recoverable === remote this.recoverable = undefined this.connected = undefined this.connectionProgress = undefined this.pendingWorkspaceSelection = undefined this.gatewaySwitch.disconnectRemote() const cleanup = Promise.allSettled([ this.closePreview(), this.closeCodexVirtual(), this.closeCursorVirtual(), this.codexStreamBridge.closeCodexStreams(remote.client), remote.client.close(), ]) this.logger.warn('remote Harness transport closed', { targetDeviceId: shortId(remote.target.deviceId) }) // CodeX/ACP have separate virtual workspace lifetimes; never replace them // with Harness authority after a disconnect. if (!this.closed && this.gatewaySwitch.status().mode === 'remote') this.noteClientAuthFailure(error) if (!recover || this.closed) return this.reconnect.start(async signal => { await cleanup signal.throwIfAborted() const next = await this.connect(remote.target.deviceId, signal) try { signal.throwIfAborted() this.selectRemoteTarget(next) this.connected = next this.connection.clearConnectionProgress(next.progressRunId) this.recoveryGeneration += 1 } catch (error) { await next.client.close().catch(() => undefined) throw error } }, error) } } export { probeRemoteHostFeatures, remoteHostFeatures } from './client-capabilities.js' export { ClientModeError } from './client-runtime-contract.js' export type { HostAuthorizationControl, HostConnectionHandle, HostConnectionRpc, RemoteDeviceView, RemoteDirectoryEntry, RemoteDirectoryListing, RemoteHostFeatures, RemoteWorkspaceView } from './client-runtime-contract.js'