diff --git a/packages/client-core/src/acp-client.ts b/packages/client-core/src/acp-client.ts new file mode 100644 index 0000000..138c9c8 --- /dev/null +++ b/packages/client-core/src/acp-client.ts @@ -0,0 +1,328 @@ +import type { + AcpModelSelection, + AcpSessionModels, + AcpWorkspaceToolCallEndpoint, + AgentAcpStreamOpenParams, + AgentAcpFrameData, + AgentAcpStreamClosedData, + AgentAcpTransferCommitResult, + AgentAcpTransferReadResult, + AcpSessionArchivedData, +} from '@dsh-remote/protocol' +import { + AGENT_ACP_TRANSFER_CHUNK_BYTES, + MAX_AGENT_ACP_TRANSFER_BYTES, +} from '@dsh-remote/protocol' +import type { RemoteClientCore } from './index.js' +import { createRemoteId, RemoteGatewayError } from './remote-gateway.js' + +export type AcpAgentBackend = 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes' | (string & {}) + +/** + * `session/prompt` blocks until the upstream turn finishes. Keep this well above + * the default RemoteClientCore timeout (Android uses ~35s for ApiProxy). + */ +export const ACP_PROMPT_RPC_TIMEOUT_MS = 10 * 60_000 + +export interface AcpRemoteSession { + sessionId: string + cwd?: string + mode?: 'agent' | 'plan' | 'ask' +} + +export interface AcpStream { + streamId: string + close(): Promise +} + +/** Shared Web/Android client for the generic Agent ACP domain in Remote. */ +export class AgentAcpClient { + constructor(private readonly core: RemoteClientCore, private readonly capabilities: readonly string[] = []) {} + + supportsArchive(backend: string): boolean { + return backend === 'opencode' && this.capabilities.includes('agent.acp.opencode.archive.v1') + } + + onSessionArchived(handler: (data: AcpSessionArchivedData) => void): () => void { + return this.core.onEvent(event => { + if (event.event === 'agent.acp.catalog.changed' && isRecord(event.data) && event.data.backend === 'opencode' + && event.data.archived === true && typeof event.data.sessionId === 'string' && /^[A-Za-z0-9_-]{1,256}$/.test(event.data.sessionId)) handler(event.data as unknown as AcpSessionArchivedData) + }) + } + + async archiveSession(sessionId: string, backend: string, signal?: AbortSignal): Promise { + if (!this.supportsArchive(backend)) throw new RemoteGatewayError('OPENCODE_ARCHIVE_UNAVAILABLE', 'Update the Host plugin to support OpenCode native archiving.') + const result = await this.call('dsh/sessionArchive', { sessionId, backend }, signal) + if (!isRecord(result) || result.backend !== backend || result.sessionId !== sessionId || result.archived !== true) throw new RemoteGatewayError('INVALID_RESPONSE', 'OpenCode did not confirm the session archive state.') + return result as unknown as AcpSessionArchivedData + } + + async call(method: string, params: unknown = {}, signal?: AbortSignal): Promise { + const timeoutMs = method === 'session/prompt' ? ACP_PROMPT_RPC_TIMEOUT_MS : undefined + return this.core.rpc('agent.acp.call', { method, params }, signal, timeoutMs) + } + + async initialize( + params: { protocolVersion?: number; clientInfo?: { name?: string; version?: string } } = {}, + signal?: AbortSignal, + ): Promise { + return this.call('initialize', params, signal) + } + + async respond( + requestHandle: string, + decision: 'allow-once' | 'reject-once' | 'cancel', + result?: unknown, + signal?: AbortSignal, + ): Promise { + return this.core.rpc('agent.acp.respond', { + requestHandle, + decision, + ...(result === undefined ? {} : { result }), + }, signal) + } + + async sessionModels(sessionId: string, backend: 'cursor' | 'claude' | 'antigravity' | 'pi' | 'opencode' | 'hermes', signal?: AbortSignal): Promise { + return this.call('dsh/sessionModels', { sessionId, backend }, signal) as Promise + } + + async selectModel(sessionId: string, backend: 'cursor' | 'claude' | 'antigravity' | 'pi' | 'opencode' | 'hermes', selection: AcpModelSelection, signal?: AbortSignal): Promise { + if (selection.provider !== backend) throw new RemoteGatewayError('INVALID_MESSAGE', 'The model provider does not match the ACP backend.') + if (backend === 'antigravity' && !this.capabilities.includes('agent.acp.antigravity.model-load.v1')) { + await this.call('session/load', { sessionId, backend }, signal) + } + const result = await this.call('dsh/selectModel', { sessionId, backend, model: selection.model, + ...(selection.reasoningEffort === undefined ? {} : { reasoningEffort: selection.reasoningEffort }) }, signal) + if (!isRecord(result) || !isRecord(result.selected) || result.selected.provider !== backend || typeof result.selected.model !== 'string') { + throw new RemoteGatewayError('INVALID_RESPONSE', 'ACP did not confirm the selected model.') + } + return result.selected as unknown as AcpModelSelection + } + + async selectPermission(sessionId: string, backend: 'cursor' | 'claude' | 'antigravity' | 'pi' | 'opencode' | 'hermes', preset: string, signal?: AbortSignal): Promise { + return this.call('dsh/selectPermission', { sessionId, backend, preset }, signal) + } + + async workspaceToolCall(sessionId: string, backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes', endpoint: AcpWorkspaceToolCallEndpoint, args: Record, signal?: AbortSignal): Promise { + return this.call('dsh/toolCall', { sessionId, backend, endpoint, args }, signal) + } + + async listWorkspaces( + backend?: AcpAgentBackend, + signal?: AbortSignal, + ): Promise> { + const result = await this.call('dsh/workspaceList', { + ...(backend === undefined ? {} : { backend }), + }, signal).catch(error => { + if (backend === 'pi' || backend === 'claude' || backend === 'hermes') throw error + return [] + }) + if ((backend === 'pi' || backend === 'claude' || backend === 'hermes') && !Array.isArray(result)) { + throw new RemoteGatewayError('INVALID_RESPONSE', 'ACP workspace catalog is invalid.') + } + return Array.isArray(result) ? result as Array<{ path: string; title?: string; sessionCount?: number }> : [] + } + + async listSessions( + path: string, + backend?: AcpAgentBackend, + limit?: number, + signal?: AbortSignal, + ): Promise> { + const result = await this.call('dsh/sessionList', { + path, + ...(backend === undefined ? {} : { backend }), + ...(limit === undefined ? {} : { limit }), + }, signal).catch(error => { + if (backend === 'pi' || backend === 'claude' || backend === 'hermes') throw error + return { items: [] } + }) + if ((backend === 'pi' || backend === 'claude' || backend === 'hermes') && (!isRecord(result) || !Array.isArray(result.items))) { + throw new RemoteGatewayError('INVALID_RESPONSE', 'ACP session catalog is invalid.') + } + return isRecord(result) && Array.isArray(result.items) ? result.items as Array<{ + conversationId: string + title: string + createdAt: number + updatedAt: number + }> : [] + } + + async loadSessionHistory( + sessionId: string, + backend?: AcpAgentBackend, + signal?: AbortSignal, + ): Promise { + const result = await this.transferCall('dsh/sessionHistory', { + sessionId, + ...(backend === undefined ? {} : { backend }), + }, signal).catch(error => { + if (backend === 'pi' || backend === 'claude' || backend === 'opencode' || backend === 'hermes') throw error + return { events: [] } + }) + if ((backend === 'pi' || backend === 'claude' || backend === 'opencode' || backend === 'hermes') && (!isRecord(result) || !Array.isArray(result.events))) { + throw new RemoteGatewayError('INVALID_RESPONSE', 'ACP session history is invalid.') + } + return isRecord(result) && Array.isArray(result.events) ? result.events : [] + } + + async createSession( + cwd: string, + mode?: 'agent' | 'plan' | 'ask', + backend?: AcpAgentBackend, + signal?: AbortSignal, + ): Promise { + const result = await this.call('session/new', { + cwd, + mcpServers: [], + ...(mode === undefined ? {} : { mode }), + ...(backend === undefined ? {} : { backend }), + }, signal) + const sessionId = readString(result, 'sessionId') + if (sessionId === undefined) throw new RemoteGatewayError('INVALID_RESPONSE', 'ACP session/new did not return sessionId.') + return { + sessionId, + cwd, + ...(mode === undefined ? {} : { mode }), + } + } + + async prompt(sessionId: string, text: string, signal?: AbortSignal, images: Array<{ type: 'image'; mimeType: string; data: string }> = [], backend?: AcpAgentBackend): Promise { + const params = { sessionId, ...(backend === undefined ? {} : { backend }), prompt: [...(text.length > 0 ? [{ type: 'text', text }] : []), ...images] } + return images.length > 0 ? this.transferCall('session/prompt', params, signal) : this.call('session/prompt', params, signal) + } + + async cancel(sessionId: string, signal?: AbortSignal): Promise { + return this.call('session/cancel', { sessionId }, signal) + } + + async listDirectory(path: string, signal?: AbortSignal): Promise { + return this.call('dsh/directoryList', { path }, signal) + } + + async openStream( + sessionId: string, + onFrame: (frame: AgentAcpFrameData) => void, + onClosed?: (closed: AgentAcpStreamClosedData) => void, + signal?: AbortSignal, + tool?: AgentAcpStreamOpenParams['tool'], + ): Promise { + const streamId = createRemoteId() + const unsubscribe = this.core.onEvent(event => { + if (event.event === 'agent.acp.frame' && isRecord(event.data)) { + const data = event.data as unknown as AgentAcpFrameData + if (tool ? data.streamId !== streamId : !frameMatchesSubscription(data, streamId, sessionId)) return + onFrame(data) + } + if (event.event === 'agent.acp.stream.closed' && isRecord(event.data) && event.data.streamId === streamId) { + onClosed?.(event.data as unknown as AgentAcpStreamClosedData) + } + }) + try { + await this.core.rpc('agent.acp.stream.open', { streamId, sessionId, ...(tool ? { tool } : {}) }, signal) + if (signal?.aborted) { unsubscribe(); await this.core.rpc('agent.acp.stream.close', { streamId }).catch(() => undefined); throw signal.reason } + } catch (error) { + unsubscribe() + throw error + } + return { + streamId, + close: async () => { + unsubscribe() + await this.core.rpc('agent.acp.stream.close', { streamId }).catch(() => undefined) + }, + } + } + + async transferCall(method: string, params: unknown, signal?: AbortSignal): Promise { + const requestBytes = new TextEncoder().encode(JSON.stringify({ method, params })) + if (requestBytes.byteLength > MAX_AGENT_ACP_TRANSFER_BYTES) { + throw new RemoteGatewayError('REQUEST_TOO_LARGE', 'The ACP transfer request exceeds the bounded limit.') + } + const transferId = createRemoteId() + const totalChunks = Math.ceil(requestBytes.byteLength / AGENT_ACP_TRANSFER_CHUNK_BYTES) + try { + await this.core.rpc('agent.acp.transfer.open', { + transferId, + totalBytes: requestBytes.byteLength, + totalChunks, + }, signal) + for (let index = 0; index < totalChunks; index += 1) { + const start = index * AGENT_ACP_TRANSFER_CHUNK_BYTES + const end = Math.min(start + AGENT_ACP_TRANSFER_CHUNK_BYTES, requestBytes.byteLength) + await this.core.rpc('agent.acp.transfer.chunk', { + transferId, + index, + data: bytesToCanonicalBase64(requestBytes.subarray(start, end)), + }, signal) + } + const commit = await this.core.rpc('agent.acp.transfer.commit', { transferId }, signal, + method === 'session/prompt' ? ACP_PROMPT_RPC_TIMEOUT_MS : undefined) as AgentAcpTransferCommitResult + if (commit.kind === 'inline') return commit.response + if (commit.kind !== 'chunked' || commit.transferId !== transferId || !Number.isSafeInteger(commit.totalBytes) || commit.totalBytes < 1 || commit.totalBytes > MAX_AGENT_ACP_TRANSFER_BYTES + || commit.totalChunks !== Math.ceil(commit.totalBytes / AGENT_ACP_TRANSFER_CHUNK_BYTES)) throw new RemoteGatewayError('INVALID_RESPONSE', 'Invalid ACP transfer descriptor.') + const chunks: Uint8Array[] = [] + for (let index = 0; index < commit.totalChunks; index += 1) { + const part = await this.core.rpc('agent.acp.transfer.read', { transferId, index }, signal) as AgentAcpTransferReadResult + if (part.transferId !== transferId || part.index !== index || typeof part.data !== 'string' || part.data.length > Math.ceil(AGENT_ACP_TRANSFER_CHUNK_BYTES / 3) * 4) throw new RemoteGatewayError('INVALID_RESPONSE', 'Invalid ACP transfer chunk.') + const chunk = canonicalBase64ToBytes(part.data) + const expected = Math.min(AGENT_ACP_TRANSFER_CHUNK_BYTES, commit.totalBytes - index * AGENT_ACP_TRANSFER_CHUNK_BYTES) + if (chunk.length !== expected || bytesToCanonicalBase64(chunk) !== part.data) throw new RemoteGatewayError('INVALID_RESPONSE', 'Invalid ACP transfer chunk size or encoding.') + chunks.push(chunk) + } + const bytes = concat(chunks, commit.totalBytes) + return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as unknown + } finally { + await this.core.rpc('agent.acp.transfer.close', { transferId }).catch(() => undefined) + } + } +} + +function readString(value: unknown, key: string): string | undefined { + return isRecord(value) && typeof value[key] === 'string' ? value[key] : undefined +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** Match Host frames by explicit stream id or by ACP session id (fallback delivery). */ +function frameMatchesSubscription( + data: AgentAcpFrameData, + streamId: string, + sessionId: string, +): boolean { + if (data.streamId === streamId) return true + if (data.streamId === sessionScopedStreamId(sessionId)) return true + const params = isRecord(data.frame.params) ? data.frame.params : undefined + if (params === undefined) return false + if (params.sessionId === sessionId) return true + return isRecord(params.update) && params.update.sessionId === sessionId +} + +export function sessionScopedStreamId(sessionId: string): string { + return `session:${sessionId}` +} + +function concat(chunks: readonly Uint8Array[], totalBytes: number): Uint8Array { + const output = new Uint8Array(totalBytes) + let offset = 0 + for (const chunk of chunks) { + output.set(chunk, offset) + offset += chunk.byteLength + } + return output +} + +function bytesToCanonicalBase64(bytes: Uint8Array): string { + let binary = '' + for (const value of bytes) binary += String.fromCharCode(value) + return btoa(binary) +} + +function canonicalBase64ToBytes(value: string): Uint8Array { + const binary = atob(value) + const bytes = new Uint8Array(binary.length) + for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index) + return bytes +}