diff --git a/packages/plugin/src/acp/virtual-harness.ts b/packages/plugin/src/acp/virtual-harness.ts new file mode 100644 index 0000000..8b58401 --- /dev/null +++ b/packages/plugin/src/acp/virtual-harness.ts @@ -0,0 +1,1076 @@ +import { AgentAcpClient } from '@dsh-remote/client-core' +import type { AcpSessionModels } from '@dsh-remote/protocol' +import { ACP_TOOL_CALL_ENDPOINTS, ACP_TOOL_STREAM_ENDPOINTS } from '@dsh-remote/protocol' +import { AcpSessionHistoryCache, type CachedAcpSessionHistory } from '../session-history-cache.js' +import type { RemoteTypertGatewayTarget, TypertGatewayRequest, TypertRpcResult } from '../typert-gateway-contract.js' +import type { AcpImage } from './image-content.js' +import { acpImageContent, acpImageLimits, parseAcpImage } from './image-content.js' +import type { AcpCatalogBackend, AcpModelSelection, AcpVirtualWorkspaceView } from './virtual-catalog.js' +import { acpBackendLabel, createAcpWorkspaceView, modelCatalog, nativeWorkspace, recreateWorkspaceFromId } from './virtual-catalog.js' +import type { + AcpClientLike, + AcpPermissionPreset, + AcpSessionState, + FollowState, + JsonRecord, + NativeEvent, + PendingApproval, +} from './virtual-contract.js' +import { + acpPermissionsProjection, + array, + AsyncValueQueue, + business, + carrierArgs, + extractPromptText, + extractSessionId, + fail, + failFrom, + failure, + isAcpPermissionPreset, + isRecord, + nativeAcpId, + optionalInteger, + optionalPositiveInteger, + record, + requestArg, + requiredString, + sessionPrefix, + string, + success, +} from './virtual-contract.js' +import { AcpEventCarrier } from './virtual-event-carrier.js' +import { AcpLiveProjection } from './virtual-live.js' +import { AcpSessionTitles } from './virtual-titles.js' + +/** + * Browser-safe, in-memory Harness projection for the independent Agent ACP domain. Projects + * cwd workspaces and ACP sessions onto the native DSH Workspace / Session / + * Composer surface without writing DSH SessionStore. + */ +export class AcpVirtualHarness implements RemoteTypertGatewayTarget { + private readonly live: AcpLiveProjection + private readonly events: AcpEventCarrier + private readonly titles: AcpSessionTitles + + + private readonly workspaceById = new Map() + private readonly sessions = new Map() + private readonly workspaceStreams = new Set() + private readonly controlStreams = new Set() + private readonly eventStreams = new Map() + private readonly follows = new Set() + private readonly pendingApprovals = new Map() + private readonly pendingHistory = new Map>() + private selectedWorkspaceId?: string + private lastOpenedSessionId?: string + private readonly openedWorkspaceSessions = new Map() + private readonly selectedModels = new Map() + private readonly selectedPermissions = new Map() + private commandSeq = 0 + private lastProjectionSeq = 0 + private readonly imageAttachments = new Map() + private closed = false + private readonly archivedSessionIds = new Set() + private readonly unsubscribeArchived?: () => void + + constructor( + private readonly client: AcpClientLike, + private readonly host: { deviceId: string; name: string }, + readonly backend: AcpCatalogBackend = "cursor", + /** + * Host gateway used for endpoints this virtual Harness does not project + * (settings, plugins, models, credentials, …). A real Harness workspace + * serves them from the Host; without this fallback the native Client would + * see `method-not-found` for every global surface and can fail its render. + */ + private readonly hostCarrier?: RemoteTypertGatewayTarget, + private readonly historyCache: AcpSessionHistoryCache = new AcpSessionHistoryCache(), + ) { + const owner = this + this.live = new AcpLiveProjection({ + ensureSessionRegistered: (...args) => owner.ensureSessionRegistered(...args), + get sessions() { return owner.sessions }, + hydrateSession: (...args) => owner.hydrateSession(...args), + historyPage: (...args) => owner.historyPage(...args), + get follows() { return owner.follows }, + get backend() { return owner.backend }, + modelSelectionProjection: (...args) => owner.modelSelectionProjection(...args), + get client() { return owner.client }, + emitRemoteEvent: (...args) => owner.events.emitRemoteEvent(...args), + get selectedModels() { return owner.selectedModels }, + publishProjection: (...args) => owner.events.publishProjection(...args), + nextProjectionSeq: (...args) => owner.nextProjectionSeq(...args), + refreshSessionTitle: (...args) => owner.titles.refresh(...args), + applySessionTitle: (...args) => owner.titles.applyNative(...args), + publishWorkspaceBaseline: () => owner.publishWorkspaceBaseline(), + get pendingApprovals() { return owner.pendingApprovals }, + emitApproval: (...args) => owner.events.emitApproval(...args), + modelSelection: (...args) => owner.modelSelection(...args), + permissionsProjection: (...args) => owner.permissionsProjection(...args), + permissionSelection: (...args) => owner.permissionSelection(...args), + rememberOpenedSession: sessionId => owner.rememberOpenedSession(sessionId), + syncSessionCache: session => owner.syncSessionCache(session), + }) + this.events = new AcpEventCarrier({ + get archivedSessionIds() { return owner.archivedSessionIds }, + get workspaceStreams() { return owner.workspaceStreams }, + visibleWorkspaces: (...args) => owner.visibleWorkspaces(...args), + get controlStreams() { return owner.controlStreams }, + get eventStreams() { return owner.eventStreams }, + get selectedWorkspaceId() { return owner.selectedWorkspaceId }, + get workspaceById() { return owner.workspaceById }, + backendLabel: (...args) => owner.backendLabel(...args), + get pendingApprovals() { return owner.pendingApprovals }, + get client() { return owner.client }, + get sessions() { return owner.sessions }, + nextProjectionSeq: (...args) => owner.nextProjectionSeq(...args), + }) + + this.titles = new AcpSessionTitles(backend, client, this.sessions, + (sessionId, title) => this.events.publishProjection(sessionId, 'title', title)) + this.unsubscribeArchived = client.onSessionArchived?.(data => { + if (this.closed || data.backend !== this.backend) return + this.applyArchived(`${sessionPrefix(this.backend)}${data.sessionId}`) + }) + } + + static remote( + core: ConstructorParameters[0], + host: { deviceId: string; name: string }, + backend: AcpCatalogBackend = "cursor", + capabilities: readonly string[] = [], + hostCarrier?: RemoteTypertGatewayTarget, + historyCache?: AcpSessionHistoryCache, + ): AcpVirtualHarness { + return new AcpVirtualHarness(new AgentAcpClient(core, capabilities), host, backend, hostCarrier, historyCache) + } + + get openedSessionId(): string | undefined { + return this.lastOpenedSessionId + } + + get openedSessions(): ReadonlyMap { + return new Map(this.openedWorkspaceSessions) + } + + private rememberOpenedSession(sessionId: string): void { + if (this.closed) return + this.lastOpenedSessionId = sessionId + for (const workspace of this.workspaceById.values()) { + if (!workspace.sessionIds.includes(sessionId)) continue + this.openedWorkspaceSessions.delete(workspace.workspaceId) + this.openedWorkspaceSessions.set(workspace.workspaceId, sessionId) + if (this.openedWorkspaceSessions.size > 64) { + this.openedWorkspaceSessions.delete(this.openedWorkspaceSessions.keys().next().value!) + } + } + } + + async workspaces(): Promise { + for (const workspace of this.workspaceById.values()) this.sortWorkspaceSessions(workspace) + return [...this.workspaceById.values()] + } + + private backendLabel(): string { + return acpBackendLabel(this.backend) + } + + async selectWorkspace(workspaceId: string): Promise { + const workspace = this.workspaceById.get(workspaceId) ?? recreateWorkspaceFromId(workspaceId, this.backend) + if (workspace === undefined) throw new Error(`The selected ${this.backendLabel()} workspace is no longer available.`) + this.workspaceById.set(workspace.workspaceId, workspace) + this.selectedWorkspaceId = workspace.workspaceId + await this.discoverAndAttachSessions(workspace) + if (workspace.sessionIds.length === 0) { + await this.ensureInitialSession(workspace) + } + this.publishWorkspaceBaseline() + return this.workspaceById.get(workspace.workspaceId) ?? workspace + } + + async selectOrCreateWorkspace(path: string): Promise { + const trimmed = path.trim() + if (trimmed.length === 0) throw new Error(`A ${this.backendLabel()} working directory is required.`) + const existing = [...this.workspaceById.values()].find(item => item.path === trimmed) + const workspace = existing ?? createAcpWorkspaceView(trimmed, this.backend) + this.workspaceById.set(workspace.workspaceId, workspace) + this.selectedWorkspaceId = workspace.workspaceId + await this.discoverAndAttachSessions(workspace) + if (workspace.sessionIds.length === 0) { + await this.ensureInitialSession(workspace) + } + this.publishWorkspaceBaseline() + return this.workspaceById.get(workspace.workspaceId) ?? workspace + } + + async preferredSessionId( + preferredSessionId = this.openedWorkspaceSessions.get(this.selectedWorkspaceId ?? ''), + ): Promise { + const selected = this.selectedWorkspaceId === undefined + ? undefined + : this.workspaceById.get(this.selectedWorkspaceId) + const sessionIds = selected?.sessionIds ?? [] + if (preferredSessionId !== undefined && sessionIds.includes(preferredSessionId) && !this.archivedSessionIds.has(preferredSessionId)) { + return preferredSessionId + } + let bestSessionId: string | undefined + let bestUpdatedAt = -1 + for (const sessionId of sessionIds) { + const session = this.sessions.get(sessionId) + if (session !== undefined && !session.running && !session.blank && session.updatedAt > bestUpdatedAt) { + bestUpdatedAt = session.updatedAt + bestSessionId = sessionId + } + } + if (bestSessionId !== undefined) return bestSessionId + for (const sessionId of sessionIds) { + const session = this.sessions.get(sessionId) + if (session !== undefined && !session.running) return sessionId + } + return sessionIds[0] ?? sessionIds.at(-1) + } + + async invoke(request: TypertGatewayRequest): Promise { + const result = await this.dispatch( + `${request.namespace}/${request.method}`, + { args: request.args }, + request.signal ?? new AbortController().signal, + ) + if (result.ok) return result.value + throw Object.assign(new Error(result.error.message), { + isDSHRemoteError: true as const, + code: result.error.code, + details: result.error.details, + }) + } + + async dispatch(endpoint: string, payload: unknown, signal: AbortSignal): Promise { + try { + const args = carrierArgs(payload) + if (ACP_TOOL_CALL_ENDPOINTS.some(item => item === endpoint)) { + if (!this.client.workspaceToolCall) return business(failure('method-not-found', 'The Host does not support ACP workspace tools.')) + const sessionId = requiredString(args.workspaceFileScopeId ?? args.agentId ?? args.sessionId, 'sessionId') + return business(await this.client.workspaceToolCall(nativeAcpId(sessionId, this.backend), this.backend, endpoint as typeof ACP_TOOL_CALL_ENDPOINTS[number], args, signal)) + } + switch (endpoint) { + case '$events/result': return business(await this.events.answerRemoteEvent(args, signal)) + case 'workspace/list': return business(success({ + items: this.visibleWorkspaces().map(nativeWorkspace), + archivedSessionIds: [...this.archivedSessionIds], + pinnedSessionIds: [], + })) + case 'workspace/create': return business(await this.createWorkspace(requestArg(args))) + case 'workspace/rename': return business(await this.renameWorkspace(requestArg(args))) + case 'workspace/delete': return business(failure('workspace-read-only', `${this.backendLabel()} virtual Workspaces cannot be deleted from Desktop yet.`)) + case 'workspace/insertBefore': return business({ + workspaceIds: this.visibleWorkspaces().map(item => item.workspaceId), + }) + case 'workspace/insertSessionBefore': return business(await this.workspaceForSession(requestArg(args))) + case 'workspace/archiveSession': return business(await this.archiveSession(requestArg(args))) + case 'session/list': return business(success({ items: await this.handleSessionList() })) + case 'session/projections': return business(await this.sessionProjections(requestArg(args))) + case 'session/search': return business(success({ items: [], hasMore: false })) + case 'session/create': return business(await this.createSession(requestArg(args), signal)) + case 'session/fork': return business(failure('bad-request', `${this.backendLabel()} Remote does not support session fork yet.`)) + case 'session/history': return business(await this.sessionHistory(requestArg(args))) + case 'session/events': + case 'session/page': return business(await this.sessionPage(requestArg(args))) + case 'session/prompt': return business(await this.prompt(requestArg(args), signal)) + case 'session/cancel': return business(await this.cancel(requestArg(args), signal)) + case 'session/rename': return business(await this.renameSession(requestArg(args))) + case 'session/updateQueue': return business(failure('queue-item-not-found', `${this.backendLabel()} does not expose a DSH inbox queue.`)) + case 'session/attachment': return business(await this.attachment(requestArg(args))) + case 'session/modelCatalog': { + const sessionId = await this.preferredSessionId() + const catalog = modelCatalog(this.backend) + if (!sessionId) return business(success(catalog)) + const models = await this.hostSessionModels(sessionId) + return business(success({ default: models.current, routableProviders: models.routable ? [models.current.provider] : [], groups: models.groups, failures: models.failures })) + } + case 'session/models': { + const sessionId = this.resolveSessionId(extractSessionId(requestArg(args))) + try { + return business(success(await this.hostSessionModels(sessionId))) + } catch { + return business(failure('model-unavailable', 'The Host model catalog is unavailable.')) + } + } + case 'session/selectModel': return business(await this.selectModel(requestArg(args))) + case 'session/selectPermission': { + const rawId = extractSessionId(requestArg(args)) + const sessionId = this.resolveSessionId(rawId) + const preset = requiredString(requestArg(args).preset, 'preset') + if (!isAcpPermissionPreset(preset)) return business(failure('invalid-preset', `unknown preset "${preset}"`)) + this.setPermissionSelection(sessionId, preset) + return business(success({ preset })) + } + case 'session/initializeDefaultModel': return business(success(undefined)) + case 'session/canOpenWorkspacePath': return business(this.selectedWorkspaceId !== undefined) + case 'session/openWorkspacePath': return business(failure('bad-request', `Opening Host paths is unavailable in ${this.backendLabel()} mode.`)) + case 'host/describe': return business(success(this.describeHost())) + case 'host/listDirectory': + case 'directoryPicker/list': return business(await this.listDirectory(requestArg(args), signal)) + case 'skills/list': return business(success({ items: [] })) + case 'job/kill': return this.hostCarrier === undefined ? business(success({ outcome: 'already-finished' })) : await this.hostCarrier.dispatch(endpoint, payload, signal) + case 'commands/list': return business(this.commandList(requestArg(args))) + case 'commands/execute': return business(await this.executeCommand(requestArg(args))) + default: + return this.hostCarrier === undefined + ? fail('method-not-found', `${this.backendLabel()} virtual Harness does not implement ${endpoint}.`) + : await this.hostCarrier.dispatch(endpoint, payload, signal) + } + } catch (error) { + return failFrom(error) + } + } + + async open(endpoint: string, payload: unknown, signal: AbortSignal): Promise> { + const args = carrierArgs(payload) + if (ACP_TOOL_STREAM_ENDPOINTS.some(item => item === endpoint)) { + const sessionId = requiredString(args.workspaceFileScopeId ?? args.agentId ?? args.sessionId, 'sessionId') + const queue = new AsyncValueQueue(signal) + const stream = await this.client.openStream(nativeAcpId(sessionId, this.backend), frame => { + if (frame.frame.method === 'dsh/workspaceTool') queue.push(record(frame.frame.params).value) + }, () => queue.close(), signal, { backend: this.backend, endpoint: endpoint as typeof ACP_TOOL_STREAM_ENDPOINTS[number], args }) + return queue.iterate(() => { void stream.close().catch(() => undefined) }) + } + if (endpoint === 'workspace/follow') return this.events.workspaceFollow(signal) + if (endpoint === 'session/control') return this.events.sessionControl(signal) + if (endpoint === 'session/follow') return this.live.sessionFollow(requestArg(args), signal) + if (endpoint === '$events') return this.events.remoteEvents(signal) + if (endpoint === 'job/list' || endpoint === 'job/follow') return this.events.emptyJobStream(endpoint, signal) + if (this.hostCarrier !== undefined) return this.hostCarrier.open(endpoint, payload, signal) + throw Object.assign(new Error(`${this.backendLabel()} virtual Harness does not implement stream ${endpoint}.`), { + isDSHRemoteError: true as const, + code: 'method-not-found', + details: {}, + }) + } + + async close(): Promise { + if (this.closed) return + this.closed = true + for (const session of this.sessions.values()) { + if (session.hydrated || session.events.length > 0) { + this.syncSessionCache(session) + } + } + this.titles.close() + this.unsubscribeArchived?.() + for (const stream of this.workspaceStreams) stream.close() + for (const stream of this.controlStreams) stream.close() + for (const stream of this.eventStreams.values()) stream.close() + this.workspaceStreams.clear() + this.controlStreams.clear() + this.eventStreams.clear() + const follows = [...this.follows] + this.follows.clear() + for (const follow of follows) { + follow.queue.close() + await follow.close?.().catch(() => undefined) + } + this.pendingApprovals.clear() + this.imageAttachments.clear() + } + + private visibleWorkspaces(): AcpVirtualWorkspaceView[] { + for (const workspace of this.workspaceById.values()) this.sortWorkspaceSessions(workspace) + if (this.selectedWorkspaceId === undefined) return [...this.workspaceById.values()] + const selected = this.workspaceById.get(this.selectedWorkspaceId) + if (selected === undefined) return [...this.workspaceById.values()] + return [ + selected, + ...[...this.workspaceById.values()].filter(item => item.workspaceId !== selected.workspaceId), + ] + } + + private async createWorkspace(request: JsonRecord): Promise { + const path = string(request.path)?.trim() + if (path === undefined || path.length === 0) return failure('bad-request', 'A Cursor working directory is required.') + const workspace = await this.selectOrCreateWorkspace(path) + this.publishWorkspaceBaseline() + return success({ workspace: nativeWorkspace(workspace), created: true }) + } + + private async renameWorkspace(request: JsonRecord): Promise { + const workspaceId = requiredString(request.workspaceId, 'workspaceId') + const title = string(request.title)?.trim() + const workspace = this.workspaceById.get(workspaceId) + if (workspace === undefined) return failure('workspace-not-found', 'The Cursor virtual Workspace was not found.') + if (title === undefined || title.length === 0) return failure('bad-request', 'A Workspace name is required.') + const next = { ...workspace, title, updatedAt: new Date().toISOString() } + this.workspaceById.set(workspaceId, next) + this.publishWorkspaceBaseline() + return success({ workspace: nativeWorkspace(next) }) + } + + private async workspaceForSession(request: JsonRecord): Promise { + const sessionId = string(request.sessionId) + const workspace = [...this.workspaceById.values()].find(item => sessionId !== undefined && item.sessionIds.includes(sessionId)) + return workspace === undefined + ? failure('workspace-not-found', 'The Cursor virtual Workspace was not found.') + : success({ workspace: nativeWorkspace(workspace) }) + } + + private async archiveSession(request: JsonRecord): Promise { + const sessionId = extractSessionId(request) + if (this.backend === 'opencode') { + if (!this.client.supportsArchive?.(this.backend) || !this.client.archiveSession) return failure('archive-unavailable', 'Update the Host plugin to archive OpenCode conversations.') + await this.client.archiveSession(nativeAcpId(sessionId, this.backend), this.backend) + this.applyArchived(sessionId) + return success({ archivedSessionIds: [...this.archivedSessionIds] }) + } + return failure('archive-unavailable', `Native session archiving is unavailable for ${this.backendLabel()}.`) + } + + private applyArchived(sessionId: string): void { + this.archivedSessionIds.add(sessionId) + this.historyCache.delete(sessionId) + for (const [workspaceId, workspace] of this.workspaceById) { + if (!workspace.sessionIds.includes(sessionId)) continue + const sessionIds = workspace.sessionIds.filter(id => id !== sessionId) + this.workspaceById.set(workspaceId, { + ...workspace, + sessionIds, + sessionCount: sessionIds.length, + updatedAt: new Date().toISOString(), + }) + } + this.events.emitRemoteEvent('api-session/removed', [sessionId]) + this.publishWorkspaceBaseline() + } + + private async createSession(request: JsonRecord, signal: AbortSignal): Promise { + const workspaceId = string(request.workspaceId) ?? this.selectedWorkspaceId + const workspace = workspaceId === undefined ? undefined : this.workspaceById.get(workspaceId) + const cwd = string(request.cwd) ?? workspace?.path + if (cwd === undefined) return failure('workspace-not-found', 'The Cursor virtual Workspace was not found.') + const requestedSessionId = string(request.sessionId) + const reusable = requestedSessionId === undefined ? undefined : this.sessions.get(requestedSessionId) + if (reusable !== undefined && reusable.cwd === cwd && reusable.blank && !reusable.running) { + return success({ sessionId: reusable.sessionId }) + } + const created = await this.client.createSession(cwd, 'agent', this.backend, signal) + if (this.backend !== 'cursor' && this.sessions.has(`${sessionPrefix(this.backend)}${created.sessionId}`)) { + return failure('session-already-exists', 'The backend returned an existing conversation for a new Session.') + } + const session = this.registerSession(created.sessionId, cwd, workspace?.title) + this.attachSessionToWorkspace(cwd, session.sessionId) + this.publishWorkspaceBaseline() + const seq = this.nextProjectionSeq() + this.events.emitRemoteEvent('api-session/added', [this.sessionSummary(session, seq)]) + this.events.publishProjection(session.sessionId, 'title', session.title ?? this.backendLabel(), seq) + this.events.publishProjection(session.sessionId, 'modelSelection', this.modelSelectionProjection(session.sessionId), seq) + return success({ sessionId: session.sessionId }) + } + + private ensureSessionRegistered(sessionId: string): AcpSessionState | undefined { + let session = this.sessions.get(sessionId) + if (session !== undefined) return session + const prefix = sessionPrefix(this.backend) + if (this.backend !== 'cursor') { + if (sessionId.startsWith(prefix)) { + const acpSessionId = sessionId.slice(prefix.length) + const workspace = this.selectedWorkspaceId !== undefined ? this.workspaceById.get(this.selectedWorkspaceId) : undefined + const cwd = workspace?.path ?? '/' + session = this.registerSession(acpSessionId, cwd, this.backendLabel(), Date.now(), Date.now(), false) + if (workspace && !workspace.sessionIds.includes(sessionId)) { + workspace.sessionIds.unshift(sessionId) + workspace.sessionCount = workspace.sessionIds.length + this.publishWorkspaceBaseline() + } + return session + } + const prefixed = `${prefix}${sessionId}` + const found = this.sessions.get(prefixed) + if (found !== undefined) return found + } + return undefined + } + + private async prompt(request: JsonRecord, signal: AbortSignal): Promise { + const sessionId = extractSessionId(request) + const session = this.ensureSessionRegistered(sessionId) ?? this.sessions.get(sessionId) + if (session === undefined) return failure('session-not-found', 'The Session was not found.') + await this.hydrateSession(session) + const text = extractPromptText(array(request.content)) + let images: AcpImage[] + try { + images = array(request.content).filter(part => record(part).type === 'image').map(parseAcpImage) + if (images.length > 4 || (images.length > 0 && this.backend !== 'antigravity' && this.backend !== 'hermes') || array(request.content).some(part => !['text', 'image'].includes(String(record(part).type)))) throw new Error('Unsupported ACP content.') + } catch { return failure('attachment-error', 'Invalid or unsupported image attachment.') } + if (text === undefined && images.length === 0) return failure('attachment-error', 'A prompt or image is required.') + const imageBlocks = images.map(image => acpImageContent(image, `agy-image:${crypto.randomUUID()}.${image.mimeType === 'image/jpeg' ? 'jpg' : image.mimeType.slice(6)}`)) + this.cacheImageAttachments(sessionId, imageBlocks) + const requestId = typeof request.requestId === 'string' && request.requestId.length > 0 + ? request.requestId + : undefined + await this.live.ensureFollow(session) + const follow = [...this.follows].find(f => f.sessionId === sessionId) + if (follow !== undefined) { + follow.turn += 1 + follow.stepOpen = true + this.live.pushEvent(follow, 'turn/start', { turn: follow.turn }) + this.live.pushEvent(follow, 'step/start', { turn: follow.turn, step: 1 }) + this.live.pushEvent(follow, 'user/message', { + id: `user:${Date.now()}`, + role: 'user', + content: [...(text ? [{ type: 'text', text }] : []), ...imageBlocks], + source: requestId ? { kind: 'user', rpcId: requestId } : { kind: 'user' }, + }) + } + this.titles.applyPrompt(session, text) + session.blank = false + session.hydrated = true + session.running = true + session.updatedAt = Date.now() + this.syncSessionCache(session) + this.events.emitRemoteEvent('api-session/status', [sessionId, true]) + this.publishWorkspaceBaseline() + await this.client.prompt(session.acpSessionId, text ?? '', signal, images, this.backend) + return success({ accepted: true }) + } + + private async cancel(request: JsonRecord, signal: AbortSignal): Promise { + const sessionId = extractSessionId(request) + const session = this.ensureSessionRegistered(sessionId) ?? this.sessions.get(sessionId) + if (session === undefined) return failure('session-not-found', 'The Session was not found.') + await this.client.cancel(session.acpSessionId, signal) + session.running = false + for (const follow of this.follows) { + if (follow.sessionId === sessionId) { + this.live.closeFollowAfterRemoteStreamClosed(follow, { kind: 'aborted', reason: { kind: 'user' } }) + } + } + this.syncSessionCache(session) + this.events.emitRemoteEvent('api-session/status', [sessionId, false]) + return success({ accepted: true }) + } + + private async renameSession(request: JsonRecord): Promise { + const sessionId = extractSessionId(request) + const title = string(request.title)?.trim() + const session = this.ensureSessionRegistered(sessionId) ?? this.sessions.get(sessionId) + if (session === undefined) return failure('session-not-found', 'The Session was not found.') + if (title === undefined) return failure('bad-request', 'A Session title is required.') + session.title = title + session.titleOverridden = true + session.updatedAt = Date.now() + this.syncSessionCache(session) + this.events.publishProjection(sessionId, 'title', title) + return success({ sessionId }) + } + + private cacheImageAttachments(sessionId: string, content: unknown[]): void { + for (const value of content) { + const block = record(value) + const attachment = record(block.attachment) + if (block.type === 'image' && typeof attachment.attachmentId === 'string' && typeof block.data === 'string') { + this.imageAttachments.set(attachment.attachmentId, { sessionId, attachment, data: block.data }) + } + } + } + + private async attachment(request: JsonRecord): Promise { + const sessionId = extractSessionId(request) + // 0.2.2 sends the full ImageAttachmentRef; older clients send only its id. + const attachmentId = string(request.attachmentId) + ?? string(record(request.attachment).attachmentId) + const session = this.ensureSessionRegistered(sessionId) + if ((this.backend !== 'antigravity' && this.backend !== 'hermes') || session === undefined || !attachmentId?.startsWith('agy-image:')) return failure('attachment-error', 'The image is not referenced by this Session.') + await this.hydrateSession(session) + const cached = this.imageAttachments.get(attachmentId) + return cached?.sessionId === sessionId ? success({ attachment: cached.attachment, data: cached.data }) : failure('attachment-error', 'The image attachment is unavailable or expired.') + } + + private async hydrateSession(session: AcpSessionState): Promise { + if (this.backend === 'cursor' || session.blank || (session.events.length > 0 && !session.staleHistory)) return + const cached = this.historyCache.getFresh(session.sessionId) + if (cached !== undefined && (!Number.isFinite(session.updatedAt) || session.updatedAt === cached.hostUpdatedAt)) { + this.restoreCachedSession(session, cached, false) + return + } + const pending = this.pendingHistory.get(session.sessionId) + if (pending) return pending + const read = this.hydrateSessionOnce(session) + this.pendingHistory.set(session.sessionId, read) + try { await read } finally { if (this.pendingHistory.get(session.sessionId) === read) this.pendingHistory.delete(session.sessionId) } + } + + private async hydrateSessionOnce(session: AcpSessionState): Promise { + let events: unknown[] = [] + if (this.client.loadSessionHistory !== undefined) { + try { + events = await this.client.loadSessionHistory(session.sessionId, this.backend) + } catch (error) { + const stale = this.historyCache.getStale(session.sessionId) + if (stale !== undefined && stale.events.length > 0) { + this.restoreCachedSession(session, stale, true) + return + } + // A failed history read is not a successful empty baseline; do not continue + // a restored conversation until its authoritative history is available. + if (this.backend === 'pi' || this.backend === 'claude' || this.backend === 'opencode' || this.backend === 'hermes') throw error + // Preserve legacy AGY history availability behavior. + } + } + if (events.length > 0) { + session.hydrated = true + session.staleHistory = false + session.events = events as unknown as Array<{ type: 'event'; event: NativeEvent }> + const firstUser = session.events.find(entry => entry.event.type === 'user/message') + this.titles.applyPrompt(session, extractPromptText(array(record(firstUser?.event.data).content))) + session.blank = false + for (const event of session.events) this.cacheImageAttachments(session.sessionId, array(record(event.event.data).content ?? record(record(event.event.data).message).content)) + this.syncSessionCache(session) + } + } + + private restoreCachedSession(session: AcpSessionState, cached: CachedAcpSessionHistory, staleFallback: boolean): void { + session.events = cached.events + session.hydrated = !staleFallback && !cached.stale && !cached.truncated + session.staleHistory = staleFallback || Boolean(cached.stale) || Boolean(cached.truncated) + session.blank = cached.blank + if (cached.title !== undefined && (!session.titleOverridden || cached.titleOverridden)) { + session.title = cached.title + session.titleOverridden = cached.titleOverridden + session.titleFromPrompt = cached.titleFromPrompt + } + if (cached.selectedModel !== undefined && !this.selectedModels.has(session.sessionId)) { + this.selectedModels.set(session.sessionId, cached.selectedModel) + } + if (cached.permissionPreset !== undefined && !this.selectedPermissions.has(session.sessionId)) { + this.selectedPermissions.set(session.sessionId, cached.permissionPreset) + } + for (const event of session.events) { + this.cacheImageAttachments(session.sessionId, array(record(event.event.data).content ?? record(record(event.event.data).message).content)) + } + } + + private syncSessionCache(session: AcpSessionState): void { + if (this.backend === 'cursor') return + const existing = this.historyCache.getStale(session.sessionId) + const isStale = Boolean(session.running || session.staleHistory) + const hostUpdatedAt = session.staleHistory && existing !== undefined + ? existing.hostUpdatedAt + : session.updatedAt + const selectedModel = this.selectedModels.get(session.sessionId) + const permissionPreset = this.selectedPermissions.get(session.sessionId) + this.historyCache.set(session.sessionId, { + events: session.events, + blank: session.blank && session.events.length === 0, + hydrated: Boolean((session.hydrated || session.events.length > 0) && !session.staleHistory), + stale: isStale, + ...(session.title === undefined ? {} : { title: session.title }), + ...(session.titleOverridden === undefined ? {} : { titleOverridden: session.titleOverridden }), + ...(session.titleFromPrompt === undefined ? {} : { titleFromPrompt: session.titleFromPrompt }), + hostUpdatedAt, + ...(selectedModel === undefined ? {} : { selectedModel }), + ...(permissionPreset === undefined ? {} : { permissionPreset }), + }) + } + + private async sessionHistory(request: JsonRecord): Promise { + const sessionId = extractSessionId(request) + const session = this.ensureSessionRegistered(sessionId) ?? this.sessions.get(sessionId) + if (session === undefined) return failure('session-not-found', 'The Session was not found.') + await this.hydrateSession(session) + const beforeSeq = optionalInteger(request.beforeSeq) + if (beforeSeq === undefined) { + this.rememberOpenedSession(session.sessionId) + } + const page = this.historyPage(session, { + beforeSeq, + limit: optionalPositiveInteger(request.maxMessages) ?? 50, + }) + return success({ + ...page, + events: page.records.map(entry => ({ event: entry.event })), + projections: { + asOfSeq: page.cursor, + values: { + title: session.title ?? acpBackendLabel(this.backend), + sessionListMetadata: { blank: session.blank && session.events.length === 0, lastPromptAt: null }, + modelSelection: this.modelSelectionProjection(sessionId), + permissions: this.permissionsProjection(sessionId), + imageLimits: acpImageLimits(this.backend), + }, + }, + }) + } + + private async sessionProjections(request: JsonRecord): Promise { + const sessionId = extractSessionId(request) + const session = this.ensureSessionRegistered(sessionId) ?? this.sessions.get(sessionId) + if (session === undefined) return success(null) + await this.hydrateSession(session) + return success(this.sessionSummary(session, session.events.at(-1)?.event.seq ?? -1).projections) + } + + private async sessionPage(request: JsonRecord): Promise { + const sessionId = extractSessionId(request) + const session = this.ensureSessionRegistered(sessionId) ?? this.sessions.get(sessionId) + if (session === undefined) return failure('session-not-found', 'The Session was not found.') + await this.hydrateSession(session) + const page = this.historyPage(session, { + beforeSeq: optionalInteger(request.beforeSeq), + throughSeq: optionalInteger(request.throughSeq), + limit: optionalPositiveInteger(request.limit) ?? optionalPositiveInteger(request.maxMessages) ?? 50, + }) + return success({ records: page.records, hasMore: page.hasMore, cursor: page.cursor }) + } + + private historyPage( + session: AcpSessionState, + options: { beforeSeq?: number; throughSeq?: number; limit?: number } = {}, + ) { + const lastSessionSeq = session.events.at(-1)?.event.seq ?? -1 + const throughSeq = Math.min(options.throughSeq ?? lastSessionSeq, lastSessionSeq) + const endSeq = Math.min(throughSeq, options.beforeSeq === undefined ? throughSeq : options.beforeSeq - 1) + const window = endSeq < 0 ? [] : session.events.filter(entry => entry.event.seq <= endSeq) + const limit = options.limit ?? 50 + const records = window.slice(Math.max(0, window.length - limit)) + const cursor = records.at(-1)?.event.seq ?? -1 + return { + header: { + version: 3, + id: session.sessionId, + createdAt: session.createdAt, + cwd: session.cwd, + isSeeded: false, + }, + cursor, + nextTurn: Math.max(0, ...session.events.map(entry => isRecord(entry.event.data) && typeof entry.event.data.turn === 'number' ? entry.event.data.turn : 0)) + 1, + records, + hasMore: window.length > records.length, + ...(session.running ? { activeTurnId: 'cursor-live' } : {}), + assistantStream: { revision: 0 }, + } + } + + private describeHost(): JsonRecord { + const workspace = this.selectedWorkspaceId === undefined + ? undefined + : this.workspaceById.get(this.selectedWorkspaceId) + const name = this.backendLabel() + return { + version: `${name} Remote`, + cwd: workspace?.path ?? '', + home: workspace?.path ?? '', + provider: name, + model: modelCatalog(this.backend).default.model, + attachedSessions: this.sessions.size, + canOpenPath: workspace !== undefined, + } + } + + private async listDirectory(request: JsonRecord, signal: AbortSignal): Promise { + const workspace = this.selectedWorkspaceId === undefined + ? undefined + : this.workspaceById.get(this.selectedWorkspaceId) + if (workspace === undefined) return failure('workspace-not-found', `The ${this.backendLabel()} virtual Workspace was not found.`) + const path = string(request.path) ?? workspace.path + return success(await this.client.listDirectory(path, signal)) + } + + private registerSession( + acpSessionId: string, + cwd: string, + title?: string, + createdAt: number = Date.now(), + updatedAt: number = Date.now(), + blank: boolean = true, + ): AcpSessionState { + const nativeTitle = this.titles.nativeTitle(title) + const session: AcpSessionState = { + sessionId: `${sessionPrefix(this.backend)}${acpSessionId}`, + acpSessionId, + cwd, + ...(nativeTitle === undefined ? {} : { title: nativeTitle }), + blank, + running: false, + createdAt, + updatedAt, + events: [], + } + this.sessions.set(session.sessionId, session) + return session + } + + private async discoverAndAttachSessions(workspace: AcpVirtualWorkspaceView): Promise { + if (this.backend === 'cursor') return + const previousTitles = new Map([...this.sessions].map(([id, session]) => [id, session.title])) + try { + let discovered: Array<{ conversationId: string; title: string; createdAt: number; updatedAt: number }> = [] + if (this.client.listSessions !== undefined) { + try { + discovered = await this.client.listSessions(workspace.path, this.backend, 30) + } catch (error) { + if (this.backend === 'pi' || this.backend === 'claude' || this.backend === 'hermes') throw error + // Preserve legacy AGY catalog availability behavior. + } + } + for (const item of discovered) { + const sessionId = `${sessionPrefix(this.backend)}${item.conversationId}` + if (!this.sessions.has(sessionId)) { + this.registerSession(item.conversationId, workspace.path, item.title, item.createdAt, item.updatedAt, false) + } + const existing = this.sessions.get(sessionId) + if (existing !== undefined) { + // Refresh activity from the Host without moving a live turn backwards. + if (Number.isFinite(item.updatedAt)) existing.updatedAt = Math.max(existing.updatedAt, item.updatedAt) + if (!previousTitles.has(sessionId) || existing.title === previousTitles.get(sessionId)) { + this.titles.applyNative(existing, item.title) + } + } + if (!this.archivedSessionIds.has(sessionId) && !workspace.sessionIds.includes(sessionId)) { + workspace.sessionIds.push(sessionId) + } + } + workspace.sessionCount = workspace.sessionIds.length + this.sortWorkspaceSessions(workspace) + workspace.updatedAt = new Date().toISOString() + } catch (error) { + if (this.backend === 'pi' || this.backend === 'claude' || this.backend === 'hermes') throw error + // Preserve legacy AGY catalog availability behavior. + } + } + + private attachSessionToWorkspace(cwd: string, sessionId: string): void { + const workspace = [...this.workspaceById.values()].find(item => item.path === cwd) + ?? createAcpWorkspaceView(cwd, this.backend) + const sessionIds = [sessionId, ...workspace.sessionIds.filter(id => id !== sessionId)] + const next = { + ...workspace, + sessionIds, + sessionCount: sessionIds.length, + updatedAt: new Date().toISOString(), + } + this.workspaceById.set(next.workspaceId, next) + if (this.selectedWorkspaceId === undefined) this.selectedWorkspaceId = next.workspaceId + } + + private async ensureInitialSession(workspace: AcpVirtualWorkspaceView): Promise { + const cwd = workspace.path + const created = await this.client.createSession(cwd, 'agent', this.backend) + const sessionId = created.sessionId + const title = this.backend === 'antigravity' ? 'Antigravity' : this.backend === 'opencode' ? 'OpenCode' : workspace.title + const session = this.registerSession(sessionId, cwd, title) + this.attachSessionToWorkspace(cwd, session.sessionId) + const seq = this.nextProjectionSeq() + this.events.emitRemoteEvent('api-session/added', [this.sessionSummary(session, seq)]) + this.events.publishProjection(session.sessionId, 'title', session.title ?? this.backendLabel(), seq) + this.events.publishProjection(session.sessionId, 'modelSelection', this.modelSelectionProjection(session.sessionId), seq) + this.publishWorkspaceBaseline() + return session + } + + private async handleSessionList(): Promise { + for (const workspace of this.workspaceById.values()) { + await this.discoverAndAttachSessions(workspace) + if (workspace.sessionIds.length === 0) { + await this.ensureInitialSession(workspace) + } + } + return this.sessionSummaries() + } + + private sessionSummaries(): unknown[] { + const selected = this.selectedWorkspaceId === undefined + ? undefined + : this.workspaceById.get(this.selectedWorkspaceId) + const allowed = new Set(selected?.sessionIds ?? [...this.sessions.keys()]) + return [...this.sessions.values()] + .filter(session => allowed.has(session.sessionId) && !this.archivedSessionIds.has(session.sessionId)) + .sort((a, b) => b.updatedAt - a.updatedAt || a.sessionId.localeCompare(b.sessionId)) + .map(session => this.sessionSummary(session, 0)) + } + + private sortWorkspaceSessions(workspace: AcpVirtualWorkspaceView): void { + workspace.sessionIds.sort((a, b) => + (this.sessions.get(b)?.updatedAt ?? 0) - (this.sessions.get(a)?.updatedAt ?? 0) || a.localeCompare(b)) + } + + private sessionSummary(session: AcpSessionState, asOfSeq: number): JsonRecord { + return { + sessionId: session.sessionId, + agentAvailable: true, + running: session.running, + blank: session.blank, + cwd: session.cwd, + updatedAt: session.updatedAt, + projections: { + kind: 'sequenced', + asOfSeq, + values: { + title: session.title ?? acpBackendLabel(this.backend), + sessionListMetadata: { blank: session.blank, lastPromptAt: null }, + modelSelection: this.modelSelectionProjection(session.sessionId), + permissions: this.permissionsProjection(session.sessionId), + imageLimits: acpImageLimits(this.backend), + }, + }, + } + } + + private resolveSessionId(rawId: string): string { + if (this.sessions.has(rawId)) { + return rawId + } + const prefixed = `${sessionPrefix(this.backend)}${rawId}` + if (this.sessions.has(prefixed)) { + return prefixed + } + throw Object.assign(new Error('The Session was not found.'), { code: 'session-not-found' }) + } + + private modelSelection(sessionId: string): AcpModelSelection { + const resolved = this.resolveSessionId(sessionId) + return this.selectedModels.get(resolved) ?? this.selectedModels.get(sessionId) ?? modelCatalog(this.backend).default + } + + private modelSelectionProjection(sessionId: string): { lastUsed: AcpModelSelection; next: AcpModelSelection } { + const selection = this.modelSelection(sessionId) + return { lastUsed: selection, next: selection } + } + + private permissionSelection(sessionId: string): AcpPermissionPreset | undefined { + const resolved = this.resolveSessionId(sessionId) + return this.selectedPermissions.get(resolved) ?? this.selectedPermissions.get(sessionId) + } + + private permissionsProjection(sessionId: string): unknown { + return acpPermissionsProjection(this.permissionSelection(sessionId)) + } + + private setPermissionSelection(sessionId: string, preset: AcpPermissionPreset | undefined): void { + const resolved = this.resolveSessionId(sessionId) + if (preset === undefined) { + this.selectedPermissions.delete(resolved) + this.selectedPermissions.delete(sessionId) + } else { + this.selectedPermissions.set(resolved, preset) + this.selectedPermissions.set(sessionId, preset) + } + const seq = this.nextProjectionSeq() + this.events.publishProjection(resolved, 'permissions', this.permissionsProjection(resolved), seq) + if (resolved !== sessionId) { + this.events.publishProjection(sessionId, 'permissions', this.permissionsProjection(resolved), seq) + } + const session = this.sessions.get(resolved) + if (session !== undefined) this.syncSessionCache(session) + if (this.client.selectPermission) { + void this.client.selectPermission(nativeAcpId(resolved, this.backend), this.backend, preset ?? 'workspace-write').catch(() => undefined) + } + } + + private commandList(args: JsonRecord): unknown[] { + const rawId = extractSessionId(args) + if (rawId) this.resolveSessionId(rawId) + return [{ + name: 'permission', + description: `Switch the ${this.backendLabel()} Remote sandbox mode and approval policy`, + input: { hint: '' }, + }] + } + + private async executeCommand(args: JsonRecord): Promise { + const rawId = requiredString(args.agentId ?? args.sessionId, 'agentId') + const sessionId = this.resolveSessionId(rawId) + const line = requiredString(args.line, 'command line').trim() + const match = /^\/permission(?:\s+([\s\S]*))?$/u.exec(line) + if (match === null) return undefined + + const commandId = `acp-permission:${++this.commandSeq}` + const requested = (match[1] ?? '').trim() + if (requested === '') { + return { + commandId, + result: { kind: 'success', text: `current preset ${this.permissionSelection(sessionId) ?? 'Host settings (not reported)'}` }, + } + } + if (!isAcpPermissionPreset(requested)) { + return { + commandId, + result: { kind: 'error', text: `unknown preset "${requested}" (available: workspace-write, danger-full-access)` }, + } + } + this.setPermissionSelection(sessionId, requested) + return { commandId, result: { kind: 'success', text: `preset ${requested}` } } + } + + private async hostSessionModels(sessionId: string): Promise { + const resolvedId = this.resolveSessionId(sessionId) + if (!this.client.sessionModels) { + const catalog = modelCatalog(this.backend) + return { + current: this.modelSelection(resolvedId), + routable: false, + groups: catalog.groups, + failures: [], + } + } + const models = await this.client.sessionModels(nativeAcpId(resolvedId, this.backend), this.backend) + this.selectedModels.set(resolvedId, models.current) + return models + } + + private async selectModel(request: JsonRecord): Promise { + const rawSessionId = extractSessionId(request) + const sessionId = this.resolveSessionId(rawSessionId) + const provider = requiredString(request.provider, 'provider') + const model = requiredString(request.model, 'model') + const reasoningEffort = string(request.reasoningEffort) + const catalog = await this.hostSessionModels(sessionId) + const group = catalog.groups.find(g => g.id === provider || g.id.toLowerCase() === provider.toLowerCase()) + let targetModel = group?.models.find(item => item.id === model) + if (targetModel === undefined) { + const aliases = group?.models.filter(item => item.id.endsWith(`/${model}`) || model.endsWith(`/${item.id}`)) + if (aliases?.length === 1) targetModel = aliases[0] + } + if (group === undefined || targetModel === undefined) { + return failure('model-unavailable', `The selected ${this.backend} model is unavailable on this Host.`) + } + const supportedEfforts = targetModel.reasoning?.efforts.map(effort => effort.id) ?? [] + if (reasoningEffort !== undefined && !supportedEfforts.includes(reasoningEffort)) { + return failure('model-unavailable', `The selected reasoning effort is unavailable for this ${this.backend} model.`) + } + const selected: AcpModelSelection = { + provider: group.id, + model: targetModel.id, + ...(reasoningEffort === undefined ? {} : { reasoningEffort }), + } + if (!this.client.selectModel) return failure('model-unavailable', 'The Host does not support ACP model selection.') + const confirmed = await this.client.selectModel(nativeAcpId(sessionId, this.backend), this.backend, selected) + this.selectedModels.set(sessionId, confirmed) + if (rawSessionId && rawSessionId !== sessionId) this.selectedModels.set(rawSessionId, confirmed) + const session = this.sessions.get(sessionId) + if (session !== undefined) this.syncSessionCache(session) + const seq = this.nextProjectionSeq() + this.events.publishProjection(sessionId, 'modelSelection', this.modelSelectionProjection(sessionId), seq) + if (rawSessionId && rawSessionId !== sessionId) { + this.events.publishProjection(rawSessionId, 'modelSelection', this.modelSelectionProjection(sessionId), seq) + } + return success({ selected: this.modelSelection(sessionId) }) + } + + private publishWorkspaceBaseline(): void { + for (const queue of this.workspaceStreams) { + for (const workspace of this.visibleWorkspaces()) { + queue.push({ type: 'upsert', workspace: nativeWorkspace(workspace) }) + } + queue.push({ type: 'archived', archivedSessionIds: [...this.archivedSessionIds] }) + } + } + + private nextProjectionSeq(): number { + this.lastProjectionSeq += 1 + return this.lastProjectionSeq + } +} + +export { acpCwdWorkspaceId, createAcpWorkspaceView, discoverAcpVirtualWorkspaces, modelCatalog } from './virtual-catalog.js' +export { acpPermissionsProjection, isAcpPermissionPreset } from './virtual-contract.js' +export type { AcpModelSelection, AcpModelView, AcpVirtualWorkspaceView } from './virtual-catalog.js' +export type { AcpClientLike, AcpPermissionPreset } from './virtual-contract.js'