ds-harness-remote-fast/packages/plugin/src/acp/virtual-harness.ts

1077 lines
52 KiB
TypeScript

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<string, AcpVirtualWorkspaceView>()
private readonly sessions = new Map<string, AcpSessionState>()
private readonly workspaceStreams = new Set<AsyncValueQueue>()
private readonly controlStreams = new Set<AsyncValueQueue>()
private readonly eventStreams = new Map<string, AsyncValueQueue>()
private readonly follows = new Set<FollowState>()
private readonly pendingApprovals = new Map<string, PendingApproval>()
private readonly pendingHistory = new Map<string, Promise<void>>()
private selectedWorkspaceId?: string
private lastOpenedSessionId?: string
private readonly openedWorkspaceSessions = new Map<string, string>()
private readonly selectedModels = new Map<string, AcpModelSelection>()
private readonly selectedPermissions = new Map<string, AcpPermissionPreset>()
private commandSeq = 0
private lastProjectionSeq = 0
private readonly imageAttachments = new Map<string, { sessionId: string; attachment: unknown; data: string }>()
private closed = false
private readonly archivedSessionIds = new Set<string>()
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<typeof AgentAcpClient>[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<string, string> {
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<AcpVirtualWorkspaceView[]> {
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<AcpVirtualWorkspaceView> {
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<AcpVirtualWorkspaceView> {
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<string | undefined> {
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<unknown> {
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<TypertRpcResult> {
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<AsyncIterable<unknown>> {
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<void> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<void> {
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<void> {
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<unknown> {
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<unknown> {
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<unknown> {
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<unknown> {
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<void> {
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<AcpSessionState> {
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<unknown[]> {
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: '<preset>' },
}]
}
private async executeCommand(args: JsonRecord): Promise<unknown> {
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<AcpSessionModels> {
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<unknown> {
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'