diff --git a/packages/plugin/src/control-runtime.ts b/packages/plugin/src/control-runtime.ts new file mode 100644 index 0000000..04a4111 --- /dev/null +++ b/packages/plugin/src/control-runtime.ts @@ -0,0 +1,868 @@ +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 }, + }, + } +}