import { hostname } from 'node:os' import { existsSync } from 'node:fs' import { execFile } from 'node:child_process' import { promisify } from 'node:util' import type { ControlResult } from './control-result.js' import { setLiteModeEnabled } from './lite-mode.js' import { setForceRelayEnabled } from './relay-preference.js' import { resolveConfig, type Config, type ConfigInput, type ResolvedConfig } from './config.js' import { ClientModeError, type ClientModeRuntime, type HostConnectionHandle, type HostAuthorizationControl, } from './client-runtime.js' import { IdentityInvalidError, IdentityStore, resetDefaultIdentityRoles, serverStorageDirectory, type RemoteDeviceRole, } from './identity-store.js' import { safeStartupError } from './safe-error.js' import { ClientServerApi, HostServerApi } from './server-api.js' import { ServerCredentialStore, ServerCredentialsInvalidError } from './server-credentials.js' import { registerControlRoute, type HostWebServerLike } from './control-route.js' import { ControlStatusStream } from './control-stream.js' import type { PluginUpdateSnapshot } from './update-check.js' import { codexBinaryCandidates } from './codex/domain.js' import { cursorBinaryCandidates } from './acp/gateway.js' import { defaultCheckExecutable, installOrConfigureBackend, isBuiltinAcpBackend } from './acp/backend-installer.js' const execFileAsync = promisify(execFile) export interface PluginSettingsView { config: Config deviceName: string writable: boolean applies: 'live' | 'restart' association?: PluginAssociation associations: Partial> acpAvailability?: Record acpInstallResult?: { backend: string action: 'configured' | 'installed' | 'download_required' downloadUrl?: string } startupError?: { code: string message: string } } export interface PluginAssociation { method: 'account' | 'host_registration_code' | 'owned_device' | 'device_pairing' account?: string } /** * Live read/write face of the plugin's profile-owned entry Config. * * DSH 0.1.7-rc.1 (DSH-0.1.7-RC1-04) removed the settings-namespace registry * and its scope type: the entry's editable fields are a single * `.volatile()` Cordis Config, read through `.get()`, and writes go to * `ctx.settings.replace(entryId, section)` (persisted in the active profile's * `cordis.patch.yml` under the entry id). */ export interface PluginSettingsBinding { /** The current config, read from the entry's live volatile reference. */ get(): ConfigInput /** Replace the entry's editable fields in the active profile. */ replace(section: Config): Promise } /** Loopback-only control plane shared by Local/Remote switching and plugin setup. */ export class PluginControlRuntime { private logoutFlight?: Promise private serverSwitchFlight?: Promise private startupFailure?: unknown private storageAvailable = true setStartupFailure(error: unknown, options?: { storageAvailable?: boolean }): void { this.startupFailure = error if (options?.storageAvailable !== undefined) { this.storageAvailable = options.storageAvailable } this.client = undefined this.host = undefined } clearStartupFailure(): void { this.startupFailure = undefined this.storageAvailable = true } setIdentityDirectory(directory: string): void { this.identityDirectory = directory this.storageAvailable = true } constructor( private config: ResolvedConfig, private identityDirectory: string, private readonly settings: PluginSettingsBinding | undefined, private client: ClientModeRuntime | undefined, private host: HostAuthorizationControl | undefined, private readonly switchServer?: (config: ResolvedConfig) => Promise<{ client: ClientModeRuntime | undefined host: HostAuthorizationControl }>, /** Update-check snapshots merged into every `status` result; absent when the plugin is disabled. */ private readonly updates?: { snapshot(): PluginUpdateSnapshot | undefined }, private readonly useDefaultStorage = false, ) {} register(connection: HostConnectionHandle, webServer?: HostWebServerLike): () => Promise { const statusStream = new ControlStatusStream(() => this.streamStatus()) return registerControlRoute( connection, (endpoint, payload, signal) => this.handle(endpoint, payload, signal), webServer, statusStream, ) } /** * Read the value the status event stream pushes. It resolves through the same * endpoint handler as the unary `status` control call, so a pushed status and * a polled one can never diverge. */ private async streamStatus(): Promise { const result = await this.handle('status', {}, new AbortController().signal) if (!result.ok) throw new ClientModeError('STATUS_UNAVAILABLE', result.error.message) return result.value } private async handle(endpoint: string, payload: unknown, signal: AbortSignal): Promise> { try { // A request arriving during replacement must use the new Server runtime. if (endpoint !== 'settings.server.set' && endpoint !== 'settings.identity.reset' && endpoint !== 'settings.startup.retry') await this.serverSwitchFlight if (endpoint.startsWith('host.pairing.')) { if (this.host?.pairingControl === undefined) throw new ClientModeError('METHOD_NOT_ALLOWED', 'Host device pairing is unavailable.') const action = endpoint.slice('host.pairing.'.length) if (action !== 'start' && action !== 'status' && action !== 'confirm' && action !== 'cancel') throw new ClientModeError('METHOD_NOT_ALLOWED', 'Unknown pairing action.') const input = record(payload) if (Object.keys(input).some(key => key !== 'sessionId' && key !== 'verificationCode') || input.sessionId !== undefined && typeof input.sessionId !== 'string' || input.verificationCode !== undefined && typeof input.verificationCode !== 'string') throw new ClientModeError('INVALID_MESSAGE', 'Invalid pairing request.') if (action === 'start') await this.client?.handleControl('mode.set', { mode: 'local' }, signal) const view = await this.host.pairingControl(action, input as { sessionId?: string; verificationCode?: string }) if (view?.localSaved && this.host.hostStatus().pairingHostOnly) await this.client?.handleControl('mode.set', { mode: 'local' }, signal) return ok(view) } if (endpoint === 'settings.development.set') return ok(await this.setDevelopment(payload)) if (endpoint === 'settings.appearance.set') return ok(await this.setAppearance(payload)) if (endpoint === 'settings.lite.set') return ok(await this.setLite(payload)) if (endpoint === 'settings.forceRelay.set') return ok(await this.setForceRelay(payload)) if (endpoint === 'settings.get') return ok(await this.settingsView()) if (endpoint === 'settings.configure') return ok(await this.configure(payload)) if (endpoint === 'settings.server.set') return ok(await this.setServer(payload)) if (endpoint === 'settings.startup.retry') return ok(await this.retryStartup()) if (endpoint === 'settings.role.set') return ok(await this.setRole(payload)) if (endpoint === 'settings.codex.set') return ok(await this.setCodex(payload)) if (endpoint === 'settings.cursor.set') return ok(await this.setCursor(payload)) if (endpoint === 'settings.acp.set') return ok(await this.setAcp(payload)) if (endpoint === 'settings.acp.add') return ok(await this.addAcp(payload)) if (endpoint === 'settings.acp.remove') return ok(await this.removeAcp(payload)) if (endpoint === 'settings.acp.installOrConfigure') return ok(await this.installOrConfigureAcp(payload)) if (endpoint === 'settings.logout') return ok(await this.logout()) if (endpoint === 'settings.identity.reset') return ok(await this.resetIdentity(payload)) if (endpoint === 'host.authorization.set' && this.client !== undefined) { const value = record(payload) if (typeof value.enabled !== 'boolean') throw new ClientModeError('INVALID_MESSAGE', 'Host authorization state is required.') const status = await this.client.setHostAuthorization(value.enabled) if (this.settings !== undefined) { const current = resolveConfig(this.settings.get()) await this.settings.replace(editableConfig({ ...current, hostControl: { enabled: value.enabled } })) } return ok(status) } if (endpoint === 'host.reconnect') { if (this.host === undefined) throw new ClientModeError('METHOD_NOT_ALLOWED', 'This plugin is not running as a Host.') this.host.reconnectHost() return withUpdate(ok(this.hostOnlyStatus()), this.updates?.snapshot()) } if (endpoint === 'status') { if (this.startupFailure !== undefined) { const startupError = safeStartupError(this.startupFailure) const failureStatus: Record = { mode: 'local', available: false, controlUnavailable: false, connected: false, transport: 'Disconnected', startupError, hostAuthorizationAvailable: false, } return withUpdate(ok(failureStatus), this.updates?.snapshot()) } // Both mode paths merge the update snapshot here, so the SSE stream, // polling, and the unary call always observe the same payload shape. const base = this.client !== undefined ? await this.client.handleControl(endpoint, payload, signal) : ok(this.hostOnlyStatus()) return withUpdate(base, this.updates?.snapshot()) } if (this.client !== undefined) return this.client.handleControl(endpoint, payload, signal) if (endpoint === 'devices') return ok([]) if (endpoint === 'host.account.login') { if (this.host === undefined) throw new ClientModeError('METHOD_NOT_ALLOWED', 'This plugin is not running as a Host.') const value = record(payload) if (typeof value.email !== 'string' || typeof value.password !== 'string') { throw new ClientModeError('INVALID_MESSAGE', 'Email and password are required.') } return ok(await this.host.authorizeHostWithAccount(value.email, value.password)) } if (endpoint === 'host.registration-code.submit') { if (this.host === undefined) throw new ClientModeError('METHOD_NOT_ALLOWED', 'This plugin is not running as a Host.') const value = record(payload) if (typeof value.code !== 'string' || value.code.trim() === '') { throw new ClientModeError('INVALID_MESSAGE', 'A Host registration code is required.') } return ok(await this.host.authorizeHostWithCode(value.code)) } if (endpoint === 'mode.set' && record(payload).mode === 'local') { return withUpdate(ok(this.hostOnlyStatus()), this.updates?.snapshot()) } if (this.startupFailure instanceof Error) { throw this.startupFailure } throw new ClientModeError('METHOD_NOT_ALLOWED', 'Remote Client mode is disabled by the plugin role.') } catch (error) { return fail(error) } } private async configure(payload: unknown): Promise> { if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const value = record(payload) if (value.role !== 'host' && value.role !== 'client') { throw new ClientModeError('INVALID_MESSAGE', 'Role must be Host or Client.') } if (typeof value.serverUrl !== 'string') { throw new ClientModeError('INVALID_MESSAGE', 'Server URL is required.') } const current = editableConfig(resolveConfig(this.settings.get())) if (value.role === 'client' && this.host?.hostStatus?.()?.pairingHostOnly) throw new ClientModeError('DEVICE_SCOPE_REQUIRED', 'This Host only accepts incoming connections.') const next = resolveConfig({ ...current, role: value.role, serverUrl: value.serverUrl }) if (!this.storageAvailable && this.startupFailure instanceof Error) { throw this.startupFailure } const identities = new IdentityStore({ directory: serverStorageDirectory(this.identityDirectory, next.serverUrl!, value.role), role: value.role, }) let identity = await identities.loadOrCreate(hostname()) const api = value.role === 'host' ? new HostServerApi(next.serverUrl!, new ServerCredentialStore(identities.directory), fetch, 'host', next.httpServerAllowlist) : new ClientServerApi(next.serverUrl!, new ServerCredentialStore(identities.directory), fetch, next.httpServerAllowlist) let authorization if (value.role === 'host' && typeof value.registrationCode === 'string' && value.registrationCode.trim() !== '') { authorization = await api.authorizeHostWithCode(identity, value.registrationCode) } else { if (typeof value.email !== 'string' || typeof value.password !== 'string') { throw new ClientModeError('INVALID_MESSAGE', 'Email and password are required for account authorization.') } authorization = await api.authorizeWithAccount(identity, value.email, value.password, async () => { identity = await identities.reset(hostname()) return identity }) } if (value.role === 'client' && resolveConfig(this.settings.get()).hostControl?.enabled !== false) { await this.client?.authorizeHostByDefault() } await this.settings.replace(editableConfig(next)) return { status: 'authorized', role: value.role, ...(authorization.account === undefined ? {} : { account: authorization.account }), settings: await this.settingsView(), } } private async setServer(payload: unknown): Promise { if (this.serverSwitchFlight !== undefined) { throw new ClientModeError('SERVER_SWITCH_BUSY', 'A Server switch is already in progress.') } const flight = this.applyServer(payload) this.serverSwitchFlight = flight try { return await flight } finally { if (this.serverSwitchFlight === flight) this.serverSwitchFlight = undefined } } private async retryStartup(): Promise { if (this.serverSwitchFlight !== undefined) { throw new ClientModeError('SERVER_SWITCH_BUSY', 'A Server switch is already in progress.') } if (this.startupFailure === undefined) return this.settingsView() const switchServer = this.switchServer if (switchServer === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'Remote startup retry is unavailable in this profile.') } const flight = (async () => { await this.logoutFlight try { const runtimes = await switchServer(this.config) this.client = runtimes.client this.host = runtimes.host this.clearStartupFailure() } catch (error) { this.setStartupFailure(error) throw error } return this.settingsView() })() this.serverSwitchFlight = flight try { return await flight } finally { if (this.serverSwitchFlight === flight) this.serverSwitchFlight = undefined } } private async applyServer(payload: unknown): Promise { await this.logoutFlight if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const value = record(payload) if (typeof value.serverUrl !== 'string') { throw new ClientModeError('INVALID_MESSAGE', 'Server URL is required.') } const current = editableConfig(resolveConfig(this.settings.get())) const next = resolveConfig({ ...current, serverUrl: value.serverUrl }) await this.settings.replace(editableConfig(next)) if (this.switchServer !== undefined) { if (next.serverUrl !== this.config.serverUrl || this.startupFailure !== undefined) { try { const runtimes = await this.switchServer(next) this.client = runtimes.client this.host = runtimes.host this.clearStartupFailure() } catch (error) { this.config = next this.setStartupFailure(error) throw error } } this.config = next return { ...await this.settingsView(), applies: 'live' } } return this.settingsView() } private async resetIdentity(payload: unknown): Promise { if (this.serverSwitchFlight !== undefined) { throw new ClientModeError('SERVER_SWITCH_BUSY', 'A Server switch is already in progress.') } const flight = this.applyResetIdentity(payload) this.serverSwitchFlight = flight try { return await flight } finally { if (this.serverSwitchFlight === flight) this.serverSwitchFlight = undefined } } private async applyResetIdentity(payload: unknown): Promise { await this.logoutFlight const value = payload === undefined ? {} : record(payload) const roleArg = value.role === undefined ? 'all' : value.role if (roleArg !== 'host' && roleArg !== 'client' && roleArg !== 'all') { throw new ClientModeError('INVALID_MESSAGE', 'Role must be host, client, or all.') } const roles: RemoteDeviceRole[] = roleArg === 'client' ? ['client'] : roleArg === 'host' ? ['host'] : ['host', 'client'] const config = this.settings === undefined ? this.config : resolveConfig(this.settings.get()) const nextDirectory = await resetDefaultIdentityRoles( roles, config.serverUrl, hostname(), this.useDefaultStorage ? {} : { directory: this.identityDirectory }, ) this.setIdentityDirectory(nextDirectory) if (this.switchServer !== undefined) { try { const runtimes = await this.switchServer(config) this.client = runtimes.client this.host = runtimes.host this.config = config this.clearStartupFailure() } catch (error) { this.setStartupFailure(error) throw error } return { ...await this.settingsView(), applies: 'live' } } this.clearStartupFailure() return { ...await this.settingsView(), applies: 'live' } } private async setLite(payload: unknown): Promise { if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const enabled = record(payload).enabled if (typeof enabled !== 'boolean') { throw new ClientModeError('INVALID_MESSAGE', 'The lite mode switch must be a boolean.') } const current = editableConfig(resolveConfig(this.settings.get())) await this.settings.replace({ ...current, liteMode: enabled }) setLiteModeEnabled(enabled) return { ...await this.settingsView(), applies: 'live' } } /** * Relay-only preference. Applies to new connections; the Host re-dials the * Server so its advertised capabilities (and the Server-side negotiation) * drop LAN/P2P/TURN right away. */ private async setForceRelay(payload: unknown): Promise { if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const enabled = record(payload).enabled if (typeof enabled !== 'boolean') { throw new ClientModeError('INVALID_MESSAGE', 'The relay preference must be a boolean.') } const current = editableConfig(resolveConfig(this.settings.get())) await this.settings.replace({ ...current, forceRelay: enabled }) setForceRelayEnabled(enabled) this.host?.reconnectHost() return { ...await this.settingsView(), applies: 'live' } } private async setRole(payload: unknown): Promise { if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const role = record(payload).role if (role !== 'host' && role !== 'client') { throw new ClientModeError('INVALID_MESSAGE', 'Role must be Host or Client.') } const current = editableConfig(resolveConfig(this.settings.get())) const currentRole = current.role === 'client' ? 'client' : 'host' if (role === 'client' && this.host?.hostStatus?.()?.pairingHostOnly) throw new ClientModeError('DEVICE_SCOPE_REQUIRED', 'This Host only accepts incoming Remote connections.') if (role !== currentRole && current.serverUrl !== undefined && await this.association(current.serverUrl, role) === undefined) { await this.authorizeOwnedRole(current.serverUrl, currentRole, role) } await this.settings.replace({ ...current, role }) return this.settingsView() } private async setDevelopment(payload: unknown): Promise { if (this.settings === undefined) throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') const value = record(payload) if (value.debugLogging !== undefined && typeof value.debugLogging !== 'boolean') throw new ClientModeError('INVALID_MESSAGE', 'The debug logging switch must be a boolean.') if (value.remoteToolsEnabled !== undefined && typeof value.remoteToolsEnabled !== 'boolean') throw new ClientModeError('INVALID_MESSAGE', 'The Remote Tools switch must be a boolean.') if (value.terminalEnabled !== undefined && typeof value.terminalEnabled !== 'boolean') throw new ClientModeError('INVALID_MESSAGE', 'The terminal switch must be a boolean.') if (value.ports !== undefined && (!Array.isArray(value.ports) || value.ports.some((port) => !Number.isInteger(port)))) throw new ClientModeError('INVALID_MESSAGE', 'Loopback ports must be integers.') if (value.terminalEnabled === undefined && value.remoteToolsEnabled === undefined && value.ports === undefined && value.debugLogging === undefined) throw new ClientModeError('INVALID_MESSAGE', 'A development setting is required.') const current = editableConfig(resolveConfig(this.settings.get())) const next = resolveConfig({ ...current, logLevel: value.debugLogging === undefined ? current.logLevel : value.debugLogging ? 'debug' : 'info', terminal: { enabled: value.terminalEnabled === undefined ? (current.terminal?.enabled ?? true) : value.terminalEnabled }, remoteTools: { enabled: value.remoteToolsEnabled === undefined ? (current.remoteTools?.enabled ?? true) : value.remoteToolsEnabled }, loopback: { ports: value.ports === undefined ? (current.loopback?.ports ?? []) : value.ports }, }) await this.settings.replace(editableConfig(next)) if (value.terminalEnabled !== undefined) this.host?.setTerminalEnabled?.(value.terminalEnabled) if (value.ports !== undefined) this.host?.setLoopbackPorts?.(value.ports) return this.settingsView() } private async setAppearance(payload: unknown): Promise { if (this.settings === undefined) throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') const entry = record(payload).sidebarEntry if (entry !== 'standard' && entry !== 'compact') throw new ClientModeError('INVALID_MESSAGE', 'The sidebar entry style must be Standard or Compact.') const current = editableConfig(resolveConfig(this.settings.get())) await this.settings.replace(editableConfig(resolveConfig({ ...current, sidebar: { entry } }))) return this.settingsView() } private async setCodex(payload: unknown): Promise { if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const enabled = record(payload).enabled if (typeof enabled !== 'boolean') { throw new ClientModeError('INVALID_MESSAGE', 'Codex Remote enabled must be a boolean.') } return this.setAcp({ backend: 'codex', enabled }) } private async setCursor(payload: unknown): Promise { if (this.settings === undefined) { throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') } const enabled = record(payload).enabled if (typeof enabled !== 'boolean') { throw new ClientModeError('INVALID_MESSAGE', 'Cursor Remote enabled must be a boolean.') } const current = editableConfig(resolveConfig(this.settings.get())) const next = resolveConfig({ ...current, cursor: { ...current.cursor, enabled }, acp: { enabled: enabled || current.acp?.enabled === true, backends: current.acp?.backends?.map(item => item.id === 'cursor' ? { ...item, enabled } : item), }, }) await this.settings.replace(editableConfig(next)) await this.host?.setAgentBackends?.(resolveConfig(this.settings.get())) return { ...await this.settingsView(), applies: 'live' } } private async setAcp(payload: unknown): Promise { if (this.settings === undefined) throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') const value = record(payload) const backend = value.backend const enabled = value.enabled if (typeof backend !== 'string' || typeof enabled !== 'boolean') throw new ClientModeError('INVALID_MESSAGE', 'ACP backend and enabled are required.') const current = resolveConfig(this.settings.get()) if (!current.acp?.backends.some(item => item.id === backend)) throw new ClientModeError('INVALID_MESSAGE', 'Unknown ACP backend.') const backends = current.acp.backends.map(item => item.id === backend ? { ...item, enabled } : item) await this.settings.replace({ ...editableConfig(current), ...(backend === 'cursor' ? { cursor: { ...current.cursor, enabled } } : {}), ...(backend === 'codex' ? { codex: { ...current.codex, enabled } } : {}), acp: { enabled: enabled || current.acp.enabled, backends }, }) await this.host?.setAgentBackends?.(resolveConfig(this.settings.get())) return { ...await this.settingsView(), applies: 'live' } } private async addAcp(payload: unknown): Promise { if (this.settings === undefined) throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') const value = record(payload) if (typeof value.id !== 'string' || typeof value.command !== 'string' || !Array.isArray(value.args) || !value.args.every(item => typeof item === 'string')) { throw new ClientModeError('INVALID_MESSAGE', 'ACP name, command, and arguments are required.') } const current = resolveConfig(this.settings.get()) if (value.id === 'kimi') throw new ClientModeError('INVALID_MESSAGE', 'Kimi is not implemented.') if (current.acp?.backends.some(item => item.id === value.id)) throw new ClientModeError('INVALID_MESSAGE', 'ACP backend already exists.') const backends = [...(current.acp?.backends ?? []), { id: value.id, command: value.command, args: value.args, enabled: false }] const next = resolveConfig({ ...editableConfig(current), acp: { enabled: current.acp?.enabled ?? true, backends } }) await this.settings.replace(editableConfig(next)) await this.host?.setAgentBackends?.(resolveConfig(this.settings.get())) return { ...await this.settingsView(), applies: 'live' } } private async removeAcp(payload: unknown): Promise { if (this.settings === undefined) throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') const id = record(payload).id if (typeof id !== 'string' || ['codex', 'cursor', 'antigravity', 'pi', 'claude', 'opencode', 'hermes'].includes(id)) throw new ClientModeError('INVALID_MESSAGE', 'Only custom ACP backends can be removed.') const current = resolveConfig(this.settings.get()) const backends = (current.acp?.backends ?? []).filter(item => item.id !== id) await this.settings.replace(editableConfig({ ...current, acp: { enabled: current.acp?.enabled ?? true, backends } })) await this.host?.setAgentBackends?.(resolveConfig(this.settings.get())) return { ...await this.settingsView(), applies: 'live' } } private async installOrConfigureAcp(payload: unknown): Promise { if (this.settings === undefined) throw new ClientModeError('SETTINGS_UNAVAILABLE', 'DSH user settings are unavailable in this profile.') const value = record(payload) const backend = value.backend if (typeof backend !== 'string' || !isBuiltinAcpBackend(backend)) { throw new ClientModeError('INVALID_MESSAGE', 'A valid built-in ACP backend is required.') } const outcome = await installOrConfigureBackend(backend) if (outcome.action === 'download_required') { const view = await this.settingsView() return { ...view, acpInstallResult: { backend, action: 'download_required', downloadUrl: outcome.downloadUrl, }, } } const detected = outcome.detectedCommand if (!detected) { throw new ClientModeError('ACP_UNAVAILABLE', `Backend ${backend} could not be configured.`) } const defaultArgsMap: Record = { codex: ['app-server'], cursor: ['acp'], antigravity: ['--input-format', 'stream-json', '--output-format', 'stream-json'], hermes: ['acp'], opencode: ['acp'], pi: [], claude: [], } const defaultArgs = defaultArgsMap[backend] ?? ['acp'] const current = resolveConfig(this.settings.get()) const existing = current.acp?.backends.some(item => item.id === backend) const backends = existing ? (current.acp?.backends ?? []).map(item => item.id === backend ? { ...item, command: detected, enabled: true } : item) : [...(current.acp?.backends ?? []), { id: backend, command: detected, enabled: true, args: defaultArgs }] await this.settings.replace({ ...editableConfig(current), ...(backend === 'cursor' ? { cursor: { ...current.cursor, binary: detected, enabled: true } } : {}), ...(backend === 'codex' ? { codex: { ...current.codex, binary: detected, enabled: true } } : {}), acp: { enabled: true, backends }, }) await this.host?.setAgentBackends?.(resolveConfig(this.settings.get())) const view = await this.settingsView() return { ...view, applies: 'live', acpInstallResult: { backend, action: outcome.action, downloadUrl: outcome.downloadUrl, }, } } private async authorizeOwnedRole( serverUrl: string, sourceRole: 'host' | 'client', targetRole: 'host' | 'client', ): Promise { if (!this.storageAvailable && this.startupFailure instanceof Error) { throw this.startupFailure } const current = resolveConfig(this.settings?.get() ?? {}) const sourceDirectory = serverStorageDirectory(this.identityDirectory, serverUrl, sourceRole) const sourceIdentity = await new IdentityStore({ directory: sourceDirectory, role: sourceRole }).loadOrCreate(hostname()) const sourceStore = new ServerCredentialStore(sourceDirectory) if (await sourceStore.load(serverUrl, sourceIdentity.deviceId) === undefined) return const sourceApi = sourceRole === 'host' ? new HostServerApi(serverUrl, sourceStore, fetch, 'host', current.httpServerAllowlist) : new ClientServerApi(serverUrl, sourceStore, fetch, current.httpServerAllowlist) sourceApi.bindIdentity(sourceIdentity) await sourceApi.loadStoredPolicy() if (sourceApi.pairingHostOnly()) throw new ClientModeError('DEVICE_SCOPE_REQUIRED', 'Paired Host cannot create a Client identity.') const sourceCredentials = await sourceApi.authenticate(sourceIdentity) const targetDirectory = serverStorageDirectory(this.identityDirectory, serverUrl, targetRole) const targetIdentity = await new IdentityStore({ directory: targetDirectory, role: targetRole }).loadOrCreate(hostname()) const targetApi = targetRole === 'host' ? new HostServerApi(serverUrl, new ServerCredentialStore(targetDirectory), fetch, 'host', current.httpServerAllowlist) : new ClientServerApi(serverUrl, new ServerCredentialStore(targetDirectory), fetch, current.httpServerAllowlist) await targetApi.authorizeOwnedRole(targetIdentity, sourceCredentials.accessToken, sourceCredentials.account) } private logout(): Promise { if (this.logoutFlight !== undefined) return this.logoutFlight const task = this.clearAuthorization() this.logoutFlight = task void task.finally(() => { if (this.logoutFlight === task) this.logoutFlight = undefined }).catch(() => undefined) return task } private async clearAuthorization(): Promise { if (!this.storageAvailable && this.startupFailure instanceof Error) { throw this.startupFailure } const config = this.settings === undefined ? this.config : resolveConfig(this.settings.get()) if (config.serverUrl !== undefined) { const runtimes = await Promise.allSettled([ this.client?.clearClientAuthorization(), this.host?.clearHostAuthorization(), ]) const stores = await Promise.allSettled((['host', 'client'] as const).map(async role => { const directory = serverStorageDirectory(this.identityDirectory, config.serverUrl!, role) await new ServerCredentialStore(directory).clear() })) // A failed revocation must not skip the other role or leave its local // credential behind. Report failure only after every cleanup settles. const failure = [...runtimes, ...stores].find(result => result.status === 'rejected') if (failure?.status === 'rejected') throw failure.reason } return this.settingsView() } private async settingsView(): Promise { const config = this.settings === undefined ? editableConfig(this.config) : editableConfig(resolveConfig(this.settings.get())) const associations = await this.associations(config) const role = config.role === 'client' ? 'client' : 'host' const association = associations[role] return { config, deviceName: hostname(), writable: this.settings !== undefined, applies: 'restart', associations, acpAvailability: await this.acpAvailability(config.acp?.backends ?? []), ...(association === undefined ? {} : { association }), ...(this.startupFailure === undefined ? {} : { startupError: safeStartupError(this.startupFailure), }), } } /** Probes run off the event loop; the TTL cache above keeps them rare. */ private async acpAvailability(backends: readonly { id: string, command?: string }[]): Promise> { const entries = await Promise.all(backends.map(async item => [item.id, await backendCommandAvailable(item.id, item.command ?? '')] as const)) return Object.fromEntries(entries) } private async associations(config: Config): Promise { if (config.serverUrl === undefined || !this.storageAvailable) return {} const [host, client] = await Promise.all([ this.association(config.serverUrl, 'host'), this.association(config.serverUrl, 'client'), ]) return { ...(host === undefined ? {} : { host }), ...(client === undefined ? {} : { client }), } } private async association(serverUrl: string, role: 'host' | 'client'): Promise { if (role === 'client' && this.host?.hostStatus?.()?.pairingHostOnly) return undefined try { const identities = new IdentityStore({ directory: serverStorageDirectory(this.identityDirectory, serverUrl, role), role, }) const identity = await identities.loadExisting() if (identity === undefined) return undefined const credentials = await new ServerCredentialStore(identities.directory).load(serverUrl, identity.deviceId) if (credentials === undefined) return undefined return { method: credentials.authorizationMethod, ...(credentials.account === undefined ? {} : { account: credentials.account }), } } catch (error) { if (error instanceof IdentityInvalidError || error instanceof ServerCredentialsInvalidError) { return undefined } throw error } } private hostOnlyStatus(): Record { return { mode: 'local', available: false, deviceName: hostname(), hostAuthorizationAvailable: this.host !== undefined, ...(this.host === undefined ? {} : { host: this.host.hostStatus() }), } } } /** * Probing a backend spawns `which`, which blocks the event loop; every settings * read used to pay for it (2x per save on a two-backend profile). The answer only * changes when the user installs a binary, so a short cache is enough. */ const COMMAND_AVAILABILITY_TTL_MS = 30_000 const commandAvailability = new Map, at: number }>() /** * Probing a backend spawns `which`. It used to run synchronously on every * settings read, blocking the event loop (and the frame pump) for tens of * milliseconds; now it runs off-thread and the answer is cached for a while. */ function backendCommandAvailable(backend: string, command: string): Promise { if (!command || typeof command !== 'string' || command.trim().length === 0) return Promise.resolve(false) const trimmed = command.trim() const cacheKey = `${backend}\u0000${trimmed}` const now = Date.now() const cached = commandAvailability.get(cacheKey) if (cached !== undefined && now - cached.at < COMMAND_AVAILABILITY_TTL_MS) return cached.value const value = probeBackendCommand(backend, trimmed) commandAvailability.set(cacheKey, { value, at: now }) return value } async function probeBackendCommand(backend: string, trimmed: string): Promise { if (defaultCheckExecutable(trimmed)) return true const candidates = backend === 'codex' ? codexBinaryCandidates(trimmed) : backend === 'cursor' || backend === 'antigravity' || backend === 'opencode' ? cursorBinaryCandidates(trimmed) : [trimmed] for (const candidate of candidates) { if (defaultCheckExecutable(candidate)) return true if (await commandAvailable(candidate)) return true } return false } async function commandAvailable(command: string): Promise { try { await execFileAsync(process.platform === 'win32' ? 'where' : 'which', [command], { timeout: 5000 }) return true } catch { return false } } export function editableConfig(config: ResolvedConfig): Config { return { enabled: config.enabled, role: config.role, ...(config.serverUrl === undefined ? {} : { serverUrl: config.serverUrl }), httpServerAllowlist: config.httpServerAllowlist, terminal: config.terminal, remoteTools: config.remoteTools, sidebar: config.sidebar, hostControl: config.hostControl ?? { enabled: true }, loopback: config.loopback, forceRelay: config.forceRelay, logLevel: config.logLevel, liteMode: config.liteMode, reconnect: config.reconnect.enabled ? { initialDelayMs: config.reconnect.initialDelayMs, maxDelayMs: config.reconnect.maxDelayMs, jitter: config.reconnect.jitter, } : false, codex: { enabled: config.codex.enabled, binary: config.codex.binary, }, cursor: { enabled: config.cursor.enabled, binary: config.cursor.binary, }, ...(config.acp === undefined ? {} : { acp: { enabled: config.acp.enabled, backends: config.acp.backends } }), } } function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) } function record(value: unknown): Record { if (!isRecord(value)) throw new ClientModeError('INVALID_MESSAGE', 'The control request payload is invalid.') return value } function ok(value: unknown): ControlResult { return { ok: true, value } } /** Attach the update-check snapshot to a successful status-shaped result. */ function withUpdate(result: ControlResult, update: PluginUpdateSnapshot | undefined): ControlResult { if (update === undefined || !result.ok || !isRecord(result.value)) return result return ok({ ...result.value, update }) } function fail(error: unknown): ControlResult { const source = error instanceof Error ? error : undefined const remoteCode = source !== undefined && 'code' in source && typeof source.code === 'string' ? source.code : source instanceof ClientModeError ? source.code : undefined return { ok: false, error: { code: 'internal', message: source?.message ?? 'The plugin control operation failed.', details: remoteCode === undefined ? {} : { remoteCode }, }, } }