From ffede49e2aab40e32faf354db58ba52953841d27 Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 14:17:28 +0800 Subject: [PATCH] Import apps/android/src/services/connection.ts --- apps/android/src/services/connection.ts | 462 ++++++++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 apps/android/src/services/connection.ts diff --git a/apps/android/src/services/connection.ts b/apps/android/src/services/connection.ts new file mode 100644 index 0000000..783de9e --- /dev/null +++ b/apps/android/src/services/connection.ts @@ -0,0 +1,462 @@ +import { AgentAcpClient, CodexRemoteClient, HarnessAlphaClient, RemoteClientCore, RemoteTypertGateway, probeRemoteHostFeatures, remoteWorkspaceTypeAvailable, type RemoteHostFeatures } from '@dsh-remote/client-core' +import { classifyControlClose } from '@dsh-remote/protocol' +import { AdaptiveTransport, type AdaptiveConnectionDetails, type RtcIceServer } from '@dsh-remote/webrtc' +import { websocketUrl } from '../lib/server-url' +import { connectionFailure, connectionLog } from './connection-log' +import { strings } from '../locales/i18n' +import type { DeviceIdentity, MuxStreamFrame, RemoteDevice } from '../types' +import { AcpSessionTools, HarnessSessionTools, type SessionTools } from './session-tools' +import { SecureTransport } from './secure-transport' +import { BotRemoteClient } from './bot-catalog' + +export type MuxFrameHandler = (frame: MuxStreamFrame) => void +export type CloseHandler = (options?: { retryable: boolean; lastTransport?: 'lan' | 'p2p' | 'turn' | 'relay' }) => void +type RemoteHarnessClient = HarnessAlphaClient + +export interface AndroidConnectionOptions { + onOpencodeArchived?: (sessionId: string) => void + preferredTransports?: Array<'lan' | 'p2p' | 'turn' | 'relay'> + forceRelay?: boolean + refreshAccessToken?: () => Promise + fetchIceServers?: (connectionId: string) => Promise + onSecureHandshake?: () => void + onWebRtcFallback?: () => void + onClose?: CloseHandler +} + +export class AndroidRemoteConnection { + private compactHistorySupported = false + private pluginRouteSupported = false + private core?: RemoteClientCore + private proxy?: RemoteHarnessClient + private codex?: CodexRemoteClient + private cursor?: AgentAcpClient + private acpBackends = new Set() + private codexAvailable = false + private sessionTools?: HarnessSessionTools + private closeMux?: (notifyRemote?: boolean) => Promise + private unsubscribeClose?: () => void + private unsubscribeArchived?: () => void + private muxHandler?: MuxFrameHandler + private transport?: AdaptiveTransport + private connectionAttempt = 0 + private healthTimer?: ReturnType + private healthFlight?: { core: RemoteClientCore; result: Promise } + /** Consecutive failed health probes for the active core; reset per carrier and on success. */ + private healthCheckFailures = 0 + + async configureHistory(compact: boolean): Promise { + if (this.core !== undefined && this.compactHistorySupported) { + await this.core.rpc('remote.history.configure', { compact }) + } + } + + async connect( + baseUrl: string, + identity: DeviceIdentity, + host: RemoteDevice, + accessToken: string, + onFrame: MuxFrameHandler, + options: AndroidConnectionOptions = {}, + ): Promise { + // Replacing a connection must not wait for a graceful stream-close RPC: + // the old data path may be exactly what is being recovered from. + const attempt = ++this.connectionAttempt + connectionLog('connect', { attempt, phase: 'starting', forceRelay: options.forceRelay === true }) + await this.clearConnection() + if (attempt !== this.connectionAttempt) throw new Error('The connection attempt was superseded.') + this.muxHandler = onFrame + let webRtcFallback = false + let retryableClose = true + let lastTransport: 'lan' | 'p2p' | 'turn' | 'relay' | undefined + const createTransport = (relayOnly: boolean) => new AdaptiveTransport(websocketUrl(baseUrl), { + role: 'client', + deviceId: identity.deviceId, + accessToken, + refreshAccessToken: options.refreshAccessToken, + targetDeviceId: host.deviceId, + forceRelay: options.forceRelay || relayOnly, + preferredTransports: options.forceRelay || relayOnly + ? ['relay'] + : options.preferredTransports ?? ['lan', 'p2p', 'turn', 'relay'], + // TURN-only attempts may need extra time for relay allocation and TCP + // fallback. Keep automatic hole punching on its shorter mobile budget. + negotiateTimeoutMs: !options.forceRelay && !relayOnly + && options.preferredTransports?.includes('turn') + && !options.preferredTransports.some(transport => transport === 'lan' || transport === 'p2p') + ? 12_000 + : 6_000, + iceServersTimeoutMs: 5_000, + fetchIceServers: options.fetchIceServers, + onDisconnect: event => { + // Refused/replaced credentials, protocol errors and malformed frames + // need manual recovery; do not automatically compete for ownership. + const retryableControlClose = event.closeCode !== undefined + && classifyControlClose(event.closeCode, event.closeReason).retryable + retryableClose = event.reason !== 'invalid-control-frame' + && !(event.closeCode !== undefined && !retryableControlClose && (event.closeCode >= 4000 + || [1002, 1003, 1007, 1008, 1009].includes(event.closeCode))) + if (event.transport !== undefined) lastTransport = event.transport + connectionLog('disconnect', { reason: event.reason, closeCode: event.closeCode, transport: event.transport }) + }, + onWebRtcFallback: (error, diagnostics) => { + webRtcFallback = true + options.onWebRtcFallback?.() + // Do not include credentials, SDP, prompts, or tunnel payloads. + connectionLog('fallback', { reason: connectionFailure(error), + connectionState: diagnostics?.connectionState, + iceConnectionState: diagnostics?.iceConnectionState, + localCandidates: diagnostics?.localCandidates.byType, + remoteCandidates: diagnostics?.remoteCandidates.byType, + }) + }, + onWebRtcDiagnostic: event => { + if (event.type !== 'selected-path') return + // Selected-path telemetry contains candidate types and address scopes, + // never the candidate IPs, SDP, credentials, or tunnel payloads. + connectionLog('selected-path', { transport: event.selectedPath.mode, protocol: event.selectedPath.protocol, localCandidateType: event.selectedPath.localCandidateType, remoteCandidateType: event.selectedPath.remoteCandidateType, localCandidates: event.diagnostics.localCandidates.byType, + remoteCandidates: event.diagnostics.remoteCandidates.byType }) + }, + }) + const connectCore = async (relayOnly: boolean) => { + const transport = createTransport(relayOnly) + this.transport = transport + // Host-side Typert calls are capped at 30s. Leave a small delivery + // margin, then treat silence as an unhealthy business channel. + const core = new RemoteClientCore( + new SecureTransport(transport, identity, host, options.onSecureHandshake), + 35_000, + ) + this.core = core + // A fresh carrier has no health history: a failure counted on the + // previous connection must not retire this one after a single probe. + this.healthCheckFailures = 0 + this.unsubscribeClose = core.onClose(() => { + // A late close from a replaced connection must not tear down the new + // connection that may already be stored on this instance. + if (this.core !== core) return + this.clearHealthTimer() + void this.closeMux?.(false) + this.closeMux = undefined + this.core = undefined + this.proxy = undefined + this.codex = undefined + this.codexAvailable = false + this.cursor = undefined + this.acpBackends.clear() + this.sessionTools = undefined + options.onClose?.({ retryable: retryableClose, ...(lastTransport !== undefined ? { lastTransport } : {}) }) + }) + await core.connect() + if (attempt !== this.connectionAttempt || this.core !== core) throw new Error('The connection attempt was superseded.') + return core + } + try { + // A WebRTC fallback continues on the same connection id: the Host keeps + // the tunnel alive and switches its data plane to Relay. Rebuilding a + // second relay-only connection doubled every fallback into two full + // handshakes and added 10s+ to mobile connections. + const core = await connectCore(false) + const features = await probeRemoteHostFeatures(core, host.clientVersion) + if (attempt !== this.connectionAttempt || this.core !== core) throw new Error('The connection attempt was superseded.') + const emitFrame = (frame: MuxStreamFrame) => { + if (this.core !== core) return + if (frame.payload.type === 'stream/closed' && frame.payload.reason === 'failed') { + connectionLog('stream-failed') + // A live carrier failure is an offline channel, even if its socket + // still answers. Reconnect will create a fresh follow subscription. + void this.close() + options.onClose?.() + return + } + this.muxHandler?.(frame) + } + this.compactHistorySupported = features.capabilities.includes('remote.history.compact.v1') + this.applyBackendFeatures(core, features) + this.unsubscribeArchived = this.cursor?.onSessionArchived(data => { + if (this.core === core) options.onOpencodeArchived?.(data.sessionId) + }) + if (features.remoteGateway) { + this.sessionTools = new HarnessSessionTools(new RemoteTypertGateway(core)) + const alpha = new HarnessAlphaClient( + core, + { + clientVersion: host.clientVersion, + harnessVersion: host.harnessVersion, + ...(features.sessionFormat === undefined ? {} : { sessionFormat: features.sessionFormat }), + }, + frame => emitFrame(frame as unknown as MuxStreamFrame), + ) + alpha.start() + this.proxy = alpha + this.closeMux = async (notifyRemote = true) => { await alpha.close(notifyRemote) } + } else { + throw new Error('The remote Host exposes no supported Harness transport.') + } + this.scheduleHealthCheck(core) + connectionLog('connect', { attempt, phase: 'ready' }) + } catch (error) { + connectionLog('connect', { attempt, phase: 'failed', reason: connectionFailure(error) }) + if (attempt === this.connectionAttempt) await this.clearConnection() + throw error + } + } + + /** Reprobe readiness on workspace refresh so Host backend switches need no reconnect. */ + async refreshBackends(): Promise { + if (this.core === undefined) throw new Error(strings.runtime.connectHostFirst) + const core = this.core + const features = await probeRemoteHostFeatures(core) + if (this.core !== core) return + this.applyBackendFeatures(core, features) + } + + private applyBackendFeatures(core: RemoteClientCore, features: RemoteHostFeatures): void { + this.pluginRouteSupported = features.pluginRoute + this.codexAvailable = features.capabilities.includes('codex.appserver.transfer.v1') + && remoteWorkspaceTypeAvailable(features.capabilities, features.workspaceTypes, 'codex', 'codex.appserver.v1') + if (this.codexAvailable) this.codex ??= new CodexRemoteClient(core, true) + this.acpBackends.clear() + for (const backend of ['cursor', 'antigravity', 'pi', 'opencode', 'claude', 'hermes'] as const) { + if (remoteWorkspaceTypeAvailable(features.capabilities, features.workspaceTypes, backend, `agent.acp.${backend}.v1`)) { + this.acpBackends.add(backend) + } + } + if (this.acpBackends.size > 0) this.cursor ??= new AgentAcpClient(core, features.capabilities) + } + + /** Harness business client; only available while connected. */ + requireProxy(): RemoteHarnessClient { + if (this.proxy === undefined) throw new Error(strings.runtime.connectHostFirst) + return this.proxy + } + + /** + * Read an existing session attachment through its native carrier; never accept + * a filesystem path. 0.2.2 Hosts require the full image reference (id, media + * type, byte length and dimensions are verified), while older Hosts only know + * the durable id. Always carry that id: a 0.2.2 Host can recover the verified + * reference from session events even when only partial fields are available. + */ + async readSessionImageAttachment( + sessionId: string, + attachment: Record, + signal: AbortSignal, + ): Promise { + const core = this.core + const proxy = this.requireProxy() + if (core === undefined) throw new Error(strings.runtime.connectHostFirst) + const attachmentId = typeof attachment.attachmentId === 'string' ? attachment.attachmentId : undefined + if (attachmentId === undefined) throw new Error(strings.common.unavailable) + const fullReference = typeof attachment.mediaType === 'string' && typeof attachment.bytes === 'number' + && typeof attachment.width === 'number' && typeof attachment.height === 'number' + const request: Record = { sessionId, attachmentId } + if (fullReference) request.attachment = attachment + const value = await new RemoteTypertGateway(core).call('session/attachment', { + args: { request }, + }, signal, { maxResponseBytes: 12 * 1024 * 1024 }) + if (this.core !== core || this.proxy !== proxy || signal.aborted) throw new Error(strings.runtime.connectHostFirst) + // Typert versions may preserve the official business Result inside the carrier result. + if (typeof value === 'object' && value !== null && 'ok' in value) { + if (value.ok === true && 'value' in value) return value.value + throw new Error(strings.common.unavailable) + } + return value + } + + requireBotClient(): BotRemoteClient { + const core = this.core + const proxy = this.proxy + if (core === undefined || proxy === undefined) throw new Error(strings.runtime.connectHostFirst) + if (!this.pluginRouteSupported) throw new Error(strings.bots.unsupported) + const current = () => { + if (this.core !== core || this.proxy !== proxy) throw new Error(strings.runtime.connectHostFirst) + if (!this.pluginRouteSupported) throw new Error(strings.bots.unsupported) + } + return new BotRemoteClient( + (body, signal) => { current(); return core.rpc('plugin.route.call', { route: 'api/bot', body }, signal) }, + () => { current(); return proxy.sessionList() }, + current, + ) + } + + async rpc(method: string, params: unknown, signal?: AbortSignal): Promise { + if (this.core === undefined) throw new Error(strings.runtime.connectHostFirst) + return this.core.rpc(method, params, signal) + } + + /** Optional CodeX business client; available only when the Host advertises both domain capabilities. */ + requireCodex(): CodexRemoteClient { + if (this.codex === undefined || !this.codexAvailable) throw new Error(strings.runtime.codexUnavailable) + return this.codex + } + + requireSessionTools(sessionId?: string): SessionTools { + if (sessionId?.startsWith('cursor:') && this.cursor !== undefined) return new AcpSessionTools(this.cursor, 'cursor') + if (sessionId?.startsWith('pi:')) return new AcpSessionTools(this.requirePi(), 'pi') + if (sessionId?.startsWith('antigravity:') && this.cursor !== undefined) return new AcpSessionTools(this.cursor, 'antigravity') + if (sessionId?.startsWith('claude:')) return new AcpSessionTools(this.requireClaude(), 'claude') + if (sessionId?.startsWith('hermes:')) return new AcpSessionTools(this.requireHermes(), 'hermes') + if (sessionId?.startsWith('opencode:') && this.cursor !== undefined) return new AcpSessionTools(this.cursor, 'opencode') + if (this.sessionTools === undefined) throw Object.assign(new Error('Native session tools require a compatible Host.'), { code: 'FEATURE_NOT_SUPPORTED' }) + return this.sessionTools + } + + hasCodex(): boolean { + return this.codex !== undefined && this.codexAvailable + } + + /** Optional Agent ACP client (Cursor UI backend); available when the Host advertises agent.acp.cursor.v1. */ + requireCursor(): AgentAcpClient { + if (this.cursor === undefined || !this.acpBackends.has('cursor')) throw new Error(strings.runtime.cursorUnavailable) + return this.cursor + } + + hasCursor(): boolean { + return this.cursor !== undefined && this.acpBackends.has('cursor') + } + + /** Optional Agent ACP client (Antigravity UI backend); available when the Host advertises agent.acp.antigravity.v1. */ + requireAntigravity(): AgentAcpClient { + if (this.cursor === undefined || !this.acpBackends.has('antigravity')) throw new Error(strings.runtime.antigravityUnavailable) + return this.cursor + } + + hasAntigravity(): boolean { + return this.cursor !== undefined && this.acpBackends.has('antigravity') + } + + requirePi(): AgentAcpClient { + if (this.cursor === undefined || !this.acpBackends.has('pi')) throw new Error(strings.runtime.piUnavailable) + return this.cursor + } + + hasPi(): boolean { + return this.cursor !== undefined && this.acpBackends.has('pi') + } + + /** Optional Agent ACP client (OpenCode UI backend); available when the Host advertises agent.acp.opencode.v1. */ + requireOpencode(): AgentAcpClient { + if (this.cursor === undefined || !this.acpBackends.has('opencode')) throw new Error(strings.runtime.opencodeUnavailable) + return this.cursor + } + + hasOpencode(): boolean { + return this.cursor !== undefined && this.acpBackends.has('opencode') + } + + requireClaude(): AgentAcpClient { + if (this.cursor === undefined || !this.acpBackends.has('claude')) throw new Error(strings.runtime.claudeUnavailable) + return this.cursor + } + + hasClaude(): boolean { + return this.cursor !== undefined && this.acpBackends.has('claude') + } + + /** Optional Agent ACP client (Hermes Agent UI backend); available when the Host advertises agent.acp.hermes.v1. */ + requireHermes(): AgentAcpClient { + if (this.cursor === undefined || !this.acpBackends.has('hermes')) throw new Error(strings.runtime.hermesUnavailable) + return this.cursor + } + + hasHermes(): boolean { + return this.cursor !== undefined && this.acpBackends.has('hermes') + } + + getStats() { + return this.core?.getStats() + } + + /** A locally open socket can be half-open after Android suspends networking. */ + checkHealth(): Promise { + const core = this.core + if (core === undefined || !core.getStats().connected) return Promise.resolve(false) + if (this.healthFlight?.core === core) return this.healthFlight.result + const result = this.probeHealth(core) + this.healthFlight = { core, result } + void result.finally(() => { + if (this.healthFlight?.result === result) this.healthFlight = undefined + }) + return result + } + + private async probeHealth(core: RemoteClientCore): Promise { + try { + // Existing authenticated, encrypted capability RPC; no new wire heartbeat. + await core.rpc('harness.transport.describe', {}, undefined, { timeoutMs: 5_000 }) + return this.core === core + } catch { + return false + } + } + + private scheduleHealthCheck(core: RemoteClientCore, delayMs = 25_000): void { + this.clearHealthTimer() + this.healthTimer = setTimeout(() => { + this.healthTimer = undefined + if (this.core !== core) return + void this.checkHealth().then(healthy => { + if (this.core !== core) return + if (healthy) { + this.healthCheckFailures = 0 + this.scheduleHealthCheck(core) + return + } + // A single slow probe (congested relay, brief radio gap) must not kill + // a carrier that still delivers: every forced close sends the user + // through a full reconnect + session history catch-up before live + // streaming resumes. Confirm with one fast retry first. + this.healthCheckFailures += 1 + if (this.healthCheckFailures >= 2) { + connectionLog('health-failed', { phase: 'closed' }) + // close() on the core publishes the same offline/recovery transition + // as a socket close, including when the OS never delivered onclose. + void core.close().catch(() => undefined) + } else { + connectionLog('health-failed', { phase: 'checking' }) + this.scheduleHealthCheck(core, 5_000) + } + }) + }, delayMs) + } + + private clearHealthTimer(): void { + if (this.healthTimer !== undefined) clearTimeout(this.healthTimer) + this.healthTimer = undefined + } + + async getNetworkDetails(): Promise { + return await this.transport?.connectionDetails() + } + + async close(): Promise { + ++this.connectionAttempt + await this.clearConnection() + } + + private async clearConnection(): Promise { + this.clearHealthTimer() + this.muxHandler = undefined + const mux = this.closeMux + this.closeMux = undefined + const core = this.core + this.core = undefined + // Closing the whole transport makes a remote stream-close redundant. + // Only remove the local subscription here so a half-open RTC path cannot + // add another RPC timeout before recovery begins. + this.unsubscribeClose?.() + this.unsubscribeClose = undefined + this.unsubscribeArchived?.() + this.unsubscribeArchived = undefined + this.transport = undefined + this.proxy = undefined + this.codex = undefined + this.codexAvailable = false + this.cursor = undefined + this.acpBackends.clear() + this.sessionTools = undefined + if (mux !== undefined) await mux(false).catch(() => undefined) + if (core !== undefined) await core.close() + } +}