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

869 lines
40 KiB
TypeScript

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<Record<'host' | 'client', PluginAssociation>>
acpAvailability?: Record<string, boolean>
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<void>
}
/** Loopback-only control plane shared by Local/Remote switching and plugin setup. */
export class PluginControlRuntime {
private logoutFlight?: Promise<PluginSettingsView>
private serverSwitchFlight?: Promise<PluginSettingsView>
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<void> {
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<unknown> {
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<ControlResult<unknown>> {
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<string, unknown> = {
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<Record<string, unknown>> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<string, string[]> = {
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<void> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<PluginSettingsView> {
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<Record<string, boolean>> {
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<PluginSettingsView['associations']> {
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<PluginAssociation | undefined> {
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<string, unknown> {
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<string, { value: Promise<boolean>, 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<boolean> {
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<boolean> {
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<boolean> {
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<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function record(value: unknown): Record<string, unknown> {
if (!isRecord(value)) throw new ClientModeError('INVALID_MESSAGE', 'The control request payload is invalid.')
return value
}
function ok(value: unknown): ControlResult<unknown> { return { ok: true, value } }
/** Attach the update-check snapshot to a successful status-shaped result. */
function withUpdate(result: ControlResult<unknown>, update: PluginUpdateSnapshot | undefined): ControlResult<unknown> {
if (update === undefined || !result.ok || !isRecord(result.value)) return result
return ok({ ...result.value, update })
}
function fail(error: unknown): ControlResult<unknown> {
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 },
},
}
}