UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

800 lines (748 loc) • 33.9 kB
import { randomUUID } from "node:crypto"; import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs"; import { dirname, join } from "node:path"; import { atomicWriteFile } from "../config/atomic-write"; import { getConfigDir } from "../config/paths"; import { workspaceSecretFileExists, workspaceSecretPermissions, type WorkspaceSecretPermissions } from "./workspace-secret-store"; import { RemoteWorkspaceCoordinator, type RemoteWorkspaceTransport } from "./workspace-coordinator"; import type { RemoteWorkspaceHub } from "./workspace-hub"; import { isRemoteWorkspaceAgentProfile, type RemoteWorkspaceAgentProfile } from "./workspace-agent-protocol"; import type { RemoteWorkspaceExecutionRequest } from "./workspace-executor"; import { runRemoteWorkspaceCleanupSteps } from "./workspace-process"; import { truncateRemoteWorkspaceUtf8 } from "./workspace-utf8"; import { REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE } from "./protocol"; import { parseRemoteWorkspaceCapabilities, remoteWorkspaceToolsForCapabilities, type RemoteWorkspaceCapability, type RemoteWorkspaceToolName, type RemoteWorkspaceToolResult, } from "./workspace-tools"; export const REMOTE_WORKSPACE_SESSION_STATE_VERSION = 1 as const; export type RemoteWorkspaceSessionStatus = | "starting" | "ready" | "running" | "waiting_for_executor" | "failed" | "stopped"; export type RemoteWorkspaceAccessMode = "read-only" | "workspace"; export interface RemoteWorkspaceSessionEvent { sequence: number; at: string; type: "status" | "assistant" | "tool" | "error"; text: string; } export interface RemoteWorkspaceSessionSummary { id: string; profile: RemoteWorkspaceAgentProfile; accessMode: RemoteWorkspaceAccessMode; deviceId: string; deviceName: string; rootId: string; rootLabel: string; capabilities: RemoteWorkspaceCapability[]; tools: RemoteWorkspaceToolName[]; threadId: string | null; /** True only after the runtime has created durable history that can be resumed. */ resumable: boolean; status: RemoteWorkspaceSessionStatus; createdAt: string; updatedAt: string; events: RemoteWorkspaceSessionEvent[]; } export interface RemoteWorkspaceRuntimeHandle { threadId: string; canResume?(): boolean; prompt(text: string): Promise<void>; stop(): Promise<void>; } export interface RemoteWorkspaceRuntimeFactory { profile: RemoteWorkspaceAgentProfile; available(): Promise<{ available: boolean; version?: string; reason?: string }>; start(options: { sessionId: string; deviceId: string; deviceName: string; rootId: string; rootLabel: string; capabilities: RemoteWorkspaceCapability[]; tools: RemoteWorkspaceToolName[]; resumeThreadId?: string; coordinator: RemoteWorkspaceCoordinator; emit(type: RemoteWorkspaceSessionEvent["type"], text: string): void; }): Promise<RemoteWorkspaceRuntimeHandle>; } export interface RemoteWorkspaceSessionState { version: typeof REMOTE_WORKSPACE_SESSION_STATE_VERSION; sessions: RemoteWorkspaceSessionSummary[]; } export interface RemoteWorkspaceSessionStateStore { load(): RemoteWorkspaceSessionState | null; save(state: RemoteWorkspaceSessionState): void; } interface LiveSession extends RemoteWorkspaceSessionSummary { handle: RemoteWorkspaceRuntimeHandle | null; unregister: (() => void) | null; closeTransport: (() => Promise<void>) | null; operation: Promise<void>; stopOperation: Promise<boolean> | null; remoteTransport: SwitchableRemoteWorkspaceTransport | null; turnActive: boolean; } const MAX_EVENTS_PER_SESSION = 100; const MAX_EVENT_TEXT_BYTES = 8 * 1024; const MAX_PROMPT_BYTES = 256 * 1024; const MAX_LIVE_SESSIONS = 8; const MAX_RETAINED_SESSIONS = 64; const MAX_LIST_EVENTS_PER_SESSION = 20; const MAX_PERSISTED_EVENTS_PER_SESSION = 40; const MAX_PERSISTED_EVENT_TEXT_BYTES = 4 * 1024; const MAX_SESSION_STATE_BYTES = 16 * 1024 * 1024; const AVAILABILITY_CACHE_MS = 30_000; type RuntimeAvailability = Record<RemoteWorkspaceAgentProfile, { available: boolean; version?: string; reason?: string }>; class SwitchableRemoteWorkspaceTransport implements RemoteWorkspaceTransport { constructor(private current: RemoteWorkspaceTransport) {} replace(next: RemoteWorkspaceTransport): void { this.current = next; } isOnline(deviceId: string): boolean { return this.current.isOnline(deviceId); } invoke(request: RemoteWorkspaceExecutionRequest): Promise<RemoteWorkspaceToolResult> { return this.current.invoke(request); } } function boundedPrompt(value: unknown): string { if (typeof value !== "string" || value.trim().length < 1 || Buffer.byteLength(value, "utf8") > MAX_PROMPT_BYTES) { throw new Error("remote workspace prompt must contain 1 to 262144 UTF-8 bytes"); } return value; } function boundedEventText(value: string): string { if (Buffer.byteLength(value, "utf8") <= MAX_EVENT_TEXT_BYTES) return value; const marker = "\n[truncated]"; return `${truncateRemoteWorkspaceUtf8(value, MAX_EVENT_TEXT_BYTES - Buffer.byteLength(marker, "utf8"))}${marker}`; } function boundedPersistedEventText(value: string): string { if (Buffer.byteLength(value, "utf8") <= MAX_PERSISTED_EVENT_TEXT_BYTES) return value; const marker = "\n[truncated for restart snapshot]"; const maximum = MAX_PERSISTED_EVENT_TEXT_BYTES - Buffer.byteLength(marker, "utf8"); return `${truncateRemoteWorkspaceUtf8(value, maximum)}${marker}`; } function boundedString(value: unknown, label: string, maximum = 256): string { if (typeof value !== "string" || value.length < 1 || value.length > maximum || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) { throw new Error(`invalid remote workspace ${label}`); } return value; } function timestamp(value: unknown): string { const result = boundedString(value, "timestamp", 64); if (!Number.isFinite(Date.parse(result))) throw new Error("invalid remote workspace timestamp"); return result; } function parseStatus(value: unknown): RemoteWorkspaceSessionStatus { if (value === "starting" || value === "ready" || value === "running" || value === "waiting_for_executor" || value === "failed" || value === "stopped") return value; throw new Error("invalid remote workspace session status"); } function parseAccessMode(value: unknown): RemoteWorkspaceAccessMode { if (value === undefined || value === "workspace") return "workspace"; if (value === "read-only") return value; throw new Error("invalid remote workspace access mode"); } function parseEvent(value: unknown): RemoteWorkspaceSessionEvent { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace session event"); const raw = value as Record<string, unknown>; if (typeof raw.sequence !== "number" || !Number.isSafeInteger(raw.sequence) || raw.sequence < 1) { throw new Error("invalid remote workspace event sequence"); } if (raw.type !== "status" && raw.type !== "assistant" && raw.type !== "tool" && raw.type !== "error") { throw new Error("invalid remote workspace event type"); } return { sequence: raw.sequence, at: timestamp(raw.at), type: raw.type, text: boundedString(raw.text, "event text", MAX_EVENT_TEXT_BYTES), }; } function parseSession(value: unknown): RemoteWorkspaceSessionSummary { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace session"); const raw = value as Record<string, unknown>; if (!isRemoteWorkspaceAgentProfile(raw.profile)) throw new Error("invalid remote workspace session profile"); const accessMode = parseAccessMode(raw.accessMode); const capabilities = parseRemoteWorkspaceCapabilities(raw.capabilities); if (accessMode === "read-only" && (capabilities.length !== 1 || capabilities[0] !== "workspace.read")) { throw new Error("read-only remote workspace state contains write capabilities"); } const tools = remoteWorkspaceToolsForCapabilities(capabilities); if (!Array.isArray(raw.events) || raw.events.length > MAX_EVENTS_PER_SESSION) { throw new Error("invalid remote workspace session events"); } if (raw.threadId !== null && typeof raw.threadId !== "string") throw new Error("invalid remote workspace thread ID"); const resumable = raw.resumable === undefined ? raw.threadId !== null : raw.resumable === true; if (raw.resumable !== undefined && typeof raw.resumable !== "boolean") { throw new Error("invalid remote workspace resumable state"); } if (resumable && raw.threadId === null) throw new Error("resumable remote workspace session has no thread ID"); return { id: boundedString(raw.id, "session ID"), profile: raw.profile, accessMode, deviceId: boundedString(raw.deviceId, "device ID"), deviceName: boundedString(raw.deviceName, "device name", 80), rootId: boundedString(raw.rootId, "root ID"), rootLabel: boundedString(raw.rootLabel, "root label", 80), capabilities, tools, threadId: raw.threadId === null ? null : boundedString(raw.threadId, "thread ID"), resumable, status: parseStatus(raw.status), createdAt: timestamp(raw.createdAt), updatedAt: timestamp(raw.updatedAt), events: raw.events.map(parseEvent), }; } export function parseRemoteWorkspaceSessionState(value: unknown): RemoteWorkspaceSessionState { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace session state"); const raw = value as Record<string, unknown>; if (raw.version !== REMOTE_WORKSPACE_SESSION_STATE_VERSION || !Array.isArray(raw.sessions)) { throw new Error("unsupported remote workspace session state"); } if (raw.sessions.length > MAX_RETAINED_SESSIONS) throw new Error("remote workspace retained session limit exceeded"); const ids = new Set<string>(); const sessions = raw.sessions.map(item => { const session = parseSession(item); if (ids.has(session.id)) throw new Error("duplicate remote workspace session ID"); ids.add(session.id); return session; }); return { version: REMOTE_WORKSPACE_SESSION_STATE_VERSION, sessions }; } export class RemoteWorkspaceSessionFileStore implements RemoteWorkspaceSessionStateStore { constructor( private readonly path = join(getConfigDir(), "remote-workspace-sessions.json"), private readonly permissions: WorkspaceSecretPermissions = workspaceSecretPermissions, ) {} load(): RemoteWorkspaceSessionState | null { if (!workspaceSecretFileExists(this.path)) return null; this.permissions.prepareDirectory(dirname(this.path)); this.permissions.hardenFile(this.path); const metadata = statSync(this.path); if (!metadata.isFile() || metadata.size > MAX_SESSION_STATE_BYTES) { throw new Error("remote workspace session state is too large"); } return parseRemoteWorkspaceSessionState(JSON.parse(readFileSync(this.path, "utf8"))); } save(state: RemoteWorkspaceSessionState): void { const parsed = parseRemoteWorkspaceSessionState(state); const body = `${JSON.stringify(parsed, null, 2)}\n`; if (Buffer.byteLength(body, "utf8") > MAX_SESSION_STATE_BYTES) { throw new Error("remote workspace session state is too large"); } this.permissions.prepareDirectory(dirname(this.path)); if (workspaceSecretFileExists(this.path)) this.permissions.hardenFile(this.path); atomicWriteFile(this.path, body); } } export class RemoteWorkspaceSessionService { private shuttingDown = false; private readonly pendingCreates = new Set<Promise<RemoteWorkspaceSessionSummary>>(); private startupCleanupFailure: Error | null = null; private readonly sessions = new Map<string, LiveSession>(); private readonly runtimeReservations = new Map<string, string>(); private readonly runtimes = new Map<RemoteWorkspaceAgentProfile, RemoteWorkspaceRuntimeFactory>(); private sequence = 0; private availabilityCache: { at: number; value: RuntimeAvailability } | null = null; private availabilityFlight: Promise<RuntimeAvailability> | null = null; constructor( private readonly hub: RemoteWorkspaceHub, factories: readonly RemoteWorkspaceRuntimeFactory[], private readonly now: () => number = Date.now, private readonly store?: RemoteWorkspaceSessionStateStore, ) { for (const factory of factories) { if (this.runtimes.has(factory.profile)) throw new Error("duplicate remote workspace runtime profile"); this.runtimes.set(factory.profile, factory); } for (const summary of this.store?.load()?.sessions ?? []) { const restoredStatus = summary.status === "stopped" ? "stopped" : summary.threadId && summary.resumable ? "waiting_for_executor" : "failed"; this.sessions.set(summary.id, { ...summary, status: restoredStatus, handle: null, unregister: null, closeTransport: null, operation: Promise.resolve(), stopOperation: null, remoteTransport: null, turnActive: false, }); for (const event of summary.events) this.sequence = Math.max(this.sequence, event.sequence); } } async availability(): Promise<RuntimeAvailability> { if (this.availabilityCache && this.now() - this.availabilityCache.at < AVAILABILITY_CACHE_MS) { return structuredClone(this.availabilityCache.value); } if (this.availabilityFlight) return structuredClone(await this.availabilityFlight); this.availabilityFlight = (async () => { const probe = async (profile: RemoteWorkspaceAgentProfile) => { const factory = this.runtimes.get(profile); if (!factory) return { available: false, reason: "runtime adapter is not installed" }; try { return await factory.available(); } catch { return { available: false, reason: "runtime availability probe failed" }; } }; const [codex, claude, pi] = await Promise.all([ probe("codex"), probe("claude"), probe("pi"), ]); const value: RuntimeAvailability = { codex, claude, pi }; this.availabilityCache = { at: this.now(), value }; return value; })(); try { return structuredClone(await this.availabilityFlight); } finally { this.availabilityFlight = null; } } list(): RemoteWorkspaceSessionSummary[] { this.refreshOfflineStates(); return [...this.sessions.values()].map(session => this.publicSession(session, MAX_LIST_EVENTS_PER_SESSION)); } get(sessionId: string): RemoteWorkspaceSessionSummary | null { this.refreshOfflineStates(); const session = this.sessions.get(sessionId); return session ? this.publicSession(session) : null; } private reserveRuntime(deviceId: string): () => void { const live = [...this.sessions.values()].filter(session => session.handle !== null); const pending = [...this.runtimeReservations.values()]; if (live.length + pending.length >= MAX_LIVE_SESSIONS) { throw new Error("remote workspace active session limit reached"); } if (live.filter(session => session.deviceId === deviceId).length + pending.filter(device => device === deviceId).length >= REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE) { throw new Error("remote workspace executor session limit reached"); } const reservation = randomUUID(); this.runtimeReservations.set(reservation, deviceId); return () => { this.runtimeReservations.delete(reservation); }; } create(input: { profile: RemoteWorkspaceAgentProfile; deviceId: string; rootId: string; accessMode?: RemoteWorkspaceAccessMode; }): Promise<RemoteWorkspaceSessionSummary> { const operation = this.createSession(input); this.pendingCreates.add(operation); void operation.then(() => this.pendingCreates.delete(operation), () => this.pendingCreates.delete(operation)); return operation; } private async createSession(input: { profile: RemoteWorkspaceAgentProfile; deviceId: string; rootId: string; accessMode?: RemoteWorkspaceAccessMode; }): Promise<RemoteWorkspaceSessionSummary> { if (this.shuttingDown) throw new Error("remote workspace hub is stopping"); this.pruneRetainedSessions(); const releaseRuntime = this.reserveRuntime(input.deviceId); try { const factory = this.runtimes.get(input.profile); if (!factory) throw new Error(`remote workspace ${input.profile} runtime is not installed on the hub`); const available = await factory.available(); if (this.shuttingDown) throw new Error("remote workspace hub is stopping"); if (!available.available) throw new Error(available.reason ?? `remote workspace ${input.profile} runtime is unavailable`); const device = this.hub.listDevices().find(candidate => candidate.id === input.deviceId); if (!device) throw new Error("remote workspace device not found"); const root = device.roots.find(candidate => candidate.id === input.rootId); if (!root) throw new Error("remote workspace root not found on the selected device"); const connection = this.hub.connection(device.id); if (!connection) throw new Error("remote workspace executor is offline"); const id = randomUUID(); const accessMode = parseAccessMode(input.accessMode ?? "read-only"); const deviceCapabilities = parseRemoteWorkspaceCapabilities(device.capabilities); const capabilities = accessMode === "read-only" ? parseRemoteWorkspaceCapabilities(["workspace.read"]) : deviceCapabilities; const tools = remoteWorkspaceToolsForCapabilities(capabilities); const connectionCapabilities = connection.capabilities(); if (capabilities.some(capability => !connectionCapabilities.includes(capability))) { throw new Error("remote workspace executor capability advertisement is stale; refresh and try again"); } const timestamp = new Date(this.now()).toISOString(); const session: LiveSession = { id, profile: input.profile, accessMode, deviceId: device.id, deviceName: device.name, rootId: root.id, rootLabel: root.label, capabilities, tools, threadId: null, resumable: false, status: "starting", createdAt: timestamp, updatedAt: timestamp, events: [], handle: null, unregister: null, closeTransport: null, operation: Promise.resolve(), stopOperation: null, remoteTransport: null, turnActive: false, }; this.sessions.set(id, session); this.emit(session, "status", `Starting ${input.profile} on ${device.name}/${root.label}`); try { this.persist(); } catch (error) { this.sessions.delete(id); throw error; } try { session.closeTransport = () => connection.closeSession(id); const transport = await connection.openSession({ sessionId: id, rootId: root.id, profile: input.profile, capabilities }); if (session.stopOperation) { await session.closeTransport().catch(() => {}); session.closeTransport = null; throw new Error("remote workspace session was stopped while starting"); } const remoteTransport = new SwitchableRemoteWorkspaceTransport(transport); session.remoteTransport = remoteTransport; const coordinator = new RemoteWorkspaceCoordinator(remoteTransport); const handle = await factory.start({ sessionId: id, deviceId: device.id, deviceName: device.name, rootId: root.id, rootLabel: root.label, capabilities, tools, coordinator, emit: (type, text) => this.emit(session, type, text), }); if (session.stopOperation || this.shuttingDown) { await this.stopLateRuntime(handle); throw new Error("remote workspace session was stopped while starting"); } session.threadId = handle.threadId; session.resumable = handle.canResume?.() ?? true; session.handle = handle; session.unregister = coordinator.register({ sessionId: id, threadId: handle.threadId, executorDeviceId: device.id, executorName: device.name, rootId: root.id, capabilities, tools, }); this.status(session, "ready", `${input.profile} is ready on ${device.name}/${root.label}`); return this.publicSession(session); } catch (error) { let reported = error; if (session.status !== "stopped") { try { this.status(session, "failed", error instanceof Error ? error.message : "remote workspace session failed to start"); } catch (persistenceError) { reported = persistenceError; } } session.unregister?.(); session.unregister = null; await session.handle?.stop().catch(() => {}); session.handle = null; await session.closeTransport?.().catch(() => {}); session.closeTransport = null; session.remoteTransport = null; throw reported; } } finally { releaseRuntime(); } } async prompt(sessionId: string, value: unknown): Promise<RemoteWorkspaceSessionSummary> { const session = this.startPrompt(sessionId, value); await session.operation; return this.publicSession(session); } submitPrompt(sessionId: string, value: unknown): RemoteWorkspaceSessionSummary { return this.publicSession(this.startPrompt(sessionId, value)); } private startPrompt(sessionId: string, value: unknown): LiveSession { const prompt = boundedPrompt(value); const session = this.sessions.get(sessionId); if (!session || session.status === "stopped") throw new Error("remote workspace session is not ready"); if (!session.handle && (!session.threadId || !session.resumable)) { throw new Error("remote workspace session cannot be resumed"); } if (session.turnActive) throw new Error("remote workspace session already has an active turn"); if (session.stopOperation) throw new Error("remote workspace session is stopping"); session.turnActive = true; const run = async () => { try { this.status(session, "running", "Turn accepted"); await this.ensureRemoteTransport(session); await this.ensureRuntime(session); if (session.stopOperation) throw new Error("remote workspace session is stopping"); this.status(session, "running", "Turn started"); await session.handle!.prompt(prompt); session.resumable = session.handle!.canResume?.() ?? true; if (!this.hub.connection(session.deviceId) || !session.remoteTransport?.isOnline(session.deviceId)) { this.status(session, "waiting_for_executor", "Turn completed; reconnect the remote executor before continuing."); } else { this.status(session, "ready", "Turn completed"); } } catch (error) { const message = error instanceof Error ? error.message : "remote workspace turn failed"; this.status(session, this.hub.connection(session.deviceId) ? "failed" : "waiting_for_executor", message); throw error; } finally { session.turnActive = false; } }; session.operation = run(); // Polling observes the stored terminal status; awaited callers and cleanup retain // the original rejecting promise, with an observer attached before detachment. void session.operation.catch(() => {}); return session; } async stop(sessionId: string): Promise<boolean> { const session = this.sessions.get(sessionId); if (!session) return false; if (session.stopOperation) return session.stopOperation; session.stopOperation = (async () => { const handle = session.handle; const activeOperation = session.operation; // Cancellation has to run before waiting for the active turn. Waiting first makes // Stop unable to interrupt a model request or remote command that never completes. try { await runRemoteWorkspaceCleanupSteps([ async () => { if (handle) await handle.stop(); }, () => activeOperation.catch(() => {}), async () => { if (session.handle && session.handle !== handle) await session.handle.stop(); }, () => { session.unregister?.(); session.unregister = null; }, async () => { if (session.closeTransport) await session.closeTransport(); }, () => { session.closeTransport = null; session.handle = null; session.remoteTransport = null; }, ]); } catch (error) { this.status(session, "failed", "Session cleanup failed; one or more owned resources did not close."); throw error; } this.status(session, "stopped", "Session stopped"); return true; })(); return session.stopOperation; } async stopAll(): Promise<void> { const active = [...this.sessions.values()].filter(session => session.status !== "stopped"); await Promise.all(active.map(session => this.stop(session.id).then(() => undefined))); this.persist(); } async shutdown(): Promise<void> { this.shuttingDown = true; const active = [...this.sessions.values()].filter(session => session.status !== "stopped"); const results = await Promise.allSettled(active.map(async session => { if (session.stopOperation) { await session.stopOperation; return; } session.stopOperation = (async () => { const handle = session.handle; const activeOperation = session.operation; try { await runRemoteWorkspaceCleanupSteps([ async () => { if (handle) await handle.stop(); }, () => activeOperation.catch(() => {}), async () => { if (session.handle && session.handle !== handle) await session.handle.stop(); }, () => { session.unregister?.(); session.unregister = null; }, async () => { if (session.closeTransport) await session.closeTransport(); }, () => { session.closeTransport = null; session.handle = null; session.remoteTransport = null; }, ]); } catch (error) { this.status(session, "failed", "Hub shutdown could not close every Remote Workspace resource."); throw error; } this.status( session, session.threadId && session.resumable ? "waiting_for_executor" : "failed", session.threadId && session.resumable ? "Hub stopped; reconnect the executor to resume this session." : "Hub stopped before the model session was created.", ); return true; })(); await session.stopOperation; })); await Promise.allSettled([...this.pendingCreates]); if (this.startupCleanupFailure) throw this.startupCleanupFailure; const failed = results.find(result => result.status === "rejected"); if (failed?.status === "rejected") throw failed.reason; this.persist(); } private async stopLateRuntime(handle: RemoteWorkspaceRuntimeHandle): Promise<void> { try { await handle.stop(); } catch (error) { this.startupCleanupFailure = error instanceof Error ? error : new Error("remote workspace startup cleanup failed"); throw this.startupCleanupFailure; } } private status(session: LiveSession, status: RemoteWorkspaceSessionStatus, text: string): void { session.status = status; this.emit(session, status === "failed" ? "error" : "status", text); this.persist(); } private emit(session: LiveSession, type: RemoteWorkspaceSessionEvent["type"], text: string): void { const at = new Date(this.now()).toISOString(); session.updatedAt = at; session.events.push({ sequence: ++this.sequence, at, type, text: boundedEventText(text) }); if (session.events.length > MAX_EVENTS_PER_SESSION) { session.events.splice(0, session.events.length - MAX_EVENTS_PER_SESSION); } } private publicSession(session: LiveSession, eventLimit = MAX_EVENTS_PER_SESSION): RemoteWorkspaceSessionSummary { const { handle: _handle, unregister: _unregister, closeTransport: _close, operation: _operation, stopOperation: _stopOperation, remoteTransport: _remoteTransport, turnActive: _turnActive, ...publicState } = session; return structuredClone({ ...publicState, events: publicState.events.slice(-eventLimit) }); } private async ensureRemoteTransport(session: LiveSession): Promise<void> { if (session.remoteTransport?.isOnline(session.deviceId)) return; const connection = this.hub.connection(session.deviceId); if (!connection) { this.status(session, "waiting_for_executor", "Remote executor is offline; local fallback is disabled."); throw new Error("remote workspace executor is offline"); } const connectionCapabilities = connection.capabilities(); if (session.capabilities.some(capability => !connectionCapabilities.includes(capability))) { throw new Error("remote workspace executor capabilities changed; start a new session for this computer"); } this.status(session, "starting", `Reconnecting ${session.deviceName}/${session.rootLabel}`); const transport = await connection.openSession({ sessionId: session.id, rootId: session.rootId, profile: session.profile, capabilities: session.capabilities, }); if (session.stopOperation) { await connection.closeSession(session.id).catch(() => {}); throw new Error("remote workspace session is stopping"); } await session.closeTransport?.().catch(() => {}); if (session.remoteTransport) session.remoteTransport.replace(transport); else session.remoteTransport = new SwitchableRemoteWorkspaceTransport(transport); session.closeTransport = () => connection.closeSession(session.id); this.status(session, session.turnActive ? "running" : "ready", `${session.profile} reconnected to ${session.deviceName}/${session.rootLabel}`); } private async ensureRuntime(session: LiveSession): Promise<void> { if (session.handle) return; if (!session.threadId || !session.resumable || !session.remoteTransport) { throw new Error("remote workspace session cannot be resumed"); } const factory = this.runtimes.get(session.profile); if (!factory) throw new Error(`remote workspace ${session.profile} runtime is not installed on the hub`); const releaseRuntime = this.reserveRuntime(session.deviceId); try { const available = await factory.available(); if (this.shuttingDown) throw new Error("remote workspace hub is stopping"); if (!available.available) throw new Error(available.reason ?? `remote workspace ${session.profile} runtime is unavailable`); const coordinator = new RemoteWorkspaceCoordinator(session.remoteTransport); const handle = await factory.start({ sessionId: session.id, deviceId: session.deviceId, deviceName: session.deviceName, rootId: session.rootId, rootLabel: session.rootLabel, capabilities: [...session.capabilities], tools: [...session.tools], resumeThreadId: session.threadId, coordinator, emit: (type, text) => this.emit(session, type, text), }); if (this.shuttingDown || session.stopOperation) { // Stop/shutdown awaits this resume and must observe any late-handle cleanup failure. session.handle = handle; throw new Error("remote workspace session was stopped while resuming"); } try { session.unregister = coordinator.register({ sessionId: session.id, threadId: handle.threadId, executorDeviceId: session.deviceId, executorName: session.deviceName, rootId: session.rootId, capabilities: [...session.capabilities], tools: [...session.tools], }); } catch (error) { await handle.stop().catch(() => {}); throw error; } session.threadId = handle.threadId; session.handle = handle; this.status(session, session.turnActive ? "running" : "ready", `${session.profile} resumed on ${session.deviceName}/${session.rootLabel}`); } finally { releaseRuntime(); } } private refreshOfflineStates(): void { for (const session of this.sessions.values()) { if (session.status !== "ready" || this.hub.connection(session.deviceId)) continue; this.status(session, "waiting_for_executor", "Remote executor is offline; local fallback is disabled."); } } private pruneRetainedSessions(): void { if (this.sessions.size < MAX_RETAINED_SESSIONS) return; for (const [id, session] of this.sessions) { if (session.status !== "stopped" && !(session.status === "failed" && session.handle === null)) continue; this.sessions.delete(id); if (this.sessions.size < MAX_RETAINED_SESSIONS) return; } if (this.sessions.size >= MAX_RETAINED_SESSIONS) { throw new Error("remote workspace retained session limit reached; stop an active session first"); } } private persist(): void { if (!this.store) return; const sessions = [...this.sessions.values()].map(session => { const summary = this.publicSession(session); return { ...summary, events: summary.events.slice(-MAX_PERSISTED_EVENTS_PER_SESSION).map(event => ({ ...event, text: boundedPersistedEventText(event.text), })), }; }); this.store.save({ version: REMOTE_WORKSPACE_SESSION_STATE_VERSION, sessions }); } }