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 }