1665 lines
78 KiB
TypeScript
1665 lines
78 KiB
TypeScript
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<string> = new Set<CatalogBackend>(['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<string, {
|
|
id: string
|
|
client: CursorAcpLike
|
|
unsubscribeInbound: () => void
|
|
unsubscribeUnavailable: () => void
|
|
startedAt: number
|
|
}>()
|
|
private readonly sessionCwds = new Map<string, { backend: string; cwd: string }>()
|
|
private readonly workspaceState = new WorkspaceBridgeState(key => TerminalPolicy.releaseOwner(this.terminalOwners, key))
|
|
private readonly terminalOwners = new Map<string, string>()
|
|
private readonly workspaceTools = new Map<string, AcpWorkspaceTools>()
|
|
private readonly peers = new Map<string, AcpPeerBridge>()
|
|
private readonly sessionOwners = new Map<string, string>()
|
|
private readonly sessionBackends = new Map<string, string>()
|
|
private readonly sessionPermissions = new Map<string, string>()
|
|
private readonly approvals = new Map<string, PendingApproval>()
|
|
private approvalExpiryTimer?: ReturnType<typeof setTimeout>
|
|
private readonly restartAttempts = new Map<string, number>()
|
|
private readonly restartTimers = new Map<string, NodeJS.Timeout>()
|
|
private readonly launching = new Map<string, Promise<void>>()
|
|
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<void> = Promise.resolve()
|
|
/** Catch-up buffer for turns that finish while the Client is reconnecting. */
|
|
private readonly recentFrames = new Map<string, BufferedAcpFrame[]>()
|
|
/** Per-prompt live updates; attached to prompt_completed when streaming was lossy. */
|
|
private readonly promptsInProgress = new Map<string, PromptTask>()
|
|
private readonly cancelledSessions = new Set<string>()
|
|
/** Identity fences asynchronous Pi preparation from a later retry of the same session. */
|
|
private readonly preparingPrompts = new Map<string, { cancelled: boolean }>()
|
|
private readonly turnCatchUp = new Map<string, Array<{ method: string; params: unknown }>>()
|
|
|
|
private startPromise?: Promise<void>
|
|
private readonly startingClients = new Map<CursorAcpLike, ResolvedAcpBackendConfig>()
|
|
/** Desired configuration is saved immediately; unfinished cleanup must remain retryable. */
|
|
private readonly pendingReconfiguration = new Set<string>()
|
|
private readonly archivingSessions = new Set<string>()
|
|
private readonly opencodeOperations = new Map<string, number>()
|
|
private historyEpoch = 0
|
|
private minValidHistoryEpoch = 0
|
|
private readonly historyInvalidatedAt = new Map<string, number>()
|
|
private readonly pendingHistoryReads = new Map<string, { client: CursorAcpLike; readEpoch: number; promise: Promise<unknown[]> }>()
|
|
private readonly backendHistoryChains = new Map<string, Promise<void>>()
|
|
|
|
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<void> {
|
|
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<void> {
|
|
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<unknown> {
|
|
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<typeof parseAcpCall>, assertCurrent: () => void): Promise<unknown> {
|
|
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<void> }
|
|
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<boolean> }
|
|
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<string>()
|
|
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<string>()
|
|
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<unknown[]> }
|
|
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<unknown[]> }, 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<string, unknown>)
|
|
}
|
|
|
|
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<void> {
|
|
// 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<unknown[]> },
|
|
conversationId: string,
|
|
cwd: string,
|
|
assertCurrent: () => void,
|
|
): Promise<unknown[]> {
|
|
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<void>(resolve => { releaseQueue = resolve })
|
|
const nextChain = previous.then(() => currentTurn, () => currentTurn)
|
|
this.backendHistoryChains.set(backend, nextChain)
|
|
const readPromise = (async (): Promise<unknown[]> => {
|
|
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<void> {
|
|
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<string, unknown>, 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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void>
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<string>()
|
|
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<void> {
|
|
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<number | undefined>((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<string, unknown>, backend?: string): Record<string, unknown> {
|
|
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<unknown> {
|
|
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<Array<{ sessionId: string; cwd: string; title?: string; updatedAt?: string }>> {
|
|
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<string>()
|
|
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<string> {
|
|
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<string> {
|
|
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<AcpDirectoryListing> {
|
|
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<void> {
|
|
inst.unsubscribeInbound()
|
|
inst.unsubscribeUnavailable()
|
|
await inst.client.close()
|
|
}
|
|
|
|
private async disposeAllInstances(): Promise<void> {
|
|
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<typeof parseRespondEnvelope>
|
|
}
|
|
|
|
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<string>()
|
|
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<typeof parseRespondEnvelope>, 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<string, unknown> = {}
|
|
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<string, Array<{ method: string; params: unknown }>>,
|
|
sessionId: string,
|
|
): Array<{ method: string; params: unknown }> {
|
|
const list = turnCatchUp.get(sessionId) ?? []
|
|
turnCatchUp.delete(sessionId)
|
|
return list
|
|
}
|
|
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
}
|