@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
text/typescript
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 });
}
}