import { RpcDispatcher } from '../../src/main/runtime/rpc/dispatcher' import { TERMINAL_MULTIPLEX_METHODS } from '../../src/main/runtime/rpc/methods/terminal/terminal-multiplex-method' import type { OrcaRuntimeService } from '../../src/main/runtime/orca-runtime' import { TerminalStreamOpcode, decodeTerminalStreamFrame, decodeTerminalStreamText, type TerminalStreamFrame } from '../../src/shared/terminal/stream/terminal-stream-protocol' import { createHostTerminalRuntimeStub, type HostTerminalRuntimeStub } from './cross-version-wire/host-terminal-runtime-stub' export const MODEL_TERMINAL_HANDLE = 'terminal-1' /** How one direction of the live connection treats frames: deliver, buffer (a silent link), or lose. */ export type ModelLinkMode = 'pass' | 'hold' | 'drop' type ClientCallbacks = { onResponse: (response: unknown) => void onBinary?: (bytes: Uint8Array) => void onError?: (error: { code: string; message: string }) => void onClose?: () => void } type Connection = { id: string host: HostTerminalRuntimeStub handlers: Map void> client: ClientCallbacks // Frames a silent link buffered; a surviving connection flushes them, a dead one may too, late. heldToHost: TerminalStreamFrame[] heldToClient: Uint8Array[] clientAttached: boolean hostAlive: boolean lostFrames: boolean abort: AbortController } // Fault the real renderer-multiplexer/host-dispatcher link with buffered/lost/late frames and runtime restart while PTYs survive. export function createModelLink(writeInput: (text: string) => Promise) { let host = newHost() let live: Connection | null = null const zombies: Connection[] = [] let counter = 0 // Why a call: a typed const still narrows to 'pass', which would type both fields as 'pass'. const initialMode = (): ModelLinkMode => 'pass' const link = { toHost: initialMode(), toClient: initialMode(), /** Drops individual acks on an otherwise healthy connection. */ ackLoss: 0, unreachable: false, random: Math.random, /** Input frame texts the client handed to any connection, for the oracle. */ onClientInput: (_text: string): void => {}, /** Input frame texts that reached a host runtime. */ onHostInput: (_text: string): void => {}, subscribe, get liveConnected(): boolean { return live !== null }, /** Input still buffered toward a host, which may yet arrive (a heal or a late zombie flush). */ heldInputTexts: (): string[] => [live, ...zombies].flatMap((connection) => (connection?.heldToHost ?? []) .filter((frame) => frame.opcode === TerminalStreamOpcode.Input) .map((frame) => decodeTerminalStreamText(frame.payload)) ), get zombieCount(): number { return zombies.length }, /** The client notices the dead socket; the host side lingers until `retireZombies`. */ disconnect, heal, flushZombie, retireZombies, restartHost, dispose: (): void => { retireZombies() if (live) { closeHostSide(live) } } } function newHost(): HostTerminalRuntimeStub { const stub = createHostTerminalRuntimeStub({ terminalHandle: MODEL_TERMINAL_HANDLE, ptyId: 'pty-1', cols: 80, rows: 24, writeInput }) return stub } function deliverToHost(connection: Connection, frame: TerminalStreamFrame): void { if (!connection.hostAlive || connection.host !== host) { return } if (frame.opcode === TerminalStreamOpcode.Input) { link.onHostInput(decodeTerminalStreamText(frame.payload)) } connection.handlers.get(frame.streamId)?.(frame) } function deliverToClient(connection: Connection, bytes: Uint8Array): void { if (connection.clientAttached) { connection.client.onBinary?.(bytes) } } function closeHostSide(connection: Connection): void { if (!connection.hostAlive) { return } connection.hostAlive = false connection.abort.abort() connection.host.closeConnection(connection.id) } async function subscribe( _args: unknown, client: ClientCallbacks ): Promise<{ unsubscribe: () => void sendBinary: (bytes: Uint8Array) => void }> { if (link.unreachable) { throw Object.assign(new Error('Could not connect to the remote Orca runtime.'), { code: 'remote_runtime_unavailable' }) } counter += 1 const connection: Connection = { id: `model-conn-${counter}`, host, handlers: new Map(), client, heldToHost: [], heldToClient: [], clientAttached: true, hostAlive: true, lostFrames: false, abort: new AbortController() } live = connection void new RpcDispatcher({ // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the stub implements every runtime method the terminal multiplex calls and records any it lacks. runtime: host.runtime as OrcaRuntimeService, methods: TERMINAL_MULTIPLEX_METHODS }) .dispatchStreaming( { id: `req-${counter}`, authToken: 'model-token', method: 'terminal.multiplex', params: {} }, (message) => { if (connection.clientAttached && connection.hostAlive) { client.onResponse(JSON.parse(message)) } }, { connectionId: connection.id, sendBinary: (bytes) => { if (!connection.hostAlive) { return false } const isAck = decodeTerminalStreamFrame(bytes)?.opcode === TerminalStreamOpcode.InputAck if (live === connection && (link.toClient === 'drop' || connection.lostFrames)) { connection.lostFrames = true return true } if (live === connection && isAck && link.random() < link.ackLoss) { return true } if (live !== connection || link.toClient === 'hold') { connection.heldToClient.push(bytes) return true } deliverToClient(connection, bytes) return true }, registerBinaryStreamHandler: (streamId, handler) => { connection.handlers.set(streamId, handler) return () => { if (connection.handlers.get(streamId) === handler) { connection.handlers.delete(streamId) } } }, signal: connection.abort.signal } ) .catch(() => {}) return { unsubscribe: () => { connection.clientAttached = false if (live === connection) { live = null closeHostSide(connection) } }, sendBinary: (bytes) => { const frame = decodeTerminalStreamFrame(bytes) if (!frame || !connection.clientAttached) { return } if (frame.opcode === TerminalStreamOpcode.Input) { link.onClientInput(decodeTerminalStreamText(frame.payload)) } if (live !== connection) { return } // Why stay lost: TCP never delivers a frame after one it lost on the same connection. if (link.toHost === 'drop' || connection.lostFrames) { connection.lostFrames = true return } if (link.toHost === 'hold') { connection.heldToHost.push(frame) return } deliverToHost(connection, frame) } } } function disconnect(): void { const connection = live if (!connection) { return } live = null connection.clientAttached = false // Why linger: the host has not noticed yet, so buffered input may still reach it late. zombies.push(connection) link.toHost = 'pass' link.toClient = 'pass' connection.client.onClose?.() } /** The silent link recovers before anyone noticed: buffered frames arrive in order. */ function heal(): void { const connection = live if (connection?.lostFrames) { // Why: a connection that lost frames is gone (TCP never drops mid-stream); only a replacement heals. disconnect() return } link.toHost = 'pass' link.toClient = 'pass' if (!connection) { return } for (const frame of connection.heldToHost.splice(0)) { deliverToHost(connection, frame) } for (const bytes of connection.heldToClient.splice(0)) { deliverToClient(connection, bytes) } } /** A dead connection's buffered input reaches the host after the client moved on. */ function flushZombie(): void { const connection = zombies.shift() if (!connection) { return } for (const frame of connection.heldToHost.splice(0)) { deliverToHost(connection, frame) } closeHostSide(connection) } function retireZombies(): void { for (const connection of zombies.splice(0)) { connection.heldToHost = [] closeHostSide(connection) } } /** The host runtime restarts; the PTY survives in its daemon, the input ledger does not. */ function restartHost(): void { retireZombies() const connection = live if (connection) { closeHostSide(connection) } host = newHost() if (connection) { live = null connection.clientAttached = false connection.client.onClose?.() } } return link }