@rynx-ai/server 0.1.0 → 0.1.9

package/dist/session-runtime-index.js

@@ -0,0 +1,86 @@
+/**
+ * Process-local index of live Session state. Durable transcript items explain
+ * history; this index says which historical requests still have a real runtime
+ * waiter after a client reconnect. It intentionally starts empty after daemon
+ * restart because an old runner waiter cannot be resumed implicitly.
+ */
+export class SessionRuntimeIndex {
+    sessions = new Map();
+    observe(sessionId, event) {
+        const state = this.state(sessionId);
+        switch (event.type) {
+            case "response.created":
+                state.activeResponseIds.add(event.responseId);
+                state.status = "running";
+                return;
+            case "response.completed":
+                state.activeResponseIds.delete(event.responseId);
+                this.removeResponseInteractions(state, event.responseId);
+                state.status = state.activeResponseIds.size > 0 ? "running" : "idle";
+                return;
+            case "response.failed":
+                state.activeResponseIds.delete(event.responseId);
+                this.removeResponseInteractions(state, event.responseId);
+                // Response failure is Turn-local. It must not poison a reusable Session.
+                state.status = state.activeResponseIds.size > 0 ? "running" : "idle";
+                return;
+            case "session.status":
+                state.status =
+                    state.pendingInteractions.size > 0 || state.activeResponseIds.size > 0
+                        ? "running"
+                        : event.status;
+                return;
+            case "session.interaction.requested":
+                state.pendingInteractions.set(event.interaction.interactionId, {
+                    responseId: event.responseId,
+                    interaction: event.interaction,
+                });
+                state.activeResponseIds.add(event.responseId);
+                state.status = "running";
+                return;
+            case "session.interaction.resolved":
+            case "session.interaction.cancelled":
+                state.pendingInteractions.delete(event.interactionId);
+                state.status = state.activeResponseIds.size > 0 ? "running" : state.status;
+                return;
+            case "session.rotated":
+                state.activeResponseIds.clear();
+                state.pendingInteractions.clear();
+                state.status = "idle";
+                return;
+            default:
+                return;
+        }
+    }
+    snapshot(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return { status: "idle", activeResponseIds: [], pendingInteractions: [] };
+        return {
+            status: state.pendingInteractions.size > 0 ? "running" : state.status,
+            activeResponseIds: [...state.activeResponseIds],
+            pendingInteractions: [...state.pendingInteractions.values()],
+        };
+    }
+    remove(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    state(sessionId) {
+        let state = this.sessions.get(sessionId);
+        if (!state) {
+            state = {
+                status: "idle",
+                activeResponseIds: new Set(),
+                pendingInteractions: new Map(),
+            };
+            this.sessions.set(sessionId, state);
+        }
+        return state;
+    }
+    removeResponseInteractions(state, responseId) {
+        for (const [interactionId, pending] of state.pendingInteractions) {
+            if (pending.responseId === responseId)
+                state.pendingInteractions.delete(interactionId);
+        }
+    }
+}

package/dist/session-terminal-host.d.ts

@@ -0,0 +1,46 @@
+import { type RunnerManager } from "@rynx-ai/runtime";
+export type SessionTerminalRole = "owner" | "read-only";
+export interface SessionTerminalOpenOptions {
+    role: SessionTerminalRole;
+    cols: number;
+    rows: number;
+    signal?: AbortSignal;
+}
+export type SessionTerminalCloseReason = "client_closed" | "terminal_exited" | "not_live" | "unauthorized" | "capacity" | "backpressure" | "internal";
+export interface SessionTerminalCloseInfo {
+    reason: SessionTerminalCloseReason;
+    exitCode?: number;
+}
+/** One attachment; close detaches this client and never kills the tmux pane. */
+export interface SessionTerminalAttachment extends AsyncIterable<Uint8Array> {
+    readonly sessionId: string;
+    readonly role: SessionTerminalRole;
+    readonly closed: Promise<SessionTerminalCloseInfo>;
+    write(data: Uint8Array): void | Promise<void>;
+    resize(cols: number, rows: number): void | Promise<void>;
+    close(): Promise<void>;
+}
+/** Transport-neutral live terminal application port used by Local and Direct. */
+export interface SessionTerminalHost {
+    open(sessionId: string, options: SessionTerminalOpenOptions): Promise<SessionTerminalAttachment>;
+}
+export type SessionTerminalOpenErrorCode = "invalid_request" | "not_live" | "unauthorized" | "capacity" | "method_not_found" | "internal";
+export declare class SessionTerminalOpenError extends Error {
+    readonly code: SessionTerminalOpenErrorCode;
+    constructor(code: SessionTerminalOpenErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class SessionTerminalStreamError extends Error {
+    readonly reason: Exclude<SessionTerminalCloseReason, "client_closed" | "terminal_exited">;
+    constructor(reason: Exclude<SessionTerminalCloseReason, "client_closed" | "terminal_exited">, message: string, options?: ErrorOptions);
+}
+export interface RunnerSessionTerminalHostOptions {
+    runnerManager: RunnerManager;
+    /** Resolve only a currently live Session. Undefined rejects before a runner can spawn. */
+    resolveLiveSession: (sessionId: string) => {
+        cwd: string;
+    } | undefined | Promise<{
+        cwd: string;
+    } | undefined>;
+}
+/** Adapt the runner-child terminal protocol without exposing cwd or commands to clients. */
+export declare function createRunnerSessionTerminalHost(options: RunnerSessionTerminalHostOptions): SessionTerminalHost;

package/dist/session-terminal-host.js

@@ -0,0 +1,252 @@
+import { TerminalOpenError } from "@rynx-ai/runtime";
+const MAX_QUEUED_OUTPUT_FRAMES = 128;
+const MAX_QUEUED_OUTPUT_BYTES = 512 * 1024;
+const MAX_TERMINAL_DIMENSION = 1_000;
+export class SessionTerminalOpenError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SessionTerminalOpenError";
+    }
+}
+export class SessionTerminalStreamError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "SessionTerminalStreamError";
+    }
+}
+/** Adapt the runner-child terminal protocol without exposing cwd or commands to clients. */
+export function createRunnerSessionTerminalHost(options) {
+    return {
+        async open(sessionId, openOptions) {
+            validateOpen(sessionId, openOptions);
+            throwIfAborted(openOptions.signal);
+            const session = await options.resolveLiveSession(sessionId);
+            if (!session || typeof session.cwd !== "string" || session.cwd.trim().length === 0) {
+                throw new SessionTerminalOpenError("not_live", "Session terminal is not live");
+            }
+            throwIfAborted(openOptions.signal);
+            let parent;
+            try {
+                parent = options.runnerManager.openLiveTerminal(sessionId, {
+                    role: openOptions.role,
+                    cwd: session.cwd,
+                    cols: openOptions.cols,
+                    rows: openOptions.rows,
+                });
+            }
+            catch (error) {
+                if (error instanceof TerminalOpenError && error.code === "terminal_not_live") {
+                    throw new SessionTerminalOpenError("not_live", "Session terminal is not live", {
+                        cause: error,
+                    });
+                }
+                throw new SessionTerminalOpenError("internal", "Session terminal could not be opened", { cause: error });
+            }
+            const attachment = new RunnerSessionTerminalAttachment(sessionId, parent, openOptions.signal);
+            try {
+                const opened = await waitFor(parent.ready, openOptions.signal);
+                attachment.opened(opened.role);
+                attachment.throwIfOpeningFailed();
+                return attachment;
+            }
+            catch (error) {
+                await attachment.close().catch(() => undefined);
+                if (isAbort(error)) {
+                    throw new SessionTerminalOpenError("invalid_request", "Session terminal open was cancelled", { cause: error });
+                }
+                if (error instanceof TerminalOpenError && error.code === "terminal_not_live") {
+                    throw new SessionTerminalOpenError("not_live", "Session terminal is not live", {
+                        cause: error,
+                    });
+                }
+                if (error instanceof SessionTerminalOpenError)
+                    throw error;
+                throw new SessionTerminalOpenError("internal", "Session terminal could not be opened", { cause: error });
+            }
+        },
+    };
+}
+class RunnerSessionTerminalAttachment {
+    sessionId;
+    parent;
+    signal;
+    queue = [];
+    queuedBytes = 0;
+    waiter;
+    ended = false;
+    terminalError;
+    openingFailure;
+    currentRole;
+    resolveClosed;
+    closed;
+    onAbort;
+    constructor(sessionId, parent, signal) {
+        this.sessionId = sessionId;
+        this.parent = parent;
+        this.signal = signal;
+        this.currentRole = "read-only";
+        this.closed = new Promise((resolve) => {
+            this.resolveClosed = resolve;
+        });
+        this.onAbort = () => {
+            void this.close().catch(() => undefined);
+        };
+        parent.onData((chunk) => this.push(Uint8Array.from(Buffer.from(chunk, "utf8"))));
+        parent.onExit((info) => this.finish({ reason: "terminal_exited", exitCode: info.exitCode }));
+        if (signal?.aborted)
+            this.onAbort();
+        else
+            signal?.addEventListener("abort", this.onAbort, { once: true });
+    }
+    get role() {
+        return this.currentRole;
+    }
+    opened(role) {
+        this.currentRole = role;
+    }
+    throwIfOpeningFailed() {
+        if (this.openingFailure)
+            throw this.openingFailure;
+        if (this.ended) {
+            throw new SessionTerminalOpenError("internal", "Session terminal closed while opening");
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    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(new SessionTerminalStreamError("internal", "Concurrent reads from one Session terminal are not allowed"));
+        }
+        return new Promise((resolve, reject) => {
+            this.waiter = { resolve, reject };
+        });
+    }
+    async return() {
+        await this.close();
+        return { done: true, value: undefined };
+    }
+    write(data) {
+        if (this.ended || this.currentRole !== "owner" || data.byteLength === 0)
+            return;
+        this.parent.write(Buffer.from(data).toString("utf8"));
+    }
+    resize(cols, rows) {
+        validateDimensions(cols, rows);
+        if (!this.ended)
+            this.parent.resize(cols, rows);
+    }
+    async close() {
+        if (this.ended)
+            return;
+        this.parent.close();
+        this.finish({ reason: "client_closed" }, undefined, true);
+    }
+    push(data) {
+        if (this.ended || data.byteLength === 0)
+            return;
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter.resolve({ done: false, value: data });
+            return;
+        }
+        if (this.queue.length >= MAX_QUEUED_OUTPUT_FRAMES ||
+            this.queuedBytes + data.byteLength > MAX_QUEUED_OUTPUT_BYTES) {
+            const error = new SessionTerminalStreamError("backpressure", "Session terminal output exceeded its bounded queue");
+            this.openingFailure = new SessionTerminalOpenError("capacity", error.message, {
+                cause: error,
+            });
+            this.parent.close();
+            this.finish({ reason: "backpressure" }, error, true);
+            return;
+        }
+        const copy = Uint8Array.from(data);
+        this.queue.push({ data: copy, bytes: copy.byteLength });
+        this.queuedBytes += copy.byteLength;
+    }
+    finish(info, error, discardQueue = false) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.terminalError = error;
+        this.signal?.removeEventListener("abort", this.onAbort);
+        if (discardQueue) {
+            this.queue.length = 0;
+            this.queuedBytes = 0;
+        }
+        const waiter = this.waiter;
+        this.waiter = undefined;
+        if (waiter) {
+            if (error === undefined)
+                waiter.resolve({ done: true, value: undefined });
+            else
+                waiter.reject(error);
+        }
+        this.resolveClosed(info);
+    }
+}
+function validateOpen(sessionId, options) {
+    if (!sessionId || sessionId.length > 256 || /[\u0000-\u001f\u007f]/.test(sessionId)) {
+        throw new SessionTerminalOpenError("invalid_request", "Session terminal id is invalid");
+    }
+    if (options.role !== "owner" && options.role !== "read-only") {
+        throw new SessionTerminalOpenError("invalid_request", "Session terminal role is invalid");
+    }
+    validateDimensions(options.cols, options.rows);
+}
+function validateDimensions(cols, rows) {
+    if (!Number.isSafeInteger(cols) ||
+        !Number.isSafeInteger(rows) ||
+        cols < 1 ||
+        rows < 1 ||
+        cols > MAX_TERMINAL_DIMENSION ||
+        rows > MAX_TERMINAL_DIMENSION) {
+        throw new SessionTerminalOpenError("invalid_request", `Session terminal dimensions must be integers within 1..${MAX_TERMINAL_DIMENSION}`);
+    }
+}
+async function waitFor(promise, signal) {
+    if (!signal)
+        return await promise;
+    throwIfAborted(signal);
+    return await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            cleanup();
+            reject(signal.reason ?? abortError());
+        };
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        signal.addEventListener("abort", onAbort, { once: true });
+        void promise.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? abortError();
+}
+function abortError() {
+    const error = new Error("Session terminal operation was aborted");
+    error.name = "AbortError";
+    return error;
+}
+function isAbort(error) {
+    return error instanceof Error && error.name === "AbortError";
+}

package/dist/terminal-ws.d.ts

@@ -1,25 +1,14 @@
-/**
- * WebSocket bridge for the live terminal (Phase C). Attaches to the existing
- * daemon `http.Server` via the `upgrade` event — no second port — and tunnels a
- * browser xterm session to a per-session terminal on the runner child through
- * {@link RunnerManager.openTerminal}.
- *
- * Wire protocol (mirrors omnigent's terminal attach):
- *  - server → browser: BINARY frames = raw PTY output; TEXT frames = JSON
- *    control (`{t:"opened",role}`, `{t:"exit"}`, `{t:"error",message}`).
- *  - browser → server: BINARY frames = keystrokes; TEXT frames = JSON control
- *    (`{t:"resize",cols,rows}` / `{t:"input",data}`).
- */
 import type { Server } from "node:http";
-import type { RunnerManager } from "@rynx-ai/runtime";
 import { WebSocketServer } from "ws";
+import { type SessionTerminalHost } from "./session-terminal-host.js";
+import type { RuntimeConnectionResolverHost } from "./server.js";
 export interface TerminalWsDeps {
-    runnerManager: RunnerManager;
-    /** Resolve a session's terminal working directory (sync). Defaults to cwd. */
-    resolveCwd?: (sessionId: string) => string | undefined;
-    /** Inner command for the pane; defaults child-side to the login shell. */
-    command?: string;
-    args?: string[];
+    /** Canonical Local/Direct Runtime resolver. Explicit selectors never fall back. */
+    runtimeConnectionResolver?: RuntimeConnectionResolverHost;
+    /** Compatibility host for the legacy local-only path. It receives identical auth. */
+    legacyLocalTerminalHost?: SessionTerminalHost;
+    /** WebSocket protocol ping interval; override only for tests. */
+    keepAliveMs?: number;
 }
-/** Attach the terminal WS upgrade handler to a running http.Server. */
+/** Attach the authenticated Runtime-scoped terminal bridge to an HTTP server. */
 export declare function attachTerminalWs(server: Server, deps: TerminalWsDeps): WebSocketServer;