From 07f730e978901d537ff97ea66d7dcd3257b707dd Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 14:51:21 +0800 Subject: [PATCH] Import packages/plugin/src/acp/gateway.ts --- packages/plugin/src/acp/gateway.ts | 1664 ++++++++++++++++++++++++++++ 1 file changed, 1664 insertions(+) create mode 100644 packages/plugin/src/acp/gateway.ts diff --git a/packages/plugin/src/acp/gateway.ts b/packages/plugin/src/acp/gateway.ts new file mode 100644 index 0000000..17e6680 --- /dev/null +++ b/packages/plugin/src/acp/gateway.ts @@ -0,0 +1,1664 @@ +import { IsolatedAcpClient } from './adapters/isolated-process.js' +import { WorkspaceBridge, WorkspaceBridgeState, type RemoteTerminalSpawner } from '../workspace-bridge.js' +import { TerminalPolicy } from '../terminal-policy.js' +import { AcpWorkspaceTools } from './workspace-tools.js' +import { randomUUID } from 'node:crypto' +import { readdir, realpath, stat } from 'node:fs/promises' +import { homedir } from 'node:os' +import { basename, isAbsolute, join, relative, resolve } from 'node:path' +import type { ResolvedAcpConfig, ResolvedAcpBackendConfig } from '../config.js' +import type { PeerConnectionContext } from '../connection-controller.js' +import type { SafeLogger } from '../logging.js' +import { RpcError } from '../safe-error.js' +import { PLUGIN_VERSION } from '../version.js' +import { + CursorAcpError, + type CursorAcpInbound, + type CursorAcpLike, +} from './adapters/cursor-process.js' +import { ClaudeAcpClient } from './adapters/claude-process.js' +import { HermesAcpClient } from './adapters/hermes-process.js' +import { PiAcpClient } from './adapters/pi-process.js' +import { AntigravityAcpClient } from './adapters/antigravity-process.js' +import { OpencodeAcpClient, OpencodeAcpError } from './adapters/opencode-process.js' +import { + ACP_METHOD_ALLOWLIST, + isSessionMutation, + parseAcpCall, + sessionIdFromParams, + type AllowedAcpMethod, +} from './method-policy.js' +import { discoverAntigravitySessions, discoverAntigravityWorkspaces, loadTranscriptEvents } from './adapters/antigravity/transcript-loader.js' +import { AcpPeerBridge, type PublishAcpFrame } from './peer-bridge.js' + +const APPROVAL_TTL_MS = 5 * 60_000 +// A backend that stayed up this long before failing starts a fresh retry budget. +const BACKEND_STABLE_MS = 30_000 + +const DEFAULT_RESTART_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000] as const +/** Backends that expose a Host-side session catalog (session/list) and replayed history. */ +type CatalogBackend = 'pi' | 'claude' | 'opencode' | 'hermes' +const CATALOG_BACKENDS: ReadonlySet = new Set(['pi', 'claude', 'opencode', 'hermes']) +const isCatalogBackend = (value: unknown): value is CatalogBackend => typeof value === 'string' && CATALOG_BACKENDS.has(value) +const ACP_DIRECTORY_ENTRY_LIMIT = 500 +const MAX_BUFFERED_ACP_FRAMES = 200 +const ACP_FRAME_BUFFER_TTL_MS = 5 * 60_000 +const MAX_TURN_CATCH_UP_FRAMES = 120 +const CATCH_UP_SESSION_UPDATES = new Set([ + 'agent_thought_chunk', + 'agent_thought', + 'agent_message_chunk', + 'agent_message', + 'user_message_chunk', + 'tool_call', + 'tool_call_update', +]) + +interface PendingApproval { + upstreamId: string | number + connectionId: string + sessionId: string + method: string + expiresAt: number + backend: string + client: CursorAcpLike + options: Array<{ kind: string; optionId: string }> +} + +interface BufferedAcpFrame { + method: string + params: unknown + at: number +} + +interface PromptTask { + backend: string + client: CursorAcpLike +} + +interface AcpDirectoryEntry { + name: string + path: string + hidden: boolean +} + +interface AcpDirectoryListing { + path: string + home: string + crumbs: AcpDirectoryEntry[] + entries: AcpDirectoryEntry[] + truncated: boolean +} + +type AcpFactory = (binary: string, logger: SafeLogger, backend: ResolvedAcpBackendConfig) => CursorAcpLike + +/** + * Host-side Agent ACP gateway (#65). Reuses the authenticated Remote channel and + * delegates to independently configured Cursor/Antigravity adapters. Owns method policy, + * session ownership, subscriptions, and permission handles per connection. + */ +export class AcpRemoteGateway { + private readonly backendInstances = new Map void + unsubscribeUnavailable: () => void + startedAt: number + }>() + private readonly sessionCwds = new Map() + private readonly workspaceState = new WorkspaceBridgeState(key => TerminalPolicy.releaseOwner(this.terminalOwners, key)) + private readonly terminalOwners = new Map() + private readonly workspaceTools = new Map() + private readonly peers = new Map() + private readonly sessionOwners = new Map() + private readonly sessionBackends = new Map() + private readonly sessionPermissions = new Map() + private readonly approvals = new Map() + private approvalExpiryTimer?: ReturnType + private readonly restartAttempts = new Map() + private readonly restartTimers = new Map() + private readonly launching = new Map>() + private available = false + private closed = false + private state: 'disabled' | 'starting' | 'ready' | 'restarting' | 'unavailable' = 'disabled' + private unavailableCode?: string + /** Keep ACP → Client fanout ordered; concurrent publish races Noise sends. */ + private inboundChain: Promise = Promise.resolve() + /** Catch-up buffer for turns that finish while the Client is reconnecting. */ + private readonly recentFrames = new Map() + /** Per-prompt live updates; attached to prompt_completed when streaming was lossy. */ + private readonly promptsInProgress = new Map() + private readonly cancelledSessions = new Set() + /** Identity fences asynchronous Pi preparation from a later retry of the same session. */ + private readonly preparingPrompts = new Map() + private readonly turnCatchUp = new Map>() + + private startPromise?: Promise + private readonly startingClients = new Map() + /** Desired configuration is saved immediately; unfinished cleanup must remain retryable. */ + private readonly pendingReconfiguration = new Set() + private readonly archivingSessions = new Set() + private readonly opencodeOperations = new Map() + private historyEpoch = 0 + private minValidHistoryEpoch = 0 + private readonly historyInvalidatedAt = new Map() + private readonly pendingHistoryReads = new Map }>() + private readonly backendHistoryChains = new Map>() + + constructor( + public config: ResolvedAcpConfig, + private readonly logger: SafeLogger, + private readonly createAcp: AcpFactory = (binary, targetLogger, backend) => { + if (backend.id === 'antigravity') { + return new AntigravityAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd }) + } + if (backend.id === 'claude') return new ClaudeAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd }) + if (backend.id === 'hermes') return new HermesAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd }) + if (backend.id === 'pi') return new PiAcpClient(binary, targetLogger, { args: backend.args, cwd: backend.cwd }) + if (backend.id === 'opencode') { + return new OpencodeAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd }) + } + return new IsolatedAcpClient(binary, targetLogger, { args: backend.args, cwd: backend.cwd, backend: 'cursor' }) + }, + private readonly restartDelaysMs: readonly number[] = DEFAULT_RESTART_DELAYS_MS, + private readonly terminalEnabled: () => boolean = () => false, + private readonly terminalSpawner?: RemoteTerminalSpawner, + ) {} + + /** Only implemented adapters are advertised; registry entries never select an adapter by executable name. */ + enabledBackends(): string[] { + if (!this.config.enabled) return [] + return this.config.backends.filter(item => item.enabled && ['antigravity', 'cursor', 'pi', 'claude', 'opencode', 'hermes'].includes(item.id)).map(item => item.id) + } + + start(): Promise { + if (this.closed) return Promise.reject(new RpcError('CURSOR_CLOSED', 'The ACP Remote domain is closed.')) + if (!this.config.enabled || !this.enabledBackends().some(id => !this.pendingReconfiguration.has(id))) return Promise.resolve() + this.startPromise ??= this.startOnce().finally(() => { this.startPromise = undefined }) + return this.startPromise + } + + private async startOnce(): Promise { + try { + this.state = 'starting' + await this.launchAcp() + } catch (error) { + if (this.closed) return + this.available = false + this.state = 'unavailable' + this.unavailableCode = errorCode(error) + await this.disposeAllInstances() + this.logger.warn('ACP Remote domain unavailable', { code: this.unavailableCode }) + } + } + + isAvailable(): boolean { + return this.config.enabled && this.available && this.availableBackends().length > 0 + } + + availableBackends(): string[] { + const list: string[] = [] + for (const [id, inst] of this.backendInstances) { + if (!this.pendingReconfiguration.has(id) && this.enabledBackends().includes(id) && inst.client.isReady()) list.push(id) + } + return list + } + + defaultBackend(): string { + const ready = this.availableBackends() + return this.enabledBackends().find(id => ready.includes(id)) ?? this.enabledBackends()[0] ?? 'antigravity' + } + + status(): { + enabled: boolean + available: boolean + state: 'disabled' | 'starting' | 'ready' | 'restarting' | 'unavailable' + restartAttempt: number + error?: string + availableBackends?: string[] + } { + return { + enabled: this.config.enabled, + available: this.isAvailable(), + state: this.state, + restartAttempt: Math.max(0, ...this.restartAttempts.values()), + availableBackends: this.availableBackends(), + ...(this.unavailableCode === undefined ? {} : { error: this.unavailableCode }), + } + } + + createPeer(context: PeerConnectionContext, publish: PublishAcpFrame): AcpPeerBridge | undefined { + const bridge = new AcpPeerBridge(this, context, publish, this.logger) + this.peers.set(context.connectionId, bridge) + const workspaceBridge = new WorkspaceBridge(async rawId => { + const match = rawId.match(/^(acp|cursor|pi|opencode|claude|hermes):(.+)$/) + const session = match ? this.sessionCwds.get(match[2]!) : undefined + const backend = match?.[1] === 'acp' ? 'antigravity' : match?.[1] === 'pi' ? 'pi' : match?.[1] === 'opencode' ? 'opencode' + : match?.[1] === 'claude' ? 'claude' : match?.[1] === 'hermes' ? 'hermes' : 'cursor' + if (!session || session.backend !== backend) throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.') + this.requireAcp(backend) + this.requireSessionOwner(context.connectionId, match![2]!) + return session.cwd + }, this.terminalEnabled, this.workspaceState, this.terminalSpawner, { + domain: 'ACP', owns: value => typeof value === 'string' && /^(acp|cursor|pi|opencode|claude|hermes):/.test(value), + parse: value => typeof value === 'string' && /^(acp|cursor|pi|opencode|claude|hermes):[A-Za-z0-9_-]{1,240}$/.test(value) + ? { sessionId: value, nativeId: value } : undefined, + }) + this.workspaceTools.set(context.connectionId, new AcpWorkspaceTools(workspaceBridge, + new TerminalPolicy(this.terminalEnabled, context.peerDeviceId, this.terminalOwners))) + return bridge + } + + async call(connectionId: string, input: unknown): Promise { + const envelope = parseCallEnvelope(input) + const call = parseAcpCall(envelope.method, envelope.params) + const sessionId = sessionIdFromParams(call.method, call.params) + const backend = call.params.backend ?? (sessionId ? this.sessionBackends.get(sessionId) ?? this.defaultBackend() : undefined) + const assertCurrent = this.captureCallScope(connectionId, typeof backend === 'string' ? backend : this.defaultBackend()) + const reserve = backend === 'opencode' && sessionId !== undefined && ['session/load', 'session/prompt', 'dsh/selectModel'].includes(call.method) + if (reserve) { + if (this.archivingSessions.has(sessionId!)) throw new RpcError('ACP_SESSION_BUSY', 'The OpenCode session is being archived.') + this.opencodeOperations.set(sessionId!, (this.opencodeOperations.get(sessionId!) ?? 0) + 1) + } + try { + const result = await this.callInternal(connectionId, call, assertCurrent) + assertCurrent() + return result + } + finally { + if (reserve) { + const remaining = (this.opencodeOperations.get(sessionId!) ?? 1) - 1 + if (remaining) this.opencodeOperations.set(sessionId!, remaining) + else this.opencodeOperations.delete(sessionId!) + } + } + } + + private captureCallScope(connectionId: string, backend: string): () => void { + const peer = this.peers.get(connectionId) + const instance = this.backendInstances.get(backend) + return () => { + if (this.closed || this.backendInstances.get(backend) !== instance + || (instance !== undefined && this.requireAcp(backend) !== instance.client)) { + throw new RpcError('CURSOR_UNAVAILABLE', 'The ACP backend changed while handling the request.') + } + if (peer !== undefined && this.peers.get(connectionId) !== peer) { + throw new RpcError('ACP_CONNECTION_CLOSED', 'The ACP connection is closed.') + } + } + } + + private async callInternal(connectionId: string, call: ReturnType, assertCurrent: () => void): Promise { + assertCurrent() + this.logger.info('ACP call received', { + method: call.method, + sessionId: typeof call.params?.sessionId === 'string' ? shortSessionId(call.params.sessionId) : undefined, + }) + + if (typeof call.params.backend === 'string') { + const prefix = typeof call.params.sessionId === 'string' ? /^(acp|cursor|pi|claude|opencode|hermes):/.exec(call.params.sessionId)?.[1] : undefined + if (prefix && (prefix === 'acp' ? 'antigravity' : prefix) !== call.params.backend) { + throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.') + } + const sessionId = call.method === 'dsh/sessionHistory' + ? String(call.params.sessionId).replace(/^(acp|cursor|pi|claude|opencode|hermes):/, '') + : sessionIdFromParams(call.method, call.params) + const boundBackend = sessionId === undefined ? undefined : this.sessionBackends.get(sessionId) + if (boundBackend !== undefined && boundBackend !== call.params.backend) { + throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.') + } + this.requireAcp(call.params.backend) + } + + if (call.method === 'initialize') { + const requestedBackend = typeof call.params?.backend === 'string' ? call.params.backend : undefined + this.requireAcp(requestedBackend) + return this.initializeResult(call.params, requestedBackend) + } + + if (call.method === 'dsh/sessionArchive') { + const sessionId = String(call.params.sessionId) + if (this.archivingSessions.has(sessionId) || this.opencodeOperations.has(sessionId)) throw new RpcError('ACP_SESSION_BUSY', 'The OpenCode session is busy.') + this.archivingSessions.add(sessionId) + try { + const backend = 'opencode' + const client = this.requireAcp(backend) as CursorAcpLike & { archiveSession?: (sessionId: string, cwd: string) => Promise } + const instance = this.backendInstances.get(backend) + const cwd = await this.catalogSessionCwd(backend, sessionId) + assertCurrent() + if (this.closed || this.requireAcp(backend) !== client || this.backendInstances.get(backend) !== instance) throw new RpcError('OPENCODE_ARCHIVE_UNAVAILABLE', 'The OpenCode backend changed. Refresh the session list.') + if (this.promptsInProgress.has(sessionId) || [...this.approvals.values()].some(item => item.sessionId === sessionId)) throw new RpcError('ACP_SESSION_BUSY', 'Stop the OpenCode reply and resolve its approvals before archiving.') + if (!client.archiveSession) throw new RpcError('OPENCODE_ARCHIVE_UNAVAILABLE', 'The Host OpenCode adapter does not support native archiving.') + await client.archiveSession(sessionId, cwd) + this.invalidateSessionHistory(sessionId) + if (this.closed || this.requireAcp(backend) !== client || this.backendInstances.get(backend) !== instance) throw new RpcError('OPENCODE_ARCHIVE_UNAVAILABLE', 'The OpenCode backend changed. Refresh the session list to confirm the archive state.') + const result = { backend, sessionId, archived: true } as const + this.inboundChain = this.inboundChain.then(async () => { + if (!this.closed && this.backendInstances.get(backend) === instance) { + await Promise.allSettled([...this.peers.values()].map(peer => peer.publishArchived(result))) + } + }) + await this.inboundChain + if (this.closed || this.backendInstances.get(backend) !== instance) throw new RpcError('OPENCODE_ARCHIVE_UNAVAILABLE', 'The OpenCode backend changed. Refresh the session list to confirm the archive state.') + return result + } finally { this.archivingSessions.delete(sessionId) } + } + + if (typeof call.params.sessionId === 'string' && this.archivingSessions.has(call.params.sessionId) + && ['session/load', 'session/prompt', 'dsh/selectModel'].includes(call.method)) throw new RpcError('ACP_SESSION_BUSY', 'The OpenCode session is being archived.') + + const controlId = sessionIdFromParams(call.method, call.params) + if (controlId && (call.params.backend ?? this.sessionBackends.get(controlId) ?? this.defaultBackend()) === 'opencode' + && ['session/load', 'session/prompt', 'dsh/selectModel'].includes(call.method)) { + const client = this.requireAcp('opencode') as CursorAcpLike & { isSessionArchived?: (sessionId: string, cwd: string) => Promise } + if (client.isSessionArchived) { + const cwd = await this.catalogSessionCwd('opencode', controlId) + const archived = await client.isSessionArchived(controlId, cwd) + if (this.closed || this.requireAcp('opencode') !== client) throw new RpcError('OPENCODE_ARCHIVE_UNAVAILABLE', 'The OpenCode backend changed.') + if (archived) throw new RpcError('ACP_SESSION_ARCHIVED', 'This OpenCode session is archived.') + } + } + assertCurrent() + + if (call.method === 'dsh/directoryList') { + return this.listDirectory(String(call.params.path)) + } + + if (call.method === 'dsh/workspaceList') { + const requestedBackend = typeof call.params.backend === 'string' ? call.params.backend : this.defaultBackend() + if (isCatalogBackend(requestedBackend)) { + const sessions = await this.listCatalogSessions(requestedBackend) + const discovered = [...new Set(sessions.map(item => item.cwd))].map(path => ({ path, title: basename(path) || 'workspace' })) + if (discovered.length > 0 || requestedBackend !== 'opencode') return discovered + const defaultCandidates = new Set() + const cwd = process.cwd() + if (cwd) defaultCandidates.add(cwd) + for (const candidate of ['/var/lib/dsh/workspace/ds-harness-remote', '/srv/dsh-workspace', '/var/lib/dsh/local']) { + try { + const s = await stat(candidate) + if (s.isDirectory()) defaultCandidates.add(candidate) + } catch { + // ignore + } + } + return [...defaultCandidates].map(path => ({ path, title: basename(path) || 'workspace' })) + } + const candidates = new Set() + const cwd = process.cwd() + if (cwd) candidates.add(cwd) + for (const candidate of ['/var/lib/dsh/workspace/ds-harness-remote', '/var/lib/dsh/local']) { + try { + const s = await stat(candidate) + if (s.isDirectory()) candidates.add(candidate) + } catch { + // ignore + } + } + const backend = typeof call.params?.backend === 'string' ? call.params.backend : undefined + if (backend === 'antigravity') { + try { + const agyDirs = await discoverAntigravityWorkspaces() + for (const d of agyDirs) { + candidates.add(d) + } + } catch { + // ignore + } + } + + const results = await Promise.all([...candidates].map(async p => { + let sessionCount = 0 + if (backend === 'antigravity') { + try { + const sessions = await discoverAntigravitySessions(p, 100) + sessionCount = sessions.length + } catch { + // ignore + } + } + return { + path: p, + title: basename(p) || 'workspace', + ...(sessionCount > 0 ? { sessionCount } : {}), + } + })) + return results + } + + if (call.method === 'dsh/sessionList') { + const limit = typeof call.params.limit === 'number' ? call.params.limit : 30 + const path = String(call.params.path || '') + const backend = typeof call.params.backend === 'string' ? call.params.backend : this.defaultBackend() + if (backend === 'antigravity') { + // Workspace selection loads history before the user presses New. + // Prepare one idle process in that directory without awaiting startup. + if (path.trim() !== '' && call.params.prewarm !== false) { + const cwd = await this.requireExistingDirectory(path) + assertCurrent() + this.requireAcp('antigravity').prewarmSession?.(cwd) + } + const items = await discoverAntigravitySessions(path, limit) + if (path) { + const cwd = await this.requireExistingDirectory(path) + assertCurrent() + for (const item of items) this.sessionCwds.set(item.conversationId, { backend, cwd }) + } + this.logger.info('ACP session list fetched', { count: items.length }) + return { items } + } + if (isCatalogBackend(backend)) { + const cwd = path ? await this.requireExistingDirectory(path) : undefined + const sessions = await this.listCatalogSessions(backend, cwd) + sessions.sort((a, b) => (Date.parse(b.updatedAt ?? '') || 0) - (Date.parse(a.updatedAt ?? '') || 0) + || a.sessionId.localeCompare(b.sessionId)) + return { items: sessions.slice(0, limit).map(item => ({ conversationId: item.sessionId, title: item.title ?? 'Untitled Session', createdAt: Date.parse(item.updatedAt ?? '') || 0, updatedAt: Date.parse(item.updatedAt ?? '') || 0, cwd: item.cwd })) } + } + return { items: [] } + } + + if (call.method === 'dsh/sessionHistory') { + const rawSessionId = String(call.params.sessionId) + const conversationId = rawSessionId.startsWith('hermes:') ? rawSessionId.slice('hermes:'.length) : rawSessionId.startsWith('claude:') ? rawSessionId.slice(7) : rawSessionId.startsWith('pi:') ? rawSessionId.slice(3) : rawSessionId.startsWith('acp:') + ? rawSessionId.slice('acp:'.length) + : rawSessionId.startsWith('cursor:') + ? rawSessionId.slice('cursor:'.length) + : rawSessionId.startsWith('opencode:') + ? rawSessionId.slice('opencode:'.length) + : rawSessionId + const boundBackend = this.sessionBackends.get(conversationId) + const backend = typeof call.params.backend === 'string' ? call.params.backend : boundBackend ?? this.defaultBackend() + if ((boundBackend !== undefined && boundBackend !== backend) + || (rawSessionId.startsWith('hermes:') && backend !== 'hermes') + || (rawSessionId.startsWith('claude:') && backend !== 'claude') + || (rawSessionId.startsWith('pi:') && backend !== 'pi') + || (rawSessionId.startsWith('cursor:') && backend !== 'cursor') + || (rawSessionId.startsWith('opencode:') && backend !== 'opencode') + || (rawSessionId.startsWith('acp:') && backend !== 'antigravity')) { + throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.') + } + this.requireAcp(backend) + if (isCatalogBackend(backend)) { + const cwd = await this.catalogSessionCwd(backend, conversationId) + assertCurrent() + // History uses an isolated reader and must neither require nor claim + // the live session's control ownership. + const client = this.requireAcp(backend) as CursorAcpLike & { history?: (sessionId: string, cwd: string) => Promise } + if (!client.history) throw new RpcError('METHOD_NOT_ALLOWED', 'The ACP backend does not support history.') + const events = await this.readCatalogHistory(backend, client as CursorAcpLike & { history: (sessionId: string, cwd: string) => Promise }, conversationId, cwd, assertCurrent) + const preset = this.sessionPermissions.get(conversationId) + return { events, ...(preset ? { permissionPreset: preset } : {}) } + } + if (backend !== 'antigravity') return { events: [] } + const events = await loadTranscriptEvents(conversationId, rawSessionId) + this.logger.info('ACP session history fetched', { + sessionId: shortSessionId(rawSessionId), + eventCount: events.length, + }) + const preset = this.sessionPermissions.get(conversationId) + return { events, ...(preset ? { permissionPreset: preset } : {}) } + } + + if (call.method === 'session/new') { + const cwd = await this.requireExistingDirectory(String(call.params.cwd)) + assertCurrent() + const requestedBackend = typeof call.params.backend === 'string' + ? call.params.backend + : this.defaultBackend() + const acp = this.requireAcp(requestedBackend) + const result = await acp.call('session/new', { + cwd, + mcpServers: [], + ...(typeof call.params.mode === 'string' ? { mode: call.params.mode } : {}), + }) + assertCurrent() + const sessionId = readSessionId(result) + if (sessionId !== undefined) { + const bound = this.sessionBackends.get(sessionId) + if (this.sessionOwners.has(sessionId) || this.sessionCwds.has(sessionId) || (bound !== undefined && bound !== requestedBackend)) { + throw new RpcError('ACP_SESSION_COLLISION', 'The ACP backend returned an existing session identifier.') + } + this.sessionOwners.set(sessionId, connectionId) + this.sessionBackends.set(sessionId, requestedBackend) + this.sessionCwds.set(sessionId, { backend: requestedBackend, cwd }) + } + return sanitizeSessionResult(result) + } + + const sessionId = sessionIdFromParams(call.method, call.params) + if (sessionId !== undefined && call.method !== 'session/load') this.requireSessionAccess(connectionId, sessionId, call.method) + + if (call.method === 'dsh/toolCall') { + this.requireSessionOwner(connectionId, sessionId!) + return this.tools(connectionId).call(sessionId!, String(call.params.backend), String(call.params.endpoint), call.params.args as Record) + } + + if (call.method === 'session/prompt') { + const selected = this.sessionBackends.get(sessionId!) + const requested = typeof call.params.backend === 'string' ? call.params.backend : selected ?? this.defaultBackend() + if (selected !== undefined && selected !== requested) throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.') + this.requireAcp(requested) + if (Array.isArray(call.params.prompt) && call.params.prompt.some(part => isRecord(part) && part.type === 'image') && requested !== 'antigravity' && requested !== 'hermes') throw new RpcError('METHOD_NOT_ALLOWED', 'This ACP backend does not accept image prompts.') + this.sessionBackends.set(sessionId!, requested) + } + + if (call.method === 'session/load') { + const boundBackend = sessionId !== undefined ? this.sessionBackends.get(sessionId) : undefined + if (typeof call.params.backend !== 'string') throw new RpcError('INVALID_MESSAGE', 'Session load requires an explicit backend.') + const targetBackend = call.params.backend + if ((targetBackend === 'claude' || targetBackend === 'hermes') && this.promptsInProgress.has(sessionId!)) throw new RpcError('PROMPT_IN_PROGRESS', 'An ACP reply is already in progress.') + if (boundBackend !== undefined && targetBackend !== boundBackend) { + throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.') + } + if (isCatalogBackend(targetBackend)) await this.catalogSessionCwd(targetBackend, sessionId!) + assertCurrent() + this.requireSessionOwner(connectionId, sessionId!) + const acp = this.requireAcp(targetBackend) + // Track pending loads too, so reconfiguration revokes their ownership + // before an upstream result can arrive. + this.sessionBackends.set(sessionId!, targetBackend) + const result = await acp.call(call.method, { ...call.params, ...(sessionId && this.sessionCwds.get(sessionId) ? { cwd: this.sessionCwds.get(sessionId)!.cwd, mcpServers: [] } : {}) }) + assertCurrent() + const loadedId = readSessionId(result) ?? sessionId + if (loadedId !== undefined) { + if (loadedId !== sessionId || (this.sessionBackends.has(loadedId) && targetBackend !== undefined && this.sessionBackends.get(loadedId) !== targetBackend)) { + throw new RpcError('ACP_SESSION_COLLISION', 'The ACP backend returned a different session identifier.') + } + this.sessionOwners.set(loadedId, connectionId) + if (targetBackend) this.sessionBackends.set(loadedId, targetBackend) + } + return sanitizeSessionResult(result) + } + + if (isSessionMutation(call.method) && sessionId !== undefined) { + this.requireSessionOwner(connectionId, sessionId) + } + + if ((call.method === 'dsh/sessionModels' || call.method === 'dsh/selectModel') && isCatalogBackend(call.params.backend)) { + this.requireSessionOwner(connectionId, sessionId!) + const backend = call.params.backend + const cwd = await this.catalogSessionCwd(backend, sessionId!) + assertCurrent() + await this.requireAcp(backend).call('session/load', { sessionId, cwd, mcpServers: [] }) + assertCurrent() + } + + if (call.method === 'dsh/selectModel') { + if (this.promptsInProgress.has(sessionId!)) throw new RpcError('PROMPT_IN_PROGRESS', 'Stop the ACP reply before changing its model.') + const session = this.sessionCwds.get(sessionId!) + if (!session || session.backend !== call.params.backend) { + throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.') + } + // Resume straight into the target model. Loading the old model first + // starts a second CLI process that would immediately be discarded. + const result = await this.requireAcp(session.backend).call(call.method, { ...call.params, cwd: session.cwd }) + assertCurrent() + this.sessionBackends.set(sessionId!, session.backend) + return sanitizeSessionResult(result) + } + + if (call.method === 'dsh/selectPermission') { + this.requireSessionOwner(connectionId, sessionId!) + const preset = typeof call.params.preset === 'string' ? call.params.preset : undefined + if (preset !== 'workspace-write' && preset !== 'danger-full-access') { + throw new RpcError('INVALID_MESSAGE', 'Unknown permission preset.') + } + this.sessionPermissions.set(sessionId!, preset) + return { preset } + } + + // session/prompt blocks until the upstream turn ends. Returning that RPC + // only after completion prevents some Client transports from delivering + // interleaved agent.acp.frame events (Android stays on "正在回复" with no + // thought/text). Accept immediately and finish via stream updates. + if (call.method === 'session/prompt' && sessionId !== undefined) { + if (this.promptsInProgress.has(sessionId)) throw new RpcError('PROMPT_IN_PROGRESS', 'An ACP reply is already in progress.') + this.invalidateSessionHistory(sessionId) + const backend = this.sessionBackends.get(sessionId) ?? this.defaultBackend() + const task: PromptTask = { backend, client: this.requireAcp(backend) } + this.promptsInProgress.set(sessionId, task) + this.cancelledSessions.delete(sessionId) + const preparationBackend = this.sessionBackends.get(sessionId) + if (preparationBackend === 'pi' || preparationBackend === 'claude' || preparationBackend === 'hermes') { + const preparation = { cancelled: false } + this.preparingPrompts.set(sessionId, preparation) + try { + const cwd = await this.catalogSessionCwd(preparationBackend, sessionId) + if (preparation.cancelled) return { accepted: false, stopReason: 'cancelled' } + assertCurrent() + await task.client.call('session/load', { sessionId, cwd, mcpServers: [] }) + if (preparation.cancelled) return { accepted: false, stopReason: 'cancelled' } + assertCurrent() + } catch (error) { + if (preparation.cancelled) return { accepted: false, stopReason: 'cancelled' } + if (this.promptsInProgress.get(sessionId) === task) this.promptsInProgress.delete(sessionId) + throw error + } finally { + if (this.preparingPrompts.get(sessionId) === preparation) { + this.preparingPrompts.delete(sessionId) + if (preparation.cancelled && this.promptsInProgress.get(sessionId) === task) this.promptsInProgress.delete(sessionId) + } + } + } + const ownerPeer = this.peers.get(connectionId) + if (ownerPeer !== undefined && !ownerPeer.hasStreamFor(sessionId)) { + this.logger?.warn('Cursor prompt started without an open ACP stream', { + sessionId: shortSessionId(sessionId), + }) + } + this.turnCatchUp.set(sessionId, []) + void this.runPromptInBackground(sessionId, call.params, task) + return { accepted: true, stopReason: 'in_progress' } + } + + if (call.method === 'session/cancel' && sessionId !== undefined) { + this.invalidateSessionHistory(sessionId) + this.cancelledSessions.add(sessionId) + const preparation = this.preparingPrompts.get(sessionId) + if (preparation) { + // No turn exists upstream yet. Do not send a late cancel into a retry + // sharing this load: cancel only this preparation identity. + preparation.cancelled = true + this.preparingPrompts.delete(sessionId) + this.promptsInProgress.delete(sessionId) + return { stopReason: 'cancelled' } + } + const pending = [...this.approvals].filter(([, approval]) => approval.sessionId === sessionId && approval.backend === this.sessionBackends.get(sessionId)) + for (const [handle] of pending) this.approvals.delete(handle) + // Send cancellation before rejecting approvals: rejecting a blocked tool first + // can otherwise complete the turn as end_turn before upstream sees cancel. + try { + return sanitizeSessionResult(await this.requireAcp(this.sessionBackends.get(sessionId)).call(call.method, call.params)) + } finally { + await Promise.all(pending.map(([, approval]) => approval.client.respondError(approval.upstreamId, -32800, 'ACP session cancelled.').catch(() => undefined))) + } + } + const sessionBackend = sessionId !== undefined ? this.sessionBackends.get(sessionId) : undefined + return sanitizeSessionResult(await this.requireAcp(typeof call.params.backend === 'string' ? call.params.backend : sessionBackend).call(call.method, call.params)) + } + + private async runPromptInBackground(sessionId: string, params: unknown, task: PromptTask): Promise { + // A turn belongs to the session, not to the adapter that ran it: a retry may + // replace the crashed client while the inbound queue drains. + const accepted = () => !this.closed && this.promptsInProgress.get(sessionId) === task + const current = () => accepted() && !this.pendingReconfiguration.has(task.backend) + && this.backendInstances.get(task.backend)?.client === task.client + try { + const result = await task.client.call('session/prompt', params) + // Cursor emits final session/update lines before the JSON-RPC result. + // Those notifications are queued on inboundChain; drain it before we + // snapshot catch-up or the Client only sees an empty prompt_completed. + await this.inboundChain + if (!current()) return + const stopReason = isRecord(result) && typeof result.stopReason === 'string' + ? result.stopReason + : 'end_turn' + const catchUp = takeTurnCatchUp(this.turnCatchUp, sessionId) + this.logger.info('ACP prompt finished', { + sessionId: shortSessionId(sessionId), + stopReason, + catchUp: catchUp.length, + }) + await this.publishToSession(sessionId, { + method: 'session/update', + params: { + sessionId, + update: { + sessionUpdate: 'prompt_completed', + stopReason, + ...(catchUp.length > 0 ? { catchUp } : {}), + }, + }, + }) + } catch (error) { + if (!accepted()) return + this.logger?.warn('ACP session/prompt failed', { code: errorCode(error) }) + await this.inboundChain.catch(() => undefined) + if (!accepted()) return + const catchUp = takeTurnCatchUp(this.turnCatchUp, sessionId) + await this.publishToSession(sessionId, { + method: 'session/update', + params: { + sessionId, + update: { + sessionUpdate: 'prompt_failed', + code: errorCode(error), + ...(catchUp.length > 0 ? { catchUp } : {}), + }, + }, + }).catch(() => undefined) + } finally { + if (this.promptsInProgress.get(sessionId) === task) { + this.promptsInProgress.delete(sessionId) + this.invalidateSessionHistory(sessionId) + // The Client has now been told how the turn ended, so a session whose + // adapter died can be closed instead of waiting for a producer. + if (!this.isSessionBackendReady(sessionId)) await this.failSessionStreams(sessionId) + } + } + } + + private invalidateSessionHistory(sessionId: string): void { + const invalidationEpoch = ++this.historyEpoch + this.historyInvalidatedAt.delete(sessionId) + this.historyInvalidatedAt.set(sessionId, invalidationEpoch) + while (this.historyInvalidatedAt.size > 256) { + const oldestKey = this.historyInvalidatedAt.keys().next().value + if (oldestKey === undefined) break + const oldestEpoch = this.historyInvalidatedAt.get(oldestKey) ?? 0 + this.minValidHistoryEpoch = Math.max(this.minValidHistoryEpoch, oldestEpoch) + this.historyInvalidatedAt.delete(oldestKey) + } + for (const key of this.pendingHistoryReads.keys()) { + if (key.endsWith(`:${sessionId}`)) { + this.pendingHistoryReads.delete(key) + } + } + } + + private isHistoryEpochValid(sessionId: string, readEpoch: number): boolean { + return readEpoch > this.minValidHistoryEpoch && readEpoch > (this.historyInvalidatedAt.get(sessionId) ?? 0) + } + + private async readCatalogHistory( + backend: string, + client: CursorAcpLike & { history: (sessionId: string, cwd: string) => Promise }, + conversationId: string, + cwd: string, + assertCurrent: () => void, + ): Promise { + const key = `${backend}:${conversationId}` + const existing = this.pendingHistoryReads.get(key) + if ( + existing !== undefined + && existing.client === client + && this.isHistoryEpochValid(conversationId, existing.readEpoch) + ) { + const events = await existing.promise + assertCurrent() + return events + } + const readEpoch = ++this.historyEpoch + const previous = this.backendHistoryChains.get(backend) ?? Promise.resolve() + let releaseQueue!: () => void + const currentTurn = new Promise(resolve => { releaseQueue = resolve }) + const nextChain = previous.then(() => currentTurn, () => currentTurn) + this.backendHistoryChains.set(backend, nextChain) + const readPromise = (async (): Promise => { + await previous.catch(() => undefined) + try { + assertCurrent() + if (this.requireAcp(backend) !== client) { + throw new RpcError('CURSOR_UNAVAILABLE', `The ${backend} ACP backend is not ready.`) + } + return await client.history(conversationId, cwd) + } finally { + releaseQueue() + if (this.backendHistoryChains.get(backend) === nextChain) { + this.backendHistoryChains.delete(backend) + } + } + })() + this.pendingHistoryReads.set(key, { client, readEpoch, promise: readPromise }) + try { + const events = await readPromise + assertCurrent() + return events + } finally { + if (this.pendingHistoryReads.get(key)?.promise === readPromise) { + this.pendingHistoryReads.delete(key) + } + } + } + + private async failSessionStreams(sessionId: string): Promise { + const sessions = new Set([sessionId]) + await Promise.all([...this.peers.values()].map(peer => peer.failStreams('failed', sessions).catch(() => undefined))) + } + + async respond(connectionId: string, input: unknown): Promise<{ resolved: true }> { + const params = parseRespondEnvelope(input) + const pending = this.approvals.get(params.requestHandle) + if (pending === undefined || pending.expiresAt <= Date.now()) { + this.approvals.delete(params.requestHandle) + throw new RpcError('CURSOR_APPROVAL_NOT_FOUND', 'The Cursor approval is missing, expired, or belongs to another connection.') + } + if (pending.connectionId !== connectionId) { + throw new RpcError('CURSOR_APPROVAL_NOT_FOUND', 'The Cursor approval is missing, expired, or belongs to another connection.') + } + if (this.sessionOwners.get(pending.sessionId) !== connectionId + || this.sessionBackends.get(pending.sessionId) !== pending.backend + || this.requireAcp(pending.backend) !== pending.client) { + throw new RpcError('CURSOR_APPROVAL_NOT_FOUND', 'The ACP approval scope is no longer active.') + } + const result = mapPermissionDecision(params, pending) + this.approvals.delete(params.requestHandle) + const acp = pending.client + if (params.decision === 'cancel') { + await acp.respondError(pending.upstreamId, -32800, 'Cancelled by Remote client.') + return { resolved: true } + } + await acp.respond(pending.upstreamId, result) + return { resolved: true } + } + + dropPeer(connectionId: string): void { + this.peers.delete(connectionId) + void this.workspaceTools.get(connectionId)?.close() + this.workspaceTools.delete(connectionId) + for (const [sessionId, owner] of this.sessionOwners) { + if (owner === connectionId) this.sessionOwners.delete(sessionId) + } + for (const [handle, approval] of this.approvals) { + if (approval.connectionId === connectionId) { + this.approvals.delete(handle) + void approval.client.respondError(approval.upstreamId, -32800, 'Remote peer disconnected.').catch(() => undefined) + } + } + } + + private tools(connectionId: string): AcpWorkspaceTools { + const tools = this.workspaceTools.get(connectionId) + if (!tools) throw new RpcError('ACP_CONNECTION_CLOSED', 'The ACP workspace connection is closed.') + return tools + } + + /** Trusted, connection-scoped authority for the dedicated workspace uploader. */ + resolveUploadWorkspace(connectionId: string, publicId: string): string { + const match = /^(acp|cursor|pi|opencode|claude|hermes):(.+)$/.exec(publicId) + const backend = match?.[1] === 'acp' ? 'antigravity' : match?.[1] + const session = match ? this.sessionCwds.get(match[2]!) : undefined + if (!this.peers.has(connectionId) || !session || session.backend !== backend || this.closed) { + throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.') + } + this.requireAcp(backend!) + this.requireSessionOwner(connectionId, match![2]!) + return session.cwd + } + + async openToolStream(connectionId: string, sessionId: string, backend: string, endpoint: string, args: Record, signal: AbortSignal) { + const session = this.sessionCwds.get(sessionId) + if (!session || session.backend !== backend) throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.') + this.requireAcp(backend) + this.requireSessionOwner(connectionId, sessionId) + return this.tools(connectionId).open(sessionId, backend, endpoint, args, signal) + } + + /** Used by peer stream open to prove this connection may observe the session. */ + assertStreamable(connectionId: string, sessionId: string): void { + this.claimSession(connectionId, sessionId) + } + + /** Whether the session still has a turn whose terminal event has not arrived. */ + hasTurnInFlight(sessionId: string): boolean { + return this.promptsInProgress.has(sessionId) + } + + /** Whether the adapter that owns this session can still produce frames. */ + isSessionBackendReady(sessionId: string): boolean { + const backend = this.sessionBackends.get(sessionId) + if (backend === undefined) return true + if (!this.isAvailable()) return false + const instance = this.backendInstances.get(backend) + return instance !== undefined && instance.client.isReady() && !this.pendingReconfiguration.has(backend) + } + + /** + * After a Client reconnect, session ownership may have been cleared with the + * old peer. Reclaim the in-memory ACP session for the new connection so + * stream open / prompt can resume and buffered frames can replay. + */ + private claimSession(connectionId: string, sessionId: string): void { + const owner = this.sessionOwners.get(sessionId) + if (owner === undefined) { + this.sessionOwners.set(sessionId, connectionId) + return + } + if (owner !== connectionId) { + throw new RpcError('CURSOR_SESSION_OWNED', 'Another Remote connection owns this session.') + } + } + + /** Replay frames buffered while no healthy peer could receive them. */ + async replayBufferedFrames(connectionId: string, sessionId: string): Promise { + const peer = this.peers.get(connectionId) + if (peer === undefined) return + this.pruneFrameBuffer(sessionId) + const buffered = this.recentFrames.get(sessionId) ?? [] + if (buffered.length === 0) return + this.recentFrames.delete(sessionId) + this.logger.info('Replaying buffered ACP frames', { + sessionId: shortSessionId(sessionId), + count: buffered.length, + }) + for (const frame of buffered) { + await peer.publishInbound(sessionId, { method: frame.method, params: frame.params }) + } + } + + async reconfigure(config: ResolvedAcpConfig): Promise { + if (this.closed) throw new RpcError('CURSOR_CLOSED', 'The ACP Remote domain is closed.') + const previous = this.config + const implemented = (value: ResolvedAcpConfig) => ({ enabled: value.enabled, + backends: value.backends.filter(item => ['cursor', 'antigravity', 'pi', 'claude', 'opencode', 'hermes'].includes(item.id)) }) + this.config = config + if (JSON.stringify(implemented(previous)) === JSON.stringify(implemented(config)) && this.pendingReconfiguration.size === 0) return + this.clearBackendRestarts() + const changed = new Set([...this.pendingReconfiguration, ...previous.backends.filter(item => { + const next = config.backends.find(candidate => candidate.id === item.id) + return previous.enabled !== config.enabled || JSON.stringify(item) !== JSON.stringify(next) + }).map(item => item.id)]) + for (const id of changed) this.pendingReconfiguration.add(id) + const stopping = await Promise.allSettled([...this.startingClients].filter(([, backend]) => changed.has(backend.id)).map(([client]) => client.close())) + await this.startPromise?.catch(() => undefined) + const sessions = new Set([...this.sessionBackends].filter(([, backend]) => changed.has(backend)).map(([id]) => id)) + if (sessions.size > 0) await Promise.all([...this.peers.values()].map(peer => peer.failStreams('failed', sessions))) + for (const [id, session] of this.sessionCwds) if (changed.has(session.backend)) this.sessionCwds.delete(id) + const terminalError = await this.workspaceState.dispose(sessionId => changed.has(sessionId.startsWith('acp:') ? 'antigravity' : sessionId.startsWith('pi:') ? 'pi' : sessionId.startsWith('opencode:') ? 'opencode' : sessionId.startsWith('claude:') ? 'claude' : sessionId.startsWith('hermes:') ? 'hermes' : 'cursor')) + .then(() => undefined, () => new RpcError('TERMINAL_CLEANUP_FAILED', 'Some ACP terminal processes could not be stopped. Save the backend settings again to retry.')) + for (const id of sessions) { + this.sessionOwners.delete(id) + this.promptsInProgress.delete(id) + const preparation = this.preparingPrompts.get(id) + if (preparation) preparation.cancelled = true + this.preparingPrompts.delete(id) + this.sessionBackends.delete(id) + this.recentFrames.delete(id) + this.turnCatchUp.delete(id) + } + for (const [id, approval] of this.approvals) if (approval.backend !== undefined && changed.has(approval.backend)) this.approvals.delete(id) + // A terminal cleanup failure must not prevent stopping any changed backend. + // Keep failed backend instances fenced from RPC/startup until a later retry. + const processes = await Promise.allSettled([...changed].map(async id => { + const instance = this.backendInstances.get(id) + if (instance === undefined) return + await this.disposeInstance(instance) + if (this.backendInstances.get(id) === instance) this.backendInstances.delete(id) + })) + this.available = this.availableBackends().length > 0 + const cleanupFailed = terminalError !== undefined || [...stopping, ...processes].some(result => result.status === 'rejected') + this.state = this.available ? 'ready' : cleanupFailed && this.enabledBackends().length > 0 ? 'unavailable' : 'disabled' + this.unavailableCode = terminalError?.code ?? (cleanupFailed ? 'ACP_RECONFIGURE_FAILED' : undefined) + if (terminalError) throw terminalError + if (cleanupFailed) throw new RpcError('ACP_RECONFIGURE_FAILED', 'Some ACP backend processes could not be stopped. Save the backend settings again to retry.') + for (const id of changed) this.pendingReconfiguration.delete(id) + await this.start() + if (this.closed) return + // A backend that did not come back is retried like any other failure, so a + // settings change elsewhere cannot leave it parked. + for (const id of this.enabledBackends()) { + if (!this.availableBackends().includes(id)) this.scheduleBackendRestart(id) + } + } + + async close(): Promise { + if (this.closed) return + this.closed = true + this.clearBackendRestarts() + if (this.approvalExpiryTimer !== undefined) clearTimeout(this.approvalExpiryTimer) + for (const peer of this.peers.values()) await peer.closeAll() + this.peers.clear() + this.sessionCwds.clear() + const terminals = this.workspaceState.dispose().then(() => undefined, () => new RpcError('TERMINAL_CLEANUP_FAILED', 'Some ACP terminal processes could not be stopped.')) + this.sessionOwners.clear() + this.sessionBackends.clear() + this.recentFrames.clear() + this.turnCatchUp.clear() + this.promptsInProgress.clear() + for (const preparation of this.preparingPrompts.values()) preparation.cancelled = true + this.preparingPrompts.clear() + this.approvals.clear() + const processes = await Promise.allSettled([...this.startingClients.keys()].map(client => client.close()).concat(this.disposeAllInstances())) + const terminalError = await terminals + if (!terminalError) this.terminalOwners.clear() + this.available = false + this.state = 'disabled' + if (terminalError) throw terminalError + if (processes.some(result => result.status === 'rejected')) throw new RpcError('ACP_SHUTDOWN_FAILED', 'Some ACP backend processes could not be stopped.') + } + + private async launchAcp(): Promise { + const candidates = this.config.backends.filter(item => !this.pendingReconfiguration.has(item.id) && this.enabledBackends().includes(item.id)) + const results = await Promise.allSettled(candidates.map(async candidate => { + await this.launchSerialized(candidate.id) + })) + if (this.closed) return + if (this.enabledBackends().length === 0) { this.state = 'disabled'; return } + if (this.isAvailable()) { + this.state = 'ready' + if (this.pendingReconfiguration.size === 0) this.unavailableCode = undefined + return + } + const failure = results.find(result => result.status === 'rejected') + throw failure?.status === 'rejected' ? failure.reason : new CursorAcpError('CURSOR_BINARY_UNAVAILABLE', 'No ACP backend is available.') + } + + /** + * Launch one backend at most once at a time. A retry and a `start()` (from a + * reconfigure or a later failure) can target the same missing backend; without + * this both would capture the same previous instance and leak a replacement. + */ + private launchSerialized(id: string): Promise { + const candidate = this.config.backends.find(item => item.id === id) + if (candidate === undefined || !this.enabledBackends().includes(id) || this.pendingReconfiguration.has(id)) return Promise.resolve() + if (this.backendInstances.get(id)?.client.isReady()) return Promise.resolve() + const inFlight = this.launching.get(id) + if (inFlight !== undefined) return inFlight + let task: Promise + task = this.launchCandidateBinaries(candidate).finally(() => { + if (this.launching.get(id) === task) this.launching.delete(id) + }) + this.launching.set(id, task) + return task + } + + private async launchCandidateBinaries(candidate: ResolvedAcpBackendConfig): Promise { + let lastError: unknown + for (const binary of cursorBinaryCandidates(candidate.command)) { + if (this.closed || !this.backendCurrent(candidate)) return + try { + await this.launchBackendCandidate(candidate, binary) + return + } catch (error) { + lastError = error + this.logger.debug?.('ACP candidate failed', { id: candidate.id, code: errorCode(error) }) + } + } + throw lastError + } + + private backendCurrent(backend: ResolvedAcpBackendConfig): boolean { + return this.config.enabled && backend.enabled && !this.pendingReconfiguration.has(backend.id) + && JSON.stringify(this.config.backends.find(item => item.id === backend.id)) === JSON.stringify(backend) + } + + private async launchBackendCandidate(backend: ResolvedAcpBackendConfig, binary: string): Promise { + const id = backend.id + const acp = this.createAcp(binary, this.logger, backend) + this.startingClients.set(acp, backend) + try { + await acp.start() + if (this.closed || !this.backendCurrent(backend)) { + await acp.close() + return + } + } catch (error) { + await acp.close() + throw error + } finally { + this.startingClients.delete(acp) + } + const unsubscribeInbound = acp.onInbound(message => { + this.inboundChain = this.inboundChain + .then(() => this.backendInstances.get(id)?.client === acp ? this.handleInbound(id, message) : undefined) + .catch(error => { + this.logger.warn('ACP inbound fanout failed', { id, code: errorCode(error) }) + }) + }) + const unsubscribeUnavailable = acp.onUnavailable(code => { void this.handleUnavailable(id, code) }) + const prev = this.backendInstances.get(id) + if (prev !== undefined) { + await this.disposeInstance(prev) + } + if (this.closed || !this.backendCurrent(backend)) { + unsubscribeInbound() + unsubscribeUnavailable() + await acp.close() + return + } + this.available = true + this.backendInstances.set(id, { + id, + client: acp, + unsubscribeInbound, + unsubscribeUnavailable, + startedAt: Date.now(), + }) + + } + + private async handleInbound(backend: string, message: CursorAcpInbound): Promise { + const incomingId = readSessionId(message.params) ?? readNestedSessionId(message.params) + const boundBackend = incomingId === undefined ? undefined : this.sessionBackends.get(incomingId) + if (boundBackend !== undefined && boundBackend !== backend) { + if (message.kind === 'request') await this.requireAcp(backend).respondError(message.id, -32602, 'The ACP session backend does not match.') + return + } + // session/update is a stream notification even if a buggy agent attaches an id. + if (message.kind === 'notification' || message.method === 'session/update') { + const sessionId = readSessionId(message.params) ?? readNestedSessionId(message.params) + if (sessionId === undefined) return + if (!this.sessionBackends.has(sessionId)) { + this.sessionBackends.set(sessionId, backend) + } + await this.publishToSession(sessionId, { method: message.method, params: message.params }) + return + } + + const sessionId = incomingId + const owner = sessionId === undefined ? undefined : this.sessionOwners.get(sessionId) + const peer = owner === undefined ? undefined : this.peers.get(owner) + const client = this.requireAcp(backend) + if (sessionId === undefined || this.cancelledSessions.has(sessionId) || owner === undefined || peer === undefined || boundBackend !== backend + || !['session/request_permission', 'cursor/create_plan', 'cursor/ask_question'].includes(message.method) + || (message.method.startsWith('cursor/') && backend !== 'cursor')) { + await client.respondError(message.id, -32602, 'The ACP request has no active owner or supported method.') + return + } + let options: PendingApproval['options'] = [] + try { + if (message.method === 'session/request_permission') { + options = permissionOptions(message.params) + const allowOption = options.find(item => item.kind === 'allow_once') + if (this.sessionPermissions.get(sessionId) === 'danger-full-access' && allowOption) { + await client.respond(message.id, { outcome: { outcome: 'selected', optionId: allowOption.optionId } }) + return + } + } + } catch { + await client.respondError(message.id, -32602, 'The ACP permission options are invalid.') + return + } + const requestHandle = randomUUID() + this.approvals.set(requestHandle, { + upstreamId: message.id, connectionId: owner, sessionId, method: message.method, + expiresAt: Date.now() + APPROVAL_TTL_MS, backend, client, options, + }) + this.scheduleApprovalExpiry() + try { + await peer.publishInbound(sessionId, { + method: message.method, + params: { + ...(isRecord(message.params) ? message.params : {}), + requestHandle, sessionId, upstreamMethod: message.method, + }, + }) + } catch { + this.approvals.delete(requestHandle) + await client.respondError(message.id, -32800, 'Remote approval delivery failed.') + } + } + + private async publishToSession(sessionId: string, frame: { method: string; params: unknown }): Promise { + this.recordTurnCatchUp(sessionId, frame) + const ownerId = this.sessionOwners.get(sessionId) + const owner = ownerId === undefined ? undefined : this.peers.get(ownerId) + // A session belongs to exactly one connection (claimSession rejects a second + // owner), so its live output must never reach another device. Unclaimed or + // departed owners buffer for the next claimer instead of broadcasting. + if (owner === undefined) { + this.bufferFrame(sessionId, frame) + return + } + try { + await owner.publishInbound(sessionId, frame) + } catch { + this.bufferFrame(sessionId, frame) + } + } + + + private recordTurnCatchUp(sessionId: string, frame: { method: string; params: unknown }): void { + const list = this.turnCatchUp.get(sessionId) + if (list === undefined || frame.method !== 'session/update') return + const params = isRecord(frame.params) ? frame.params : undefined + const update = params !== undefined && isRecord(params.update) ? params.update : params + const kind = update !== undefined && typeof update.sessionUpdate === 'string' + ? update.sessionUpdate + : undefined + if (kind === undefined || !CATCH_UP_SESSION_UPDATES.has(kind)) return + list.push({ method: frame.method, params: frame.params }) + while (list.length > MAX_TURN_CATCH_UP_FRAMES) list.shift() + } + + private bufferFrame(sessionId: string, frame: { method: string; params: unknown }): void { + this.pruneFrameBuffer(sessionId) + const list = this.recentFrames.get(sessionId) ?? [] + list.push({ method: frame.method, params: frame.params, at: Date.now() }) + while (list.length > MAX_BUFFERED_ACP_FRAMES) list.shift() + this.recentFrames.set(sessionId, list) + this.logger.warn('Buffered ACP frame for later replay', { + sessionId: shortSessionId(sessionId), + method: frame.method, + buffered: list.length, + }) + } + + private pruneFrameBuffer(sessionId: string): void { + const list = this.recentFrames.get(sessionId) + if (list === undefined) return + const validAfter = Date.now() - ACP_FRAME_BUFFER_TTL_MS + const next = list.filter(frame => frame.at >= validAfter) + if (next.length === 0) this.recentFrames.delete(sessionId) + else this.recentFrames.set(sessionId, next) + } + + private async handleUnavailable(backend: string, code: string): Promise { + if (this.closed) return + // Scope and close the failed backend's streams before any await: a restart can + // install a replacement adapter while this handler is suspended, and its own + // streams must not be failed by the previous generation. + const sessions = new Set() + for (const [sessionId, ownerBackend] of this.sessionBackends) { + // A session with a running turn keeps its stream: closing it now would make a + // connected Client stop listening before the turn reports how it ended. + if (ownerBackend === backend && !this.promptsInProgress.has(sessionId)) sessions.add(sessionId) + } + const failures = sessions.size === 0 + ? Promise.resolve() + : Promise.all([...this.peers.values()].map(peer => peer.failStreams('failed', sessions))) + // The instance entry stays in place: a prompt already running against it + // publishes its terminal failure only while `current()` still matches. It is + // not ready, so `launchAcp` replaces it on the next start. + const instance = this.backendInstances.get(backend) + if (instance !== undefined) await this.disposeInstance(instance).catch(() => undefined) + // A crash after real uptime is a new episode; one shortly after launch keeps + // its budget so a permanently broken adapter cannot retry forever. + if (instance !== undefined && Date.now() - instance.startedAt >= BACKEND_STABLE_MS) { + this.restartAttempts.delete(backend) + } + await failures + if (this.closed) return + this.available = this.availableBackends().length > 0 + if (this.available) { + // Another adapter still answers; surface the loss and retry this one later + // instead of reporting the whole Remote domain as down. + this.state = 'ready' + this.logger.warn('ACP backend unavailable; other backends remain ready', { id: backend, code }) + } else { + this.state = 'restarting' + this.unavailableCode = code + } + this.scheduleBackendRestart(backend) + } + + // Retries are tracked per backend so one failing adapter cannot consume, or be + // reset by, another adapter's attempts. + private scheduleBackendRestart(backend: string): void { + if (this.closed || !this.config.enabled) return + if (this.restartTimers.has(backend)) return + const attempt = this.restartAttempts.get(backend) ?? 0 + if (attempt >= this.restartDelaysMs.length) { + this.logger.warn('ACP backend restart attempts exhausted', { id: backend }) + return + } + this.restartAttempts.set(backend, attempt + 1) + const timer = setTimeout(() => { + this.restartTimers.delete(backend) + void this.restartBackend(backend) + }, this.restartDelaysMs[attempt]!) + timer.unref?.() + this.restartTimers.set(backend, timer) + } + + private async restartBackend(backend: string): Promise { + if (this.closed) return + try { + await this.launchSerialized(backend) + if (!this.closed && this.pendingReconfiguration.size === 0 && this.isAvailable()) this.state = 'ready' + } catch (error) { + this.logger.warn('ACP backend restart failed', { id: backend, code: errorCode(error) }) + } + if (this.closed) return + if (this.availableBackends().includes(backend)) return + this.scheduleBackendRestart(backend) + } + + private clearBackendRestarts(): void { + for (const timer of this.restartTimers.values()) clearTimeout(timer) + this.restartTimers.clear() + this.restartAttempts.clear() + } + + private scheduleApprovalExpiry(): void { + if (this.approvalExpiryTimer !== undefined) clearTimeout(this.approvalExpiryTimer) + const next = [...this.approvals.values()].reduce((min, item) => { + if (min === undefined || item.expiresAt < min) return item.expiresAt + return min + }, undefined) + if (next === undefined) return + this.approvalExpiryTimer = setTimeout(() => { + const now = Date.now() + for (const [handle, approval] of this.approvals) { + if (approval.expiresAt <= now) { + this.approvals.delete(handle) + void approval.client.respondError(approval.upstreamId, -32800, 'Cursor approval expired.').catch(() => undefined) + } + } + this.scheduleApprovalExpiry() + }, Math.max(0, next - Date.now())) + this.approvalExpiryTimer.unref?.() + } + + private requireAcp(backend?: string): CursorAcpLike { + if (!this.config.enabled || (backend !== undefined && (!this.enabledBackends().includes(backend) || this.pendingReconfiguration.has(backend))) || !this.isAvailable()) { + throw new RpcError('CURSOR_UNAVAILABLE', 'Cursor ACP is disabled or unavailable on this Host.') + } + if (backend !== undefined) { + const instance = this.backendInstances.get(backend) + if (instance !== undefined && instance.client.isReady()) return instance.client + throw new RpcError('CURSOR_UNAVAILABLE', 'The requested ACP backend is disabled or unavailable on this Host.') + } + const selected = this.backendInstances.get(this.defaultBackend()) + if (selected !== undefined && selected.client.isReady()) return selected.client + throw new RpcError('CURSOR_UNAVAILABLE', 'Cursor ACP is disabled or unavailable on this Host.') + } + + private initializeResult(params: Record, backend?: string): Record { + const requested = typeof params.protocolVersion === 'number' ? params.protocolVersion : 1 + const actualBackend = backend ?? this.defaultBackend() + return { + protocolVersion: requested, + agentInfo: { + name: actualBackend === 'antigravity' ? 'antigravity' : 'dsh-remote-acp', + version: PLUGIN_VERSION, + }, + backend: actualBackend, + availableBackends: this.availableBackends(), + authMethods: [], + capabilities: { + loadSession: true, + promptTypes: (actualBackend === 'antigravity' || actualBackend === 'hermes') ? ['text', 'image'] : ['text'], + methods: [...ACP_METHOD_ALLOWLIST], + }, + } + } + + private callUpstream(method: string, params: unknown): Promise { + return this.requireAcp().call(method, params) + } + + private requireSessionAccess(connectionId: string, sessionId: string, method: AllowedAcpMethod): void { + if (method === 'session/load') { this.requireSessionOwner(connectionId, sessionId); return } + const owner = this.sessionOwners.get(sessionId) + if (owner === undefined) { + // Allow reclaim after the owning peer disconnected; the ACP process still + // holds the session. + this.sessionOwners.set(sessionId, connectionId) + return + } + if (owner !== connectionId && isSessionMutation(method)) { + throw new RpcError('CURSOR_SESSION_OWNED', 'Another Remote connection owns this session.') + } + } + + private requireSessionOwner(connectionId: string, sessionId: string): void { + this.claimSession(connectionId, sessionId) + } + + private captureCatalogClient(backend: CatalogBackend) { + const client = this.requireAcp(backend) + const instance = this.backendInstances.get(backend) + return { client, assertCurrent: () => { + if (this.closed || this.backendInstances.get(backend) !== instance || this.requireAcp(backend) !== client) { + throw new RpcError('CURSOR_UNAVAILABLE', 'The ACP backend changed while resolving session authority.') + } + } } + } + + private async listCatalogSessions(backend: CatalogBackend, cwd?: string): Promise> { + const { client, assertCurrent } = this.captureCatalogClient(backend) + const items: Array<{ sessionId: string; cwd: string; title?: string; updatedAt?: string }> = [] + let cursor: string | undefined + const seen = new Set() + for (let page = 0; page < 100; page++) { + const result = await client.call('session/list', { ...(cwd ? { cwd } : {}), ...(cursor ? { cursor } : {}) }) + assertCurrent() + if (!isRecord(result) || !Array.isArray(result.sessions) + || (result.nextCursor != null && (typeof result.nextCursor !== 'string' || result.nextCursor.length === 0))) { + throw new RpcError('INVALID_MESSAGE', 'The ACP session catalog response is invalid.') + } + for (const item of result.sessions) { + if (!isRecord(item) || typeof item.sessionId !== 'string' || typeof item.cwd !== 'string') continue + // Directory I/O can outlive a backend restart/reconfiguration. Only the + // directory failure is skippable; a stale generation must reject the RPC. + const canonical = await this.requireExistingDirectory(item.cwd).catch(() => undefined) + assertCurrent() + if (!canonical || (cwd && canonical !== cwd)) continue + if (this.sessionBackends.has(item.sessionId) && this.sessionBackends.get(item.sessionId) !== backend) continue + const trusted = this.sessionCwds.get(item.sessionId) + if (trusted && (trusted.backend !== backend || trusted.cwd !== canonical)) continue + this.sessionCwds.set(item.sessionId, { backend, cwd: canonical }) + this.sessionBackends.set(item.sessionId, backend) + if (backend === 'opencode' && item.archived === true) continue + items.push({ sessionId: item.sessionId, cwd: canonical, + ...(typeof item.title === 'string' ? { title: item.title } : {}), + ...(typeof item.updatedAt === 'string' ? { updatedAt: item.updatedAt } : {}) }) + } + if (result.nextCursor == null) return items + if (seen.has(result.nextCursor) || page === 99) { + throw new RpcError('INVALID_MESSAGE', 'The ACP session catalog pagination did not complete.') + } + cursor = result.nextCursor; seen.add(cursor) + } + return items + } + + private async catalogSessionCwd(backend: CatalogBackend, sessionId: string): Promise { + const { assertCurrent } = this.captureCatalogClient(backend) + if (!this.sessionCwds.has(sessionId)) await this.listCatalogSessions(backend) + assertCurrent() + const session = this.sessionCwds.get(sessionId) + if (!session || session.backend !== backend) throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.') + const canonical = await this.requireExistingDirectory(session.cwd) + assertCurrent() + const current = this.sessionCwds.get(sessionId) + if (canonical !== session.cwd || current?.backend !== backend || current.cwd !== canonical) { + throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session workspace authority changed.') + } + return canonical + } + + private async requireExistingDirectory(path: string): Promise { + if (!isAbsolute(path)) { + throw new RpcError('CURSOR_PATH_NOT_ALLOWED', 'The Cursor working directory must be an absolute path.') + } + try { + const canonical = await realpath(path) + const info = await stat(canonical) + if (!info.isDirectory()) { + throw new RpcError('CURSOR_PATH_NOT_ALLOWED', 'The Cursor working directory must be an existing directory.') + } + return canonical + } catch (error) { + if (error instanceof RpcError) throw error + throw new RpcError('CURSOR_PATH_NOT_ALLOWED', 'The Cursor working directory must be an existing directory.') + } + } + + private async listDirectory(path: string): Promise { + const home = homedir() + const target = path.trim() === '~' || path.trim() === '' + ? home + : path.startsWith('~/') + ? join(home, path.slice(2)) + : path + const canonical = await this.requireExistingDirectory(isAbsolute(target) ? target : resolve(target)) + const names = await readdir(canonical) + const entries: AcpDirectoryEntry[] = [] + let truncated = false + for (const name of names.sort((a, b) => a.localeCompare(b))) { + if (entries.length >= ACP_DIRECTORY_ENTRY_LIMIT) { + truncated = true + break + } + const child = join(canonical, name) + try { + const info = await stat(child) + if (!info.isDirectory()) continue + entries.push({ name, path: child, hidden: name.startsWith('.') }) + } catch { + // Skip unreadable entries. + } + } + return { + path: canonical, + home, + crumbs: buildCrumbs(canonical, home), + entries, + truncated, + } + } + + private async disposeInstance(inst: { client: CursorAcpLike; unsubscribeInbound: () => void; unsubscribeUnavailable: () => void }): Promise { + inst.unsubscribeInbound() + inst.unsubscribeUnavailable() + await inst.client.close() + } + + private async disposeAllInstances(): Promise { + for (const inst of this.backendInstances.values()) { + await this.disposeInstance(inst) + } + this.backendInstances.clear() + } +} + +export type { PublishAcpFrame } + +function parseCallEnvelope(input: unknown): { method: string; params: unknown } { + if (!isRecord(input) || typeof input.method !== 'string') { + throw new RpcError('INVALID_MESSAGE', 'The Cursor call envelope is invalid.') + } + return { method: input.method, params: input.params ?? {} } +} + +function parseRespondEnvelope(input: unknown): { + requestHandle: string + decision: 'allow-once' | 'reject-once' | 'cancel' + result?: unknown +} { + if (!isRecord(input) || typeof input.requestHandle !== 'string' || input.requestHandle.length === 0 + || Object.keys(input).some(key => !['requestHandle', 'decision', 'result'].includes(key)) + || typeof input.decision !== 'string' || !['allow-once', 'reject-once', 'cancel'].includes(input.decision)) { + throw new RpcError('INVALID_MESSAGE', 'The ACP respond envelope is invalid.') + } + return input as ReturnType +} + +function permissionOptions(params: unknown): PendingApproval['options'] { + if (!isRecord(params) || !Array.isArray(params.options) || params.options.length === 0) { + throw new Error('Missing permission options') + } + const ids = new Set() + const options = params.options.map(option => { + if (!isRecord(option) || typeof option.optionId !== 'string' || !option.optionId + || typeof option.kind !== 'string' || !['allow_once', 'allow_always', 'reject_once', 'reject_always'].includes(option.kind) + || ids.has(option.optionId)) throw new Error('Invalid permission option') + ids.add(option.optionId) + return { kind: option.kind, optionId: option.optionId } + }) + for (const kind of ['allow_once', 'reject_once']) { + if (options.filter(option => option.kind === kind).length > 1) throw new Error('Ambiguous permission option') + } + return options +} + +function mapPermissionDecision(params: ReturnType, pending: PendingApproval): unknown { + const invalid = () => new RpcError('INVALID_MESSAGE', 'The ACP approval result is not allowed.') + if (pending.method === 'session/request_permission') { + if (params.result !== undefined) throw invalid() + if (params.decision === 'cancel') return undefined + const kind = params.decision === 'allow-once' ? 'allow_once' : 'reject_once' + const option = pending.options.find(item => item.kind === kind) + if (!option) throw invalid() + return { outcome: { outcome: 'selected', optionId: option.optionId } } + } + const outcome = pending.method === 'cursor/create_plan' + ? params.decision === 'allow-once' ? 'accepted' : params.decision === 'cancel' ? 'cancelled' : 'rejected' + : 'cancelled' + if (params.result !== undefined) { + if (!isRecord(params.result) || Object.keys(params.result).length !== 1 + || !isRecord(params.result.outcome) || Object.keys(params.result.outcome).length !== 1 + || params.result.outcome.outcome !== outcome) throw invalid() + } + return { outcome: { outcome } } +} + +function readSessionId(value: unknown): string | undefined { + if (!isRecord(value)) return undefined + return typeof value.sessionId === 'string' ? value.sessionId : undefined +} + +function readNestedSessionId(value: unknown): string | undefined { + if (!isRecord(value)) return undefined + if (isRecord(value.update) && typeof value.update.sessionId === 'string') return value.update.sessionId + return undefined +} + +function sanitizeSessionResult(value: unknown): unknown { + if (!isRecord(value)) return value + const next: Record = {} + for (const [key, entry] of Object.entries(value)) { + if (key === 'sessionId' || key === 'stopReason' || key === 'mode') next[key] = entry + } + return Object.keys(next).length > 0 ? next : value +} + +function buildCrumbs(path: string, home: string): AcpDirectoryEntry[] { + const crumbs: AcpDirectoryEntry[] = [] + let current = path + while (true) { + crumbs.unshift({ + name: current === home ? '~' : basename(current) || current, + path: current, + hidden: false, + }) + const parent = resolve(current, '..') + if (parent === current) break + if (home !== '' && relative(home, current) === '' && current !== home) break + current = parent + if (crumbs.length >= 32) break + } + return crumbs +} + +/** + * Prefer `~/.local/bin/agent` when the user kept the default command. Explicit + * binary configuration is never rewritten. + */ +export function cursorBinaryCandidates(configured: string): string[] { + const userHome = homedir() + if (configured === 'agy' || configured === 'antigravity') { + return [ + join(userHome, '.local', 'bin', 'agy'), + 'agy', + ] + } + if (configured === 'agent' || configured === 'cursor') { + return [ + join(userHome, '.local', 'bin', 'agent'), + 'agent', + ] + } + if (configured === 'opencode') { + return [ + // Official installer location (curl -fsSL https://opencode.ai/install | bash). + join(userHome, '.opencode', 'bin', 'opencode'), + join(userHome, '.local', 'bin', 'opencode'), + 'opencode', + ] + } + return [configured] +} + +function errorCode(error: unknown): string { + if (error instanceof CursorAcpError || error instanceof OpencodeAcpError || error instanceof RpcError) return error.code + return 'CURSOR_UNAVAILABLE' +} + +function shortSessionId(sessionId: string): string { + return sessionId.length <= 16 ? sessionId : `${sessionId.slice(0, 8)}…${sessionId.slice(-4)}` +} + +function takeTurnCatchUp( + turnCatchUp: Map>, + sessionId: string, +): Array<{ method: string; params: unknown }> { + const list = turnCatchUp.get(sessionId) ?? [] + turnCatchUp.delete(sessionId) + return list +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +}