ds-harness-remote-fast/packages/plugin/src/client-runtime.ts

1174 lines
54 KiB
TypeScript

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<ConnectedRemote> {
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<ControlResult<unknown>> {
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<string, string>()
private codexOpenGeneration = 0
private cursorVirtual?: AcpVirtualHarness
private cursorVirtualSelection?: { targetDeviceId: string; workspaceId: string; backend: string }
private readonly acpOpenedSessions = new Map<string, string>()
private acpVirtualBackend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' = 'cursor'
private readonly remoteHistoryCaches = new Map<string, RemoteSessionHistoryCache>()
private readonly codexHistoryCaches = new Map<string, CodexSessionHistoryCache>()
private readonly acpHistoryCaches = new Map<string, AcpSessionHistoryCache>()
private readonly gatewaySwitch: TypertGatewaySwitch
private readonly codexStreams = new Map<string, CodexLoopbackStream>()
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<object, Promise<RemoteHostFeatures>>()
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<unknown> {
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<RtcPeerConnectionFactory | undefined> = 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<void> {
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<void> {
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<void> {
return registerControlRoute(connection, (endpoint, payload, signal) => this.control.handleControl(endpoint, payload, signal), webServer)
}
status(): Record<string, unknown> {
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<void> {
const preview = this.preview; this.preview = undefined
await preview?.close()
}
private async detailedStatus(): Promise<Record<string, unknown>> {
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<RemoteDeviceView[]> {
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<unknown> {
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<unknown> {
return this.server.startOAuthQrLogin(provider)
}
async pollClientOAuthQrLogin(qrId: string): Promise<unknown> {
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<void> {
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<unknown> {
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<Record<string, unknown>> {
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<RemoteDirectoryListing> {
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<RemoteWorkspaceView[]> {
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<RemoteWorkspaceView & { backend: string }>
unavailable: Array<{ backend: string; code: string }>
}> {
return this.withToolRemote(targetDeviceId, signal, async (remote, activeSignal) => {
const workspaces: Array<RemoteWorkspaceView & { backend: string }> = []
const unavailable: Array<{ backend: string; code: string }> = []
const read = async (backend: string, query: () => Promise<RemoteWorkspaceView[]>) => {
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<T>(
targetDeviceId: string,
signal: AbortSignal,
query: (remote: ConnectedRemote, signal: AbortSignal) => Promise<T>,
): Promise<T> {
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<void> | 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<Record<string, unknown>> {
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<CodexVirtualWorkspaceView[]> {
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<Record<string, unknown>> {
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<Record<string, unknown>> {
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<AcpVirtualWorkspaceView[]> {
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<Record<string, unknown>> {
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<Record<string, unknown>> {
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<string, unknown> {
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<void> {
if (this.closed) return
this.closed = true
this.server.close?.()
try {
await this.leaveRemote()
} finally {
this.clearHistoryCaches()
this.gatewaySwitch.restore()
}
}
private async leaveRemote(): Promise<void> {
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<unknown> {
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<PluginRouteCallResult> {
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<typeof gateway.invoke>[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<void> {
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<void> {
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<RemoteHostFeatures> {
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<ConnectedRemote> {
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'