@rynx-ai/remote-runtime-client 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type RemoteRuntimeRpcMethod, type RemoteRuntimeRpcParams, type RemoteRuntimeRpcResultFor, type RemoteRuntimeSequencedSessionEvent, type RemoteRuntimeSessionTerminalClosedFrame, type RemoteRuntimeSessionTerminalRole } from "@rynx-ai/protocol/remote-runtime-rpc";
+import { type RemoteRuntimeRpcMethod, type RemoteRuntimeRpcParams, type RemoteRuntimeRpcResultFor, type RemoteRuntimeSequencedSessionEvent, type RemoteRuntimeSessionTerminalRole } from "@rynx-ai/protocol/remote-runtime-rpc";
 import { type DaemonStatus } from "@rynx-ai/protocol/remote-runtime";
 import { type RuntimeEmulatorSurfaceClosedFrame, type RuntimeEmulatorSurfaceImageFrame, type RuntimeEmulatorSurfaceReadyFrame } from "@rynx-ai/protocol/runtime-emulator-surface";
 import { type DirectRuntimeClientIdentity, type DirectRuntimeCredential } from "./credential.js";
@@ -12,8 +12,9 @@ export interface DirectRuntimeClientOptions {
     };
 }
 export interface DirectRuntimeCallOptions {
-    /** Per-call override for operations whose expected duration differs from the handshake. */
-    timeoutMs?: number;
+    /** Per-call override for operations whose expected duration differs from the
+     * handshake. `null` leaves the operation to its own lifecycle deadlines. */
+    timeoutMs?: number | null;
 }
 export interface DirectRuntimeSessionEventsOptions {
     /** Timeout for the accepted ready barrier and cancellation acknowledgement. */
@@ -33,11 +34,34 @@ export interface DirectRuntimeSessionTerminalOptions {
     /** Timeout for the opened barrier and close acknowledgement. */
     timeoutMs?: number;
 }
-export interface DirectRuntimeSessionTerminal extends AsyncIterable<Uint8Array> {
+export interface DirectRuntimeSessionTerminalRead {
+    data: Uint8Array;
+    nextOffset: number;
+    done: boolean;
+    finalOffset?: number;
+}
+export interface DirectRuntimeSessionTerminalCloseInfo {
+    reason: "client_closed" | "terminal_exited" | "not_live" | "unauthorized" | "capacity" | "backpressure" | "internal";
+    exitCode?: number;
+    finalOffset?: number;
+}
+export interface DirectRuntimeSessionTerminal {
     readonly attachmentId: string;
     readonly sessionId: string;
     readonly role: RemoteRuntimeSessionTerminalRole;
-    readonly closed: Promise<RemoteRuntimeSessionTerminalClosedFrame>;
+    readonly seedBytes: number;
+    readonly dimensions?: {
+        cols: number;
+        rows: number;
+    };
+    readonly closed: Promise<DirectRuntimeSessionTerminalCloseInfo>;
+    readSeed(offset: number, maxBytes: number): Promise<DirectRuntimeSessionTerminalRead>;
+    start(): Promise<void>;
+    read(offset: number, maxBytes: number): Promise<DirectRuntimeSessionTerminalRead>;
+    onResize(listener: (dimensions: {
+        cols: number;
+        rows: number;
+    }) => void): void;
     write(data: Uint8Array): Promise<void>;
     resize(cols: number, rows: number): Promise<void>;
     /** Idempotently detach and wait for the remote close acknowledgement. */

package/dist/client.js

@@ -25,8 +25,6 @@ const MAX_PENDING_OUTBOUND_BYTES = 1024 * 1024;
 const MAX_E2EE_ENVELOPE_OVERHEAD_BYTES = 256;
 const MAX_SUBSCRIPTION_QUEUED_EVENTS = 128;
 const MAX_SUBSCRIPTION_QUEUED_BYTES = 256 * 1024;
-const MAX_TERMINAL_QUEUED_OUTPUT_FRAMES = 128;
-const MAX_TERMINAL_QUEUED_OUTPUT_BYTES = 512 * 1024;
 const establishedTextDecoder = new TextDecoder("utf-8", { fatal: true });
 /** Enroll a client identity, authenticate the issued grant, and probe status. */
 export async function pairDirectRuntime(untrustedOffer, options = {}) {
@@ -208,20 +206,25 @@ class DirectRuntimeConnectionImpl {
                 outcome: "not_started",
             });
         }
-        const timeoutMs = parseTimeout(options.timeoutMs ?? this.timeoutMs);
+        const timeoutMs = options.timeoutMs === null
+            ? null
+            : parseTimeout(options.timeoutMs ?? this.timeoutMs);
         return await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.pending.delete(id);
-                reject(callTransportError(clientError("deadline_exceeded", "Direct Runtime RPC timed out"), method, id));
-            }, timeoutMs);
-            timer.unref?.();
+            const timer = timeoutMs === null
+                ? undefined
+                : setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(callTransportError(clientError("deadline_exceeded", "Direct Runtime RPC timed out"), method, id));
+                }, timeoutMs);
+            timer?.unref?.();
             this.pending.set(id, { method, resolve, reject, timer });
             void this.channel.socket.sendText(frame).catch((error) => {
                 const pending = this.pending.get(id);
                 if (!pending)
                     return;
                 this.pending.delete(id);
-                clearTimeout(pending.timer);
+                if (pending.timer)
+                    clearTimeout(pending.timer);
                 pending.reject(error instanceof DirectRuntimeClientCapacityError
                     ? error
                     : callTransportError(error, pending.method, id));
@@ -232,7 +235,11 @@ class DirectRuntimeConnectionImpl {
         if (this.statusSnapshot)
             return Promise.resolve(this.statusSnapshot);
         if (!this.statusProbe) {
-            this.statusProbe = this.sendCall("status.get", {}, options).finally(() => {
+            // An application operation may deliberately have no outer deadline, but
+            // capability preflight is transport metadata and retains the connection
+            // default rather than inheriting that unbounded lifecycle.
+            const statusOptions = options.timeoutMs === null ? {} : options;
+            this.statusProbe = this.sendCall("status.get", {}, statusOptions).finally(() => {
                 this.statusProbe = undefined;
             });
         }
@@ -469,8 +476,14 @@ class DirectRuntimeConnectionImpl {
             case "session.events.closed":
                 this.receiveSessionFrame(value, frame.byteLength);
                 return;
-            case "session.terminal.opened":
-            case "session.terminal.output":
+            case "session.terminal.prepared":
+            case "session.terminal.seed.chunk":
+            case "session.terminal.started":
+            case "session.terminal.chunk":
+            case "session.terminal.input.ack":
+            case "session.terminal.resize.ack":
+            case "session.terminal.reader.done":
+            case "session.terminal.dimensions":
             case "session.terminal.closed":
                 this.receiveTerminalFrame(value);
                 return;
@@ -498,7 +511,8 @@ class DirectRuntimeConnectionImpl {
             return;
         }
         this.pending.delete(envelope.id);
-        clearTimeout(pending.timer);
+        if (pending.timer)
+            clearTimeout(pending.timer);
         let response;
         try {
             response = parseRemoteRuntimeRpcResponseForMethod(envelope, pending.method);
@@ -615,16 +629,30 @@ class DirectRuntimeConnectionImpl {
             return;
         }
         switch (frame.type) {
-            case "session.terminal.opened":
+            case "session.terminal.prepared":
                 this.acceptTerminal(frame);
                 return;
-            case "session.terminal.output": {
+            case "session.terminal.seed.chunk":
+            case "session.terminal.chunk":
+            case "session.terminal.started":
+            case "session.terminal.input.ack":
+            case "session.terminal.resize.ack":
+            case "session.terminal.reader.done": {
                 const terminal = this.terminal;
                 if (!terminal || terminal.attachmentId !== frame.attachmentId) {
-                    this.fail(clientError("protocol_error", "Terminal output has no active attachment"));
+                    this.fail(clientError("protocol_error", "Terminal response has no active attachment"));
                     return;
                 }
-                terminal.push(Uint8Array.from(Buffer.from(frame.data, "base64")));
+                terminal.receive(frame);
+                return;
+            }
+            case "session.terminal.dimensions": {
+                const terminal = this.terminal;
+                if (!terminal || terminal.attachmentId !== frame.attachmentId) {
+                    this.fail(clientError("protocol_error", "Terminal dimensions have no active attachment"));
+                    return;
+                }
+                terminal.updateDimensions(frame.cols, frame.rows);
                 return;
             }
             case "session.terminal.closed":
@@ -643,7 +671,7 @@ class DirectRuntimeConnectionImpl {
         }
         this.pendingTerminal = undefined;
         clearTimeout(pending.timer);
-        const terminal = new SessionTerminalImpl(frame, pending.timeoutMs, (data) => this.writeTerminal(frame.attachmentId, data), (cols, rows) => this.resizeTerminal(frame.attachmentId, cols, rows), () => this.closeTerminal(frame.attachmentId), (error) => this.fail(error));
+        const terminal = new SessionTerminalImpl(frame, pending.timeoutMs, (value) => this.channel.socket.sendText(encodeRemoteRuntimeSessionTerminalClientFrame(value)), () => this.closeTerminal(frame.attachmentId), (error) => this.fail(error));
         this.terminal = terminal;
         pending.resolve(terminal);
     }
@@ -746,28 +774,6 @@ class DirectRuntimeConnectionImpl {
             ...point,
         }));
     }
-    async writeTerminal(attachmentId, data) {
-        if (data.byteLength === 0)
-            return;
-        for (let offset = 0; offset < data.byteLength; offset += REMOTE_RUNTIME_SESSION_TERMINAL_MAX_DATA_BYTES) {
-            const chunk = data.subarray(offset, Math.min(offset + REMOTE_RUNTIME_SESSION_TERMINAL_MAX_DATA_BYTES, data.byteLength));
-            const frame = encodeRemoteRuntimeSessionTerminalClientFrame({
-                type: "session.terminal.input",
-                attachmentId,
-                data: Buffer.from(chunk).toString("base64"),
-            });
-            await this.channel.socket.sendText(frame);
-        }
-    }
-    async resizeTerminal(attachmentId, cols, rows) {
-        const frame = encodeRemoteRuntimeSessionTerminalClientFrame({
-            type: "session.terminal.resize",
-            attachmentId,
-            cols,
-            rows,
-        });
-        await this.channel.socket.sendText(frame);
-    }
     async closeTerminal(attachmentId) {
         const terminal = this.terminal;
         if (!terminal || terminal.attachmentId !== attachmentId)
@@ -847,7 +853,8 @@ class DirectRuntimeConnectionImpl {
     }
     rejectPending(error) {
         for (const [id, pending] of this.pending) {
-            clearTimeout(pending.timer);
+            if (pending.timer)
+                clearTimeout(pending.timer);
             pending.reject(callTransportError(error, pending.method, id));
         }
         this.pending.clear();
@@ -1176,31 +1183,39 @@ function sessionEventsError(frame, sessionId) {
 }
 class SessionTerminalImpl {
     timeoutMs;
-    sendInput;
-    sendResize;
+    sendFrame;
     requestClose;
     reportBackpressure;
-    queue = [];
-    queuedBytes = 0;
-    waiter;
-    terminalError;
-    ended = false;
-    closing = false;
+    state = "prepared";
+    seedOffset = 0;
+    liveOffset = 0;
+    closedSettled = false;
+    detachedSettled = false;
+    pending = new Map();
     resolveClosed;
     rejectClosed;
+    resolveDetached;
+    rejectDetached;
     closed;
+    detached;
     attachmentId;
     sessionId;
     role;
-    constructor(opened, timeoutMs, sendInput, sendResize, requestClose, reportBackpressure) {
+    seedBytes;
+    dimensions;
+    resizeListener;
+    constructor(opened, timeoutMs, sendFrame, requestClose, reportBackpressure) {
         this.timeoutMs = timeoutMs;
-        this.sendInput = sendInput;
-        this.sendResize = sendResize;
+        this.sendFrame = sendFrame;
         this.requestClose = requestClose;
         this.reportBackpressure = reportBackpressure;
         this.attachmentId = opened.attachmentId;
         this.sessionId = opened.sessionId;
         this.role = opened.role;
+        this.seedBytes = opened.seedBytes;
+        this.dimensions = opened.cols === undefined || opened.rows === undefined
+            ? undefined
+            : { cols: opened.cols, rows: opened.rows };
         let resolveClosed;
         let rejectClosed;
         this.closed = new Promise((resolve, reject) => {
@@ -1209,111 +1224,225 @@ class SessionTerminalImpl {
         });
         this.resolveClosed = resolveClosed;
         this.rejectClosed = rejectClosed;
+        let resolveDetached;
+        let rejectDetached;
+        this.detached = new Promise((resolve, reject) => {
+            resolveDetached = resolve;
+            rejectDetached = reject;
+        });
+        this.resolveDetached = resolveDetached;
+        this.rejectDetached = rejectDetached;
         void this.closed.catch(() => undefined);
+        void this.detached.catch(() => undefined);
     }
-    [Symbol.asyncIterator]() {
-        return this;
+    onResize(listener) {
+        this.resizeListener = listener;
+        if (this.dimensions)
+            queueMicrotask(() => listener(this.dimensions));
     }
-    next() {
-        const queued = this.queue.shift();
-        if (queued) {
-            this.queuedBytes -= queued.bytes;
-            return Promise.resolve({ done: false, value: queued.data });
-        }
-        if (this.terminalError !== undefined)
-            return Promise.reject(this.terminalError);
-        if (this.ended)
-            return Promise.resolve({ done: true, value: undefined });
-        if (this.waiter) {
-            return Promise.reject(clientError("protocol_error", "concurrent reads from one Session terminal are not allowed"));
-        }
-        return new Promise((resolve, reject) => {
-            this.waiter = { resolve, reject };
+    updateDimensions(cols, rows) {
+        if (this.state === "ended")
+            return;
+        this.dimensions = { cols, rows };
+        this.resizeListener?.(this.dimensions);
+    }
+    readSeed(offset, maxBytes) {
+        if (this.state !== "prepared" || offset !== this.seedOffset) {
+            return Promise.reject(clientError("protocol_error", "Session terminal seed read is out of order"));
+        }
+        return this.requestRead("session.terminal.seed.chunk", {
+            type: "session.terminal.seed.read",
+            attachmentId: this.attachmentId,
+            requestId: this.nextRequestId(),
+            offset,
+            maxBytes: Math.min(maxBytes, REMOTE_RUNTIME_SESSION_TERMINAL_MAX_DATA_BYTES),
+        }).then((result) => {
+            this.seedOffset = result.nextOffset;
+            if (result.done && result.nextOffset !== this.seedBytes) {
+                throw clientError("protocol_error", "Session terminal seed length changed");
+            }
+            return result;
         });
     }
-    async return() {
-        await this.close();
-        return { done: true, value: undefined };
+    async start() {
+        if (this.state !== "prepared" || this.seedOffset !== this.seedBytes) {
+            throw clientError("protocol_error", "Session terminal history must be consumed before start");
+        }
+        this.state = "starting";
+        await this.requestVoid("session.terminal.started", {
+            type: "session.terminal.start",
+            attachmentId: this.attachmentId,
+            requestId: this.nextRequestId(),
+        });
+        if (this.state === "starting")
+            this.state = "started";
+    }
+    read(offset, maxBytes) {
+        if (this.state !== "started" || offset !== this.liveOffset) {
+            return Promise.reject(clientError("protocol_error", "Session terminal read is out of order"));
+        }
+        return this.requestRead("session.terminal.chunk", {
+            type: "session.terminal.read",
+            attachmentId: this.attachmentId,
+            requestId: this.nextRequestId(),
+            offset,
+            maxBytes: Math.min(maxBytes, REMOTE_RUNTIME_SESSION_TERMINAL_MAX_DATA_BYTES),
+        }).then((result) => {
+            this.liveOffset = result.nextOffset;
+            return result;
+        });
     }
     async write(data) {
-        if (this.ended || this.closing || this.role !== "owner" || data.byteLength === 0)
+        if (this.state !== "started" || this.role !== "owner" || data.byteLength === 0)
             return;
-        await this.sendInput(Uint8Array.from(data));
+        for (let offset = 0; offset < data.byteLength; offset += REMOTE_RUNTIME_SESSION_TERMINAL_MAX_DATA_BYTES) {
+            const chunk = data.subarray(offset, Math.min(offset + REMOTE_RUNTIME_SESSION_TERMINAL_MAX_DATA_BYTES, data.byteLength));
+            await this.requestVoid("session.terminal.input.ack", {
+                type: "session.terminal.input",
+                attachmentId: this.attachmentId,
+                requestId: this.nextRequestId(),
+                data: Buffer.from(chunk).toString("base64"),
+            });
+        }
     }
     async resize(cols, rows) {
-        if (this.ended || this.closing)
+        if (this.state !== "started")
             return;
-        await this.sendResize(cols, rows);
+        await this.requestVoid("session.terminal.resize.ack", {
+            type: "session.terminal.resize",
+            attachmentId: this.attachmentId,
+            requestId: this.nextRequestId(),
+            cols,
+            rows,
+        });
     }
     async close() {
-        if (this.ended)
+        if (this.state === "ended")
             return;
         await this.requestClose();
     }
-    push(data) {
-        if (this.ended || this.closing || data.byteLength === 0)
-            return;
-        if (this.waiter) {
-            const waiter = this.waiter;
-            this.waiter = undefined;
-            waiter.resolve({ done: false, value: data });
+    receive(frame) {
+        if (frame.type === "session.terminal.reader.done") {
+            if (!this.closedSettled) {
+                this.closedSettled = true;
+                this.resolveClosed({
+                    reason: frame.reason,
+                    exitCode: frame.exitCode,
+                    finalOffset: frame.finalOffset,
+                });
+            }
             return;
         }
-        if (this.queue.length >= MAX_TERMINAL_QUEUED_OUTPUT_FRAMES ||
-            this.queuedBytes + data.byteLength > MAX_TERMINAL_QUEUED_OUTPUT_BYTES) {
-            this.reportBackpressure(clientError("unreachable", "Remote Session terminal output exceeded its bounded client queue"));
+        const pending = this.pending.get(frame.requestId);
+        if (!pending || pending.expectedType !== frame.type) {
+            this.reportBackpressure(clientError("protocol_error", "Remote Session terminal response is duplicate or out of order"));
             return;
         }
-        const copy = Uint8Array.from(data);
-        this.queue.push({ data: copy, bytes: copy.byteLength });
-        this.queuedBytes += copy.byteLength;
+        this.pending.delete(frame.requestId);
+        clearTimeout(pending.timer);
+        if (frame.type === "session.terminal.seed.chunk" || frame.type === "session.terminal.chunk") {
+            pending.resolve({
+                data: Uint8Array.from(Buffer.from(frame.data, "base64")),
+                nextOffset: frame.nextOffset,
+                done: frame.done,
+                ...(frame.finalOffset === undefined ? {} : { finalOffset: frame.finalOffset }),
+            });
+        }
+        else
+            pending.resolve(undefined);
     }
     beginClose() {
-        if (this.ended || this.closing)
+        if (this.state === "ended" || this.state === "closing")
             return false;
-        this.closing = true;
-        this.clearQueue();
+        this.state = "closing";
+        this.rejectPending(clientError("closed", "Remote Session terminal is closing"));
         return true;
     }
     remoteClose(frame) {
-        if (this.ended)
+        if (this.state === "ended")
             return;
+        this.state = "ended";
         const error = frame.reason === "client_closed" || frame.reason === "terminal_exited"
             ? undefined
             : sessionTerminalError(frame, this.sessionId);
-        this.finish(frame, error, frame.reason !== "terminal_exited");
+        this.rejectPending(error ?? clientError("closed", "Remote Session terminal detached"));
+        if (!this.closedSettled) {
+            this.closedSettled = true;
+            if (error)
+                this.rejectClosed(error);
+            else
+                this.resolveClosed({ reason: frame.reason, ...(frame.exitCode === undefined ? {} : { exitCode: frame.exitCode }) });
+        }
+        if (!this.detachedSettled) {
+            this.detachedSettled = true;
+            if (error)
+                this.rejectDetached(error);
+            else
+                this.resolveDetached();
+        }
     }
     terminate(error) {
-        if (this.ended)
+        if (this.state === "ended")
             return;
-        this.finish(undefined, error, true);
+        this.state = "ended";
+        this.rejectPending(error);
+        if (!this.closedSettled) {
+            this.closedSettled = true;
+            this.rejectClosed(error);
+        }
+        if (!this.detachedSettled) {
+            this.detachedSettled = true;
+            this.rejectDetached(error);
+        }
     }
     waitClosed() {
-        return this.closed.then(() => undefined);
+        return this.detached;
     }
-    finish(frame, error, discardQueue = false) {
-        if (this.ended)
-            return;
-        this.ended = true;
-        this.terminalError = error;
-        if (discardQueue)
-            this.clearQueue();
-        const waiter = this.waiter;
-        this.waiter = undefined;
-        if (waiter) {
-            if (error === undefined)
-                waiter.resolve({ done: true, value: undefined });
-            else
-                waiter.reject(error);
+    requestRead(expectedType, frame) {
+        return this.request(expectedType, frame);
+    }
+    requestVoid(expectedType, frame) {
+        return this.request(expectedType, frame).then(() => undefined);
+    }
+    request(expectedType, frame) {
+        if (!("requestId" in frame)) {
+            return Promise.reject(clientError("protocol_error", "terminal request id is missing"));
         }
-        if (frame)
-            this.resolveClosed(frame);
-        else
-            this.rejectClosed(error ?? clientError("closed", "Remote Session terminal closed"));
+        const pull = expectedType === "session.terminal.seed.chunk" || expectedType === "session.terminal.chunk";
+        const sameClassPending = [...this.pending.values()].some((pending) => {
+            const pendingPull = pending.expectedType === "session.terminal.seed.chunk" ||
+                pending.expectedType === "session.terminal.chunk";
+            return pendingPull === pull;
+        });
+        if (sameClassPending) {
+            return Promise.reject(clientError("protocol_error", pull ? "concurrent terminal pulls are not allowed" : "concurrent terminal controls are not allowed"));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(frame.requestId);
+                reject(clientError("deadline_exceeded", "Remote Session terminal operation timed out"));
+            }, this.timeoutMs);
+            timer.unref?.();
+            this.pending.set(frame.requestId, { expectedType, resolve, reject, timer });
+            void this.sendFrame(frame).catch((error) => {
+                const pending = this.pending.get(frame.requestId);
+                if (!pending)
+                    return;
+                this.pending.delete(frame.requestId);
+                clearTimeout(pending.timer);
+                pending.reject(error);
+            });
+        });
     }
-    clearQueue() {
-        this.queue.length = 0;
-        this.queuedBytes = 0;
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    nextRequestId() {
+        return `treq_${randomBytes(12).toString("base64url")}`;
     }
 }
 function sessionTerminalError(frame, sessionId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/remote-runtime-client",
-  "version": "0.1.11-beta.4",
+  "version": "0.1.11-beta.41",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -25,8 +25,8 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@rynx-ai/protocol": "0.1.11-beta.4",
-    "@rynx-ai/remote-runtime-e2ee": "0.1.11-beta.4"
+    "@rynx-ai/protocol": "0.1.11-beta.41",
+    "@rynx-ai/remote-runtime-e2ee": "0.1.11-beta.41"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"